マイグレーション

番号付きの SQL ファイルを順に適用し、適用履歴はデータベースのテーブルに記録します。

my-app/
  migrations/
    0001_init.sql
    0002_add_posts.sql

runlot pg migrate

0001_init
0002_add_posts

適用するマイグレーションがない場合は、CLI がその旨を知らせます。

ファイル名の規則

ファイル名は NNNN_名前.sql の形式である必要があります。番号は正の整数でなければなりません。既定のディレクトリは <プロジェクト>/migrations で、--migrations オプションで変更できます。

適用履歴

適用したマイグレーションは、データベースの次のテーブルに記録されます。

CREATE TABLE IF NOT EXISTS schema_migrations (
  version    int  PRIMARY KEY,
  name       text NOT NULL,
  sha256     text NOT NULL,
  applied_at timestamptz NOT NULL DEFAULT now()
)

いつどのマイグレーションが適用されたかを、SQL からすぐに確認できます。

runlot pg execute -c "select version, name, applied_at from schema_migrations order by version"

ファイル 1 つを 1 つのトランザクションとして適用します

各ファイルの DDL と適用履歴の記録は、同じトランザクションで実行されます。実行中にエラーが発生すると、ファイルの内容と履歴がまとめてロールバックされるため、一部だけが適用された状態は残りません。

不整合がある場合は適用しません

次の状況では、何も実行せずに停止します。

すでに適用したファイルの内容が変更されている場合（sha256 の不一致）
適用履歴にはあるがファイルが存在しない場合
すでに適用した番号より小さい番号の新しいファイルが追加された場合

すでにデプロイしたマイグレーションファイルは変更せず、新しい番号のファイルとして変更内容を追加してください。

ORM のマイグレーションツールと併用する

prisma migrate と drizzle-kit は SQL の生成のみに使用してください。生成された SQL を migrations/NNNN_*.sql に移したうえで、runlot pg migrate で適用します。

# Prisma
npx prisma migrate diff --from-schema-datamodel prisma/schema.prisma \
  --to-schema-datasource prisma/schema.prisma --script > migrations/0003_posts.sql

# Drizzle
npx drizzle-kit generate
cp drizzle/0003_*.sql migrations/0003_posts.sql

ワーカーの中では prisma migrate deploy を実行できません。ワーカーに Prisma の migration engine がないためです。

TypeORM の synchronize と Sequelize の sync({ force: true }) は、ランタイムで DDL を実行するため動作します。開発中は便利ですが、本番のマイグレーション方法としては使用しないでください。

SQL を一度だけ実行したい場合

runlot pg execute -c "alter table posts add column pinned boolean not null default false"
runlot pg execute -f ./fix.sql

このコマンドで実行した SQL は、適用履歴には残りません。スキーマ変更はマイグレーションファイルで管理する方法をおすすめします。