Supabase スキル

Supabase

基本原則

1. Supabase は頻繁に変更されます — 実装前に変更履歴と現在のドキュメントを必ず確認してください。 Supabase の機能に関してトレーニングデータに依存しないでください。関数シグネチャ、config.toml の設定、API の慣例はバージョン間で変更される可能性があります。

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

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

3. エラーから回復し、ループしないでください。 アプローチが 2〜3 回試行しても失敗した場合は、立ち止まって再検討してください。別の方法を試し、ドキュメントを確認し、エラーをより注意深く調査し、利用可能な場合は関連ログを確認してください。Supabase の問題は、同じコマンドを再試行するだけで解決できるとは限らず、答えが常にログにあるわけでもありませんが、ログは先に進む前に確認する価値があります。

4. データ API へのテーブル公開: ユーザーの Data API 設定 によっては、新しく作成されたテーブルがデータ (REST) API を介して自動的に公開されない場合があります。この場合、anon ロールと authenticated ロールに明示的にアクセスを許可する必要があります。

これは RLS とは別のものであることに注意してください。RLS はテーブルがアクセス可能になった後にどの 行 が表示されるかを制御するものであり、テーブル自体がアクセス可能かどうかを制御するものではありません。

ユーザーが SQL で作成したテーブルに予期せずアクセスできないと報告した場合は、Data API 設定と、明示的な GRANT SQL によってロールにアクセスが許可されているかどうかを確認してください。パブリック（anon/authenticated）アクセスを許可する場合は、RLS も必ず有効にしてください。完全な設定ワークフローについては、テーブルを Data API に公開する を参照してください。

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

6. セキュリティチェックリスト。 auth、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_ 環境変数はすべてブラウザに送信されます。

• 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 を実行してください。

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

  • Storage upsert には INSERT + SELECT + UPDATE が必要です。 INSERT のみを許可すると、新しいアップロードはできますが、ファイルの置き換え（upsert）は静かに失敗します。3 つすべてが必要です。

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

Supabase CLI

常に --help でコマンドを確認してください — 推測しないでください。CLI の構造はバージョン間で変更されます。

supabase --help                    # すべてのトップレベルコマンド
supabase <group> --help            # サブコマンド（例：supabase db --help）
supabase <group> <command> --help  # 特定のコマンドのフラグ

Supabase CLI の既知の注意点：

• supabase db query には CLI v2.79.0+ が必要 → フォールバックとして MCP execute_sql または psql を使用
• supabase db advisors には CLI v2.81.3+ が必要 → フォールバックとして MCP get_advisors を使用
• 新しいマイグレーション SQL ファイルが必要な場合は、必ず最初に supabase migration new <name> で作成してください。マイグレーションファイル名を考えたり、期待される形式を記憶に頼ったりしないでください。

バージョン確認とアップグレード： 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 を使用します。エージェントで認証フローをトリガーし、ブラウザで完了し、セッションをリロードするようにユーザーに指示してください。

Supabase ドキュメント

Supabase 機能を実装する前に、関連するドキュメントを見つけてください。以下の方法を優先順位順に使用してください：

1. MCP search_docs ツール（推奨 — 関連スニペットを直接返します）
2. ドキュメントページをマークダウンとして取得 — 任意のドキュメントページは、URL パスに .md を追加することで取得できます。
3. Supabase 固有のトピックについて、どのページを見ればよいかわからない場合のウェブ検索。

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

スキーマ変更を行うには、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

リファレンスガイド

• スキルフィードバック → references/skill-feedback.md ユーザーがこのスキルが誤ったガイダンスを提供した、または情報が不足していると報告した場合は必ず読んでください。