マイグレーション

データベースマイグレーションは、データベースをバージョン管理する方法です。各マイグレーションは migrations フォルダー内の .sql ファイルとして保存されます。migrations フォルダーは、最初のマイグレーションを作成したときにプロジェクトディレクトリに作られます。データベース開発を通じて、変更を保存し、追跡できます。

機能

現時点のマイグレーションシステムは、シンプルで実用的であることを目指しています。いまの実装では、次の操作ができます。

空のマイグレーションファイルを作成する。
未適用のマイグレーションを一覧表示する。
残りのマイグレーションを適用する。

migrations フォルダー内の各マイグレーションファイルには、ファイル名にバージョン番号が付きます。ファイルは連番順に並びます。各マイグレーションファイルは SQL ファイルで、実行するクエリを記述します。

Wrangler のカスタマイズ

デフォルトでは、マイグレーションは Worker プロジェクトディレクトリの migrations/ フォルダーに作成されます。マイグレーションを作成すると、適用済みマイグレーションの記録がデータベース内の d1_migrations テーブルに残ります。

この場所とテーブル名は、Wrangler ファイルの D1 バインディング内でカスタマイズできます。

{
	"d1_databases": [
		{
			"binding": "<BINDING_NAME>", // i.e. if you set this to "DB", it will be available in your Worker at `env.DB`
			"database_name": "<DATABASE_NAME>",
			"database_id": "<UUID>",
			"preview_database_id": "<UUID>",
			"migrations_table": "<d1_migrations>", // Customize this value to change your applied migrations table name
			"migrations_dir": "<FOLDER_NAME>", // Specify your custom migration directory
			"migrations_pattern": "<GLOB>" // Optional: discover migrations using a glob pattern (see below)
		}
	]
}

[[d1_databases]]
binding = "<BINDING_NAME>"
database_name = "<DATABASE_NAME>"
database_id = "<UUID>"
preview_database_id = "<UUID>"
migrations_table = "<d1_migrations>"
migrations_dir = "<FOLDER_NAME>"
migrations_pattern = "<GLOB>"

入れ子のマイグレーション構成

デフォルトでは、wrangler d1 migrations apply は migrations_dir 直下の .sql ファイルを探します。Drizzle ↗ のような ORM が、マイグレーションごとにサブディレクトリを切る場合（例: migrations/0001_init/migration.sql）は、その構成に合う glob を migrations_pattern に設定します。

{
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "my-database",
			"database_id": "<UUID>",
			"migrations_dir": "migrations",
			"migrations_pattern": "migrations/*/migration.sql"
		}
	]
}

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "<UUID>"
migrations_dir = "migrations"
migrations_pattern = "migrations/*/migration.sql"

migrations_pattern のルールは次のとおりです。

設定する場合は、migrations_dir も設定する必要があります。
パターンは、migrations_dir に設定した値で始まる必要があります。
各マイグレーションの名前は、migrations_dir からの相対パスとしてマイグレーションテーブルに記録されます（例: 0001_init/migration.sql）。これで、テーブルはマシン間で移植しやすくなります。

パターンは標準の glob です。* は 1 つのパスセグメント、** は任意の数のセグメントに一致します。migrations/**/*.sql は、任意の深さの .sql ファイルを拾います。

wrangler d1 migrations create は migrations_dir 直下のファイルだけを書き出します。そのため、migrations_pattern が入れ子ファイルだけに一致する場合（Drizzle の構成など）は、新しいマイグレーションは ORM のコマンド（例: drizzle-kit generate）で生成してください。

外部キー制約

マイグレーションを適用するとき、外部キー制約を一時的に無効にする必要がある場合があります。外部キーに違反する変更を行う前に、PRAGMA defer_foreign_keys = true を呼び出します。

外部キーと D1 の扱い方は、外部キーのドキュメントを参照してください。