Drizzle ORM 示例

Drizzle ORM ↗ 是注重类型安全的轻量级 TypeScript ORM。本示例演示如何在 Workers 应用中通过 Cloudflare Hyperdrive 将 Drizzle ORM 与 MySQL 配合使用。

前提条件

拥有 Workers 访问权限的 Cloudflare 账户
MySQL 数据库
指向 MySQL 数据库的 Hyperdrive 配置

1. 安装 Drizzle

安装 Drizzle ORM 及其依赖，例如 mysql2 ↗ 驱动：

# mysql2 v3.13.0 or later is required
npm i drizzle-orm mysql2 dotenv
npm i -D drizzle-kit tsx @types/node

在 wrangler.jsonc 文件中添加所需的 Node.js 兼容性标志和 Hyperdrive 绑定（binding）：

在 wrangler.jsonc 中添加 Node.js 兼容性标志和 Hyperdrive 绑定（binding）：

{
	// required for database drivers to function
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<your-hyperdrive-id-here>"
		}
	]
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-08-17"

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"

2. 配置 Drizzle

2.1. 定义 schema

使用 Drizzle ORM 时，我们在 TypeScript 中定义 schema，而非编写原始 SQL。

在 /src/ 中创建 /db/ 文件夹。
创建 schema.ts 文件。

在 schema.ts 中定义如下 users 表。

src/db/schema.tsts

// src/schema.ts
import { mysqlTable, int, varchar, timestamp } from "drizzle-orm/mysql-core";

export const users = mysqlTable("users", {
	id: int("id").primaryKey().autoincrement(),
	name: varchar("name", { length: 255 }).notNull(),
	email: varchar("email", { length: 255 }).notNull().unique(),
	createdAt: timestamp("created_at").defaultNow(),
});

2.2. 使用 Hyperdrive 将 Drizzle ORM 连接到数据库

使用 Drizzle ORM 时，请使用 Hyperdrive 配置的凭据连接数据库。

按如下所示填充 index.ts 文件。

src/index.tsts

// src/index.ts

import { drizzle } from "drizzle-orm/mysql2";
import { createConnection } from "mysql2/promise";
import { users } from "./db/schema";

export interface Env {
	HYPERDRIVE: Hyperdrive;
  }

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a connection using the mysql2 driver with the Hyperdrive credentials (only accessible from your Worker).
		const connection = await createConnection({
			host: env.HYPERDRIVE.host,
			user: env.HYPERDRIVE.user,
			password: env.HYPERDRIVE.password,
			database: env.HYPERDRIVE.database,
			port: env.HYPERDRIVE.port,

			// Required to enable mysql2 compatibility for Workers
			disableEval: true,
		});

		// Create the Drizzle client with the mysql2 driver connection
		const db = drizzle(connection);

		// Sample query to get all users
		const allUsers = await db.select().from(users);

		return Response.json(allUsers);
	},
} satisfies ExportedHandler<Env>;

2.3. 配置 Drizzle-Kit 迁移（可选）

可使用 Drizzle Kit CLI 根据 schema 生成并运行 SQL 迁移。请参阅 Drizzle ORM 文档 ↗ 获取更多指导。

在项目根目录创建 .env 文件，并添加数据库连接字符串。Drizzle Kit CLI 将使用此连接字符串创建并应用迁移。
.envtoml
```
# .env
# 替换为你的直接数据库连接字符串
DATABASE_URL='mysql://user:password@db-host.cloud/database-name'
```

在项目根目录创建 drizzle.config.ts 文件以配置 Drizzle Kit，并添加以下内容：

drizzle.config.tsts

import 'dotenv/config';
import { defineConfig } from 'drizzle-kit';
export default defineConfig({
out: './drizzle',
schema: './src/db/schema.ts',
dialect: 'mysql',
dbCredentials: {
url: process.env.DATABASE_URL!,
  },
});

根据 schema 文件为数据库生成迁移文件并应用迁移。

npx drizzle-kit generate

No config path provided, using default 'drizzle.config.ts'
Reading config file 'drizzle.config.ts'
Reading schema files:
/src/db/schema.ts

1 tables
users 4 columns 0 indexes 0 fks

[✓] Your SQL migration file ➜ drizzle/0000_daffy_rhodey.sql 🚀

npx drizzle-kit migrate

No config path provided, using default 'drizzle.config.ts'
Reading config file 'drizzle.config.ts'

3. 部署 Worker

部署 Worker。

npx wrangler deploy

后续步骤

了解更多 Hyperdrive 工作原理。
参阅故障排除指南以排查常见问题。
进一步了解 Cloudflare Workers 可用的其他存储选项。