名称: drizzle-orm-d1 描述: | 使用Drizzle的Cloudflare D1数据库的类型安全ORM。使用场景：构建D1数据库模式、编写类型安全的SQL查询、使用Drizzle Kit管理迁移、定义表关系、实现预备语句、使用D1批处理API，或遇到D1_ERROR、事务错误、外键约束失败或模式推断问题。

关键词：drizzle orm, drizzle d1, type-safe sql, drizzle schema, drizzle migrations, drizzle kit, orm cloudflare, d1 orm, drizzle typescript, drizzle relations, drizzle transactions, drizzle query builder, schema definition, prepared statements, drizzle batch, migration management, relational queries, drizzle joins, D1_ERROR, BEGIN TRANSACTION d1, foreign key constraint, migration failed, schema not found, d1 binding error, schema design, database indexes, soft deletes, uuid primary keys, enum constraints, performance optimization, naming conventions, schema testing 许可证: MIT

Drizzle ORM for Cloudflare D1

状态: 生产就绪 ✅ 最后更新: 2025-12-14 最新版本: drizzle-orm@0.44.7, drizzle-kit@0.31.7 依赖: 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',
  driver: 'd1-http',
  dbCredentials: {
    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
    databaseId: process.env.CLOUDFLARE_DATABASE_ID!,
    token: process.env.CLOUDFLARE_D1_TOKEN!,
  },
});

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                           # 生成SQL
bunx wrangler d1 migrations apply my-database --local   # 本地应用
bunx wrangler d1 migrations apply my-database --remote  # 生产应用

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需要批处理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批处理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`	配置wrangler.jsonc用于D1
`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.44.7"
  },
  "devDependencies": {
    "drizzle-kit": "^0.31.7"
  }
}

官方文档

Drizzle ORM: https://orm.drizzle.team/
Drizzle with 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

节省令牌: ~65% (参考中的全面模式) 错误预防: 100% (所有12个记录的问题) 准备生产! ✅