最初に: 親スキル neon を使用して、Neonの概要、始め方、Neon開発のベストプラクティスなどを参照してください。

neon スキルがインストールされていない場合は、https://neon.com/docs/ai/skills/neon/SKILL.md から取得するか、以下でインストールしてください:

npx skills add neondatabase/agent-skills --skill neon

Neon Object Storage

これはパブリックベータ機能であり、現在 us-east-2 と eu-central-1 で利用可能です。

Neon Object Storage は、プロジェクトのブランチと連動するS3互換オブジェクトストレージです。各ブランチは独立したストレージ状態を持ち、ファイルとデータベース行が開発、プレビュー、ステージング、本番環境で同期します。

このスキルを使用して、ユーザーがデータベースと一緒にブランチするファイルを保存および配信できるように支援してください。動作するバケットとアップロード/ダウンロードフロー、注入された環境変数に接続されたブランチ対応のS3クライアント、または公式Neonドキュメントからの正確な回答を提供します。

使用すべきタイミング

Neon Object Storage は、アプリとそのユーザーが生成するファイル（アップロード、添付ファイル、アバター、画像、ドキュメント、生成アセット、バックアップ）に使用します。アプリがすでにNeon上にある場合、これらのファイルを置くデフォルトの場所です。

すでにLakebase Postgresを使用しており、別のプロバイダーを追加したくない場合。 単一のバックエンド、単一の請求、単一のCLI、単一のブランチセット — 別のAWS S3 / R2 / Supabase Storageアカウントを立てて接続する必要はありません。データベースを支える同じNeonクレデンシャルがストレージも支えます。
ファイルがデータベースと環境間で同期している必要がある場合。 ストレージはPostgresデータと 一緒に ブランチします。ブランチをフォークすると、子ブランチはその時点での親のバケットとオブジェクトを即座に継承します — コピーオンライトであるため、データは複製されません。これにより、エージェント、開発、プレビュー、テスト環境がシームレスになります。プレビューブランチは、行とそれらが参照するファイルの両方の一貫したスナップショットを取得し、子ブランチでの書き込みは親に影響を与えません。
安全で使い捨て可能な環境が必要な場合。 プレビュー/CIブランチでファイルをアップロード、上書き、削除しても、本番データにリスクはなく、ブランチを削除するだけです。
標準のS3ツールを使用したい場合。 S3セマンティクス上に構築されており、S3 APIを話すため、AWS SDK、boto3、AWS CLI、プリサインドURLがすべて動作します — 信頼性が高く、なじみ深く、独自クライアントは不要です。

問題のファイルがアプリ自体に同梱されている場合（HTML、JSバンドル、CSS、public/ 内の画像）は、静的ウェブホスティングに該当し、Vercel、Netlify、またはCloudflareを使用する必要があります。バケットから配信されるパブリックアセットは、その前にCDNを配置する必要があります（アーキテクチャ: Object Storageの位置づけを参照）。

機能

S3互換 — 既存のS3 SDK、boto3、AWS CLI、プリサインドURLで動作します。パススタイルアドレッシングとSigV4のみをサポートします。
データベースとブランチ — すべてのNeonブランチは、独立したコピーオンライトストレージ状態を取得します。フォークしてもデータはコピーされません。
2つのアクセスモード — private バケットはすべての操作にクレデンシャルを要求します。public_read バケットは認証付き書き込みで匿名読み取りを許可します。
単一のクレデンシャルシステム — FunctionsやAI Gatewayと同じNeonクレデンシャルシステムを使用します。

可用性

何かを設定する前にこの前提条件を確認してください: Neon Object Storage はパブリックベータ機能であり、現在 us-east-2 と eu-central-1 で利用可能です。ユーザーのNeonプロジェクトがこれらのリージョンのいずれかにあることを確認してから先に進んでください。

アーキテクチャ: Object Storageの位置づけ

Neon（Object Storageを含む）は フルスタックアプリホスティングではなく、バックエンドプリミティブ です。Object Storage は、アプリとそのユーザーが生成するファイル（アップロード、添付ファイル、アバター、ドキュメント、生成画像、バックアップ）を保持します。これらは同じブランチのPostgres行からキーが付けられます。これにより、2つの境界が生じます:

パブリックアセットの前面にCDNを配置する。 public_read オブジェクトは ${AWS_ENDPOINT_URL_S3}/<bucket>/<object-key> で匿名で読み取られます。これはブランチのストレージエンドポイントであり、環境変数として注入されます（環境変数を参照）。ブラウザがすべてのページビューで読み込むアセット（アバター、商品画像、ホットなもの）には、CloudflareやVercel CDNのオリジンとしてこのエンドポイントを使用し、PutObject で Cache-Control を設定してエッジが各オブジェクトを保持する期間を認識できるようにします。キャッシュされたオブジェクトはキーと同じだけ新鮮なため、各バージョンを新しいキーに書き込み（avatars/<user-id>/<uuid>.jpg）、Postgresに保存されたキーを再ポイントします。1つのキーを上書きしてTTLが切れるのを待つ必要はありません。エンドポイントはブランチスコープであるため、本番CDNは本番ブランチをポイントし、プレビューブランチはキャッシュを共有せずに独自のエンドポイントを直接読み取ります。プライベートバケットは代わりにプリサインドURLを使用し、署名をクエリ文字列に保持します。
アプリ自体は別の場所でホストする。 リポジトリにチェックインされているもの（HTML、JSバンドル、CSS、public/ に同梱される画像やフォント）は、Vercel、Netlify、またはCloudflareに属します。インデックスドキュメント、SPAフォールバック、カスタムドメインも同様です。Neonにはそれらを配信するためのウェブサイトモードはありません: PutBucketWebsite は 501 Not Implemented を返します。

セットアップ

オブジェクトストレージは neon.ts のinfrastructure-as-code設定の一部です（ブランチファーストワークフロー、link/checkout、neon.ts の基本については neon スキルを参照）。preview.buckets の下にバケット名をキーとして宣言します:

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  preview: {
    buckets: {
      images: {}, // デフォルトで private
      "public-assets": { access: "public_read" },
    },
  },
});

リンクされたブランチに宣言されたバケットをプロビジョニングします:

neon deploy   # `neon config apply` のエイリアス

Neon Infrastructure as Code (`neon.ts`)

上記の preview.buckets ブロックは、Neonのinfrastructure-as-codeファイルである neon.ts の一部です。1つのTypeScriptファイルが、ブランチが持つべき他のすべてのサービスと一緒にバケットを宣言します（完全なリファレンスは neon スキルを参照）。Terraform方式でブランチに対して宣言を調整します:

neon config status   # ブランチの現在の設定を表示（どのバケットが存在するか）
neon config plan     # apply が変更する内容のドライランディフ
neon config apply    # 宣言されたバケットを作成（neon deploy はエイリアス）

バケットは ブランチスコープ です: neon.ts が存在する場合、neon checkout はブランチを作成するときにポリシーを適用するため、新しいプレビュー/CIブランチはバケットがすでにプロビジョニングされ（親からコピーオンライトオブジェクトを継承し）た状態で起動します。既存の ブランチをチェックアウトしても調整は行われません — 変更を適用するには neon deploy を実行します。プロビジョニング（config apply / deploy）、link、checkout は、ブランチのS3クレデンシャルをローカルの .env.local にプルするため、以下に示す env pull と同じ手順がこれらのコマンドでも実行されます。

環境変数

preview.buckets が宣言されると、Neonは AWS標準 のS3環境変数を注入するため、AWS SDKが追加設定なしで環境から動作します。デプロイされたNeon Function内では自動的に注入されます。ローカルでは、CLIを介してそれらをディスクにプルするか（または実行時に注入します）:

neon env pull            # ブランチの変数を .env（または .env.local）に書き込む
# または、ファイルを書き込まずに実行時に注入:
neon-env run -- <your dev command>

変数	意味
`AWS_ACCESS_KEY_ID`	S3 Access Key ID（ブランチクレデンシャルのトークンID）
`AWS_SECRET_ACCESS_KEY`	S3 Secret Access Key
`AWS_ENDPOINT_URL_S3`	ブランチS3エンドポイントURL
`AWS_REGION`	リージョン、例: `us-east-2`

名前がAWS標準であるため、AWS SDKは環境から自動的にクレデンシャル、エンドポイント、リージョンを取得します。クレデンシャルはブランチスコープであり、そのブランチとそのすべての子孫に対して有効です。

process.env を直接読み取る代わりに、これらのクレデンシャルへの型付けされた検証済みアクセスを行うには、同じ neon.ts 設定オブジェクトを @neon/env の parseEnv に渡します。これにより、設定から派生した env.storage 名前空間（accessKeyId、secretAccessKey、endpoint、region）が返されます。neon スキルを参照してください。

オブジェクトの操作: Files SDK（推奨）

オブジェクトの読み書きに最もシンプルで移植性の高い方法は、Files SDK とその neon アダプタを使用することです。これは、ウェブ標準のI/O上に構築された小さな統一ストレージAPI（upload、download、url、list、exists、copy、delete、signedUploadUrl）です。内部でAWS S3クライアントをNeon用に適切に設定して使用し、エラーを Neon error としてラベル付けします。そのため、誤設定の心配はありません。最初にこれを試してください。

アダプタが内部で使用するAWS S3ピア依存関係と一緒にインストールします:

npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

アダプタは、同じ注入された AWS_* 環境変数からエンドポイント、リージョン、クレデンシャルを解決します。バケット名のみを渡します:

import { Files } from "files-sdk";
import { neon } from "files-sdk/neon";

const files = new Files({ adapter: neon({ bucket: "images" }) });

// アップロード — body は Buffer、Uint8Array、Blob、File、ReadableStream、または文字列
await files.upload("generated/cat.jpg", fileBuffer, { contentType: "image/jpeg" });

// ダウンロード
const file = await files.download("generated/cat.jpg");
const bytes = new Uint8Array(await file.arrayBuffer());

// プリサインドGET — クレデンシャルを公開せずに共有（デフォルトは1時間の有効期限）
const url = await files.url("generated/cat.jpg", { expiresIn: 3600 });

// 他にも: files.exists()、files.list({ prefix })、files.copy()、files.delete()、files.signedUploadUrl()

アダプターのインポートを変更する（files-sdk/s3、files-sdk/r2、files-sdk/gcs、...）だけで、コードの残りは変更されません。

オブジェクトの操作: AWS S3クライアント（代替）

NeonはS3 APIを直接話すため、ネイティブクライアントを好む場合やすでに依存している場合は、AWS SDKにダウンレベルできます。クレデンシャル、エンドポイント、リージョンは標準のAWS環境チェーンから読み取られるため、渡す設定は forcePathStyle: true のみです — Neonはパススタイルアドレッシングを必要とするため、S3クライアントは必ずこれを設定する必要があります:

import { S3Client } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  forcePathStyle: true, // 必須: Neonはパススタイルアドレッシングを使用
});

その後、生のコマンドオブジェクトを使用してアップロード、ダウンロード、プリサインド署名を行います:

import { PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const BUCKET = "images";

// アップロード
await s3.send(
  new PutObjectCommand({
    Bucket: BUCKET,
    Key: "generated/cat.jpg",
    Body: fileBuffer,
    ContentType: "image/jpeg",
  }),
);

// ダウンロード
const res = await s3.send(
  new GetObjectCommand({ Bucket: BUCKET, Key: "generated/cat.jpg" }),
);
const bytes = await res.Body?.transformToByteArray();

// プリサインドGET — クレデンシャルを公開せずに共有
const url = await getSignedUrl(
  s3,
  new GetObjectCommand({ Bucket: BUCKET, Key: "generated/cat.jpg" }),
  { expiresIn: 3600 },
);

ブランチ上のストレージとデータベースのペアリング

標準的なパターン: エージェントが画像を生成 → PutObject で images バケットに保存 → Postgresに行を挿入 → 読み取り時にプリサインドURLを返す。バケットのキー（バイトではない）をPostgres列に保存し、読み取り時にプリサインします。行とオブジェクトが同じブランチ上にあるため、一緒にブランチし、ずれることはありません。

CLIのバケットおよびオブジェクトコマンド

組み込みのブランチログ

neon logs query --branch production --source storage --since 1h

ストレージは、現在ブランチログがカバーする2つのソースの1つで、Neon Functionsと並んでいます。ログは単一ブランチにスコープされるため、デバッグしているバケットがチェックアウトしているブランチにない場合は --branch を渡します。ログに関するその他のすべて（必要なCLIバージョン、フィルター、SDK、Loki互換読み取りAPI）は、親の neon スキルの オブザーバビリティ セクションにあります。

Neonドキュメント

Neonドキュメントが信頼できる情報源であり、Object Storageは急速に進化しているため、常に公式ドキュメントと照合してください。任意のドキュメントページは、URLに .md を追加するか、Accept: text/markdown をリクエストすることでマークダウンとして取得できます。ドキュメントインデックス（https://neon.com/docs/llms.txt）とチェンジログのお知らせから適切なページを見つけてください。

neondatabase/neon-object-storage

neon-object-storage とは？

お気に入りのAIに質問する

ドキュメント