AIものさし

SupabaseのPGRST204で列が見つからないとき、schema cacheとqueryを切り分ける

SupabaseのPGRST204で列が見つからない場合、指定列・schema cache・queryのselect対象を照合する手順を解説します。

AIものさし編集部

目次

まず確認するのは「どのcolumn指定か」

SupabaseのData APIでPGRST204が返ったら、最初にHTTP statusだけでなくJSONのcode、message、details、hintを確認します。Supabase公式Error Codesでは、PGRST204はcolumns query parameterで指定されたcolumnが見つからない場合のエラーです。似た文面の「列がない」エラーでも、対象のAPI操作やエラーコードが違えば原因の層も違います。

最初に調べるのは、requestのcolumnsに何が入っているか、どのtableへのどの操作でエラーになったかです。列名のtypo、JSON payloadのkey、upsert時に指定した列、対象tableの違い、DDL変更後のschema cacheの古さを分けて確認します。「schema cache」という語が見えるからといって、毎回cache reloadを実行するのではなく、DBに存在しAPIから利用可能な列なのにPostgREST側の認識だけが古いケースかを確かめます。

この記事ではSupabase公式資料にあるPGRST204の範囲、PostgREST schema cacheを更新する正式手順、Supabase JavaScriptのinsert/upsertの扱いを整理します。個別のプロジェクトのテーブル定義、公開schema、migration状態は確認していないため、特定の列が存在する、または権限が正しいとは断定しません。

PGRST204の意味と、似た症状との違い

公式のエラー表でPGRST204はHTTP 400として分類され、columns query parameterで指定された列が見つからない場合に発生すると説明されています。したがって、まずrequest payloadやcolumns指定に含まれる列名が、そのAPI操作とtableに対して正しいかを確認します。

ここで、PGRST204を「schema cacheが古い」の同義語として扱わないことが大切です。DBに列がない、誤ったtableへ送っている、payloadのkeyが列名とずれているなら、schema cacheを読み直しても解決しません。DDLを実行して列を追加した直後で、DB側に正しい列が存在するのにPostgRESTがまだその構造を認識していないと確認できた場合に、schema cacheの更新を検討します。

また、Data APIへ公開されていないschema/tableや、SQL権限・RLSの問題は別の確認軸です。これらを調べる際は、エラーコード、HTTP status、request path、操作、認証主体をセットで見ます。PGRST204という結果だけで「権限不足」「RLS拒否」と確定しないでください。

最初の5分で記録する情報

  1. 操作の種類：select、insert、upsert、updateなど、実際に送ったHTTP操作とsupabase-jsの呼び出しを記録します。ライブラリのメソッド名だけでなく、requestのmethod、path、query parameterも確認します。

  2. エラーJSON：code、message、details、hintを保持します。response body全体を社外共有する前に、行データ、ユーザー識別子、tokenなどの機微情報を取り除きます。

  3. 対象schema / table：requestが意図したproject、環境、schema、tableを参照しているかを確かめます。開発projectのmigrationを本番projectのエラーと取り違えていないかも確認します。

  4. 列名の出どころ：columns query parameter、JSON bodyのkey、select()文字列、onConflict等の指定を区別します。各列名を実際のDB定義と一つずつ照合します。

  5. 直近の変更：直前のmigration、列のrename/drop、schema変更、権限やAPI設定変更、デプロイの有無を時系列で記録します。変更がないのにcache更新から始めず、request自体を先に検証します。

再現ログは、API keyやAuthorization tokenを出さずに残します。エラーを再現するのに必要なrequest shapeと列名は記録し、実データや秘密を含むヘッダーをチャットやissueへ貼らないでください。

原因を分ける診断フロー

1. Request内の列名を正確に照合する

失敗したrequestの列名を抽出し、DBの実際の列定義と比較します。大文字・小文字、snake_case、複合語の綴り、rename前の旧名、JSONネストの位置、insert先とselect先の違いを確認してください。たとえばDB列がcustomer_idなのにpayloadがcustomerIdなら、アプリ側で変換しているかを確かめます。勝手に似た名前へ置換せず、アプリケーションのデータ契約を確認します。

supabase-jsでupsert()を使っている場合は、書き込むオブジェクトのkey、onConflictに指定した列、必要に応じてignoreDuplicatesなどの指定を別々に見ます。upsertを使っているというだけで、原因をupsert固有と決めつけないでください。実際のnetwork requestまたは安全なデバッグログで、送信された列名と対象relationを確認します。

2. Database definitionとmigration状態を確認する

SQL Editorやmigration履歴など、権限のある管理経路で対象projectのtable定義を確認します。ここでは列が本当に追加されているか、名前・型・schemaが意図どおりかを見ます。クライアントから列をselectできないことだけでは、DBに列がない証拠になりません。逆に、管理画面の別projectで列が見えることも、エラーを返したprojectに存在する証拠ではありません。

変更がまだmigrationとして適用されていないなら、schema cache reloadではなくmigrationの適用状態が先です。migrationをどの環境に適用するか、既存データ・制約・アプリ互換性への影響を確認し、Production schemaを即興で変更しないでください。DDLはData Modelへの変更なので、通常のデバッグ操作と区別して扱います。

3. APIに公開されたschemaと権限を確認する

DB列が存在するなら、API requestが正しいschema/tableへ届いているか、対象schemaがData APIで公開されているか、実行roleに必要な権限があるかを確認します。権限エラーは別のcode/statusで返る場合があり、PGRST204から権限問題を推定するのではなく、レスポンスを確認して必要な調査へ分岐します。

RLSはユーザーごとに行の可視性を制御します。列名を認識できないPGRST204とは別の層です。RLSを緩めたり無効化したりして列エラーを回避しないでください。通常利用者のroleと管理者roleを混同せず、権限の確認は許可されたテスト環境・アカウントで行います。

4. Cacheの古さが残る条件を確認する

DBに列が正しく存在し、requestが正しいschema/tableを使い、エラーがDDL直後に始まったなど、PostgRESTがschema cacheの更新を受け取っていない可能性が具体的になったときにだけrefreshを候補にします。Supabaseの公式手順では、Project DashboardのSQL EditorでNOTIFY pgrst, 'reload schema';を実行してschemaを再読み込みします。

この操作は無条件な修正ボタンではありません。対象projectと権限を確認してから実施し、成功メッセージを確認し、同じ安全なrequestで再テストします。該当の列がDBに存在しない場合、誤ったrequest列を送っている場合、migrationが未適用の場合に通知だけを送っても根本原因は残ります。

分岐表：観測から次の確認へ

表は横にスクロールできます

観測有力な確認先次のアクション
columnsに綴り違い・旧名があるclient payload、生成型、rename履歴API契約とDB名を照合し、必要なコード側の列指定を修正
requestのtable/schemaが想定外project URL、path、schema指定environment/configと呼び出し箇所を直し、安全な環境で再試行
DBに列がないmigration状態、schema定義正しいmigrationを確認。cache reloadでは埋め合わせない
DBに列があるがAPI認識が古い可能性DDL実行時刻、PostgREST schema cache対象projectで公式reload手順を実行し再確認
エラーがcolumn not found以外のcoderesponse code/status、Postgres/API docs別のエラーとして原因層を調査
管理者と利用者の結果が異なるAPI exposure、権限、RLS policyroleごとに差を確認。RLSを無効にしない

この表は観測と調査先の対応です。エラー文面だけで結論を出さず、request、DB定義、API経路、変更履歴を合わせて判断してください。

supabase-jsの呼び出しをどう確認するか

insert()やupsert()へ渡すオブジェクトのkeyがDB列名と一致しているかを確認します。型生成を使っている場合も、型がどのproject・schemaの時点で生成されたか確認してください。生成型が古いと、エディター上で正しいように見えても実際のDBとのずれを検出できないことがあります。

upsertでは、衝突判定に使う列と書き込む列を混同しないようにします。onConflictを指定している場合、その列が対象tableに存在し、一意性の設計と合っているかを確認します。エラーがcolumns parameterを指すなら、どの列がそのparameterに入るかを追い、upsertの全ての設定を闇雲に削除しないでください。

selectで列を指定するコードでは、tableのaliasや埋め込みrelationを含む場合に、列がどのtableのものかも確認します。列名が別relationに属する、relationshipが古い、schema cache上のrelation定義が変わったなどは別のエラーとして報告されることもあります。実際のcodeを優先し、似たエラーを一括で同じ原因にしないでください。

安全な修正後テスト

修正の種類に合わせてテストを分けます。payloadのtypoを直した場合は、意図した列へ値が入ることと、既存の必須列・null制約・型検証が働くことをテストします。migrationを適用した場合は、適用対象環境、schema定義、API経由での読み書き、関連する既存クエリを確認します。cache reloadを行った場合は、対象環境の同じrequestで列が認識されるかを再試験します。

最低限、次のケースを確認します。

・正しいtableに既存列を指定した読み取りまたは書き込みが成功する。

・存在しない列を指定した場合、アプリが適切な失敗表示・記録を行い、秘密情報を漏らさない。

・migrationで新設する列なら、適用前・適用後の挙動と依存コードの互換性を確認する。

・開発と本番で環境設定やschemaがずれていない。

・他のAPI呼び出し、RLS、制約、既存行の値を不用意に変えていない。

手元のテストで直っただけでは本番反映済みとは言えません。ProductionのschemaやAPI設定を変更する必要がある場合は、影響範囲とrollbackを整理して別のRelease gateで扱います。

よくある誤診

「PGRST204ならschema cacheをreloadすればよい」：公式定義はcolumns query parameterの指定列が見つからないというものです。typoやmigration未適用を先に除外し、DBとAPIの認識差が残る場合だけreloadを検討します。

「列を追加したからAPIからすぐ見えるはず」：migrationがどのprojectへ適用されたか、schema cacheが更新されたか、APIに公開されたschemaかを順に確認します。別環境での成功は対象projectの成功を保証しません。

「select権限やRLSを緩めれば列エラーが直る」：PGRST204はまず列指定の問題として扱います。権限やRLSは実際のresponse codeやrole別挙動を確認し、意図した最小権限を維持します。

「databaseに列が見えたので、アプリのrequestは正しい」：table、schema、project、payloadの全てが一致するかを確認します。DB定義を見た画面と、失敗したAPIの対象が同じとは限りません。

判断を閉じるチェックリスト

修正を完了扱いにする前に、次を埋めてください。

  1. 失敗したrequestのmethod、path、query、対象schema/tableは何か。

  2. エラーJSONのcodeがPGRST204で、どの列を指すか特定できたか。

  3. 対象projectのDBにその列があるか。migrationは適用済みか。

  4. その列指定はpayload、columns parameter、select句、upsert設定のどこから来たか。

  5. APIに対象schemaが公開され、呼び出すroleに必要な権限があるか。

  6. cache reloadが必要と判断する独立した根拠があるか。単に文面にschema cacheとあるからではないか。

  7. 安全な環境と認証主体で修正後テストを行い、他のpermissionやdata behaviorを壊していないか。

列を新しく作るべきか、requestを直すべきか、cacheを再読み込みすべきかは、ここまでの答えで決めます。原因不明のまま列追加、権限拡大、schema公開、RLS変更を重ねないでください。

公式情報と確認範囲

次のSupabase公式資料を2026-10-15に確認しました。Error CodesはPGRST204の定義、schema refreshページはDashboardのSQL Editorで実行する通知文、JavaScript referenceは各データ操作の呼び出し契約を説明しています。対象ユーザーのproject状態・実際のDDL・API requestは未確認です。

・REST API Error Codes：https://supabase.com/docs/guides/api/rest/postgrest-error-codes（新しいタブで開く）

・Reload/refresh PostgREST schema：https://supabase.com/docs/guides/troubleshooting/refresh-postgrest-schema（新しいタブで開く）

・JavaScript upsert：https://supabase.com/docs/reference/javascript/upsert（新しいタブで開く）

・JavaScript insert：https://supabase.com/docs/reference/javascript/insert（新しいタブで開く）