neon-postgres

すでに Neon のデータベースがあって、それを触るときに効きます。接続文字列・SQL・スキーマ・性能の調査・検索が守備範囲です。

まず親の neon スキルを使う

本文の最初の指示は「まず親の neon スキルを使え」です。全体像と始め方は親の担当で、このスキルはデータベースそのものの深い話を受け持ちます。

扱うこと

• 接続プール経由か直結か、ドライバの選び方
• マイグレーション本番の複製（ブランチ）で試してから当てる
• 性能の調査neon inspect db の読み取り専用の点検
• 運用の機能自動拡縮、使わないときの停止、瞬時の復元、読み取り専用の複製、IP の許可リスト、論理レプリケーション
• 検索ベクトル検索・全文検索（BM25）・両方の組み合わせ

接続の使い分けが中心

Neon は同じデータベースに接続文字列を 2 つくれます。ここを取り違えると、原因の分かりにくい失敗が起きます。

neon env pull は 2 つを別の名前で書き出す

neon env pull は 2 つを DATABASE_URL（プール経由）と DATABASE_URL_UNPOOLED（直結）として書き出す、と本文に書かれています。

新しく作るとき

新しいバックエンド、認証、ファイル、関数、LLM の呼び出しは親の neon スキルへ回せと description に明記されています。ログインやセッションは neon-auth の担当です。

画面に変化をすぐ映す、リアルタイムのデータ

データの変化をそのまま画面に映す問い合わせや、リアルタイムのデータは、同じリポジトリの neon-realtime の担当だと description と本文に書かれています。

問い合わせそのものの書き直しや索引の設計

本文は、原因が「問い合わせの形・索引・スキーマ・ロック・vacuum」だと分かったら postgres-best-practices という別のスキルに調査結果を引き継げと指示しています。

Neon 固有の判断（計算資源・キャッシュ・接続）だけをここに残す分け方です。

Neon 以外の Postgres

点検のコマンドも接続の決まりも Neon 前提です。

解析で見つかった記述

SKILL.md の解析では、シェルコマンドの実行の記述が見つかっています。

同梱ファイルは 4 件で、ベクトル検索・全文検索・その組み合わせの手引きと、それらを Drizzle ORM で扱う手引きです。ベクトル検索の手引きには、埋め込みを Neon の AI Gateway で作る手順も入っています。

プール経由でマイグレーションを流すと、原因の見えない形で失敗する

本文が挙げている例です。

• Prisma Migrate が prepared statement "s0" already exists を出す
• SET search_path が次の問い合わせまで残らず、relation does not exist になる
• 書き込みがときどき「読み取り専用のトランザクション」（SQLSTATE 25006）で弾かれる

どれもエラーの文面に「プール」が出てきません。

.env を書き換える

接続文字列が無いとき、取得して .env に DATABASE_URL として保存します。「先にファイルを読んで、既存の値を上書きするな」と指示されていますが、書き換え自体は起きます。

すでに接続文字列を渡している場合は、それを使って別のものを取りに行かない決まりです。

点検の結果を、そのまま削除の根拠にしない決まり

使われていない索引の一覧は「消してよい許可ではなく候補」、bloat は統計上の推定、と本文が念を押しています。

拡張機能を入れる CREATE EXTENSION を勧められた場合も、データベースを変えるので実行前に確認を取れと書かれています。

EXPLAIN (ANALYZE ...) は文を実際に実行するので、書き換えを伴う SQL には自分の判断で流すな、とも書かれています。

使わないときに止まる設定の影響がある

何もしない状態が既定で 5 分続くと計算資源が止まり、止まったあとの最初の問い合わせは数百ミリ秒ほど遅くなる、と書かれています。待つ時間は変えられますが、止まる動き自体を切れるのは Launch と Scale のプランだけです。

さらに、止まるとキャッシュと統計が消えるので、直後に取った性能の数字は実態より悪く出ます。

親のスキルを URL から取りに行く記述がある

親の neon が入っていないとき、neon.com から SKILL.md を取得するか neon skills で入れるよう指示されています。

親より子のほうが多く入っている

インストール数は約 14 万件です。同じリポジトリで収録しているのは親の neon とこの 2 件で、約 9.7 万件と約 14 万件（2026-09-07 の上流集計）。親より子のほうが多く入っています。

親の neon スキルも入れる必要がありますか

本文は入れる前提で書かれています。最初の行が「まず親の neon スキルを使え」です。始め方や全体の作法は親にあり、このスキルはデータベースの深い話だけを扱います。入っていなければ、取得するか neon skills -s neon -y で入れるよう指示されます。

Prisma で `prepared statement already exists` が出ます

プール経由の接続でマイグレーションを流している可能性が高いです。Neon のプールは PgBouncer のトランザクション単位の動きなので、セッションに状態を持つ操作が壊れます。マイグレーションには直結の接続文字列を使い、Prisma なら directUrl にそれを渡してください。

遅い問い合わせをどう探しますか

neon inspect db の点検から入るよう書かれています。累計の実行時間が長い順は outliers、回数が多い順は calls、いま 5 分以上走っているものは long-running-queries です。outliers は平均の遅さの順ではないので、取り違えに注意してください。

本番のデータで移行を試せますか

Neon のブランチを使います。本番の複製を瞬時に作れる（データを丸ごと複写しない）ので、そこでマイグレーションを試してから本番に当てる、が本文の手順です。ブランチの作り方の詳細は neon-postgres-branches という別のスキルに分かれています。