neon-postgres

Neon Serverless Postgres

使用するタイミング

Neon Serverless Postgres を使用する際のガイドやベストプラクティスが必要な場合に、このスキルを使用します。セットアップ、接続方法、ブランチング、自動スケーリング、スケールトゥゼロ、読み取りレプリカ、コネクションプーリング、Neon Auth、Neon CLI、MCP サーバー、REST API、TypeScript SDK、Python SDK を扱います。Neon データベースやツールに関する具体的な質問に使用してください。

セットアップ、接続、ブランチング、高度な機能など、Neon に関するあらゆる作業をユーザーに案内します。動作する Neon 接続、完了した機能設定、または公式 Neon ドキュメントに基づく具体的な回答を提供します。

Neon は、コンピューティングとストレージを分離することで、自動スケーリング、ブランチング、即時復元、スケールトゥゼロを提供するサーバーレス Postgres プラットフォームです。Postgres と完全な互換性があり、Postgres をサポートするあらゆる言語、フレームワーク、ORM で使用できます。

Neon ドキュメント

Neon に関するすべての情報の信頼できる情報源は、Neon ドキュメントです。回答する前に、必ず公式ドキュメントで情報を確認してください。Neon の機能や API は進化するため、学習データに頼るのではなく、最新のドキュメントを取得してください。

Markdown 形式でのドキュメント取得

Neon のドキュメントページは、次の 2 つの方法で Markdown として取得できます。

1. URL に .md を追加する（最も簡単です）：https://neon.com/docs/introduction/branching.md
2. 標準 URL に text/markdown を指定する：curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching

どちらも同じ Markdown コンテンツを返します。使用するツールがサポートする方法を選んでください。

適切なページを見つける

ドキュメントのインデックスには、利用可能なすべてのページと、その URL および簡単な説明が記載されています。

https://neon.com/docs/llms.txt

よく使われるドキュメント URL は、以下のトピックリンクにまとめられています。必要なページが記載されていない場合は、ドキュメントのインデックスを検索してください：https://neon.com/docs/llms.txt。URL を推測しないでください。

Neon とは

実装方法を案内する前に、アーキテクチャの説明や用語（組織、プロジェクト、ブランチ、エンドポイント）の確認に使用してください。

リンク：https://neon.com/docs/introduction/architecture-overview.md

はじめに

Neon の初回セットアップをユーザーに案内する際に、このセクションを使用します。

現状の確認

セットアップを始める前に、ユーザーのコードベースと環境を確認してください。

• 既存のデータベース接続コード
• 既存の Neon MCP サーバーまたは Neon CLI の設定
• .env ファイルと DATABASE_URL 環境変数の有無
• 既存の ORM（Prisma、Drizzle、TypeORM）の設定

Neon CLI または MCP サーバーを使用した自動セットアップ

既存の接続済み Neon プロジェクトを調べるか、Neon CLI または MCP サーバーを使用して新しいプロジェクトを作成することを提案してください。どちらもセットアップされていない場合は、まずインストール方法、API キーの作成方法、ホスト設定の変更について説明し、その範囲の作業について承認を得てください。--agent フラグを使用する前に、固定された CLI リリースと現在のヘルプを確認してください。認証は自動的に処理されます。ユーザーがログインしていない場合は、ブラウザーが開いて OAuth が開始され、完了するまで待ってから続行します。

npx -y neon@latest init --agent <agent-name>

対応している --agent の値：cursor、copilot、claude、claude-desktop、codex、opencode、cline、gemini-cli、goose、zed。

これにより、Neon 拡張機能（Cursor／VS Code 用）または MCP サーバー（その他のエージェント用）がインストールされ、API キーが作成され、プロジェクトに neon-postgres エージェントスキルが追加されます。

init が適切でない場合は、個別の手順を非対話形式で実行できます。

• 拡張機能： cursor --install-extension databricks.neon-local-connect
• MCP サーバー： npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -y -a <agent-name>
• エージェントスキル： npx skills add neondatabase/agent-skills --skill neon-postgres --agent <agent-name> -y

CLI のインストール方法について詳しくは、https://neon.com/docs/reference/cli-install.md を参照してください。

セットアップの流れ

1. 組織とプロジェクトを選択する

MCP サーバーまたは CLI を使って、組織とプロジェクトを一覧表示します。既存のプロジェクトを選択するか、新しいプロジェクトを作成するかをユーザーに選んでもらいます。

2. 接続文字列を取得する

MCP サーバーまたは CLI を使って接続文字列を取得します。既存のキーを維持したまま、プライベートで Git の追跡対象外になっている .env に DATABASE_URL として保存します。キー名は確認しても、認証情報の値をチャットやログに出力しないでください。デプロイにはシークレットマネージャーを使用してください。

3. 接続方法とドライバーを選択する

デプロイ先のプラットフォームに基づいて適切なドライバーを選ぶには、接続方法のガイドを参照してください：https://neon.com/docs/connect/choose-connection.md

4. Neon Auth によるユーザー認証（必要な場合）

CLI ツール、スクリプト、またはユーザーアカウントのないアプリでは、この手順をスキップします。アプリで認証が必要な場合は、MCP サーバーの provision_neon_auth ツールを使用してから、認証の概要（https://neon.com/docs/auth/overview.md）を参照してセットアップしてください。認証とデータベースクエリについては、JavaScript SDK のリファレンス（https://neon.com/docs/reference/javascript-sdk.md）を参照してください。

5. ORM のセットアップ（任意）

既存の ORM（Prisma、Drizzle、TypeORM）があるか確認します。ない場合は、ORM を導入するかどうかをユーザーに尋ねてください。Drizzle との連携については、https://neon.com/docs/guides/drizzle.md を参照してください。

6. スキーマのセットアップ

• 既存のマイグレーションファイルまたは ORM スキーマを確認します
• ない場合は、サンプルスキーマの作成を提案するか、ユーザーと一緒に設計します

セットアップの再開

セットアップを再開する場合は、すでに設定されている項目（MCP 接続、DATABASE_URL を含む .env、依存関係、スキーマ）を確認し、次の未完了の手順から続けます。

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

認証情報には環境変数を使用し、接続文字列を決してコミットしないこと、最小権限のデータベースロールを使用することをユーザーに伝えてください。

接続方法とドライバー

実行環境の制約（TCP、HTTP、WebSocket、エッジ、サーバーレス、長時間稼働）に応じて適切なトランスポートとドライバーを選ぶ際に使用します。

リンク：https://neon.com/docs/connect/choose-connection.md

推奨：Drizzle と実行環境に適したドライバー

スキーマ管理やマイグレーションを簡単にするため、Neon と Drizzle などの ORM を組み合わせることもできます。実行環境でのコードの扱いに応じてドライバーを選択してください。

• 長時間稼働または共有実行環境 → node-postgres（pg）。 Neon Functions や、関数の実行環境がリクエスト間で共有される、または流動的コンピュートで実行されるホスト（例：Fluid コンピュートを使用する Vercel）では、モジュールスコープのプロセスが多数のリクエストにわたって存続します。pg プールをモジュールスコープで一度だけ開き、リクエスト間で再利用してください。
• 完全に分離されたサーバーレス（Lambda 型）→ Neon のサーバーレスドライバー（@neondatabase/serverless）。 ホストがリクエストごとにすべてのインスタンスを破棄すると想定せず、実際のデプロイ環境で再利用と同時実行を確認してください。サーバーレスドライバーは HTTP 経由でクエリを実行し、この用途向けに構築されています。

Neon Functions／Vercel／流動的コンピュート — Drizzle + node-postgres：

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import * as schema from "./schema";

// Created once at module scope; reused by every request the instance handles.
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
const db = drizzle({ client: pool, schema });

Vercel（Fluid コンピュート）では、インスタンスが一時停止する前に関数の実行環境がアイドル状態の接続を解放できるよう、@vercel/functions の attachDatabasePool を使ってプールもアタッチしてください。

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { attachDatabasePool } from "@vercel/functions";
import * as schema from "./schema";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
attachDatabasePool(pool); // let the Vercel runtime manage the pooled connections
const db = drizzle({ client: pool, schema });

Netlify およびその他の完全に分離されたサーバーレス環境 — Drizzle + Neon サーバーレスドライバー：

import { drizzle } from "drizzle-orm/neon-http";
import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL!);
const db = drizzle({ client: sql });

サーバーレスドライバー

HTTP クエリ、WebSocket トランザクション、実行環境固有の最適化など、@neondatabase/serverless のパターンを使用する場合に参照してください。

リンク：https://neon.com/docs/serverless/serverless-driver.md

Neon JS SDK

PostgREST スタイルのクエリと型付きクライアントのセットアップを用いた、Neon Auth と Data API の統合ワークフローに使用します。

リンク：https://neon.com/docs/reference/javascript-sdk.md

開発者ツール

これは、npx -y neon@latest init --agent <agent-name> によるローカル開発の有効化、VSCode 拡張機能のセットアップ、および Neon MCP サーバーの設定に使用します。

ツール	URL
CLI Init コマンド	https://neon.com/docs/reference/cli-init.md
VSCode 拡張機能	https://neon.com/docs/local/vscode-extension.md
MCP サーバー	https://neon.com/docs/ai/neon-mcp-server.md
Neon CLI	https://neon.com/docs/reference/neon-cli.md

Neon CLI

これは、neon を使用したターミナルファーストのワークフロー、スクリプト、および CI/CD 自動化に使用します。

リンク: https://neon.com/docs/reference/neon-cli.md

Neon Admin API

Neon Admin API は、Neon リソースをプログラムで管理するために使用できます。これは Neon CLI と MCP サーバーの背後で使用されていますが、より複雑な自動化ワークフローや、Neon を他のアプリケーションに組み込む場合に直接使用することもできます。

Neon REST API

これは、直接的な HTTP 自動化、エンドポイントレベルの制御、API キー認証、レート制限の処理、およびオペレーションのポーリングに使用します。

リンク: https://neon.com/docs/reference/api-reference.md

Neon TypeScript SDK

これは、@neondatabase/api-client を介して TypeScript で Neon リソースの型付きプログラマティック制御を実装する場合に使用します。

リンク: https://neon.com/docs/reference/typescript-sdk.md

Neon Python SDK

これは、neon-api パッケージを使用して Python でプログラムによる Neon 管理を実装する場合に使用します。

リンク: https://neon.com/docs/reference/python-sdk.md

Neon Auth

これは、マネージドユーザー認証のセットアップ、UI コンポーネント、認証方式、および Next.js と React アプリにおける Neon Auth 統合の落とし穴に使用します。

リンク: https://neon.com/docs/auth/overview.md

Neon Auth は Neon JS SDK にも組み込まれています。ユースケースによっては、Neon Auth 単体ではなく Neon JS SDK を使用したい場合があります。詳細は https://neon.com/docs/connect/choose-connection.md を参照してください。

Neon Infrastructure as Code (neon.ts)

neon.ts は Neon のブランチ設定および Infrastructure as Code ファイルです。ブランチが持つサービスを宣言し、型安全な環境変数を取得し、ブランチごとのコンピュートをプログラムできます — すべて TypeScript で行えます（完全なリファレンスは neon スキルを参照してください）。Postgres はすべてのブランチに常に存在するため、データベース自体を宣言する必要はありません。ここでコード化するのは Postgres に隣接するサーフェスです — Neon Auth、Data API、およびブランチごとのコンピュート設定（オートスケーリングとスケール・トゥ・ゼロ）です。

@neon/config で追加します:

npm i @neon/config

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

export default defineConfig({
  auth: true, // Neon Auth (adds NEON_AUTH_* env vars)
  dataApi: true, // Data API (adds NEON_DATA_API_URL); requires auth: true (or an external IdP)
  // Postgres exists on every branch; tune its compute per branch:
  branch: (branch) => {
    if (branch.exists) return {}; // leave existing branches untouched
    if (branch.isDefault) return { protected: true }; // prod keeps default compute
    return {
      ttl: "7d", // non-prod branches auto-expire (max 30d)
      postgres: {
        computeSettings: {
          autoscalingLimitMinCu: 0.25, // active compute floor; suspension is configured separately
          autoscalingLimitMaxCu: 1, // keep dev/preview cheap
          suspendTimeout: "5m",
        },
      },
    };
  },
});

CLI から宣言を調整します — terraform plan / apply に相当する Neon の機能です:

neon config status   # print the branch's live config
neon config plan     # dry-run diff of what apply would change
neon config apply    # provision the declared services / settings
neon deploy          # alias for `neon config apply`

neon checkout はブランチを作成する際にポリシーを適用するため、新しいブランチはこれらのコンピュート設定（および Auth / Data API）がすでに適用された状態で起動します。_既存_のブランチをチェックアウトしても調整されることはありません — 変更を適用するには neon deploy を実行してください。

neon.ts は TypeScript であるため、無効な組み合わせは実行可能なメッセージとともにコンパイルエラーになります。Data API はデフォルトで Neon Auth を使用してリクエストを検証するため、auth: true なしの dataApi: true は型エラーになります（修正方法 — auth: true、または jwksUrl を伴う authProvider: 'external' — はメッセージに記載されています）。neon スキルの型安全な設定に関する注記を参照してください。

結果として得られる環境変数を、@neon/env の parseEnv を使用して、ポリシーに対して型付けおよび検証された状態で読み戻します:

import { parseEnv } from "@neon/env";
import config from "./neon";

const env = parseEnv(config);
env.postgres.databaseUrl; // typed; enabling auth / dataApi above surfaces env.auth / env.dataApi

ブランチ

ユーザーが分離された環境、スキーマ移行のテスト、プレビュー環境へのデプロイ、またはブランチのライフサイクル自動化を計画している場合に使用します。

主なポイント：

• ブランチは即時に作成されるコピーオンライトのクローンです（データ全体をコピーしません）。
• ブランチにはコンピュートエンドポイントが関連付けられている場合があります。各ブランチにすでにエンドポイントがあると想定せず、実際のブランチとエンドポイントの状態を確認してください。
• neon CLI または MCP サーバーを使用して、ブランチの作成、確認、比較を行います。

リンク：https://neon.com/docs/introduction/branching.md

ブランチ作成の詳細なワークフロー（通常ブランチとスキーマのみのブランチ、親からのリセット、CLI/MCP の選択）には、利用可能な場合、neon-postgres-branches スキルを使用してください

または、次の URL からブランチスキル全体を取得してください：

https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md

このスキルがインストールされていない場合は、次のコマンドを使用してインストールできます：

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

オートスケーリング

ワークロードに応じてコンピュートを自動的にスケーリングする必要があり、CU のサイズや実行時の動作について案内が必要な場合に使用します。

リンク：https://neon.com/docs/introduction/autoscaling.md

ゼロへのスケーリング

アイドル時のコストを最適化し、コールドスタートのトレードオフを含む一時停止／再開の動作を説明する場合に使用します。

主なポイント：

• アイドル状態のコンピュートは自動的に一時停止します（デフォルトは 5 分で、設定可能です。ただし、launch & scale プランでは無効にできます）
• 一時停止後の最初のクエリでは、通常、コールドスタートによる遅延が発生します（数百 ms 程度）
• コンピュートが一時停止している間も、ストレージはアクティブな状態を維持します。

リンク：https://neon.com/docs/introduction/scale-to-zero.md

即時復元

ユーザーが特定時点への復旧を必要としている場合や、従来のバックアップ復元ワークフローを使わずにデータの状態を復元したい場合に使用します。

主なポイント：

• 即時復元で利用できる履歴期間は、プランの制限によって異なります。
• ユーザーは過去の特定時点からブランチを作成できます。
• Time Travel クエリを、過去の状態を調査するワークフローに利用できます。

リンク：https://neon.com/docs/introduction/branch-restore.md

読み取りレプリカ

ストレージを重複させずに専用の読み取り専用コンピュートが必要な、読み取り負荷の高いワークロードに使用します。

主なポイント：

• レプリカは、同じストレージを共有する読み取り専用のコンピュートエンドポイントです。
• 作成は高速で、スケーリングはプライマリコンピュートから独立しています。
• 代表的なユースケース：分析、レポート作成、読み取り負荷の高い API。

リンク：https://neon.com/docs/introduction/read-replicas.md

コネクションプーリング

サーバーレス環境や高い同時実行性が求められる環境で、安全かつスケーラブルな Postgres 接続管理が必要な場合に使用します。

主なポイント：

• Neon のプーリングには PgBouncer を使用します。
• プール接続を利用するには、エンドポイントのホスト名に -pooler を追加します。
• 同時実行数が急増するサーバーレスランタイムでは、特にプーリングが重要です。

リンク：https://neon.com/docs/connect/connection-pooling.md

IP 許可リスト

信頼できるネットワーク、IP、または CIDR 範囲に基づいてデータベースへのアクセスを制限する必要がある場合に使用します。

リンク：https://neon.com/docs/introduction/ip-allow.md

論理レプリケーション

CDC パイプライン、外部 Postgres との同期、またはレプリケーションを利用したデータ移動を統合する場合に使用します。

主なポイント：

• Neon はネイティブの論理レプリケーションワークフローに対応しています。
• 外部の Postgres システムとの間でレプリケーションを行う場合に役立ちます。

リンク：https://neon.com/docs/guides/logical-replication-guide.md

制限事項

• このスキルは、タスクが上流の製品または API の対象範囲に明確に合致する場合にのみ使用してください。
• 変更を加える前に、コマンド、API の動作、料金、クォータ、認証情報、デプロイへの影響を、最新の公式ドキュメントで確認してください。
• 生成された例を、環境固有のテスト、セキュリティレビュー、または破壊的な操作やコストが発生する操作に対するユーザーの承認の代わりとして扱わないでください。

インテグレーションのインストール、ブランチの作成、または設定の調整を行うコマンドは、ローカルまたはリモートの状態を変更し、コストが発生する場合があります。承認された適用の前に、読み取り専用のステータス確認やプラン確認を行ってください。ブランチのクローンには本番環境の個人データが含まれている場合があるため、プレビューにはスキーマのみ、またはサニタイズ済みのフィクスチャを優先してください。このバンドルには CLI の実装も、関連する neon スキルも含まれていません。使用前に、製品 API、ホストの動作、例を、リンク先の最新ドキュメントで確認する必要があります。ドキュメントを取得できなかった場合、それを確認済みとして報告してはなりません。