Drizzle ORM 示例

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

前提条件

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

1. 安装 Drizzle

安装 Drizzle ORM 及其依赖，例如 node-postgres ↗（pg）驱动：

npm i drizzle-orm pg dotenv
npm i -D drizzle-kit tsx @types/pg @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/db/schema.ts
import { pgTable, serial, varchar, timestamp } from "drizzle-orm/pg-core";

export const users = pgTable("users", {
	id: serial("id").primaryKey(),
	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 { Client } from "pg";
import { drizzle } from "drizzle-orm/node-postgres";
import { users } from "./db/schema";

export interface Env {
	HYPERDRIVE: Hyperdrive;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new client instance for each request.
		const client = new Client({
			connectionString: env.HYPERDRIVE.connectionString,
		});

		// Connect to the database
		await client.connect();

		// Create the Drizzle client with the node-postgres connection
		const db = drizzle(client);

		// 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='postgres://user:password@db-host.cloud/database-name'
```

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

drizzle.config.tsts

// drizzle.config.ts
import "dotenv/config";
import { defineConfig } from "drizzle-kit";
export default defineConfig({
	out: "./drizzle",
	schema: "./src/db/schema.ts",
	dialect: "postgresql",
	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'
1 tables
users 4 columns 0 indexes 0 fks

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

npx drizzle-kit migrate

No config path provided, using default 'drizzle.config.ts'
Reading config file 'drizzle.config.ts'
Using 'postgres' driver for database querying

3. 部署 Worker

部署 Worker。

npx wrangler deploy

后续步骤

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