supabase-migration-deep-dive

Supabase マイグレーションの詳細

概要

Supabase のマイグレーションは、CLI で管理するタイムスタンプ付きの SQL ファイルで、環境間のスキーマ変更を追跡します。このスキルでは、@supabase/supabase-js の実際の CLI コマンドと createClient を使用して、マイグレーションの全ライフサイクル（作成、ダウンタイムなしのスキーマ変更、バッチバックフィル、バージョン管理、ロールバック、TypeScript 型の生成）を扱います。

使用する場面： 新しいデータベースマイグレーションの作成、ダウンタイムなしでの本番スキーマの変更、列の追加後に既存データをバックフィルする場合、開発／ステージング／本番環境間でのマイグレーション履歴の管理、失敗したマイグレーションのロールバック、TypeScript 型の再生成。

前提条件

• Supabase CLI がインストールされていること：npm install -g supabase または npx supabase --version
• プロジェクトに @supabase/supabase-js v2 以降がインストールされていること
• ローカルで Supabase が起動していること：npx supabase start
• PostgreSQL の DDL とトランザクションの動作を理解していること

手順

ステップ 1：マイグレーションの作成と管理

各マイグレーションをタイムスタンプ付きの SQL ファイルとして作成し、DDL を記述して、ローカルでリセットしてテストした後、db push を使って各環境に反映します：

npx supabase migration new add_profiles_table   # create timestamped SQL file
npx supabase migration list                      # show applied/pending status
npx supabase db reset                            # apply + seed locally (destructive)
npx supabase gen types typescript --local > lib/database.types.ts
npx supabase link --project-ref "<ref>" && npx supabase db push   # promote to remote

スキーマの適用時に完全な状態になるよう、RLS を有効化し、ポリシー、インデックス、トリガーを同じファイルに記述します。profiles テーブル（RLS ポリシー、メールアドレスのインデックス、サインアップトリガー、updated_at トリガーを含む）の完全なマイグレーション例、およびローカルテストとステージング／本番環境への反映コマンドについては、マイグレーションの作成を参照してください。

ステップ 2：ダウンタイムなしのマイグレーションパターン

本番環境のスキーマ変更では、テーブルのロックを避ける必要があります。基本ルール：Postgres 11 以降では、デフォルト値を持つ NULL 許容列の追加はロックフリーです。CREATE INDEX CONCURRENTLY を使うインデックスの作成は、-- supabase:disable-transaction を指定したマイグレーションで行います。列の名前変更や型変更は、インプレースの ALTER COLUMN ではなく、2 段階（新しい列の追加、バックフィル、同期トリガーの追加、古い列の削除）で行います。安全に列を追加する例：

-- Nullable column with a default does NOT lock the table in Postgres 11+
ALTER TABLE public.orders ADD COLUMN status text DEFAULT 'pending';
-- Then, in a separate -- supabase:disable-transaction migration:
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_status ON public.orders(status);

同期トリガーを使った2段階の列名変更、追加・バックフィル・切り替えによる安全な型変更、マイグレーション中にクエリのレイテンシをサンプリングする SDK のヘルスチェックなど、パターンの全容については、ダウンタイムなしのパターンを参照してください。

ステップ 3：データのバックフィル、バージョン管理、ロールバック

SDK を使ったバッチバックフィルのパターン、環境間のスキーマバージョン管理、3 つのロールバック戦略（補完マイグレーション、修復、フィーチャーフラグ）、およびマイグレーション後の型の再生成については、データのバックフィル、バージョン管理、ロールバックを参照してください。

出力

このスキルでは、以下を行います。

• マイグレーション作成ワークフロー — 説明的な SQL ファイルを使った npx supabase migration new とローカルテスト
• ダウンタイムなしのパターン — 安全な列の追加、2段階の列名変更、並行インデックス作成
• バッチバックフィル — 進捗ログとレート制限を用いた、SDK ベースの行ごとの更新
• スキーマのバージョン管理 — 環境の比較に使う supabase migration list と db diff
• ロールバック戦略 — 補完マイグレーション、migration repair、フィーチャーフラグを使ったスキーマ変更
• 型の再生成 — スキーマを変更するたびに実行する supabase gen types typescript
• マイグレーションの反映 — ローカルからステージング、本番へと進める db push ワークフロー

エラー処理

エラー	原因	解決策
migration has already been applied	適用済みのマイグレーションを再実行した	supabase migration list を使って状態を確認します。適用済みのマイグレーションは変更しないでください
cannot run inside a transaction block	トランザクション内での CREATE INDEX CONCURRENTLY	マイグレーションファイルの先頭に -- supabase:disable-transaction コメントを追加します
マイグレーション後に column does not exist	マイグレーションが適用されていないか、型が古い	supabase db push を実行してから supabase gen types typescript を実行します
バックフィル中に deadlock detected	同じ行への同時更新	バッチサイズを小さくし、指数バックオフによる再試行ロジックを追加します
大きなテーブルで statement timeout	マイグレーションの所要時間がタイムアウトを超えている	マイグレーションで statement_timeout を増やします：SET statement_timeout = '300s';
migration repair が失敗した	バージョン番号が正しくない	supabase migration list に表示される正確なバージョン（タイムスタンプのプレフィックス）を使います
db diff で予期しない変更が表示される	SQL Editor での手動変更によるスキーマのドリフト	supabase db pull を実行して、手動変更をマイグレーションとして取り込みます
マイグレーション後に型が一致しない	生成された型が新しいスキーマと一致しない	database.types.ts を削除し、--local または --linked から再生成します

例

実際のカラム追加における作成・書き込み・テスト・プッシュのワークフロー：

npx supabase migration new add_tags_to_projects
cat > supabase/migrations/20260322150000_add_tags_to_projects.sql << 'SQL'
ALTER TABLE public.projects ADD COLUMN tags text[] DEFAULT '{}';
CREATE INDEX idx_projects_tags ON public.projects USING GIN(tags);
SQL
npx supabase db reset
npx supabase gen types typescript --local > lib/database.types.ts
npx supabase link --project-ref <staging-ref> && npx supabase db push

完全な実例を3つ紹介している例を参照してください。ローカルから本番環境へのマイグレーションワークフロー全体、SDK から進捗を追跡するバッチバックフィル、ALTER TYPE の代わりに CHECK 制約を使う安全な列挙型マイグレーションを確認できます。

リソース

• データベースマイグレーション — Supabase ドキュメント
• Supabase CLI のマイグレーションコマンド
• supabase db push — Supabase ドキュメント
• supabase gen types — Supabase ドキュメント
• ダウンタイムのない PostgreSQL マイグレーション
• supabase db diff — Supabase ドキュメント

次のステップ

• マイグレーション後の高度なトラブルシューティングについては、supabase-advanced-troubleshooting を参照してください
• 複数環境へのマイグレーションの昇格については、supabase-multi-env-setup を参照してください
• スキーマ変更後のパフォーマンス調整については、supabase-performance-tuning を参照してください