技能介绍

Cloudflare D1 配合 Drizzle ORM 做 schema 变更时，最容易踩的坑不是迁移命令本身，而是 Drizzle 对简单改动生成破坏性 SQL，以及迁移中途失败后留下「半拉子」状态：重试报列已存在，跳过又漏迁移。这个技能把 D1 迁移拆成一套可重复执行的步骤，覆盖生成、审查、应用、验证、修复五个环节。

核心工作流

生成迁移：运行 pnpm db:generate（或 drizzle-kit generate）在 drizzle/ 下产出 .sql 文件。
审查 SQL（关键）：应用前必须读一遍生成的 SQL。Drizzle 改列默认值时可能触发整表重建，INSERT SELECT 会引用旧表不存在的新列，迁移直接失败。若只是加新列、未改现有列类型或约束，可手动把 .sql 简化为 ALTER TABLE my_table ADD COLUMN new_column TEXT DEFAULT 'value'; 再应用。
先本地后远程：pnpm db:migrate:local 与 pnpm db:migrate:remote 都要跑完再测试，否则会出现「本地行生产崩」。
验证结构：用 wrangler d1 execute DB_NAME --local --command "PRAGMA table_info(my_table)" 与远程结果核对表结构。

卡死迁移的诊断与修复

迁移部分应用时（列已加但未记录），wrangler 重试会因重复列报错。诊断路径：核对列/表是否存在，查 SELECT * FROM d1_migrations ORDER BY id 确认已记录的迁移。修复方式：把卡住的迁移手动 INSERT 进 d1_migrations（含 name 与 applied_at），再跑剩余迁移。

批量插入与适用边界

大批量 INSERT 会因 D1 参数限制静默失败，按约 10 行分批（行×列 ≤ 100–150 参数）。
列命名有三层约定：Drizzle schema 用 camelCase，原始 SQL 用 snake_case，API 响应对齐 SQL 别名。
新项目顺序：先部署 Worker，再 npx wrangler d1 create，把 database_id 写入 wrangler.jsonc 的 d1_databases，重新部署后跑迁移。
表结构设计不在本技能范围内，见 d1-drizzle-schema。