← Cloudflare D1 / d1 / reference

Миграции

Миграции базы данных представляют собой способ версионирования вашей базы данных. Каждая миграция хранится в виде .sql файл в вашем migrations папку. migrations папка создаётся в каталоге вашего проекта при создании первой миграции. Это позволяет хранить и отслеживать изменения на протяжении всей разработки базы данных.

На данный момент система миграций стремится быть простой, но эффективной. В текущей реализации вы можете:

• Создание пустой файл миграции.
• Список неприменённых миграций.
• Применить оставшихся миграций.

Каждый файл миграции в migrations папка содержит номер версии в имени файла. Файлы перечислены по порядку. Каждый файл миграции представляет собой SQL-файл, в котором можно указать запросы для выполнения.

По умолчанию миграции создаются в migrations/ папку в каталоге проекта Worker. При создании миграций записи о применённых миграциях будут сохраняться в 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 ищет на верхнем уровне .sql файлы внутри migrations_dir. Если вы используете ORM, например Drizzle ↗ с записью каждой миграции в отдельный подкаталог (например, migrations/0001_init/migration.sql), задайте migrations_pattern шаблону glob, соответствующему структуре вашего проекта:

{
	"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: * соответствует одному сегменту пути, ** соответствует любому количеству сегментов. migrations/**/*.sql будет распознавать произвольно глубокие .sql файлы.

wrangler d1 migrations create записывает только файлы верхнего уровня внутри migrations_dir, поэтому если у вас migrations_pattern соответствует только вложенным файлам (как в случае с макетом Drizzle), создавайте новые миграции с помощью команды вашего ORM (например, drizzle-kit generate) вместо этого.

При применении миграции может потребоваться временно отключить ограничения внешнего ключа. Для этого вызовите PRAGMA defer_foreign_keys = true перед внесением изменений, которые нарушили бы внешние ключи.

См. документация по внешним ключам чтобы узнать больше о работе с внешними ключами и D1.