supabase

Supabase

管理 API を通じて Supabase プロジェクトに対して SQL を実行します。データのクエリ、 スキーマの変更（DDL）、ポリシー（RLS）、ストレージのメタデータ、マイグレーションに対応しています。SQL は 管理 API の権限で実行されるため、データベースへの管理者レベルのアクセスとして扱ってください。

すべての操作は、次の 3 つのコマンドを備えた 1 つのスクリプト scripts/supabase.sh を通じて行います。

• env — 接続環境を管理します（environments.json に保存）
• sql — SQL 文字列を実行します
• sql-file — ファイル内の SQL を実行します

環境

各環境は environments.json（Git の追跡対象外、chmod 600）内の名前付きエントリで、 url と省略可能な access_token を保持します。env サブコマンドで管理します。

# List configured envs (tokens masked)
scripts/supabase.sh env list

# Add an env (--url required; --access-token and --description optional)
scripts/supabase.sh env add dev  --url https://<dev-ref>.supabase.co  --access-token sbp_...
scripts/supabase.sh env add prod --url https://<prod-ref>.supabase.co --description "Production"

# Update one or more fields on an existing env
scripts/supabase.sh env update dev --url https://<new-ref>.supabase.co --access-token sbp_...

# Inspect one env: human (default), json, or shell export
scripts/supabase.sh env get dev
scripts/supabase.sh env get dev --format json
scripts/supabase.sh env get dev --format export

# Remove an env (refused if it is the only one)
scripts/supabase.sh env remove prod

# Verify at least one env is configured (non-zero exit otherwise)
scripts/supabase.sh env check

スクリプトが適用するルールは次のとおりです。

• env add には --url が必要です。環境名は一意でなければなりません。
• 最後に残った環境は env remove で削除できません。
• アクセストークンはシークレットです。環境に保存されていない場合は、シェルの SUPABASE_ACCESS_TOKEN が代わりに使用されます。
• environments.json はスキルのルートから読み込まれます。すでに存在する場合は ~/.config/claude/supabase-environments.json から読み込まれます。

スクリプトが no environments configured または SUPABASE_URL not set と報告した場合、 ユーザーはまだセットアップを完了していません。env add を実行して最初の環境を作成するか、 README を参照するよう案内してください。

環境の選択

コマンドごとに --env <name> を指定して環境を選びます。解決の優先順位は次のとおりです。

1) --env <name> set            -> use that env from environments.json
2) SUPABASE_URL + TOKEN exported -> use those exported values
3) exactly one env configured  -> use it (--env optional)
4) multiple envs, none named   -> error: pass --env <name>

ユーザーが環境を指定した場合（「prod で」「dev で」など）は、--env <name> を渡します。 環境が複数あり、ユーザーが指定していない場合は、実行前にどの環境を使うか確認してください。

SQL の実行

# Run a SQL string
scripts/supabase.sh sql --env dev "SELECT * FROM users LIMIT 5"
scripts/supabase.sh sql --env prod "SELECT count(*) FROM users"
scripts/supabase.sh sql --env dev "INSERT INTO users (name, email) VALUES ('Alice', '[email protected]')"

# Run SQL from a file (prefer for long or multi-statement SQL)
scripts/supabase.sh sql-file --env dev ./migrations/001_init.sql

• SQL は引用符で囲みます。内部の二重引用符はエスケープしてください（例：ポリシー名の \"items_read_own\"）。
• sql は文字列全体を 1 つのクエリとして送信するため、; で区切られた複数の文もまとめて実行されます。
• $ を含む SQL — ドル引用符で囲まれた関数／トリガーの本文（$$ … $$）や位置パラメーター（$1）など — は sql-file で実行する必要があります。二重引用符で囲んだ sql 引数では、シェルが $$（PID に展開）と $1 を展開し、 文が破損するためです。ファイルの内容はそのまま送信されるため、sql-file は安全です。

出力の読み取り

出力は、管理 API から返された生の JSON を jq に通したものです。

• クエリが成功すると、結果が JSON として返されます（SELECT の場合は行オブジェクトの配列です）。
• クエリが拒否されると、message フィールドを含むオブジェクトが返されます。例： {"message": "syntax error at or near ..."}。message キーのみのオブジェクトかどうかを確認して失敗を判定してください。SQL が拒否されても、HTTP 呼び出しと終了コードは通常成功扱いになります。

安全性

これらのコマンドは管理 API（管理者）の権限で実行されるため、誤った文によってデータが削除されたり、本番プロジェクトが破損したりする可能性があります。実行前に次の点を確認してください。

• 破壊的な文はユーザーに確認してください — DROP、TRUNCATE、および WHERE 句のない DELETE／UPDATE。特に本番環境に対する操作では必ず確認してください。
• 書き込み先の環境を確認してください。 環境が複数設定されていて、要求が書き込みまたは DDL の場合は、実行前に対象の環境（--env <name>）を確認してください。書き込み時に環境が自動選択される状態にしてはいけません。
• まず読み取り専用で調査してください。 データやスキーマを変更する前に、SELECT ... LIMIT で確認することを優先してください。
• マイグレーションをアトミックにしてください。 複数段階の変更は、途中で失敗した場合にロールバックされるよう、sql-file を使って BEGIN; ... COMMIT; で囲んでください。CREATE INDEX CONCURRENTLY はトランザクション内で実行できないため、単独の文として実行してください。
• マイグレーションを再実行可能にしてください。 CREATE TABLE IF NOT EXISTS、CREATE OR REPLACE、ADD COLUMN IF NOT EXISTS、DROP ... IF EXISTS を優先してください。

SQL リファレンス

DDL、インデックス、列挙型、ビュー、関数／RPC、トリガー、RLS、データパターン（upsert、JSONB）、pgvector の類似検索、ストレージ、スキーマのイントロスペクションを含む、すぐに使える例については、references/sql-cookbook.md を参照してください。