用途:为 Cloudflare D1(基于 SQLite)数据库提供 Drizzle ORM 的配置与使用模式,实现类型安全的查询、模式定义与迁移管理,并规避 D1 特有的事务与迁移问题。
主要能力:支持 sqliteTable 定义表与字段、relations 定义关系以实现类型安全联表、drizzle-kit generate 生成 SQL 迁移文件、通过 Wrangler 应用迁移、在 Worker 中执行 select/insert/update/delete 及 .returning(),以及使用 db.batch() 处理批量操作。使用 TypeScript 可获得完整的类型推断与 IDE 自动补全。
使用方式:安装 npm install drizzle-orm 与 npm install -D drizzle-kit;在项目根目录创建 drizzle.config.ts,需设置 dialect: 'sqlite'、driver: 'd1-http',并通过环境变量提供 accountId、databaseId、token;在 wrangler.jsonc 中配置 d1_databases 的 binding、database_name、database_id 与 migrations_dir: "./migrations";在 src/db/schema.ts 定义表与关系;执行 npx drizzle-kit generate 生成迁移,再执行 npx wrangler d1 migrations apply my-database --local 或 --remote 应用;在 Worker 中用 drizzle(env.DB) 创建实例并查询。
适用场景:部署于 Cloudflare Workers 的无服务器应用,需要类型安全数据库访问、本地与生产环境迁移管理、以 SQL 风格但无抽象开销的方式操作 D1 数据。
限制与注意:D1 不支持 SQL BEGIN TRANSACTION,须改用 db.batch(),且 batch 失败不会自动回滚,需手动处理;日期字段需用 integer 配合 mode: 'timestamp';动态默认值须用 .$defaultFn() 而非 .default();单条结果用 .get(),多条用 .all();迁移仅用 Wrangler 应用,不要混用 drizzle-kit migrate,也不要对生产使用 drizzle-kit push;配置文件须命名为 drizzle.config.ts 并置于项目根目录;D1 不缓存预处理语句;统一使用 wrangler.jsonc,不要混用 wrangler.toml。资料提及防止 12 类已知问题,但具体模板文件内容暂未提供。