drizzle-orm-d1

适用于 Cloudflare D1 的 Drizzle ORM

状态：已可用于生产环境 ✅ 最近更新：2025-12-14 最新版本：[email protected]，[email protected] 依赖项：cloudflare-d1、cloudflare-worker-base

---

快速开始（10 分钟）

1. 安装 Drizzle

bun add drizzle-orm drizzle-kit

2. 配置 Drizzle Kit

创建 drizzle.config.ts：

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/db/schema.ts',
  out: './migrations',
  dialect: 'sqlite',          // MANDATORY since drizzle-kit 0.21 (D1 = sqlite)
  driver: 'd1-http',          // D1 HTTP driver for remote migrations/Studio
  dbCredentials: {            // MANDATORY: drizzle-kit 0.30+ tightened zod validation
    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
    databaseId: process.env.CLOUDFLARE_DATABASE_ID!,
    token: process.env.CLOUDFLARE_D1_TOKEN!,
  },
});

drizzle-kit 0.30/0.31 注意事项：现在会严格验证 dialect 和 dbCredentials。如果配置中省略 dialect，或使用旧的 connectionString/uri 键，将无法通过验证。对于 D1，请使用 dialect: 'sqlite' + driver: 'd1-http'，并配置 accountId/databaseId/token（或基于 wrangler 的凭据）。drizzle-orm/<driver>/migrator 中运行时 migrate() 的签名从 0.36 到 0.45 保持不变（仅在 1.0-beta 中更改，不在 ^0.45 的范围内）。

3. 定义架构

创建 src/db/schema.ts：

import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
import { relations } from 'drizzle-orm';

export const users = sqliteTable('users', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  email: text('email').notNull().unique(),
  name: text('name').notNull(),
  createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(() => new Date()),
});

export const posts = sqliteTable('posts', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  title: text('title').notNull(),
  content: text('content').notNull(),
  authorId: integer('author_id')
    .notNull()
    .references(() => users.id, { onDelete: 'cascade' }),
});

export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts),
}));

4. 生成并应用迁移

bunx drizzle-kit generate                           # Generate SQL
bunx wrangler d1 migrations apply my-database --local   # Apply local
bunx wrangler d1 migrations apply my-database --remote  # Apply prod

5. 在 Worker 中查询

import { drizzle } from 'drizzle-orm/d1';
import { users } from './db/schema';
import { eq } from 'drizzle-orm';

export default {
  async fetch(request: Request, env: { DB: D1Database }): Promise<Response> {
    const db = drizzle(env.DB);
    const allUsers = await db.select().from(users).all();
    return Response.json(allUsers);
  },
};

---

关键规则

始终执行

规则	原因
使用 drizzle-kit generate 生成迁移	切勿手动编写 SQL
先在本地测试迁移	先用 --local，再用 --remote
单条结果使用 .get()	返回第一行或 undefined
使用 db.batch() 执行事务	D1 不支持 SQL BEGIN/COMMIT
日期使用 integer 和 mode: 'timestamp'	D1 没有原生日期类型
动态默认值使用 .$defaultFn()	函数不能使用 .default()

切勿执行

规则	原因
使用 SQL BEGIN TRANSACTION	D1 要求使用 batch API（错误 #1）
混用 drizzle-kit migrate 和 wrangler apply	只使用 Wrangler
在生产环境使用 drizzle-kit push	使用 generate + apply
将凭据提交到 drizzle.config.ts	使用环境变量
对函数调用使用 .default()	改用 .$defaultFn()

---

最常见的 5 个严重错误

#	错误	解决方案
1	D1_ERROR: Cannot use BEGIN TRANSACTION	使用 db.batch([...])，不要使用 db.transaction()
2	FOREIGN KEY constraint failed	定义级联操作：.references(() => users.id, { onDelete: 'cascade' })
3	env.DB is undefined	确保 wrangler.jsonc 中的绑定与 env.DB 一致
4	No such module "wrangler"	使用 import { drizzle } from 'drizzle-orm/d1'
5	Type instantiation excessively deep	使用 InferSelectModel<typeof users> 指定显式类型

参见：references/error-catalog.md，其中列出了全部 12 个错误及其完整解决方案。

---

常见模式摘要

模式	用例	模板
CRUD 操作	基本数据库操作	templates/basic-queries.ts
关联与联接	嵌套查询、手动联接	templates/relations-queries.ts
批量操作	事务（D1 batch API）	templates/transactions.ts
架构设计	命名、索引、软删除	references/schema-patterns.md

---

配置摘要

文件	用途	模板
drizzle.config.ts	Drizzle Kit 配置	templates/drizzle.config.ts
wrangler.jsonc	D1 绑定设置	references/wrangler-setup.md
package.json	迁移用的 npm 脚本	templates/package.json

npm 脚本：

{
  "db:generate": "drizzle-kit generate",
  "db:migrate:local": "wrangler d1 migrations apply my-database --local",
  "db:migrate:remote": "wrangler d1 migrations apply my-database --remote"
}

---

迁移工作流

步骤	命令	备注
1. 编辑架构	编辑 src/db/schema.ts	进行更改
2. 生成	npm run db:generate	创建 SQL 迁移
3. 本地测试	npm run db:migrate:local	在本地验证
4. 部署代码	npm run deploy	推送到 Cloudflare
5. 应用到生产环境	npm run db:migrate:remote	应用迁移

参见：references/migration-workflow.md，了解完整工作流。

---

TypeScript 类型推断

import { InferSelectModel, InferInsertModel } from 'drizzle-orm';
import { users } from './db/schema';

export type User = InferSelectModel<typeof users>;
export type NewUser = InferInsertModel<typeof users>;

---

何时加载参考资料

参考资料	加载时机……
references/error-catalog.md	调试 D1 错误、事务失败、绑定问题时
references/schema-patterns.md	设计架构、命名约定、索引、软删除时
references/migration-workflow.md	设置或排查迁移问题时
references/query-builder-api.md	处理复杂查询、运算符、联接语法时
references/wrangler-setup.md	为 D1 配置 wrangler.jsonc 时
references/common-errors.md	快速查找错误时

---

捆绑资源

模板：basic-schema.ts、basic-queries.ts、transactions.ts、relations-queries.ts、prepared-statements.ts、drizzle.config.ts、package.json

参考资料：error-catalog.md、schema-patterns.md、migration-workflow.md、query-builder-api.md、wrangler-setup.md、common-errors.md、links-to-official-docs.md

---

依赖项

{
  "dependencies": {
    "drizzle-orm": "^0.45.2"
  },
  "devDependencies": {
    "drizzle-kit": "^0.31.10"
  }
}

---

安全安装

安装 Drizzle ORM 和 D1 驱动程序包时，请遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或 Bun：默认禁用）
• 冷却期 — 等待 7 天，让社区审核新版本的软件包
• 安装前审计 — 运行 socket package score npm <pkg>，或使用 socket npm install <pkg> 检查软件包

加载 dependency-upgrade 技能，获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

官方文档

• Drizzle ORM：https://orm.drizzle.team/
• Drizzle 与 D1：https://orm.drizzle.team/docs/connect-cloudflare-d1
• Drizzle Kit：https://orm.drizzle.team/docs/kit-overview
• GitHub：https://github.com/drizzle-team/drizzle-orm

---

Token 节省：约 65%（参考资料中包含全面的模式） 错误预防：100%（涵盖全部 12 个已记录问题） 已可投入生产！ ✅