claimable-postgres

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

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

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

クレーム可能な Postgres

ローカル開発、デモ、プロトタイピング、テスト環境向けの即時利用可能な Postgres データベースです。アカウントは不要です。Neon アカウントにクレームしない場合、データベースは 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）：1 つのコマンドでプロビジョニングし、.env に書き込みます。Node.js を利用でき、ユーザーが簡単なセットアップを希望する場合に便利です。
• SDK（neon-new/sdk）：Node.js でのスクリプト作成や、プログラムによるプロビジョニングに使用します。
• Vite プラグイン（vite-plugin-neon-new）：DATABASE_URL が設定されていない場合、vite dev の実行時に自動でプロビジョニングします。ユーザーが Vite プロジェクトを使用している場合に利用します。
• ブラウザー：ユーザーが CLI や API を実行できない場合は、https://neon.new に案内します。

自動プロビジョニング

タスクを完了するためにエージェントがデータベースを必要とする場合（例：「実際のデータベースを使った ToDo アプリを作って」）、かつユーザーが接続文字列を提供していない場合は、API を使ってプロビジョニングし、ユーザーに伝えてください。引き継いで利用できるよう、クレーム URL も含めてください。

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

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. 報告する： 出力チェックリストの全項目を伝えます。
7. 任意： 簡単な接続テスト（例：SELECT 1）を提案します。

CLI を使う場合

1. .env を確認する： 対象の .env に既存の DATABASE_URL（または選択したキー）があるか確認します。存在する場合は実行しません。削除、--env、または --key の使用を提案し、確認を得てください（実行前の確認を参照）。
2. 意図を確認する： 依頼が曖昧な場合は、一時的で、サインアップ不要のデータベースをユーザーが希望しているか確認します。簡易または一時的なデータベースを明示的に求めている場合は、この確認を省略します。
3. オプションを集める： コンテキストから必要と判断できる場合（例：ユーザーが独自の環境変数ファイル、シード SQL、論理レプリケーションについて言及している場合）を除き、デフォルトを使用します。
4. 実行する： 確認済みのオプションに @latest --yes を付けて実行します。キャッシュされた古いバージョンの使用を避けるため、必ず @latest を使用してください。エージェントの処理が止まる対話型プロンプトを省略するため、--yes を指定します。

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

5. 確認する： 接続文字列が指定したファイルに書き込まれたことを確認します。
6. 報告する： 出力チェックリストの全項目を伝えます。
7. 任意： 簡単な接続テスト（例：SELECT 1）を提案します。

出力チェックリスト

必ず以下を報告してください：

• 接続文字列を書き込んだ場所（例：.env）
• 使用した変数キー（DATABASE_URL または独自のキー）
• クレーム URL（.env または API レスポンスから取得）
• クレームされていないデータベースは一時的（72 時間）であること：データベースはすぐに利用でき、72 時間以内にクレームすれば永続的に保持できます

安全性と UX に関する注意事項

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

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	はい	データベースのプロビジョニングを行った人を識別する追跡タグです。このスキルを通じてプロビジョニングする場合は "agent-skills" を使用してください。
enable_logical_replication	いいえ	論理レプリケーションを有効にします（デフォルト：false。有効にすると無効化できません）

API が返す connection_string は、プール接続 URL です。直接接続（プールなし）の接続（例：Prisma のマイグレーション）には、ホスト名から -pooler を削除してください。CLI はプール接続と直接接続の両方の 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	メッセージ
ref がない、または空	400	Missing referrer
データベース ID が無効	400	Database not found
JSON 本文が無効	500	Failed to create the database.

CLI

npx neon-new@latest --yes

データベースをプロビジョニングし、接続文字列を .env に一度に書き込みます。エージェントの処理を止めてしまう対話型プロンプトを省略するため、必ず @latest と --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 ファイルのパス	なし
--logical-replication	-L	論理レプリケーションを有効にします	false
--ref	-r	リファラー ID（このスキル経由でプロビジョニングする場合は agent-skills を使用します）	なし

代替パッケージマネージャー：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 プロジェクトでは、DATABASE_URL がない場合、vite-plugin-neon-new が vite dev の実行時にデータベースを自動でプロビジョニングします。npm install -D vite-plugin-neon-new でインストールします。設定については、Claimable Postgres のドキュメントを参照してください。

クレーム

クレームは任意です。データベースはクレームしなくてもすぐに使用できます。任意でクレームするには、ユーザーがブラウザーでクレーム URL を開き、Neon アカウントにサインインするか新規作成して、データベースをクレームします。

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

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

Neon Infrastructure as Code（neon.ts）

クレーム可能なデータベースは使い捨てを前提としており、上記のとおり neon.new 経由でプロビジョニングされるため、neon.ts では管理しません。ユーザーがデータベースを Neon アカウントにクレームすると、通常の Neon プロジェクトになります。その時点以降の管理には、Neon の Infrastructure as Code ファイルである neon.ts を使用します（詳細は neon スキルのリファレンスを参照してください）。ブランチに必要なサービスを宣言し、ブランチごとのコンピューティングをプログラムで設定し、型安全な環境変数を取得できます。

npm i @neon/config

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

export default defineConfig({
  auth: true, // Neon Auth, once you outgrow a bare connection string
  dataApi: true, // Data API
  branch: (branch) => (branch.exists ? {} : { ttl: "7d" }), // ephemeral non-default branches
});

neon config apply   # provision the declared services (neon deploy is an alias)

ブランチ、複数のサービス、またはバージョン管理で追跡する永続的なインフラストラクチャが必要なプロジェクトでは、使い捨てのクレーム可能なデータベースを再プロビジョニングするのではなく、まずクレームしてから neon.ts を導入することを推奨してください。

デフォルトと制限

パラメーター	値
プロバイダー	AWS
リージョン	us-east-2
Postgres	17

クレーム可能なデータベースではリージョンを変更できません。未クレームのデータベースには、より厳しいクォータが適用されます。クレームすると、制限は無料プランのデフォルトにリセットされます。

	未クレーム	クレーム済み（無料プラン）
ストレージ	100 MB	512 MB
転送量	1 GB	~5 GB
ブランチ	いいえ	はい
有効期限	72 時間	なし