マイグレーションと型

スキーマの変更をバージョン付きの SQL として適用・記録する方法、スキーマを SQL でダウンロードする方法、supabase-js 用の TypeScript 型の作り方。

マイグレーションと型

スキーマを変更する SQL をバージョン付きのファイルとして残しておくと、同じ変更をほかのプロジェクト（ステージング → 本番）に同じ順序で適用し直せます。run_sql で変更したものは記録が残りません。

list_migrations             適用したマイグレーションのバージョン・名前・時刻（古い順）
apply_migrations            まだ適用していないものだけをバージョン順に実行し、記録します
remove_migration_record     記録を1つ削除します（作られたものはそのまま）
dump_schema                 今のスキーマを作り直せる SQL として
generate_typescript_types   supabase-js の Database 型

適用のされ方

マイグレーション1つがトランザクション1つです。失敗すると、そのマイグレーションだけをまるごと元に戻して止まります。
バージョンは数字で（通常は YYYYMMDDHHMMSS）、数値の大きさの順に実行します。すでに記録されたバージョンは飛ばします。
すでに適用された最後のバージョンより前のバージョンが新しく来ると拒否します。あとから統合したブランチなら include_all: true です。
記録されたあとで内容が変わったファイルは再実行せず、drifted として知らせます。直すには新しいマイグレーションを書いてください。
run_sql と同じ権限（書き込みトークン、オーナー・管理者・開発者）で、プロジェクトの service_role として実行します。
データスキーマが search_path の先頭にあるため、create table notes (...) のように名前だけを書けば十分です。

記録はどこに

プロジェクトの oneend_migrations テーブルです。オーナーは SQL で読めます。RLS が有効でルールがないため、公開キーでは見えません。 supabase_migrations.schema_migrations と同じ役割です。

スキーマをファイルに、型をコードに

dump_schema は、型・シーケンス・テーブルと制約・外部キー・インデックス・関数・ビュー・トリガー・RLS とルールを SQL で返します。既存のプロジェクトをマイグレーションで管理し始めるときは、これを最初のマイグレーションとして保存し、 apply_migrations に record_only: true を付けて記録だけを残してください。実行すると、すでにあるテーブルとぶつかります。

generate_typescript_types は supabase gen types typescript と同じ形（Tables の Row/Insert/Update/Relationships、 Views、Functions の Args/Returns、Enums、CompositeTypes）を返します。スキーマ名は public です。

同じことを HTTP で

GET    /projects/<ref>/migrations
POST   /projects/<ref>/migrations          {migrations: [{version, name, sql}], include_all, record_only, dry_run}
DELETE /projects/<ref>/migrations/<version>
GET    /projects/<ref>/schema              {sql, objects}
GET    /projects/<ref>/types/typescript?schema=public   {types}