Supabase Vercelデプロイ連携｜環境変数の自動同期とプレビュー環境のDB分離

Supabase を Vercel へつなぐ作業で手が止まるのは、コードではなく配線の設計です。接続文字列をどの環境へ入れるか、プレビュー環境から本番データベースを触らせるのか、サーバーレス関数から何本の接続を張るのか。この3つを決めないまま Marketplace の統合を入れると、後から請求先も権限も動かせなくなります。この記事では 2026年9月時点の公式ドキュメントを前提に、統合の入口の選び方、同期される環境変数の扱い、プレビュー環境の分離、接続プーラーのモード選択、本番昇格の順序を実装順に並べ、手元で走らせて確かめられるコマンドと設定ファイルを各工程に置きます。

まとめ：Supabase Vercelデプロイ連携で先に決める4点

この連携の骨格は「どこで作ったプロジェクトか」で決まります。Vercel Marketplace 経由で作った Supabase プロジェクトは、請求も権限も Vercel 側に紐づき、後から Supabase 単体へ切り離す操作が用意されていません。受託開発でクライアント名義の契約が必要な案件では、この一点が採否を分けます。

着手前に決める点は4つあります。第一に、Marketplace 経由で新規に作るのか、既に動いている Supabase プロジェクトへ環境変数だけを流し込むのか。第二に、プレビュー環境ごとにデータベースを分けるのか、開発用の1つを共有するのか。第三に、Vercel の関数から 6543 のトランザクションモードで通すと決め切り、直結の 5432 はマイグレーションとダンプに限定すること。第四が本番昇格の順序で、スキーマ変更とアプリのデプロイのどちらを先に出すかを、ロールバックできない側から逆算して決めます。

この4点は、いずれも公式ドキュメントに書かれた仕様から機械的に導けます。判断の根拠になる箇所には、Supabase の Vercel Marketplace ドキュメントやVercel の環境変数ドキュメントへのリンクをその場に置いたので、社内の設計レビューではリンク先の原文と突き合わせてください。アプリ側のクライアント生成やセッション更新の実装はSupabase Next.js連携の実装記事で扱っているため、ここでは配布と接続の層に絞ります。

連携の入口は2通り｜Marketplace経由と既存プロジェクト接続の分かれ道

最初の分岐は、Supabase プロジェクトの所有権をどちらのプラットフォームへ置くかです。Vercelの仕組みを整理した記事で扱うホスティング側から作るか、データベース側から作るかで、その後の運用が変わります。

Marketplace経由で作ると請求と権限がVercel側へ寄る

Vercel Marketplace から作成した Supabase の組織とプロジェクトは、Supabase 内で直接作ったものと同じように動きます。違いは周辺の仕組みです。公式ドキュメントは、課金が Vercel アカウント経由で処理され、使用量が Vercel へ送られて Vercel の請求書に載ると明記しています。単価そのものは Supabase で直接契約した場合と同一で、Supabase の料金ページにある Pro プランの月額25ドルという金額は変わりません。ただし請求サイクルは Vercel と別で、統合を入れた日が起点になります。プラン変更を行った場合、その日を起点に請求サイクルが引き直される点も原文に注記があります。

権限も連動します。Supabase の組織と Vercel のチームが1対1で対応し、Vercel 側の member は Supabase の developer、owner は owner という対応で役割が同期されます。データベースを作成した本人が Supabase 組織の owner になり、以降は Vercel ダッシュボードで役割を変えれば Supabase 側へ反映される作りです。注意すべきは招待の扱いで、Vercel を使っていないメンバーを Supabase 組織へ招くことはできても、その権限は Vercel と同期されません。ホスティング側の料金体系そのものはVercel料金の解説記事に整理があります。

Public Alphaの制約から見た採用条件と見送り場面の判断

採否を分ける情報は Limitations 節に集まっています。公式ドキュメントが挙げる制約は4つです。プロジェクトは Vercel ダッシュボードからしか作れないこと。組織は手動で削除できず、Marketplace 統合をアンインストールしたときにだけ消えること。Supabase ダッシュボード側から owner を追加できないこと。そして請求と支払いを Supabase 側で管理できないこと。加えてカスタムドメインが非対応で、環境変数には常に基本の SUPABASE_URL が入ります。

さらに、この統合は執筆時点で Public Alpha と表示されています。個人開発や社内の検証環境なら、請求が1本にまとまる利点が勝ちます。一方で、納品後にクライアント名義へ契約を移す前提の受託案件、あるいはデータベースのドメインを自社ドメイン配下へ置く要件がある案件では、Marketplace 経由を選ばないでください。この場合は Supabase 側でプロジェクトを作り、接続情報を Vercel の環境変数へ手で入れる構成にします。手で入れる場合でも、値の管理方法はdotenvで環境変数を管理する記事の考え方をそのまま持ち込めます。

自動同期される13個の環境変数と、そのまま使ってよい値の線引き

Marketplace 経由で作ったプロジェクトを Vercel プロジェクトへ接続すると、環境変数が自動で同期されます。同期される変数名は公式ドキュメントに列挙があり、全部で13個です。

POSTGRES_系とSUPABASE_系の役割分担と選択基準

入ってくる変数は、用途で2つの系統に割れます。

• Postgres へつなぐ7個：POSTGRES_URL、POSTGRES_PRISMA_URL、POSTGRES_URL_NON_POOLING、POSTGRES_USER、POSTGRES_HOST、POSTGRES_PASSWORD、POSTGRES_DATABASE
• Supabase の API を叩く6個：SUPABASE_URL、SUPABASE_SECRET_KEY、SUPABASE_PUBLISHABLE_KEY、SUPABASE_JWT_SECRET、NEXT_PUBLIC_SUPABASE_URL、NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

迷いやすいのは、Postgres 側に3種類の接続文字列が並ぶ点です。

Prismaのバージョン解説記事で触れているとおり、マイグレーションと実行時で接続先を変える設計が前提になっているため、この3本を取り違えると動く場面と落ちる場面がまだらに出ます。Supabase 側もPrisma 向けの接続ガイドで、実行時とスキーマ適用時に別の URL を指す構成を案内しています。

SUPABASE_SECRET_KEYをクライアントへ出さない配線

NEXT_PUBLIC_ が付いた2つだけがブラウザへ配られる値です。付いていない SUPABASE_SECRET_KEY と SUPABASE_JWT_SECRET、そして POSTGRES_ 系はサーバー側に閉じます。secret key は行レベルセキュリティのポリシーを越えて読み書きできるため、これがバンドルへ混ざると権限設計が丸ごと無効になります。鍵の種類ごとの性質はSupabase の API キーのドキュメントに整理があり、ポリシーの書き方そのものはSupabase RLSの設定手順の記事を参照してください。

実務では、ビルド時に取り込まれる変数の一覧を1度だけ目視で確かめる工程を入れてください。フレームワークの規約でクライアントへ露出する接頭辞は決まっており、そこへ機密値を入れた時点で検知は難しくなります。Vercel の環境変数ドキュメントが示す、1デプロイあたり合計 64KB まで、Edge ランタイムでは1変数 5KB という上限も併せて頭に入れておくと、証明書などを入れる場面で迷いません。

Vercel CLIで同期後の環境変数を手元へ引き出して中身を確かめる

目視の工程は、CLI へ落としてしまえば数十秒で終わります。Vercel CLI からプロジェクトをひも付け、環境ごとの変数一覧と実際の値を手元へ引き出す流れは次のとおりです。

# Vercel CLI を入れて対象プロジェクトへひも付ける
npm i -g vercel
vercel link

# Preview 環境に入っている変数名の一覧を見る
vercel env ls preview

# 値そのものをローカルへ引き出す（.env.local へ書き出される）
vercel env pull .env.local --environment=preview

# 同期された13個が揃っているかを数える
grep -c -E "SUPABASE_|POSTGRES_" .env.local

ここで NEXT_PUBLIC_ の付いた行と付かない行を並べて見ると、どの値がブラウザへ出るのかが一目で分かります。引き出したファイルはリポジトリへ入れず、確認後は削除するところまでを手順書へ書いてください。CI から同じ確認を回すなら、GitHub Actionsの環境変数の使い分けを整理した記事の考え方で、どの層が値を持つかを1箇所へ寄せておくと二重管理が消えます。

環境変数の値を差し替えたら再デプロイが要る仕様と反映確認手順

環境変数の変更は、既に出ているデプロイへ反映されません。Vercel のドキュメントは「過去のデプロイには適用されず、新しいデプロイにのみ適用される」と明記しています。キーをローテーションしたのに旧い値で動き続ける、という相談の大半がこれです。回せる鍵と回せない鍵の違いはSupabase APIキーの管理を扱った記事で扱っています。

値を差し替えたら、対象の環境で再デプロイを走らせるところまでを手順書へ含めてください。確認の順序は、変数を更新する、対象環境へ再デプロイする、vercel env ls と実際のレスポンスの両方で新しい値が効いていることを見る、の3段です。Vercel の環境ドキュメントにある Production・Preview・Development の切り分けと、どの環境へ入れた変数なのかを取り違えないよう、変更のたびに環境名を声に出して確かめる程度の慎重さで足ります。

プレビュー環境ごとにDBを分けるSupabaseブランチングの実装

Vercel は本番ブランチ以外への push で Preview Deployment を作ります。アプリは分かれるのに、データベースが本番のままでは、レビュー中の破壊的な操作が本番へ届いてしまいます。ここを分ける仕組みが Supabase のブランチングです。

Preview Branchが作るものと、データが入っていない前提

Supabase のブランチは、それぞれが独立した環境で、独自の Supabase インスタンスと API 認証情報を持ちます。Preview Branch は一時的な環境で、プルリクエストがマージまたはクローズされた時点で自動削除されます。長期に置きたい場合は Persistent branch を選び、こちらは非アクティブでの自動一時停止やマージ時の削除が起きません。

注意すべきは中身です。新しいブランチは、既定では本番プロジェクトのデータもストレージオブジェクトも引き継ぎません。公式ドキュメントは、これを本番の機微なデータを守るための既定だと説明しています。データを入れて始めたい場合の逃げ道は2つ用意されており、GitHub 連携で運用しているなら seed ファイル、ダッシュボードからブランチを作るなら Include data のオプションを使います。ただしどちらも本番の実データをそのまま複製する用途には向きません。匿名化したダンプを seed として持たせるか、共有の検証用プロジェクトを別に立てる形へ切り替えてください。

なお、セルフホストではブランチングそのものが提供されません。環境ごとにスタックを複製する形になる前提はSupabaseセルフホストの構成と運用の記事で整理しています。

config.tomlにブランチングとseedの設定を書いて反映させる手順

seed をブランチへ流すかどうかは、リポジトリの supabase/config.toml で決まります。CLI の設定リファレンスによれば、seed の有効化は db.seed.enabled、読み込むファイルの指定は db.seed.sql_paths で、既定値は seed.sql の1本です。Persistent branch では、この有効化を明示しておかないと Seed の工程が動きません。

# supabase/config.toml

[db.seed]
enabled = true
sql_paths = [ "./seeds/common.sql", "./seeds/fixtures.sql" ]

# ブランチ名ごとに別の seed を当てる書き方
[remotes.staging]
project_id = "your-project-ref"

[remotes.staging.db.seed]
sql_paths = [ "./seeds/staging.sql" ]

この remotes ブロックが効くと、レビュー用のブランチには軽い固定データ、負荷検証用のブランチには件数の多いデータ、という具合に流し分けられます。実データを配らずに検証の再現性を上げたい案件では、この分岐がそのまま品質を担保する仕組みです。マイグレーションの組み立て方そのものはSupabase CLIとローカル開発環境の記事で扱っています。

同期がPull Requestを開いた時点で走る仕組みと運用上の注意点

Vercel との連携では、対応するプレビューブランチ向けの環境変数を Supabase が Vercel プロジェクトへ自動で書き込みます。前提として、Vercel の GitHub 連携が入っていること、そして Supabase プロジェクトと Vercel プロジェクトが接続済みであることが必要です。

ここに1つ落とし穴があります。統合のドキュメントによれば「同期はプルリクエストが開かれた時点で発生し、ブランチ作成の時点ではない」という仕様です。ブランチを切って push しただけの段階では、Preview Deployment は本番向けの接続情報を掴んだまま動きます。データベースを分けたつもりで本番へ書き込む事故は、この時間差で発生します。

同じ原文には、もう一段の但し書きもあります。Supabase が変数を書き込む処理と Vercel がビルドを走らせる処理は競合し得るため、Supabase 側が該当プルリクエストの最新デプロイを自動で再デプロイする、という設計になっています。つまりプルリクエストを開いた直後の1回目のビルドは、古い変数のまま完了している可能性があり、正しい接続先で動いているのは再デプロイ後の版です。プレビューを本番から隔離する運用にするなら、プルリクエストを開くまで書き込み系の確認をしない、開いた直後は再デプロイの完了を待ってから触る、という運用側の約束まで含めて設計してください。

ブランチ固有の環境変数で共有DBへ寄せる代替案と具体的な設定手順

ブランチングを入れずに分離する方法も選択肢です。Vercel の Preview 環境変数は、すべての非本番ブランチへ適用するか、特定のブランチだけへ適用するかを選択できます。ブランチ固有の値は同名の Preview 変数を上書きするため、既存の設定を全部複製する必要はなく、差し替えたい値だけを足せば済みます。

この仕組みを使えば、検証用に立てた Supabase プロジェクトの接続情報を Preview 全体へ入れ、負荷試験用のブランチだけ別プロジェクトへ向ける、といった構成を作れます。Custom environments を使い、ステージング相当の環境を Production とも Preview とも別に切る手も選択肢です。VercelへReactアプリをデプロイする手順の記事にある基本の流れへ、この環境の切り分けを重ねる形になります。

1ブランチ毎時0.01344ドルから判断する常時起動の可否基準

ブランチングの単価は、Supabase の料金ページに「$0.01344 per branch, per hour」と示されています。時間課金であるため、費用はブランチの本数ではなく本数と稼働時間の積で効いてきます。

目安として、1本を24時間動かすと日あたり約0.32ドル、30日で約9.7ドルです。プルリクエストが常時5本開いている開発体制なら、月あたり48ドル前後が上乗せされる計算になります。Pro と Team のプランには月10ドル分の compute credits が含まれますが、これはMicro インスタンス1台分を賄う枠であり、ブランチを何本も常時起動する前提では足りません。レビューが終わったプルリクエストを開いたまま放置しない、という運用の徹底が、そのまま費用の制御になります。

サーバーレスからの接続はSupavisorのどのモードで通すか

Vercel の関数は、リクエストごとに実行環境が立ち上がる前提の実行モデルです。FaaSの制約を整理した記事で扱うとおり、同時実行が増えるほどプロセスの数も増えます。1プロセスが1本ずつ接続を張れば、Postgres 側の接続上限は簡単に埋まります。

サーバーレス接続で6543のトランザクションモードを既定にする理由

Supabase の接続方法は、経路とポートの組み合わせで整理されています。

Vercel の関数から通すなら 6543 のトランザクションモードです。トランザクション単位でサーバー側の接続を貸し出す方式のため、関数の同時実行数がそのまま接続数へ跳ね返りません。共有プーラーの実体は Supabase が開発している Supavisor で、ソースはリポジトリで確認できます。プーラーを挟む発想そのものはRDS Proxyの接続プール解説と同じ構造です。

ネットワーク層の違いも押さえてください。直結は IPv6 が既定で、IPv4 で通すには add-on が必要です。この add-on はデュアルスタック化ではなく、プロジェクトの AAAA レコードを A レコードへ差し替える挙動になるため、有効にすると経路が IPv4 のみへ寄る点に注意が要ります。共有プーラーは IPv4 で到達でき、IPv4 のみの社内網からつなぐ場面ではここが逃げ道になります。

接続文字列とORMの設定を書き換えて実際に動かすまでの作業手順

設定は3箇所です。環境変数、ORM のデータソース定義、クライアント生成のオプション。まず環境変数側で、実行時とマイグレーションの経路を分けます。

# .env（アプリ実行時＝プーラー経由・ユーザー名にプロジェクト参照が付く）
POSTGRES_URL="postgres://postgres.[プロジェクトID]:[パスワード]@aws-[リージョン].pooler.supabase.com:6543/postgres"

# .env（マイグレーションとダンプ＝直結）
POSTGRES_URL_NON_POOLING="postgresql://postgres:[パスワード]@db.[プロジェクトID].supabase.co:5432/postgres"

Prisma を使う構成なら、データソース定義で実行時とスキーマ適用時の URL を別々に指します。directUrl を書き忘れると、マイグレーションがプーラー経由で流れて途中で落ちます。

// prisma/schema.prisma
datasource db {
  provider  = "postgresql"
  url       = env("POSTGRES_PRISMA_URL")
  directUrl = env("POSTGRES_URL_NON_POOLING")
}

ドライバへ直接つなぐ構成では、クライアント生成の時点で prepared statements を切ります。次は postgres.js の例で、prepare: false の1行が抜けると本番でだけ落ちる状態になります。

// db.ts — サーバー側でのみ読み込む
import postgres from "postgres"

export const sql = postgres(process.env.POSTGRES_URL, {
  prepare: false,
  max: 1,
})

max を小さく抑えているのは、関数のインスタンスごとにプールを持たせない意図です。プーラーの手前でさらにプールを作ると、せっかく貸し出し方式にした意味が薄れます。

prepared statementsが無効になる前提でのORM設定

トランザクションモードの制約は次のとおりです。公式ドキュメントには「Transaction mode does not support prepared statements」とあり、接続ライブラリ側で prepared statements を切るよう求めています。ここを見落とすと、ローカルでは通ったクエリが本番でだけエラーになります。

Prisma なら接続文字列側のパラメータで、Drizzle ORMの解説記事で扱うようなドライバ直結の構成ならクライアントの生成オプションで、prepared statements を無効にしてください。Marketplace が入れる POSTGRES_PRISMA_URL が別枠で用意されているのは、この差を吸収するためです。

共有プーラーと専用プーラーの違いと、接続上限の数え方を押さえる

プーラーは1種類ではありません。全プロジェクトで使える共有プーラーはマルチテナントの Supavisor で、有料プランではデータベースと同じ機材へ同居する専用プーラーが用意されます。同居している分だけ往復が短く、遅延の面では専用側が有利です。IPv6 で到達できる網や IPv4 add-on を持つ環境なら、公式ドキュメントも専用側を勧めています。

数え方で誤解が起きやすいのが接続上限です。接続管理のドキュメントによれば、プールサイズを30に設定した場合、Supavisor が Postgres 側へ張れるサーバー接続は合計30本で、これを session モードの 5432 と transaction モードの 6543 が共有します。各モードが個別に30本ずつ使えるのではなく、両モードの合計が30本を越えられない設計です。専用プーラーを併用している場合も同じ枠を見ます。

インスタンスの規模でも枠は変わります。料金ページの見積もり欄では、Micro インスタンスの構成として1GB RAM・2コアの ARM CPU、直結60本・プーラー200本という数値が示されています。関数の同時実行数がこの200へ迫るなら、プーラーのモード選択ではなくインスタンスの規模を上げる判断へ切り替えてください。

5432を残す接続場面はマイグレーションとダンプ処理に限定する

直結を捨てる必要はありません。スキーマ変更を流す処理、拡張機能を入れる処理、バックアップを取る処理は、トランザクション境界を越えたセッション状態を必要とするため直結が向きます。CI から流すマイグレーションは POSTGRES_URL_NON_POOLING、アプリの実行時は POSTGRES_URL、という割り当てを最初に固定してください。

本番昇格の手順とデータベース変更で戻せない操作を見極める判断方法

ここからが、この構成でいちばん事故の起きる場所です。プレビューで動いたものを本番へ上げる工程は、アプリとスキーマという戻しやすさの違う2つを同時に動かします。

マージ時にSupabaseが走らせる工程の中身と具体的な確認方法

ブランチを本番プロジェクトへマージすると、Supabase 側がデプロイのワークフローを自動で実行します。公式ドキュメントが示す流れは Clone、Pull、Health、Configure、Migrate、Seed、Deploy の7段階です。Configure は config.toml に基づく設定反映、Migrate は保留中のマイグレーションと vault の秘密情報の適用、Deploy は Edge Functions の反映という役割分担になっています。Edge Functions 側の扱いはSupabase Edge Functionsの記事で扱っています。

この7段階には依存関係があり、途中の工程が落ちると後続はスキップされます。原文が挙げる例は、第5段のマイグレーションが失敗した場合に第6段の seed が走らない、というものです。ブランチのデータが空のままだという報告を受けたときは、seed の設定を疑う前にマイグレーションのログを先に見てください。この間、アプリ側では Vercel が本番ブランチへの push を検知して独自にビルドを走らせています。2つは別々に進むため、完了の順序は保証されません。

したがって、片方だけが先に出た状態でも壊れない変更に揃えることが前提になります。列を追加するだけ、テーブルを足すだけ、という後方互換のある変更なら、どちらが先でも耐えられます。

ロールバックできない操作から逆算して実行手順を決める判断基準

ここは判断を言い切ります。アプリのデプロイは戻せますが、データを落とすマイグレーションは戻せません。Vercel は過去のデプロイを即座に本番へ戻せる一方、削除された列の中身は復旧の対象になりません。

採用してよい順序は1つです。第一段階でスキーマへ新しい列やテーブルを足し、旧い構造も残したままにする。第二段階でアプリを新しい構造へ切り替えて配る。第三段階で、旧い構造への参照が消えたことをログで確かめてから、削除のマイグレーションを別のプルリクエストで流す。この3回に割ることで、どの時点で戻しても本番のデータが残ります。

逆に、削除を含むマイグレーションとアプリの切り替えを同じプルリクエストへ入れる進め方は見送ってください。プレビューでは空のブランチに対して流れるため成功しますが、本番では既存データを抱えた状態で走り、失敗した場合に戻す先がありません。この段取りをプロジェクトの規約として決め切るところまで含めて、業務用・Webアプリ開発ではデータベースの移行手順を設計に含めています。

三段階に分けたリリースをマイグレーションのファイル構成へ落とす

規約は文章で書くより、ファイルの並びで見せたほうが守られます。列名の変更を例に取ると、次のような3本のマイグレーションと3回のプルリクエストへ割ることになります。

supabase/migrations/
  20260910093000_add_email_verified.sql        -- 第一段階：新しい列を足すだけ
  20260917101500_backfill_email_verified.sql   -- 第二段階：旧列から値を写す
  20260924140000_drop_legacy_email_flag.sql    -- 第三段階：参照が消えてから落とす

-- 第一段階の中身（既存の行を壊さない形にする）
alter table public.users
  add column if not exists email_verified boolean not null default false;

第一段階と第二段階の間にアプリの切り替えを挟み、第三段階は旧い列への参照が消えたことを確かめてから流します。日付入りのファイル名で並ぶため、レビューの時点で「この回に削除が混ざっていないか」を目視で弾けます。

この連携構成を見送り自前インフラへ寄せる場合の具体的な判断条件

採用の条件を裏返しておきます。次のいずれかに当たる案件では、Supabase と Vercel の組み合わせを選ばない判断が妥当です。

• データベースを特定のリージョンや自社ネットワーク内へ置く契約要件があり、専用線や閉域からの接続が必要な場合
• 納品後にクライアント名義でインフラ契約を保有する必要があり、Marketplace 経由の請求統合が障害になる場合
• 長時間走るバッチ処理が主体で、関数の実行時間の上限に収まらない処理が中心を占める場合
• 本番と同じ実データでの検証が承認プロセスへ組み込まれており、空のプレビューブランチでは要件を満たせない場合

3つ目については、処理を Supabase 側へ寄せる逃げ道もあります。製品そのものの向き不向きはSupabaseとFirebaseの比較記事で整理しました。

接続とデプロイで詰まったときに最初に確認する4箇所と切り分けコマンド

この構成で持ち込まれる相談は、原因が数種類に収束します。順番に潰せるよう、確認の順序とコマンドを置きます。

環境変数が入っていないのか反映されていないのかをまず切り分ける

最初に見るのは、変数が「存在しない」のか「古い版のまま動いている」のかです。前者なら統合の接続そのものが切れており、後者なら再デプロイで解ける話になります。vercel env ls で対象環境の一覧を出し、そこに名前があるのに挙動が古いなら後者です。デプロイ一覧で該当ビルドの作成時刻と、変数を更新した時刻を並べれば判定できます。

接続エラーはポートと接頭辞のどちらが原因かをコマンドで確かめる

接続の失敗は、経路の取り違えかユーザー名の書式かのどちらかがほとんどです。プーラー経由ではユーザー名にプロジェクト参照が付くため、直結の書式のままポートだけ 6543 へ変えても通りません。手元から2本のコマンドを打てば、どちらの経路が生きているかを切り分けられます。

# 直結で通るか（IPv6 が要る経路・マイグレーション用）
psql "postgresql://postgres:[パスワード]@db.[プロジェクトID].supabase.co:5432/postgres" -c "select 1"

# プーラー経由で通るか（サーバーレスから使う経路）
psql "postgres://postgres.[プロジェクトID]:[パスワード]@aws-[リージョン].pooler.supabase.com:6543/postgres" -c "select now()"

# いま張られている接続の本数を数える
psql "$POSTGRES_URL" -c "select count(*) from pg_stat_activity"

直結だけが落ちるなら網が IPv4 のみである可能性が高く、プーラー経由だけが落ちるならユーザー名の書式かパスワードの取り違えを疑います。3本目の本数が上限へ張り付いているなら、prepared statements の設定か関数側のプール設定を見直す番です。

プレビューが本番DBを掴んだままになる時間差の見つけ方と対処法

プレビュー環境の挙動がおかしいときは、その Preview Deployment がいつ作られたかを見てください。プルリクエストを開く前に push だけした段階のビルドであれば、本番向けの接続情報を持ったまま動いています。プルリクエストを開き、Supabase 側の再デプロイが終わった版で確かめ直すのが正しい手順です。判別を簡単にするなら、ブランチ名やプロジェクト参照を画面のどこかへ表示する仕込みを開発ビルドへ入れておくと、掴んでいる接続先が一目で分かります。

よくある質問

既に動いているSupabaseプロジェクトをMarketplace管理へ移せますか？

公式ドキュメントは、Marketplace 経由のプロジェクトが Vercel ダッシュボードからのみ作成できると記載しており、既存プロジェクトを移す操作は案内されていません。既存プロジェクトを使う場合は、Supabase 側で発行した接続情報を Vercel の環境変数へ手で登録する構成にしてください。

プレビュー環境から本番のデータを参照させても構いませんか？

読み取りだけに限れば運用できますが、書き込みを含む確認が入る前提なら分けてください。プレビューは開発者以外の目にも触れる URL で配られます。個人情報を含むテーブルがある場合、参照だけでも情報の扱いとして問題になります。

NEXT_PUBLIC_付きと付かない変数の両方が入りますが、どちらを使いますか？

ブラウザで動くコードからは NEXT_PUBLIC_ が付いた側、サーバー側で動くコードからはどちらでも参照できます。判断の軸は値の性質です。publishable key はブラウザへ出て構いませんが、secret key は接頭辞の有無にかかわらずサーバー側に閉じたまま扱ってください。

関数から「接続数が上限に達した」と出ます。何を見直しますか？

接続先のポートを確かめてください。5432 の直結のままサーバーレスから接続していると、同時実行の数だけ接続が積み上がります。6543 のトランザクションモードへ切り替え、併せて prepared statements を無効にする設定を入れてください。それでも埋まるなら、プールサイズが session モードと transaction モードで共有される仕様を踏まえ、インスタンスの規模を上げる判断へ進みます。

ブランチングを使わずにプレビュー環境を運用できますか？

できます。検証用の Supabase プロジェクトを1つ立て、その接続情報を Vercel の Preview 環境変数へ入れる方式です。ブランチ単位の分離は失われますが、時間課金が発生せず、データを常駐させておける利点があります。同時に走るプルリクエストが少ないチームでは、こちらが扱いやすい構成になります。

プレビューブランチに検証用のデータを最初から入れておけますか？

入れられます。GitHub 連携で運用しているなら supabase/config.toml の db.seed に SQL ファイルを指定し、ダッシュボードからブランチを作る場合は Include data のオプションを選びます。既定はデータなしで始まる設計なので、必要な案件では明示的に設定してください。

プルリクエストを開いた直後のプレビューが古い接続先で動くのはなぜですか？

Supabase が環境変数を書き込む処理と、Vercel がビルドを走らせる処理が競合し得るためです。公式ドキュメントは、この競合を吸収するために Supabase 側が該当プルリクエストの最新デプロイを自動で再デプロイすると説明しています。1回目のビルドではなく、再デプロイ後の版で挙動を確かめてください。

関連記事

• SupabaseとFirebaseの違いを徹底比較｜料金・認証・どっちを選ぶか：製品選定の段階で読む全体像を整理しています。
• Supabase Next.js連携の実装｜proxyとgetClaimsで組むApp Router構成：アプリ側のクライアント生成とセッション更新を扱います。
• Supabase CLIとローカル開発環境：db diffで進めるマイグレーションとCI：スキーマ変更の作り方と反映手順を解説。
• Supabase RLSの設定手順とAuth連携ポリシー設計｜有効化漏れの検知まで：キーとポリシーによる権限設計の本体です。
• Vercel料金｜Hobby無料枠とPro($20)の中身・超過単価：ホスティング側の費用を確かめられます。