neon-postgres

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

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

neon skills -s neon -y

Lakebase Postgres

Lakebase Postgres は Neon の中核となるデータベースです。lakebase アーキテクチャ（クラウドオブジェクトストレージ上に直接構築された OLTP）で動作し、ストレージとコンピューティングを分離することで、自動スケーリング、ブランチ作成、即時復元、ゼロへのスケーリングを実現します。Postgres と完全に互換性があり、Postgres をサポートするあらゆる言語、フレームワーク、ORM で利用できます。

Neon 経由でも Databricks 経由でも、同じデータベースです。このスキルでは Neon のアクセス方法を説明します。

ログイン、ユーザー、セッション、@neondatabase/auth については neon-auth を参照してください。

セットアップの流れ

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

DATABASE_URL がすでに指定されている（プロンプト、環境、またはリポジトリ内）か、.neon ファイルがプロジェクトを参照している場合は、それを使用してください。スキーマ作業のために組織を一覧表示したり、別のプロジェクトを作成したりしないでください。

それ以外の場合は、CLI（デフォルト）または MCP サーバーを使用して組織とプロジェクトを一覧表示します。既存のプロジェクトを選択するか、新しいプロジェクトを作成するかをユーザーに選んでもらいます。

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

DATABASE_URL がすでに指定されている場合は、それを使用してください。CLI や MCP を通じて別の接続文字列を取得しないでください。

それ以外の場合は、CLI（デフォルト）、neon env pull、または MCP サーバーを使用して接続文字列を取得します。.env に DATABASE_URL として保存してください。既存の値を上書きしないよう、変更する前にファイルを読み込んでください。

プール接続と直接接続の使い分け

用途	接続タイプ
Web アプリケーション、サーバーレス関数	プール接続（-pooler）
スキーマのマイグレーション	直接接続
pg_dump / pg_restore	直接接続
論理レプリケーション	直接接続
一時テーブルを使う長時間実行の分析処理	直接接続
SET またはセッション状態を必要とする管理タスク	直接接続
LISTEN / NOTIFY	直接接続

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

既存の ORM とドライバーをそのまま使用してください。既定の選択肢が決まっていない新規の TypeScript スキーマ作業には、Drizzle が候補になります：https://neon.com/docs/guides/drizzle.md。実行環境でコードがどのように扱われるかに基づいて適切なドライバーを選ぶには、接続方法のガイドを参照してください：https://neon.com/docs/connect/choose-connection.md。

ドライバーに関する注意事項：

• Vercel では、Vercel Fluid compute と import { attachDatabasePool } from "@vercel/functions"; を使用して node-postgres（npm install pg）を使ってください。
• Cloudflare では、Cloudflare Hyperdrive とともに node-postgres を使用してください。
• Neon Functions では、関数が長時間実行され、リクエスト間でプールを再利用するため、node-postgres を使用してください。
• サーバーレス環境やエッジ環境（たとえば Netlify を使用する場合）では、@neondatabase/serverless ドライバーを使用してください。一回限りのクエリには HTTP トランスポートを、トランザクションのサポートには WebSocket を使用します。リンク：https://neon.com/docs/serverless/serverless-driver.md

4. スキーマをセットアップする

スキーマとマイグレーションはコードとして管理してください。場当たり的なスキーママイグレーションをデータベースに対して実行するのは避けてください。管理が難しくなるためです。

ORM を使用している場合は、その ORM のベストプラクティスに従ってスキーマとマイグレーションを管理してください。たとえば Drizzle を使用する場合、別途指示がない限り、スキーマとマイグレーションの管理には Drizzle のみを使用してください。

ブランチ

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

主なポイント：

• ブランチは瞬時に作成される、コピーオンライト方式のクローンです（データ全体はコピーされません）。
• 各ブランチには独自のコンピュートエンドポイントがあります。
• neon CLI または MCP サーバーを使用して、ブランチを作成、確認、比較できます。

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

詳細なブランチ作成ワークフロー（通常のブランチとスキーマのみのブランチ、親ブランチからのリセット、CLI と MCP の選択）については、neon-postgres-branches スキルを使用してください。インストールされていない場合は、https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md から取得するか、次のコマンドでインストールしてください。

neon skills -s neon-postgres-branches -y

移行

本番環境に適用する前に、本番環境のブランチで本番環境に近いデータを使って移行をテストしてください。

移行を実行する際は、プールされた接続文字列ではなく、**直接接続の（非プール）**接続文字列を使用してください。neon connection-string はデフォルトで直接接続文字列を返します。ホスト名に -pooler というサフィックスが含まれていないことを確認してください。

トラブルシューティングと Neon 固有のパフォーマンス

カタログクエリを手動で作成する前に、Neon が事前定義している読み取り専用の診断機能を使用してください。Neon CLI の neon inspect db サブコマンドと Neon MCP サーバーの inspect_database ツールは、同じチェックを実行します。

このセクションでは、Neon 固有の診断ツール、コンピュートのキャッシュ動作、プラットフォームのシグナルについて説明します。クエリの書き換え、インデックスの選択、スキーマの変更、プランノードの解釈など、一般的な Postgres の作業が必要と判断した場合は、postgres-best-practices スキルを読み込み、診断で得られた根拠をそのワークフローに引き継いでください。

ドキュメント：

• CLI：https://neon.com/docs/cli/inspect.md
• クエリのパフォーマンス：https://neon.com/docs/postgresql/query-performance.md
• pg_stat_statements：https://neon.com/docs/extensions/pg_stat_statements.md
• Neon Local File Cache：https://neon.com/docs/extensions/neon.md

CLI と MCP の選択

ターミナルにアクセスでき、認証も利用可能な場合は、Neon CLI を優先してください。

neon inspect db <check>

CLI は現在の Neon コンテキストからプロジェクトとブランチを解決します。上書きするには、--project-id、--branch、--database-name を使用してください。ブランチ上のすべてのデータベースを確認するには、--database-name を省略します。Neon API を介して解決するのではなく、Postgres データベースを直接確認する場合に限り、--db-url を使用してください。

Neon MCP を使用する場合は、projectId と 1 つの check を指定して inspect_database を呼び出してください。必要な場合に限り、branchId、databaseName、または computeId を渡します。ブランチ上のすべてのデータベースを確認するには、databaseName を省略します。結果に切り詰められたと表示された場合に限り、limit を増やしてください。

診断項目を選ぶ

症状または質問	確認項目
ストレージを消費しているリレーションはどれですか？	table-sizes、index-sizes
未使用のインデックスや、頻繁にスキャンされるテーブルはありますか？	unused-indexes、seq-scans
5 分以上実行されているクエリや、ロックを保持しているクエリはありますか？	long-running-queries、locks
合計時間を最も消費しているクエリはどれですか？	outliers
最も頻繁に実行されるクエリはどれですか？	calls
アクティブなデータはコンピュートキャッシュに収まりますか？	lfc-hit-rate、working-set
autovacuum が遅れている、または領域が無駄になっていますか？	vacuum-stats、bloat
論理レプリケーションは正常ですか？	replication-slots、subscriptions

次の確認項目を混同しないでください。

• long-running-queries は、現在 5 分を超えて実行されているステートメントを報告します。
• outliers は、統計情報がリセットされてからの累積実行時間に基づいて、上位のクエリを順位付けします。平均レイテンシでは順位付けしません。
• calls は、同じ統計履歴における実行回数に基づいて順位付けします。

outliers と calls には pg_stat_statements が必要です。lfc-hit-rate と working-set には neon 拡張機能が必要です。確認項目で拡張機能がないと報告された場合、提案された CREATE EXTENSION ステートメントの実行を依頼する前に確認してください。拡張機能のインストールはデータベースを変更するためです。

安全に結果を解釈する

• unused-indexes は削除を許可するものではなく、候補の一覧として扱ってください。削除する前に、観測期間、制約、ワークロードを確認してください。
• シーケンシャルスキャンは、小さなテーブルやテーブルの大部分を読み取るクエリでは適切な場合があります。インデックスを追加する前に、テーブルサイズ、選択性、クエリプランを確認してください。
• bloat は統計的な推定値です。VACUUM FULL、REINDEX、または類似の対処を行う前に、影響を確認し、ロックやメンテナンスの計画を立ててください。
• コンピュートの再起動時には、スケールゼロの一時停止を含め、キャッシュと Postgres の統計情報がリセットされます。新しい lfc-hit-rate、working-set、vacuum-stats、または pg_stat_statements の結果を解釈する前に、代表的なワークロードを実行してください。
• コンピュート全体を対象とする確認項目（lfc-hit-rate、working-set、replication-slots）は、すべてのデータベースを調べる場合でも 1 回だけ実行されます。
• 1 つのデータベースで失敗すると、全データベースの検査全体が失敗することがあります。その場合は、明示的な databaseName を指定して該当する確認項目を再試行し、問題を切り分けてください。

クエリごとの Neon キャッシュ動作を調べる

標準の EXPLAIN (ANALYZE, BUFFERS) は Postgres の共有バッファーの動作を報告しますが、Neon の Local File Cache（LFC）やページのプリフェッチは表示しません。安全な読み取り専用クエリでは、Neon の FILECACHE および PREFETCH オプションを追加してください。

EXPLAIN (ANALYZE, BUFFERS, PREFETCH, FILECACHE)
SELECT ...;

• File cache: hits は、コンピュートの LFC で見つかったページ数を示します。
• File cache: misses は、LFC で見つからず、データベースストレージから取得されたページ数を示します。
• Prefetch: hits、misses、expired、duplicates は、エグゼキューターが要求する前に Neon がページをどれだけ効果的に取得したかを示します。

FILECACHE と PREFETCH はこのクエリのメトリクスを提供し、neon 拡張機能は不要です。一方、neon inspect db lfc-hit-rate と working-set はコンピュート全体の統計情報を提供し、拡張機能が必要です。

MCP の explain_sql_statement ツールは標準プランを生成できますが、FILECACHE や PREFETCH のオプションは公開しません。MCP 経由でこれらの Neon 固有のメトリクスを収集するには、上記の明示的な読み取り専用 EXPLAIN ステートメントを使って run_sql を実行してください。

ANALYZE はステートメントを実行するため、実行が安全な場合にのみ使用してください。変更を伴う SQL に対して、自律的に実行しないでください。初回実行でキャッシュが読み込まれ、その後の結果が大きく変わることがあるため、コールドキャッシュとウォームキャッシュの実行を慎重に比較してください。

パフォーマンスのワークフロー

1. 症状を再現し、発生した時間帯を記録します。
2. 上記の表から、関連する最小限の inspect チェックを実行します。
3. スキーマやコンピュートを変更する前に、具体的なクエリを特定します。標準的なプランには MCP の explain_sql_statement を、LFC またはプリフェッチの動作が関係する場合は、上記の Neon 固有の EXPLAIN を使用します。
4. ボトルネックがクエリの形状、インデックス、スキーマ、ロック、またはバキュームの動作にある場合は、postgres-best-practices を読み込み、検査結果とクエリプランを引き継ぎます。Neon のコンピュート、キャッシュ、接続、プラットフォームに関する判断は、このスキルの範囲に留めます。
5. 同じチェックとワークロードを再実行し、変更を検証します。

ユーザーがカスタムのしきい値と上限を指定して平均実行時間順にクエリを並べる必要がある場合は、inspect_database ではなく MCP の list_slow_queries を使用します。上記の明示的な EXPLAIN のケースを除き、定義済みのチェックで質問に答えられない場合に限り、読み取り専用の診断 SQL に run_sql を使用します。

自動スケーリング

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

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

ゼロへのスケール

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

主なポイント：

• アイドル状態のコンピュートは、デフォルトでは 5 分後に自動的に一時停止します。タイムアウトは設定可能で、一時停止を無効にできるのは Launch プランと Scale プランのみです。
• 一時停止後の最初のクエリでは、通常、コールドスタートによる遅延が発生します（数百ミリ秒程度）。
• コンピュートが一時停止している間も、ストレージは稼働し続けます。

リンク：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

Lakebase Search

セマンティック検索、全文検索、ハイブリッド検索には Lakebase Search を使用します。

• Neon AI Gateway での埋め込み生成を含むセマンティック検索については、ベクトル検索をお読みください。
• BM25 ランキングを使用した全文検索については、全文検索をお読みください。
• セマンティック検索と語彙検索の結果を組み合わせる方法については、ハイブリッド検索をお読みください。
• 上記のいずれかを Drizzle ORM で管理する方法については、Drizzle による Lakebase Search の管理をお読みください。

リンク：

• Lakebase Search を始める
• lakebase_vector リファレンス
• lakebase_text リファレンス

注意点

プーリング接続と直接接続：マイグレーション、ダンプ、レプリケーションには直接接続の URL を使用する

Neon では、同じデータベースに対して2つの接続文字列が提供されます。1つはプーリング接続（ホスト名に -pooler サフィックスが付くもの）、もう1つは直接接続／非プーリング接続（-pooler サフィックスが付かないもの）です。neon env pull は、それぞれを DATABASE_URL と DATABASE_URL_UNPOOLED として書き込みます。プーリング接続はトランザクションモードで PgBouncer を経由しますが、このモードではセッションレベルの操作はサポートされません。用途に応じて適切な接続を選んでください。

• プーリング接続（DATABASE_URL） — アプリケーションの通常のクエリトラフィック。特に、サーバーレスやリクエストごとに接続するワークロードに適しています。
• 直接接続（DATABASE_URL_UNPOOLED） — スキーママイグレーション（Prisma Migrate、Drizzle Kit、Alembic など）、pg_dump／pg_restore、論理レプリケーション、LISTEN／NOTIFY、および SET やその他のセッション状態に依存する処理に使用します。

プーリング接続経由でマイグレーション、ダンプ、レプリケーションを実行すると失敗することがありますが、プーリングが原因だとわかる形で失敗することはありません。たとえば、Prisma Migrate で prepared statement "s0" already exists が発生する、SET search_path がそのトランザクションを超えて保持されず、次のクエリで relation "mytable" does not exist が報告される、あるいはプーリングされたバックエンドが以前のクライアントから引き継いだ読み取り専用トランザクションにより、書き込み時に断続的に SQLSTATE 25006 が発生するといったケースがあります。一般にマイグレーションツールでは、両方の接続文字列を同時に指定します。たとえば Prisma では url と併せて directUrl を指定するため、アプリケーションのプーリングを無効にするよう DATABASE_URL を切り替えるのではなく、directUrl に直接接続の URL を指定してください。https://neon.com/docs/connect/connection-pooling.md を参照してください。