AIものさし

Supabase CLIのremote migration history不一致を安全に修復する

Supabase CLIのmigration history不一致を、接続先・local files・remote履歴・schemaに分けて照合する方法を解説します。

AIものさし編集部

supabase db pushがmigration historyの不一致で止まったとき、まずsupabase migration repairを実行するのではなく、接続先project・ローカルmigration files・remoteの履歴・実際のschemaを別々に照合します。Supabase CLIはローカルのsupabase/migrationsとremoteのsupabase_migrations.schema_migrationsを比較し、履歴にないmigrationを順番に実行します。したがって、履歴の行が欠けている状態と、SQL自体がremoteへ適用されていない状態を取り違えると、既にある変更を再実行したり、未適用SQLを適用済みと誤記録したりする危険があります。

目次

最初に対象projectを確定する

診断はread-onlyのmigration一覧から始めます。CLIのmigration listはローカルmigrationとremote履歴の差を表示します。コマンド実行前に、作業ディレクトリ、Supabase CLI version、linked projectを確認し、productionとstagingのどちらを見ているか記録してください。remoteを読む操作では--linkedを明示します。

supabase --version

supabase status

supabase projects list

supabase migration list --linked

supabase projects listで現在linkされているprojectを確認し、project refと対象環境を記録します。コマンドの既定targetはCLI commandごとに異なる場合があるため、remoteを読む操作では--linkedを明示します。migration一覧のLocalとRemoteの列はmigration timestampの有無を比較するもので、SQL内容やschemaの同一性を証明するものではありません。

migration listの取得ができない、またはlinked projectが期待と違う場合は、その時点でrepairやpushを続けません。別workspaceのsupabase/config.toml、現在の作業ディレクトリ、CLI profile、環境変数、project refを照合してください。認証先が曖昧なままのdb pushやmigration repairは、別環境へ履歴を書き込む可能性があります。

migration historyと実際のschemaを分ける

Supabaseのmigration管理には二つの状態があります。Git上のtimestamp付きmigration filesは「何を適用する予定か」を示し、remoteのmigration history tableは「どのtimestampを適用済みと記録したか」を示します。一方、remote schemaは「SQLによって現在どの構造が存在するか」を示します。この三つは一致している必要がありますが、migration listだけでschemaまで検査できるわけではありません。

表は横にスクロールできます

見えている状態可能性次に行う確認
LocalだけにtimestampがあるSQL未適用、remote履歴欠落、または別projectを見ているproject refを確認し、remote schemaに変更が既にあるかを調べる
Remoteだけにtimestampがあるlocal migration fileがない／改名された、別branch、手動反映file履歴とremote schemaを確認し、必要ならschemaをpullしてmigration化
両方にtimestampがあるのにpushが失敗SQL内容差、依存関係、failed migration、別のCLI/project状態詳細なCLI error、schema差分、migration fileと環境を確認
履歴は一致するがschema差分があるremoteで直接変更、migration内容の差、diff engineの制約schema diffとremote changeの由来を確認

どの行がLocal-onlyまたはRemote-onlyかが分かったら、まずmigration fileのtimestamp、ファイル名、内容、Git上の変更履歴を確認します。ファイルをrename・削除して一覧を見かけ上そろえるのは後回しです。手動でremoteへ加えたschema変更を疑う場合は、現状をmigrationとして保存し、以後はmigration経由に戻す必要があります。Supabaseはteam workflowでremote databaseを直接変更せず、schema変更はmigration filesから適用する運用を案内しています。

原因を切り分ける順番

次の手順は原因を確定するための順序です。ここでは履歴を修復せず、まず観測情報をそろえます。

  1. 接続先を確認する。 supabase projects listとsupabase migration list --linkedを実行し、期待するproject ref・環境と一致するか記録する。意図しないprojectなら、link設定を直す前にローカル設定の所有者と環境を確認する。

  2. ローカルmigration一覧を確認する。 supabase/migrationsのtimestamp、重複timestamp、欠落・改名されたfile、未commitの差分を調べる。複数branch間で同じmigrationを別内容にしていないかも確認する。

  3. Local/Remoteの差を分類する。 Local-only、Remote-only、両方にあるmigrationを一覧にし、エラーに含まれるversionだけでなく前後の履歴も確認する。

  4. 実schemaを読み取り比較する。 履歴が示す状態と実際のremote schemaが合うか確認する。必要に応じて、CLI versionとprojectのdiff engineを確認したうえでsupabase db diff --linkedを使い、ローカルmigrationを適用したshadow databaseとlinked remoteのschema差を調べる。diff出力がないことだけを、全データや全機能の一致証明にしない。

  5. migrationの内容と実行結果を確認する。 対象SQLがtransaction内で完了したか、部分実行され得る処理を含むか、既存objectと衝突しないかを調べる。migrationのログ、deployment履歴、変更者の記録があれば突き合わせる。

  6. 原因を一つに絞れなければ止める。 schema・履歴・実行記録のいずれかが不明なら、migration repairやdb pushを実行せず、DB ownerへ確認事項を渡す。

supabase db diff --linkedはremote schemaとローカルmigrationから構築したshadow側を比較するための補助です。出力は使用中のdiff engineと対象schemaに依存し、対応しないobjectや管理schema内の一部変更を完全に表現できない場合があります。remote project上のデータ値、functionの全挙動、アプリケーション互換性をテストするコマンドでもありません。生成SQLをmigrationとして採用する場合は、別途内容をレビューし、非production環境で確認します。

migration repairを使える条件

公式CLIのsupabase migration repair <version> --status applied|revertedは、remote migration history tableの記録を変更します。appliedは履歴へtimestampを追加し、revertedは履歴からそのtimestampの記録を削除します。このコマンドは対応するmigration SQLを実行したり、schemaを元に戻したりしません。したがって、実schemaの状態を確認せずに履歴だけを書き換えると、次回のdb pushが誤ったmigrationを適用する危険があります。

使用判断は、migrationの実態と履歴記録が逆転していると確認できた場合に限ります。たとえば、migrationのSQLが既にremote schemaへ適用済みなのに履歴だけ記録されていない場合は、対象SQLが完全に反映されていることを検証したうえでappliedを検討できます。逆に、履歴に適用済みとあるのにSQLが実行されていないと確認できた場合はrevertedを検討します。判断はversion単位で行い、周辺versionをまとめて一括修正しないでください。

supabase migration repair <migration_timestamp> --status applied

または、該当SQLが適用されていないと確認できた場合

supabase migration repair <migration_timestamp> --status reverted

上記はremote historyへ書き込む操作例です。まずstagingまたは別の検証projectで同じ履歴パターンを再現できるか確認し、対象project ref、migration timestamp、schema evidence、承認者、変更前のmigration listを記録します。実行後は同じsupabase migration list --linkedを再取得し、対象のLocal/Remote状態が想定どおりになったか確認します。その後もsupabase db push --dry-runなどで予定されるSQLを確認し、予期しないpending migrationが出たら実行を止めます。

remoteで直接変更した場合

migration historyだけの問題ではなく、DashboardやSQL Editorでremote schemaを直接変更していた場合は、単純なrepairでは解決しません。Supabaseの案内では、remoteの現在schemaをsupabase db pullでmigration fileとして取り込み、レビュー・commitしたうえで、以後の変更をmigration経由へ戻します。

db pullはローカルのmigration fileを作成し、設定済みdiff engineやCLI versionに応じて出力が変わります。auth、storageなどmanaged schema上の独自変更がある場合も、どのengine・versionで何が含まれるか確認します。生成されたSQLとmigration history変更の確認を終えるまでは、Productionの別migrationをpushしないでください。既にremoteへ加えた変更の内容・所有者が不明なら、現状のschemaと関係者の変更履歴を照合してからmigration化します。

よくある不一致パターン

表は横にスクロールできます

原因観察の手掛かり次の対応
remote projectの取り違えproject refまたは環境名が予定と異なる正しい環境への接続を明示し、履歴比較をやり直す
手動のschema変更remoteにobjectはあるが該当migration historyがない変更由来を調べ、schemaをmigrationとして取り込む
migration fileの欠落・改名RemoteだけにtimestampがあるGit branch・merge・rename履歴を探し、正本migrationの有無を確認
SQL適用後に記録失敗schema変更がある一方、history rowがないSQL全体の結果を確認し、履歴記録だけ直せる根拠を作る
適用済み記録だがSQL未実行history rowはあるがschemaに変更がない部分適用・途中失敗・別schemaを確認し、必要ならversion単位でrevertedを検討
CLI/diff engine差同じ状態でもdiff出力が異なるCLI version、config.toml、pg-delta/migraの設定と制約を記録する

やってはいけない復旧

次の操作は、migration history不一致の即席修復として使わないでください。

  • remote schemaが正しいか確認せず、Local-only migrationをすべてappliedにする。

  • 履歴を合わせる目的だけでmigration SQLを編集・削除・改名する。

  • 意味を確認せず、Remote-only migrationを一括でrevertedにする。

  • db pushを何度も試し、どのSQLがどこまで適用されたかを曖昧にする。

  • productionを対象にsupabase db reset --linkedを実行する。Supabaseはlinked remote resetを破壊的操作として説明し、throwawayのdev/staging専用としています。

  • repairをSQL rollbackと誤認し、データやschemaが戻ったと思い込む。

安全な修復は、一覧を合わせることではなく、migration file・remote history・実schemaの三つが同じ状態を表すように戻すことです。まずproject refとLocal/Remote一覧を確認し、次にschema差分と対象SQLの実行状態を調べます。履歴だけが間違っていると証明できた場合に限り、version単位でmigration repairを検討します。remote schemaが手動変更されている場合は、その変更をreview可能なmigrationとして記録します。productionでは、project確認・変更レビュー・dry-run・backup/rollback計画と専用のrelease承認を経てから適用してください。

参考資料

確認日：2026-10-15