drizzle-orm-d1

Drizzle ORM for Cloudflare D1 是一个面向 Cloudflare D1 数据库的类型安全 ORM 开发技能，状态为 Production Ready，最后更新于 2026-02-03。

用途

该技能用于在 Cloudflare D1 上使用 Drizzle ORM 构建类型安全的数据库应用，覆盖 schema 定义、迁移生成与应用、关系管理以及 D1 batch API 模式，并针对 18 个已知问题提供预防措施。

提供 /db-init、/migrate、/seed 三个命令，分别用于初始化 Drizzle ORM 与 D1 配置、生成并应用数据库迁移、填充初始或测试数据。
支持 schema 定义、Drizzle Kit 迁移、关系以及 D1 batch API 模式。
提供 Drizzle Studio 可视化数据库浏览器，可浏览表与数据、内联编辑记录、运行自定义 SQL 查询、查看 schema 关系。
提供迁移命令：generate、push、pull、check、up。
支持动态查询构建、Upsert、日志调试等高级查询模式。
针对 18 个已知问题提供预防措施，包括 D1 事务错误、外键约束失败、模块导入错误、D1 绑定未找到、迁移应用失败、schema TypeScript 推断错误、预处理语句缓存问题、事务回滚模式、TypeScript 严格模式错误、Drizzle 配置未找到、远程与本地 D1 混淆、wrangler.toml 与 wrangler.jsonc 混用、D1 100 参数限制、findFirst 与 batch API 返回错误、D1 生成列不支持、迁移生成器静默导致 CASCADE DELETE 数据丢失、sql 模板在 D1 batch 中导致 TypeError 等。

快速开始（5 分钟）：

安装：npm install drizzle-orm；npm install -D drizzle-kit。
配置 drizzle.config.ts，使用 defineConfig 设置 schema、out、dialect: 'sqlite'、driver: 'd1-http' 以及 dbCredentials（accountId、databaseId、token）。
配置 wrangler.jsonc，设置 d1_databases 的 binding、database_name、database_id、migrations_dir。
在 src/db/schema.ts 中定义 schema，使用 sqliteTable、text、integer 等。
生成并应用迁移：npx drizzle-kit generate；npx wrangler d1 migrations apply my-database --local；npx wrangler d1 migrations apply my-database --remote。
在 Worker 中查询：import { drizzle } from 'drizzle-orm/d1'；const db = drizzle(env.DB)；const allUsers = await db.select().from(users).all()。

D1 特定关键规则：

Drizzle Kit 工具：

Drizzle Studio：npx drizzle-kit studio，打开 http://local.drizzle.studio；远程 D1 数据库使用 npx drizzle-kit studio --port 3001。
迁移命令：drizzle-kit generate 从 schema 变更生成 SQL 迁移；drizzle-kit push 直接推送 schema（仅开发，不用于生产）；drizzle-kit pull 内省现有数据库生成 Drizzle schema；drizzle-kit check 验证迁移完整性；drizzle-kit up 升级迁移快照到最新格式。

高级查询模式：

动态查询构建：使用 .$dynamic() 条件构建查询。
Upsert：使用 onConflictDoNothing() 或 onConflictDoUpdate()，目标必须是唯一列或主键。
日志调试：drizzle(env.DB, { logger: true }) 或自定义 logger；使用 query.toSQL() 获取 SQL 而不执行。

适用于在 Cloudflare Workers 或 D1 环境中需要类型安全数据库访问的项目，尤其是需要 schema 定义、迁移管理、关系处理和 batch 操作的场景。