supabase

Supabase

Supabase は、単一の不透明なバックエンドではなく、複数の独立してバージョン管理されるサービスを備えた Postgres 中心のシステムとして扱ってください。マネージドプラットフォーム、CLI のローカルスタック、公式のセルフホスト用 Compose スタックは概念を共有していますが、動作環境はそれぞれ異なります。コマンドを選ぶ前に、タスクの対象を特定してください。

運用上の契約

1. 変更を加える前に、対象と現在の状態を確認します。マネージドプロジェクト、CLI のローカルスタック、セルフホスト用 Compose のいずれか、CLI とサービスのバージョン、プロジェクトのリンク状態、データベースとマイグレーションの状態、有効なサービス、公開 URL、バックアップとロールバックの手順を確認してください。
2. 最初の変更を加える前に、対象、範囲、ロールバックの手順を確認してください。読み取り専用の調査は確認なしで進められます。対象を明示したデプロイまたは変更の明示的なユーザー指示があれば、この確認条件を満たします。
3. 公開可能なキーはクライアント側でのみ使用し、シークレットキーとサービスロールキーはサーバー側でのみ使用してください。シークレットキー、データベースのパスワード、JWT 署名情報、SMTP 認証情報、パスワードを含む接続文字列を、レポートに出力、コミット、または記載しないでください。
4. データベースの変更には、バージョン管理されたマイグレーションを使用してください。生成された差分はドラフトとしてレビューし、マイグレーションチェーン全体を再適用し、RLS の否定ケースをテストしてから、デプロイ前にクライアント型を再生成してください。
5. セルフホスティングでは、公式の supabase/supabase Docker ディレクトリと、その setup.sh、run.sh、更新ノート、テストを使用してください。ユーザーが明示的に希望し、機能が失われることを了承していない限り、機能を縮小した Compose スタックを独自に作成しないでください。
6. 引き渡し時点で検証してください。コンテナの正常性は API の正常性を示すものではなく、API の応答は認可の証明にはならず、バックアップがあるだけでは復旧の証拠になりません。

パスを選択する

必要な内容	まず読む資料
サービス、信頼境界、キー、環境の違いを理解する	アーキテクチャと境界
CLI をインストールして使用する、ローカルのワークフローを確立する、またはマネージド Functions、シークレット、ブランチ、SSL 強制、CIDR 制限、ネットワーク禁止を運用する	ローカル開発と CLI
スキーマ、マイグレーション、シードデータ、RLS ポリシー、テスト、生成型を作成する	データベース開発とテスト
Auth、REST、Realtime、Storage、Edge Functions を使って構築する	アプリケーションサービス
公式 Docker スタックをデプロイまたは強化する	セルフホスティングのデプロイ
セルフホスト型インスタンスをバックアップ、復元、更新、アップグレード、監視、または復旧する	管理と復旧
コンテナの異常、誤った URL、認証の失敗、構成のずれ、マイグレーションの失敗を診断する	トラブルシューティング
評価シナリオを使って、エージェントが Supabase をどれだけ活用できるか評価する	エージェント評価ハーネス
主張が最新か、信頼できる情報源が網羅されているか確認する	情報源インデックス

最初に行う読み取り専用の調査

supabase --version
supabase status --output json       # CLI local project; may fail when stopped
supabase migration list            # linked/local migration comparison when configured
docker compose config --quiet       # self-hosted project directory
docker compose ps --format json

マネージドプロジェクトでは、プロジェクト参照、リンク状態、対象環境、直接の本番環境への変更によって構成のずれが生じていないかも確認してください。セルフホスティングでは、更新前に docker/CHANGELOG.md、docker/versions.md、有効な COMPOSE_FILE、ディスクとメモリの余裕、バックアップの証拠を確認してください。

開発ループ

プロジェクトごとに、スキーマ作成モードを 1 つ使用してください。

# Declarative: edit supabase/schemas/*.sql first
supabase db diff -f change-name

# Imperative: write the generated migration directly
supabase migration new change-name

# Both paths converge on the same checks
supabase db reset
supabase test db
supabase gen types --lang typescript --local > database.types.ts

生成されたマイグレーションはすべてレビューしてください。db diff では DML は取得されず、ポリシー名の変更、ビュー、一部の権限には既知の取得漏れがあります。db reset はローカルデータベースに対する破壊的操作ですが、再現性を証明する手段です。マイグレーションを順番に適用し、その後にシードデータを適用します。

リンク先へのデプロイ前に、次の操作を行ってください。

supabase migration list
supabase db push --dry-run
supabase db push

本番環境に対して db reset --linked や db push --include-seed を使用しないでください。コマンドのデフォルトは異なるため、別のデータベースに誤って接続するおそれがある場合は、--local または --linked を明示してください。

セルフホストのライフサイクル

デプロイメントディレクトリにチェックインされている公式ヘルパースクリプトを使用します。

sh run.sh config
sh run.sh compose-config >/dev/null
docker compose config --quiet
sh run.sh start
sh run.sh status
sh tests/test-self-hosted.sh http://localhost:8000

本番環境では、実際のシークレット、正しい外部 URL、TLS 終端、WebSocket 転送、保護されたデータベースポート、必要に応じた SMTP／プロバイダーの設定、バックアップ、復元テストが必要です。公式のデフォルトスタックでは、Kong は 8000、Kong TLS は 8443、Supavisor は 5432／6543 で公開されます。意図を明確にしてバインドまたはファイアウォールを設定してください。

検証マトリクス

レイヤー	最低限の証拠
設定	docker compose config --quiet が成功すること。プレースホルダーのシークレットがないこと。URL がプロキシ／認証コールバックと一致していること
ランタイム	必須のすべてのサービスが実行中かつ正常であること。範囲を限定したログに、現在進行中の失敗ループがないこと
データベース	想定される Postgres のバージョンであること。マイグレーション履歴が一致すること。代表的なクエリが成功すること
API ゲートウェイ	Studio の認証境界、Auth のヘルス、正しいキーのロールを使用した REST、JWKS エンドポイント
認可	anon／authenticated ユーザーとして、RLS の許可テストと拒否テストを実施すること。service-role によるバイパスを証拠として使用しないこと
ストレージ	バケット／オブジェクトのアップロード、ダウンロード、整合性、署名付き URL、クリーンアップ
Realtime	WebSocket のサブスクリプションとデータベース変更の配信を確認すること。HTTP ルートだけで済ませないこと
Functions	/functions/v1 を通じて実際の関数を呼び出すこと。認証の動作とログを確認すること
復旧	独立した論理／物理バックアップと、別のテスト対象への復元

厳守すべき境界と注意点

• CLI のローカルスタックは開発専用です。デフォルトの認証情報を使用し、TLS と本番環境向けのレート制限はありません。パブリックに公開しないでください。
• 公開スキーマのすべてのテーブルで RLS を有効にする必要があります。公開可能なキーをクライアントで安全に使用できるのは、権限付与と RLS ポリシーが正しく設定されている場合に限られます。拒否される経路もテストしてください。
• シークレットキー／service-role キーは RLS をバイパスします。ブラウザー用バンドル、モバイルアプリ、ログ、サンプル、チャット出力に含めてはなりません。
• 現在のセルフホスト構成では、API_EXTERNAL_URL に /auth/v1 が含まれます。SITE_URL はアプリケーションのランディング URL であり、必ずしも Supabase のホスト名とは限りません。
• Compose 構成は、テスト済みのリリースセットとして更新してください。任意の latest イメージを個別に取得すると、互換性のないサービス構成になることがあります。
• 新しいセルフホストデプロイメントでは、現在のデフォルトは Postgres 17 です。Postgres 15 のデータディレクトリを指定してはなりません。データベースデータと、pgsodium のルートキーを含む db-config ボリュームの両方を保持してください。
• docker compose down -v、reset.sh、リモートリセット、キーの再生成、マイグレーション履歴の修復は、データ、アクセス権、セッションを破壊する可能性があります。復旧の証拠を確認したうえで、個別の操作として実施してください。
• セルフホストで利用できる機能は、マネージドプラットフォームと同等とは限りません。バックアップ、可用性、アップグレード、不正利用対策、SMTP、可観測性、サポートは、運用者の責任です。

完了条件

要求された成果物または状態が存在し、関連する境界で検証されている場合にのみ、タスクは完了です。ローカルプロジェクトはマイグレーションから再現でき、テストに合格していること。デプロイメントは設定、ヘルス、サービスレベルのスモークテストに合格していること。更新にはロールバックの証拠と更新後の確認があること。バックアップは別の対象に復元済みであること。また、コミットまたは報告された出力にシークレット情報が含まれていないこと。