Neon の pooler 接続で search_path が空になりハマった話
新規 Neon DB を pooler 経由でつなぐと search_path が空になることがあった。直接接続に寄せた理由。
個人開発のデータベースを Neon に移したとき、接続文字列を pooler 経由にしただけでアプリがテーブルを見つけられなくなりました。原因を調べると、接続時の search_path が期待した値になっていませんでした。
ここで書くのは「Neon の pooler は常に壊れている」という話ではありません。複数の新規データベースで自分が遭遇した条件と、低トラフィックの内部サービスでは直接接続を選ぶことにした経緯です。
テーブルがあるのに見つからない
PostgreSQL では、public のようなスキーマの中にテーブルがあります。クエリで public.users のようにスキーマ名まで書かず users とだけ指定した場合、PostgreSQL は search_path に並んだスキーマを順に探します。パスに対象のスキーマがなければ、テーブルがデータベースに存在していても、名前だけのクエリからは見つかりません。
つまり、接続先のホストとパスワードが正しくても、アプリから「relation does not exist」のようなエラーに見える場合があります。データが消えたと決めつける前に、どのデータベースへ接続しているか、どのスキーマを検索しているかを確認する必要があります。
接続文字列の値は掲載せず、pooler と直接接続の違いを図にしている。
自分の環境で起きたこと
Neon の接続方法には、通常の直接接続と pooler 経由の接続があります。Neon のコンソールが返す接続 URI では、pooler を使う場合にホスト名へ -pooler が付く形式になります。新しく作成したデータベースを pooler 経由でつないだとき、こちらの環境では search_path が空になるケースがありました。
最初に確認したのは、2026年8月11日の Contact Hub の Neon 移行です。新規 DB の pooler 接続で SHOW search_path を実行すると値が空になり、アプリのようにスキーマ名を省略したクエリからテーブルを解決できませんでした。切り分けでは同じ DB の pooler URI と直接接続 URI で状態を比べました。再現確認をするときは、接続方式以外に DB・ロール・ドライバーも揃えて比較します。
最初に考えたのは、データベースの設定として ALTER DATABASE ... SET search_path TO public; を指定することでした。しかし、pooler 経由では接続側の状態が期待どおり変わらず、設定したのにアプリの挙動が変わらないケースがありました。設定値を変えたつもりで先へ進むより、アプリが実際に受け取っている接続状態を確認する必要があります。
| 確認した条件 | 観測した結果 |
|---|---|
| 新規 Contact Hub DB + Neon pooler | SHOW search_path が空。スキーマ名を省いたアプリのクエリでテーブルを解決できない |
pooler 接続のまま DB の search_path を設定 | アプリの接続状態に期待した変更が反映されなかった |
同じ DB の直接接続(pooled=false) | 今回の管理画面では接続方式をこちらへ切り替えて運用 |
この記録は Contact Hub の移行で観測した事例です。Neon の pooler 全般が常に同じ挙動になるという意味ではありません。別の新規 DB でも接続方式を変更するときは、アプリが実際に使う接続とロールで同じ確認をやり直します。
接続を比較するときの確認
移行直後に「テーブルがない」と言われたら、まずアプリと同じ接続文字列で、読み取り専用の確認をします。
SHOW search_path;
SELECT current_database(), current_schema();
SELECT to_regclass('public.確認したいテーブル名');
SHOW search_path は、そのセッションでどのスキーマを探す設定なのかを表示します。current_database() は接続先の DB、current_schema() は現在の検索パスで先頭に使われるスキーマを示します。to_regclass は、指定したテーブルが存在するかをスキーマ名付きで確認できます。
続いて、コンソールの直接接続 URI と pooler URI で同じクエリを比較します。アプリが使うドライバー、接続プール、実行ユーザーも揃えないと、コンソールでは見えるのにアプリでは見つからない差を見落とすことがあります。パスワードや接続 URI の実値をログや記事へ貼らず、結果だけ比較します。
Contact Hub ではこの比較で pooler の search_path が空であることを見つけました。直接接続へ切り替えた後は、同じ管理画面を接続数の少ない内部サービスとして運用しています。接続上限が厳しいサービスやサーバーレス環境では pooler の利点が変わるため、この結果だけで接続方式を決めないでください。
低トラフィックの内部ツールでは直接接続を選んだ
最終的に、個人向けの管理画面や内部 API では Neon の非 pooler(直接接続)を使うルールにしました。接続数が非常に多いサービスではないため、今回の運用では pooler の接続集約より、接続時の挙動を単純にして search_path を確認しやすくする方を優先しました。
これはすべてのアプリに直接接続を推奨するという意味ではありません。接続数の上限やサーバーレス実行環境との相性など、pooler が必要になるケースもあります。実際のトラフィックや接続管理を見ずに、片方を常に正解とすることはできません。今回の選択は、低トラフィックの個人用サービスで再現性を重視した結果です。
接続を変更した後は、ヘルスチェックだけで終わらせず、代表テーブルが参照できるか、既存データの件数が想定どおりかを確認します。古い接続先はすぐ削除せず、切り戻せる期間を設けます。接続文字列の差し替えは短い作業に見えますが、本番 DB では復旧経路も一緒に考えるべきです。
この記事から持ち帰れること
- テーブルが存在するかと、アプリがテーブル名を解決できるかは別の問題
search_path、現在の DB、スキーマ付きのテーブル名を確認する- Neon の直接接続 URI と pooler URI で、アプリと同じ条件のクエリを比較する
- 運用規模と接続数に合わせて接続方式を選び、変更後は読み取り確認を行う
この問題は接続ホスト名や認証情報を記事に載せず、現象と確認方法だけを共有しています。データベース運用も含めて VPS にサービスを載せる考え方は個人開発を1台の VPS に載せて回す話、Angla での接続先や AI プロキシの境界はAngla の公開までも参照してください。
PostgreSQL の search_path はスキーマ名を省略したオブジェクト参照の検索先を決めます。詳しくはPostgreSQL のスキーマと検索パスを参照してください。Neon の接続 URI で pooler を指定する方法はNeon API の接続 URI リファレンスに説明があります。
直接接続へ戻すときの順序
本番接続を切り替える場合は、接続文字列を書き換えてすぐ古い設定を消すのではなく、段階を分けます。まず直接接続 URI を安全な環境変数へ設定し、アプリを再起動した後にヘルスチェックと代表クエリを実行します。次に画面の主要な読み書きが期待どおり動くか、既存データの件数が大きく変わっていないかを確認します。
問題が出た場合に元へ戻せるよう、以前の接続設定は切り替えが安定するまで安全な場所に保管します。記事やチャット、ログへ接続 URI を貼って比較するのではなく、ホストの種類と SQL の結果だけを見ます。接続文字列はパスワードやユーザー名を含むため、診断の過程で共有しないことも作業手順の一部です。
pooler の必要性は、接続数が増えたときに改めて検討できます。その際も、現在のアプリが依存するセッション状態や、接続プールのモードで維持できる設定を試してから切り替えます。今回の運用では直接接続が単純でしたが、将来の負荷と実行環境が変われば選択も見直します。接続方式は一度決めたら永久に固定するものではなく、計測した条件に合わせて選ぶものです。
search_path 以外の原因も切り分ける
同じ「テーブルがない」ように見えるエラーでも、接続しているデータベースが違う、マイグレーションが適用されていない、接続ロールに権限がない、テーブル名の大文字小文字が異なる、といった別原因があります。search_path だけを見て直接接続へ変え、たまたま別の設定差まで変わると、何が直ったのか分からなくなります。
そのため、まず current_database() と current_user、スキーマを明記したテーブル参照を確認します。対象テーブルが public に存在するのに、名前を省略したクエリだけ失敗するなら、検索パスを調べる根拠が強くなります。どの確認で原因を特定したのかを分けて記録すれば、次に同じ障害が起きたときも接続先・権限・スキーマの順に調べられます。