Claimable Postgres

ローカル開発、デモ、プロトタイピング、テスト環境向けの即座に利用できる Postgres データベース。アカウント不要です。クレームされない限り、データベースは 72 時間後に期限切れになります。

クイックスタート

curl -s -X POST "https://neon.new/api/v1/database" \
  -H "Content-Type: application/json" \
  -d '{"ref": "agent-skills"}'

JSON レスポンスから connection_string と claim_url をパースします。connection_string をプロジェクトの .env に DATABASE_URL として記述します。

その他の方法 (CLI、SDK、Vite プラグイン) については、下記の どの方法を使う? を参照してください。

どの方法を使う?

• REST API: 構造化された JSON を返します。curl 以上の実行時の依存関係がありません。エージェントが予測可能な出力とエラーハンドリングを必要とする場合に推奨されます。
• CLI (npx neon-new@latest --yes): ワンコマンドでプロビジョニングしてから .env に書き込みます。Node.js が利用可能で、ユーザーがシンプルなセットアップを望む場合に便利です。
• SDK (neon-new/sdk): Node.js でのスクリプトまたはプログラマティックなプロビジョニング。
• Vite プラグイン (vite-plugin-neon-new): DATABASE_URL が不足している場合、vite dev で自動的にプロビジョニングします。ユーザーが Vite プロジェクトを持っている場合に使用します。
• ブラウザ: ユーザーが CLI または API を実行できない場合。https://neon.new に直接誘導します。

REST API

ベース URL: https://neon.new/api/v1

データベースを作成

curl -s -X POST "https://neon.new/api/v1/database" \
  -H "Content-Type: application/json" \
  -d '{"ref": "agent-skills"}'

パラメータ	必須	説明
ref	Yes	データベースをプロビジョニングしたユーザーを識別するトラッキングタグ。このスキルを通じてプロビジョニングする場合は "agent-skills" を使用します。
enable_logical_replication	No	ロジカルレプリケーション を有効化 (デフォルト: false、一度有効にされたら無効化はできません)

API から返される connection_string はプール接続 URL です。直接接続 (プール接続でない) (例えば Prisma マイグレーション) の場合は、ホスト名から -pooler を削除してください。CLI は、プール接続 URL と直接接続 URL の両方を自動的に書き込みます。

レスポンス:

{
  "id": "019beb39-37fb-709d-87ac-7ad6198b89f7",
  "status": "UNCLAIMED",
  "neon_project_id": "gentle-scene-06438508",
  "connection_string": "postgresql://...",
  "claim_url": "https://neon.new/claim/019beb39-...",
  "expires_at": "2026-01-26T14:19:14.580Z",
  "created_at": "2026-01-23T14:19:14.580Z",
  "updated_at": "2026-01-23T14:19:14.580Z"
}

ステータスを確認

curl -s "https://neon.new/api/v1/database/{id}"

同じレスポンス形式を返します。ステータス遷移: UNCLAIMED -> CLAIMING -> CLAIMED。データベースがクレームされた後、connection_string は null を返します。

エラーレスポンス

条件	HTTP	メッセージ
Missing or empty ref	400	Missing referrer
Invalid database ID	400	Database not found
Invalid JSON body	500	Failed to create the database.

CLI

npx neon-new@latest --yes

データベースをプロビジョニングし、ワンステップで接続文字列を .env に書き込みます。常に @latest と --yes を使用してください (--yes はエージェントを停止させるインタラクティブなプロンプトをスキップします)。

実行前のチェック

ターゲット .env に DATABASE_URL (または選択したキー) が既に存在するかどうかを確認します。CLI はキーが見つかった場合、プロビジョニングなしで終了します。

キーが既に存在する場合、ユーザーに 3 つのオプションを提示してください:

1. 既存の行を削除またはコメントアウトしてから再度実行する。
2. --env を使用して別のファイルに書き込む (例: --env .env.local)。
3. --key を使用して別の変数名で書き込む。

進める前にユーザーの確認を取得します。

オプション

オプション	省略形	説明	デフォルト
--yes	-y	プロンプトをスキップし、デフォルト値を使用	false
--env	-e	.env ファイルパス	./.env
--key	-k	接続文字列環境変数キー	DATABASE_URL
--prefix	-p	生成されたパブリック環境変数のプリフィックス	PUBLIC_
--seed	-s	シード SQL ファイルのパス	none
--logical-replication	-L	ロジカルレプリケーションを有効化	false
--ref	-r	リファラー ID (このスキルを通じてプロビジョニングする場合は agent-skills を使用)	none

別のパッケージマネージャ: yarn dlx neon-new@latest、pnpm dlx neon-new@latest、bunx neon-new@latest、deno run -A neon-new@latest。

出力

CLI はターゲット .env に以下を書き込みます:

DATABASE_URL=postgresql://...              # pooled (use for application queries)
DATABASE_URL_DIRECT=postgresql://...       # direct (use for migrations, e.g. Prisma)
PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/...

SDK

スクリプトとプログラマティックなプロビジョニングフロー用です。

import { instantPostgres } from "neon-new";

const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } =
  await instantPostgres({
    referrer: "agent-skills",
    seed: { type: "sql-script", path: "./init.sql" },
  });

databaseUrl (プール接続)、databaseUrlDirect (直接接続、マイグレーション用)、claimUrl、および claimExpiresAt (Date オブジェクト) を返します。referrer パラメータは必須です。

Vite プラグイン

Vite プロジェクトの場合、vite-plugin-neon-new は DATABASE_URL が不足している場合に vite dev でデータベースを自動的にプロビジョニングします。npm install -D vite-plugin-neon-new でインストールしてください。設定については Claimable Postgres ドキュメント を参照してください。

エージェントワークフロー

API パス

1. 意図を確認: リクエストが曖昧な場合、ユーザーが一時的で登録不要なデータベースを望んでいることを確認します。ユーザーが明示的にクイックまたは一時的なデータベースを要求した場合はスキップします。
2. プロビジョニング: {"ref": "agent-skills"} を含めて https://neon.new/api/v1/database に POST します。
3. レスポンスをパース: JSON レスポンスから connection_string、claim_url、および expires_at を抽出します。
4. .env に書き込み: DATABASE_URL=<connection_string> をプロジェクトの .env に書き込みます (またはユーザーの推奨ファイルとキー)。確認なしに既存のキーを上書きしないでください。
5. シード (必要な場合): ユーザーがシード SQL ファイルを持っている場合、新しいデータベースに対して実行します:

   psql "$DATABASE_URL" -f seed.sql
   

6. 報告: ユーザーに接続文字列がどこに書き込まれたか、どのキーが使用されたか、そしてクレーム URL を共有します。データベースは今すぐ動作します。72 時間以内にクレームして永久に保持します、ということを思い出させます。
7. オプション: クイック接続テストを提案します (例: SELECT 1)。

CLI パス

1. .env を確認: ターゲット .env で既存の DATABASE_URL (または選択したキー) を確認します。存在する場合は実行しないでください。削除、--env、または --key オプションを提案して確認を取得します。
2. 意図を確認: リクエストが曖昧な場合、ユーザーが一時的で登録不要なデータベースを望んでいることを確認します。ユーザーが明示的にクイックまたは一時的なデータベースを要求した場合はスキップします。
3. オプションを収集: コンテキストが異なることを示さない限りデフォルトを使用します (例: ユーザーがカスタム env ファイル、シード SQL、またはロジカルレプリケーションについて言及した場合)。
4. 実行: @latest --yes と確認済みのオプションで実行します。古くキャッシュされたバージョンを避けるために常に @latest を使用してください。--yes はエージェントを停止させるインタラクティブなプロンプトをスキップします。

   npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql
   

5. 検証: 接続文字列がターゲットファイルに書き込まれたことを確認します。
6. 報告: ユーザーに接続文字列がどこに書き込まれたか、どのキーが使用されたか、そしてクレーム URL は env ファイルにあることを伝えます。データベースは今すぐ動作します。72 時間以内にクレームして永久に保持します、ということを思い出させます。
7. オプション: クイック接続テストを提案します (例: SELECT 1)。

出力チェックリスト

常に以下を報告してください:

• 接続文字列がどこに書き込まれたか (例: .env)
• どの変数キーが使用されたか (DATABASE_URL またはカスタムキー)
• クレーム URL (.env または API レスポンスから)
• クレームされていないデータベースが一時的 (72 時間) であること

クレーミング

クレーミングはオプションです。データベースはそれなしで即座に動作します。オプションでクレームするには、ユーザーはブラウザでクレーム URL を開き、Neon アカウントにサインインまたは作成してデータベースをクレームします。

• API/SDK: ユーザーに作成レスポンスの claim_url を提供します。
• CLI: npx neon-new@latest claim は .env からクレーム URL を読み込み、自動的にブラウザを開きます。

ユーザーが Vercel リンクされた組織にはクレームできません。別の Neon 組織を選択する必要があります。

デフォルトと制限

パラメータ	値
Provider	AWS
Region	us-east-2
Postgres	17

リージョンはクレーム可能なデータベースについては変更できません。クレームされていないデータベースは、より厳しいクォータを持っています。クレーミングはフリープランのデフォルトにリセットされます。

	Unclaimed	Claimed (Free plan)
Storage	100 MB	512 MB
Transfer	1 GB	~5 GB
Branches	No	Yes
Expiration	72 hours	None

自動プロビジョニング

エージェントがタスクを実行するためにデータベースが必要な場合 (例: "本物のデータベースを使用して todo アプリを構築して") で、ユーザーが接続文字列を提供していない場合、API を通じてワンを提供し、ユーザーに通知します。クレーム URL を含めて、ユーザーがそれを保持できるようにします。

セキュリティと UX に関する注意事項

• 既存の環境変数を上書きしないでください。最初に確認してから、競合を避けるために --env または --key (CLI) を使用するか、書き込みをスキップします (API)。
• 破壊的なシード SQL (DROP、TRUNCATE、一括 DELETE) を実行する前に尋ねます。
• 本番ワークロードについては、一時的なクレーム可能なデータベースの代わりに標準的な Neon プロビジョニングを推奨します。
• ユーザーが長期の永続性を必要とする場合、クレーム URL をすぐに開くよう指示します。
• 認証情報を .env ファイルに書き込んだ後、それが .gitignore でカバーされていることを確認します。そうでない場合、ユーザーに警告します。確認なしに .gitignore を変更しないでください。