迁移 · Cloudflare D1 docs

数据库迁移是对数据库进行版本管理的方式。每个迁移存储为 migrations 文件夹中的 .sql 文件。创建第一个迁移时，会在项目目录中创建 migrations 文件夹。这使您能够在整个数据库开发过程中存储和跟踪更改。

功能

目前，迁移系统旨在简单且有效。通过当前实现，您可以：

创建空迁移文件。
列出未应用的迁移。
应用剩余迁移。

migrations 文件夹中的每个迁移文件在文件名中指定版本号。文件按顺序列出。每个迁移文件是一个 SQL 文件，您可以在其中指定要运行的查询。

Wrangler 自定义

默认情况下，迁移在 Worker 项目目录的 migrations/ 文件夹中创建。创建迁移会在数据库的 d1_migrations 表中保留已应用迁移的记录。

此位置和表名可以在 D1 绑定的 Wrangler 文件中自定义。

{
	"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），请将 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。