neon-object-storage

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

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

neon skills -s neon -y

Neon Object Storage

現在、aws-us-east-2、aws-us-east-1、aws-eu-central-1、aws-ap-southeast-1 で利用できます。

Neon Object Storage は、Neon プロジェクトに組み込まれた S3 互換のファイルストレージです。データベースとともにブランチが作成されるため、プレビューブランチには、そのブランチ専用のファイルのコピーと、それらを参照する行が用意されます。

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

使用する場面

アプリやユーザーが作成するファイル（アップロード、添付ファイル、アバター、画像、ドキュメント、生成アセット、バックアップ）には、Neon Object Storage を利用してください。アプリがすでに Neon を利用している場合、ファイルの保存先としてはこれが標準です。

• すでに Lakebase Postgres を利用しており、別のプロバイダーを増やしたくない場合。 AWS S3／R2／Supabase Storage などの別アカウントを用意して接続する代わりに、バックエンド、請求、CLI、ブランチを 1 つにまとめられます。データベースに使用しているものと同じ Neon 認証情報で、ストレージも利用できます。
• ファイルを環境間でデータベースとともにブランチ化する必要がある場合。 ストレージは Postgres データと一緒にブランチ化されます。ブランチをフォークすると、子ブランチはその時点での親ブランチのバケットとオブジェクトを即座に引き継ぎます。コピーオンライト方式のため、データは複製されません。これにより、エージェント、開発、プレビュー、テストの各環境をシームレスに利用できます。プレビューブランチには、行と、それらが参照するファイルの両方の一貫したスナップショットが用意され、子ブランチへの書き込みが親ブランチに影響することはありません。
• 安全で使い捨て可能な環境が必要な場合。 プレビュー／CI ブランチでファイルをアップロード、上書き、削除しても、本番データに影響する心配はありません。作業後はブランチを削除できます。
• 標準的な S3 ツールを使いたい場合。 S3 のセマンティクスに基づいて構築され、S3 API に対応しているため、AWS SDK、boto3、AWS CLI、署名付き URL をすべて利用できます。信頼性が高く使い慣れた仕組みで、独自のクライアントは必要ありません。

対象のファイルがアプリ自体とともに配布される HTML、JS バンドル、CSS、public/ 内の画像であれば、それは静的ウェブホスティングに該当するため、Vercel、Netlify、Cloudflare などを利用してください。バケットから配信する公開アセットの前段には CDN が必要です（アーキテクチャ：オブジェクトストレージの役割を参照）。

機能

• S3 互換 — 既存の S3 SDK、boto3、AWS CLI、署名付き URL を利用できます。パス形式のアドレス指定と SigV4 のみをサポートします。
• データベースとともにブランチ化 — Neon の各ブランチには、分離されたコピーオンライト方式のストレージ状態が用意されます。フォーク時にデータはコピーされません。
• 2 つのアクセスモード — private バケットではすべての操作に認証情報が必要です。public_read バケットでは、認証なしの読み取りと、認証済みの書き込みが可能です。
• 1 つの認証情報システム — Functions と AI Gateway で使用されているものと同じ Neon 認証情報システムを使用します。

利用可能なリージョン

セットアップを始める前に、この前提条件を確認してください。Neon Object Storage は現在、aws-us-east-2、aws-us-east-1、aws-eu-central-1、aws-ap-southeast-1 で利用できます。作業を進める前に、ユーザーの Neon プロジェクトがこれらのいずれかのリージョンにあることを確認してください。リージョンの対応状況：https://neon.com/docs/get-started/backend-overview.md

アーキテクチャ：オブジェクトストレージの役割

Neon（オブジェクトストレージを含む）は、フルスタックのアプリホスティングではなく、バックエンドのプリミティブです。オブジェクトストレージには、アプリやユーザーが作成するファイル（アップロード、添付ファイル、アバター、ドキュメント、生成画像、バックアップなど）が保存され、同じブランチ上の Postgres の行を使ってキーが設定されます。これには、次の 2 つの境界があります。

• 公開アセットの前段に CDN を配置します。 public_read オブジェクトは ${AWS_ENDPOINT_URL_S3}/<bucket>/<object-key>（環境変数として設定されるブランチのストレージエンドポイント。詳しくは環境変数をご覧ください）から匿名で読み取れます。アバターや商品画像など、各ページの表示時にブラウザーが読み込む頻繁にアクセスされるアセットには、Cloudflare または Vercel CDN のオリジンとしてこのエンドポイントを使用し、PutObject に Cache-Control を設定して、エッジで各オブジェクトを保持する期間を指定します。キャッシュされたオブジェクトの鮮度はキーによって決まるため、各バージョンは新しいキー（avatars/<user-id>/<uuid>.jpg）に書き込み、1 つのキーを上書きして TTL の期限切れを待つのではなく、Postgres に保存されたキーを新しいものに差し替えてください。エンドポイントはブランチごとに異なるため、本番 CDN は本番ブランチを参照し、プレビューブランチはキャッシュを共有せず、それぞれのエンドポイントを直接読み取ります。プライベートバケットでは、代わりにクエリ文字列に署名が含まれる署名付き URL を使用します。
• アプリ自体は別の場所でホストします。 リポジトリに含まれる HTML、JS バンドル、CSS、public/ に含まれる画像やフォントはすべて、関連するインデックスドキュメント、SPA フォールバック、カスタムドメインとともに、Vercel、Netlify、または Cloudflare に配置してください。Neon にはこれらを配信するウェブサイトモードがなく、PutBucketWebsite は 501 Not Implemented を返します。

セットアップ

オブジェクトストレージは、インフラストラクチャをコードで管理する neon.ts 設定の一部です（ブランチを優先するワークフロー、link／checkout、neon.ts の基本については neon スキルをご覧ください）。バケット名をキーとして、buckets の下にバケットを宣言します。

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

export default defineConfig({
  buckets: {
    images: {}, // private by default
    "public-assets": { access: "public_read" },
  },
});

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

neon deploy   # alias for `neon config apply`

Neon のインフラストラクチャ・アズ・コード（neon.ts）

上記の buckets ブロックは、Neon のインフラストラクチャ・アズ・コード用ファイルである neon.ts の一部です。この 1 つの TypeScript ファイルで、ブランチに必要な他のすべてのサービスとともにバケットを宣言します（詳しいリファレンスは neon スキルをご覧ください）。Terraform と同じ方法で、宣言内容をブランチに適用します。

neon config status   # print the branch's live config (which buckets exist)
neon config plan     # dry-run diff of what apply would change
neon config apply    # create the declared buckets  (neon deploy is an alias)

バケットはブランチごとに設定されます。neon.ts がある場合、neon checkout はブランチの作成時にポリシーを適用するため、新しいプレビュー／CI ブランチでは、バケットがすでにプロビジョニングされ、親ブランチのコピーオンライトオブジェクトが継承された状態になります。既存のブランチをチェックアウトしても変更内容は適用されないため、変更を反映するには neon deploy を実行してください。プロビジョニング（config apply／deploy）、link、checkout を実行すると、ブランチの S3 認証情報もローカルの .env.local に取り込まれるため、以下に示すのと同じ env pull の手順がこれらのコマンドで自動的に行われます。

環境変数

buckets が宣言されている場合、Neon は AWS 標準の S3 環境変数を注入するため、AWS SDK は追加設定なしで環境から値を取得できます。デプロイ済みの Neon Function 内では自動的に注入されます。ローカルでは、CLI を使ってディスクに取得するか、実行時に注入してください。

neon env pull            # writes the branch's vars into .env (or .env.local)
# or, without writing a file, inject at runtime:
neon-env run -- <your dev command>

変数	意味
AWS_ACCESS_KEY_ID	S3 アクセスキー ID（ブランチ認証情報のトークン ID）
AWS_SECRET_ACCESS_KEY	S3 シークレットアクセスキー
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 アダプターを使うことです。これは、Web 標準の 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" }) });

// Upload — body may be a Buffer, Uint8Array, Blob, File, ReadableStream, or string
await files.upload("generated/cat.jpg", fileBuffer, { contentType: "image/jpeg" });

// Download
const file = await files.download("generated/cat.jpg");
const bytes = new Uint8Array(await file.arrayBuffer());

// Presigned GET — share without exposing credentials (defaults to a 1h expiry)
const url = await files.url("generated/cat.jpg", { expiresIn: 3600 });

// Plus: 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 SDK を直接利用できます。認証情報、エンドポイント、リージョンは標準の AWS 環境変数チェーンから読み取られるため、渡す設定は forcePathStyle: true だけです。Neon ではパス形式のアドレッシングが必須のため、S3 クライアントで 必ず 設定してください。

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

const s3 = new S3Client({
  forcePathStyle: true, // required: Neon uses path-style addressing
});

続いて、生のコマンドオブジェクトを使ってアップロード、ダウンロード、署名付き URL の生成を行います。

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

const BUCKET = "images";

// Upload
await s3.send(
  new PutObjectCommand({
    Bucket: BUCKET,
    Key: "generated/cat.jpg",
    Body: fileBuffer,
    ContentType: "image/jpeg",
  }),
);

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

// Presigned GET — share without exposing credentials
const url = await getSignedUrl(
  s3,
  new GetObjectCommand({ Bucket: BUCKET, Key: "generated/cat.jpg" }),
  { expiresIn: 3600 },
);

ブランチ上でストレージとデータベースを組み合わせる

標準的なパターンは、エージェントが画像を生成し、images バケットに PutObject で保存した後、Postgres に行を挿入し、読み取り時に署名付き URL を返す方法です。Postgres の列にはバイト列ではなく、バケットの キー を保存し、読み取り時に署名付き URL を生成します。行とオブジェクトは同じブランチに存在するため、一緒にブランチ化され、食い違うことはありません。

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

neon には、スクリプトや単発の操作に使える、バケット／オブジェクト用の専用コマンド（neon bucket create|list|delete、neon bucket object put|get|list|delete）もあります。

組み込みブランチログ

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

現在、ブランチログの対象となっているソースは Neon Functions とストレージの 2 つです。ログは単一のブランチに限定されるため、デバッグ対象のバケットが現在チェックアウトしているブランチにない場合は、--branch を指定してください。ログに関するその他の情報（必要な CLI バージョン、フィルター、SDK、Loki 互換の読み取り API）については、親 neon スキルの Observability セクションを参照してください。

Neon のドキュメント

Neon のドキュメントは信頼できる情報源であり、Object Storage は急速に進化しているため、必ず公式ドキュメントで確認してください。URL の末尾に .md を追加するか、Accept: text/markdown をリクエストすると、任意のドキュメントページを Markdown として取得できます。ドキュメントのインデックス（https://neon.com/docs/llms.txt）と変更履歴のお知らせから、適切なページを見つけてください。

関連資料

• https://neon.com/docs/get-started/backend-overview.md
• https://neon.com/docs/storage/overview.md
• https://neon.com/docs/storage/get-started.md
• https://neon.com/docs/storage/buckets.md
• https://neon.com/docs/storage/objects.md
• https://neon.com/docs/storage/authentication.md
• https://neon.com/docs/storage/s3-compatibility.md
• https://neon.com/docs/storage/troubleshooting.md
• https://files-sdk.dev — Files SDK のドキュメント（neon アダプター）