supabase

Supabase

基本原則

1. Supabase は頻繁に変更されるため、実装前に変更履歴と最新のドキュメントを確認してください。 Supabase の機能について、学習データに頼らないでください。関数のシグネチャ、config.toml の設定、API の規約はバージョン間で変更されます。

まず、https://supabase.com/changelog.md（軽量な概要インデックスであり、大規模な取得ではありません）を取得し、作業に関連する breaking-change タグを確認して、該当するものがあればリンク先のページを参照してください。その後、以下のドキュメント参照方法を使って、関連するトピックを調べてください。

2. 作業を検証してください。 修正を実装したら、テストクエリを実行して変更が機能することを確認してください。検証していない修正は未完成です。

3. エラーから復旧し、同じ方法を繰り返さないでください。 2～3 回試しても方法がうまくいかない場合は、いったん止めて再検討してください。別の方法を試し、ドキュメントを確認し、エラーをより詳しく調べ、可能であれば関連するログも確認してください。Supabase の問題は同じコマンドを再試行しても必ず解決するとは限らず、答えが常にログにあるわけでもありませんが、先に進む前にログを確認する価値はよくあります。

4. Data API へのテーブルの公開： ユーザーの Data API 設定によっては、新しく作成したテーブルが Data（REST）API に自動的に公開されない場合があります。その場合、anon と authenticated のロールに明示的にアクセス権を付与する必要があります。

これは RLS とは別の仕組みです。RLS は、テーブルにアクセスできるかどうかではなく、テーブルにアクセスできる場合にどの 行 を表示するかを制御します。

SQL で作成したテーブルに予期せずアクセスできないという報告があった場合は、Data API の設定と、明示的な GRANT SQL によってロールにアクセス権が付与されているかを確認してください。パブリック（anon／authenticated）アクセス権を付与する場合は、必ず RLS も有効にしてください。設定手順の全体については、Data API へのテーブルの公開を参照してください。

5. 公開スキーマの RLS。 public をデフォルトで含む、公開スキーマ内のすべてのテーブルで RLS を有効にしてください。公開スキーマ内のテーブルは、anon／authenticated ロールにアクセス権がある場合、Data API 経由でアクセス可能になるため、これは Supabase では非常に重要です（Data API へのテーブルの公開を参照）。プライベートスキーマでは、多層防御として RLS を使用することを推奨します。RLS を有効にした後は、すべてのテーブルに同じ auth.uid() パターンを適用するのではなく、実際のアクセスモデルに合ったポリシーを作成してください。

6. セキュリティチェックリスト。 認証、RLS、ビュー、ストレージ、ユーザーデータに関わる Supabase の作業では、このチェックリストを確認してください。これらは、気付かないうちに脆弱性を生み出す、Supabase 固有のセキュリティ上の落とし穴です。

• 認証とセッションのセキュリティ

  • JWT ベースの認可判断に user_metadata のクレームを決して使わないでください。 Supabase では、raw_user_meta_data はユーザーが編集でき、auth.jwt() に含まれる場合があるため、RLS ポリシーやその他の認可ロジックに使用するのは安全ではありません。認可データは代わりに raw_app_meta_data／app_metadata に保存してください。
  • ユーザーを削除しても、既存のアクセストークンは無効になりません。 まずサインアウトするかセッションを取り消し、機密性の高いアプリでは JWT の有効期限を短く保ってください。厳密な保証が必要な場合は、機密性の高い操作で session_id を auth.sessions と照合してください。
  • 認可に app_metadata または auth.jwt() を使う場合、ユーザーのトークンが更新されるまでは JWT クレームが常に最新とは限らないことに留意してください。

• API キーとクライアントへの露出

  • service_role またはシークレットキーをパブリッククライアントで絶対に公開しないでください。 フロントエンドコードでは公開可能キーを優先してください。従来の anon キーは互換性のためにのみ使用します。Next.js では、NEXT_PUBLIC_ 環境変数はすべてブラウザーに送信されます。
  • Management API、CLI、MCP サーバーには、スコープを限定したパーソナルアクセストークンを使用してください。 従来型のパーソナルアクセストークンでは、すべての組織とプロジェクトでユーザーのアカウントに対する全アクセス権が付与されます。スクリプト、CI、エージェントで使用する場合は、タスクに必要な組織、プロジェクト、権限のみに制限したスコープ付きトークンをユーザーに作成してもらってください。パーソナルアクセストークンガイドには、各 Management API エンドポイントと MCP ツールに必要な権限が記載されています。推測せず、ガイドで権限を確認してください。

• RLS、ビュー、特権データベースコード

  • ビューはデフォルトで RLS を迂回します。 Postgres 15 以降では、CREATE VIEW ... WITH (security_invoker = true) を使用してください。古いバージョンの Postgres では、anon ロールと authenticated ロールからアクセス権を取り消すか、公開されていないスキーマにビューを配置して保護してください。
  • UPDATE には SELECT ポリシーが必要です。 Postgres RLS では、UPDATE の前に対象の行を SELECT する必要があります。SELECT ポリシーがないと、更新はエラーにならずに 0 行を返し、変更も行われません。
  • auth.role() は非推奨です。代わりに TO 句を使用してください。 Supabase は auth.role() を非推奨とし、ポリシーで TO authenticated または TO anon を指定して対象ロールを直接設定する方法を推奨しています。非推奨であることに加え、匿名サインインが有効な場合、auth.role() = 'authenticated' は意図せず機能します。匿名ユーザーには authenticated の Postgres ロールが割り当てられるため、ユーザーが実際にサインインしているかどうかにかかわらずチェックを通過します。

    -- 非推奨（使用しないでください）
    create policy "example" on table_name for select
    using ( auth.role() = 'authenticated' );
    

  • TO authenticated の指定だけでは、認証されるだけで認可されません（BOLA / IDOR）。 TO authenticated の使用で確認されるのはロールのみで、ユーザーがアクセスできる行は制限されません。正しい方法は、TO authenticated と USING の所有者述語を組み合わせることです。

    create policy "example" on table_name for select
    to authenticated
    using ( (select auth.uid()) = user_id );
    

  • UPDATE ポリシーには USING と WITH CHECK の両方が必要です。 WITH CHECK がないと、ユーザーは行の user_id を別のユーザーのものに変更できます。

    create policy "example" on table_name for update
    to authenticated
    using ( (select auth.uid()) = user_id )
    with check ( (select auth.uid()) = user_id );
    

  • SECURITY DEFINER 関数は RLS を迂回します。 SECURITY DEFINER 関数は作成者の権限で実行されます。通常、作成者は bypassrls を持つロール（例：postgres）です。権限エラーの解決に SECURITY DEFINER を追加しないでください。根本原因を解決せずにアクセス制御が暗黙的に取り除かれます。SECURITY INVOKER を優先してください。
  • public 内の SECURITY DEFINER 関数はすべてのロールから呼び出せます。 Postgres は新しい関数ごとに、デフォルトで PUBLIC に EXECUTE を許可します。そのため、public 内の SECURITY DEFINER 関数は、追加の権限付与なしで anon と authenticated（どちらも PUBLIC の権限を継承します）から呼び出せるパブリック API エンドポイントになります。SECURITY DEFINER が本当に必要な場合（例：内部参照テーブルの RLS を迂回する場合）は、関数を非公開のスキーマに配置し、関数本体に必ず auth.uid() のチェックを含め、変更後に supabase db advisors を実行してください。

• ストレージのアクセス制御

  • ストレージのアップサートには INSERT + SELECT + UPDATE が必要です。 INSERT のみを許可すると、新しいファイルはアップロードできますが、ファイルの置き換え（アップサート）は失敗してもエラーになりません。3 つすべてが必要です。

• 依存関係とサプライチェーンのセキュリティ

  • Supabase パッケージ（supabase-js、@supabase/ssr、supabase-py など）をインストールする際は、パッケージのバージョンを必ず固定し、ロックファイルをコミットしてください。チェックリストの全項目については、npm セキュリティガイドをご覧ください。

上記に記載されていないセキュリティ上の懸念については、Supabase の製品セキュリティインデックスを取得してください：https://supabase.com/docs/guides/security/product-security.md

Supabase CLI

コマンドは必ず --help で確認してください。推測してはいけません。CLI の構成はバージョンによって変わります。

supabase --help                    # All top-level commands
supabase <group> --help            # Subcommands (e.g., supabase db --help)
supabase <group> <command> --help  # Flags for a specific command

Supabase CLI でよくある注意点：

• supabase db query には CLI v2.79.0 以降が必要です。代替手段として MCP の execute_sql または psql を使用してください。
• supabase db advisors には CLI v2.81.3 以降が必要です。代替手段として MCP の get_advisors を使用してください。
• supabase login のブラウザフローでは、アカウント全体にアクセスできるクラシックトークンが作成されます。CI では、代わりにスコープを限定した個人用アクセストークンを SUPABASE_ACCESS_TOKEN に設定してください。このトークンは、保存済みのログイン情報より優先されます。データベースパスワード（--password や SUPABASE_DB_PASSWORD など。たとえば supabase db push）を使って接続するコマンドは、トークンの権限による制限を受けません。
• 命令型のマイグレーションプロジェクトでは、手書きの新しいマイグレーションファイルを作成する際、まず supabase migration new <name> を実行してください。マイグレーションのファイル名を独自に決めたり、想定される形式を記憶に頼ったりしてはいけません。宣言型スキーマプロジェクトでは、supabase/schemas/ からマイグレーションを生成します。詳しくは、以下の「スキーマ変更の作成とコミット」をご覧ください。

バージョンの確認とアップグレード： supabase --version を実行して確認してください。CLI の変更履歴やバージョン固有の機能については、CLI ドキュメントまたはGitHub リリースを参照してください。

Supabase MCP サーバー

セットアップ手順、サーバー URL、設定については、MCP セットアップガイドをご覧ください。

接続の問題を解決するには、次の手順を順番に実行してください。

1. サーバーに接続できるか確認します： curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp トークンがない場合は 401 が返るのが正常で、サーバーが稼働していることを意味します。タイムアウトまたは「connection refused」が返る場合は、サーバーが停止している可能性があります。

2. .mcp.json の設定を確認します： プロジェクトのルートに、正しいサーバー URL が設定された有効な .mcp.json があることを確認してください。ファイルがない場合は、https://mcp.supabase.com/mcp を指定して作成してください。

3. MCP サーバーを認証します： サーバーに接続でき、.mcp.json も正しいのにツールが表示されない場合は、ユーザーによる認証が必要です。Supabase MCP サーバーは OAuth 2.1 を使用します。エージェントで認証フローを開始し、ブラウザで完了してからセッションを再読み込みするようユーザーに伝えてください。 CI など、ブラウザフローを実行できない環境では、スコープを限定した個人用アクセストークンを Authorization: Bearer ヘッダーに設定してください。

4. スコープ付きトークンの権限を確認します： スコープを限定した個人用アクセストークンを使用中に、ツールが「You do not have permission to perform this action」というエラーで失敗する場合、そのトークンにツールの権限がないか、プロジェクトがトークンのスコープ外にあります。個人用アクセストークンガイドで、ツールに必要な権限を確認してください。

Supabase ドキュメント

Supabase の機能を実装する前に、該当するドキュメントを必ず確認してください。次の方法を優先度の高い順に使用してください。

1. MCP の search_docs ツール（推奨。関連する抜粋を直接取得できます）
2. ドキュメントページを Markdown として取得 — URL パスの末尾に .md を追加すると、任意のドキュメントページを取得できます。
3. ウェブ検索 — 参照すべきページがわからない場合は、Supabase 固有のトピックを検索してください。

スキーマ変更の作成とコミット

まず、プロジェクトで使用しているスキーマのワークフローを確認してください。

オプション A：宣言的スキーマ

supabase/schemas/ が存在する場合、または config.toml で schema_paths が設定されている場合に使用します。これらのファイルで目的のスキーマ状態を編集してから、マイグレーションを生成してレビューします。最初に手作業でマイグレーションを書き始めないでください。宣言的データベーススキーマガイドを参照してください。

オプション B：命令的マイグレーション

プロジェクトで宣言的スキーマを使用していない場合に使用します。

スキーマを変更するには、execute_sql（MCP）または supabase db query（CLI）を使用してください。 これらはマイグレーション履歴のエントリーを作成せずにデータベースで SQL を直接実行するため、自由に反復し、準備ができたらクリーンなマイグレーションを生成できます。

ローカルデータベースのスキーマ変更に apply_migration を使用しないでください。呼び出すたびにマイグレーション履歴のエントリーが書き込まれるため、反復できなくなり、supabase db diff / supabase db pull は空の差分または競合する差分を生成します。これを使用すると、最初に渡した SQL で固定されてしまいます。

変更をコミットする準備ができたら、マイグレーションファイルに反映します。

1. アドバイザーを実行する → supabase db advisors（CLI v2.81.3+）または MCP get_advisors。問題があれば修正します。
2. 変更にビュー、関数、トリガー、またはストレージが含まれる場合は、上記のセキュリティチェックリストを確認します。
3. マイグレーションを生成する → supabase db pull <descriptive-name> --local --yes
4. 確認する → supabase migration list --local

デバッグ

Supabase に関連するリクエストでエラーが発生した場合（例：Supabase REST API、Postgres データベース、PostgREST のエラーコード、空の結果、予期しない RLS によるブロック、Auth、Realtime、Edge Functions、Storage などの Supabase サービスのエラー）、診断や修正案の提示を行う前に、必ず Supabase のモニタリングとデバッグに関するドキュメントを取得してください。記憶に頼って対応してはいけません。同じドキュメントでは、遅いクエリや不足しているインデックスなど、パフォーマンスの最適化についても説明しています。

参考ガイド

• スキルへのフィードバック → references/skill-feedback.md 必ず読む場合： このスキルの案内に誤りがあった、または情報が不足しているとユーザーから報告されたとき。