打造 Serverless 數據庫神器：Drizzle ORM x Cloudflare D1 全攻略

在無服務器架構快速發展的今天，許多開發者卻曾在選用 ORM 工具時「踩坑」。Prisma、TypeORM 雖然功能強大，卻無法順利部署到 Cloudflare Workers 等邊緣平台，導致開發者只能回退到繁瑣的手寫 SQL。

Drizzle ORM 正是在這樣的痛點中誕生 —— 它為 TypeScript 開發者帶來極致的類型安全、輕量化體驗，並能與 Cloudflare D1 完美整合，從 schema 建構、遷移到查詢的完整型開發流程。

Drizzle ORM 的基本概念

Drizzle ORM 是一個無頭（headless）的 TypeScript ORM，專為 SQL 數據庫設計，將類型安全性置於最高優先級。與傳統 ORM 不同，Drizzle 被設計為一個庫而非框架，讓你能夠按需使用它而不必被迫遵循特定的項目結構。

Drizzle 的核心理念是「如果你懂 SQL，你就懂 Drizzle ORM」。它盡可能地採用類 SQL 語法，從底層就強類型設計，並在編譯時而非運行時識別出錯誤。

「它是唯一同時擁有關係型和類 SQL 查詢 API 的 ORM，在訪問關係型數據時為你提供兩全其美的選擇。」

Drizzle 非常輕量，壓縮後僅約 7.4kb，且沒有任何依賴項。它支持所有主流 SQL 數據庫，包括 PostgreSQL、MySQL 和 SQLite，以及 Turso、Neon、Supabase、Cloudflare D1 等無服務器數據庫。

🚀 Drizzle ORM 特點速覽：

• ✅ 極致 TypeScript 類型安全
• ✅ 類 SQL 語法，幾乎零學習成本
• ✅ 支援所有主流 SQL 數據庫
• ✅ 與無服務器平台（Cloudflare Workers、Bun、Deno）完美整合
• ✅ 提供 CLI 工具簡化遷移與版本控管

相較於 Prisma 或 TypeORM，Drizzle 不僅封裝更少、啟動更快，更適合用於冷啟動延遲敏感的邊緣執行環境。

為什麼選擇 Drizzle ORM 構建數據庫模式

TypeScript (Microsoft)

Drizzle ORM 最大的特點是極致的類型安全和對 SQL 的忠實還原。它讓你在定義表結構、關聯和查詢時，TypeScript 編譯器可以在編譯階段捕捉潛在的類型錯誤，大幅減少運行時錯誤的可能。Drizzle 的語法設計極度貼近原生 SQL，避免了傳統 ORM 對 SQL 的過度抽象，讓有 SQL 基礎的開發者幾乎零學習成本即可上手，同時完整保留 SQL 的強大靈活性。這種設計理念使你能夠精確映射資料庫結構與操作，並在 Drizzle 和原生 SQL 之間無縫切換。

此外，Drizzle 隨附的 drizzle-kit CLI 工具可自動生成 SQL 遷移文件，顯著簡化了資料庫架構的版本控制和部署流程。Drizzle 也天生為無服務器和現代運行時環境設計，支援 NodeJS、Bun、Deno、Cloudflare Workers、Edge 等主流平台，甚至可於瀏覽器端運行，讓你在任何地方都能享受一致的數據庫開發體驗。

Drizzle 與 Cloudflare D1 的集成

Cloudflare D1 是 Cloudflare 的第一個可查詢關係型數據庫，而 Drizzle ORM 完全支持 D1 數據庫和 Cloudflare Workers 環境。下面我們將介紹如何在 Cloudflare D1 中使用 Drizzle ORM。

環境設置

首先，需要安裝必要的依賴：

npm install drizzle-orm
npm install -D drizzle-kit

在wrangler.toml文件中配置 D1 數據庫：

[[ d1_databases ]]
binding = "DB"
database_name = "YOUR_DB_NAME"
database_id = "YOUR_DB_ID"
migrations_dir = "migrations"

這裡的binding是你希望如何訪問數據庫的名稱，database_name是創建數據庫時指定的名稱，database_id是數據庫創建後生成的 ID，migrations_dir是 drizzle 生成遷移的目錄。

定義數據庫架構

Drizzle 最大的亮點之一，就是可以直接用 TypeScript 定義資料庫 schema，實現全程靜態類型驗證。

// src/schema.ts
import { relations } from 'drizzle-orm';
import { int, sqliteTable, text } from 'drizzle-orm/sqlite-core';

export const userTable = sqliteTable('user_table', {
  id: int().primaryKey({ autoIncrement: true }),
  name: text().notNull(),
});

export const postTable = sqliteTable('post_table', {
  id: int().primaryKey({ autoIncrement: true }),
  title: text().notNull(),
  content: text().notNull(),
  userId: int().references(() => userTable.id),
});

export const userRelations = relations(userTable, ({ many }) => ({
  posts: many(postTable),
}));

export const postRelations = relations(postTable, ({ one }) => ({
  user: one(userTable, {
    fields: [postTable.userId],
    references: [userTable.id],
  }),
}));

這個架構定義了用戶和帖子兩個表，以及它們之間的關係。注意 Drizzle 如何讓你用類型安全的方式定義表格結構和關係。

連接到數據庫

使用 Drizzle 連接到 D1 數據庫非常簡單：

// src/db/index.ts
import { drizzle } from 'drizzle-orm/d1';
import type { Env } from '../types';
import * as schema from './schema';

export function createDB(env: Env['Bindings']) {
  const db = drizzle(env.DB, { schema });
  return db;
}

這裡我們從drizzle-orm/d1導入drizzle，並將其與我們的 D1 數據庫實例和架構一起使用。

遷移和查詢

設置好架構後，你可以使用drizzle-kit生成遷移：

npm run db:generate # 生成遷移
npm run db:migrate # 應用遷移

然後，你可以使用 Drizzle 執行查詢：

import { eq } from 'drizzle-orm';

const db = createDB(env);
// 查詢所有用戶
const allUsers = await db.select().from(userTable);

// 插入新用戶
const newUser = await db.insert(userTable).values({
  name: "John Doe"
}).returning();

// 查詢帶有帖子的特定用戶
const userWithPosts = await db
  .select()
  .from(userTable)
  .where(eq(userTable.id, 1))
  .leftJoin(postTable, eq(userTable.id, postTable.userId));

Drizzle 提供了 SQL 式的查詢 API，使查詢易於編寫和理解。

Drizzle 與 Cloudflare D1 的實際應用

Drizzle 特別適合在 Cloudflare Workers 環境中使用 D1，因為它專為無服務器環境設計，在 Cloudflare Workers 中表現出色，且極為輕量，非常適合資源受限的無服務器場景。同時，Drizzle Kit 支持通過 Cloudflare D1 的 HTTP API 運行 migrate、push、introspect 和 studio 等命令，並可結合 Drizzle Chrome 擴展，讓你直接在 Cloudflare 管理面板中瀏覽 D1 數據庫，進一步提升開發效率與體驗。

一個常見的使用模式是構建 REST API，使用 Hono 作為路由器，Drizzle ORM 查詢 D1 數據庫：

import { Hono } from 'hono';
import { drizzle } from 'drizzle-orm/d1';
import { userTable, postTable } from './schema';

type Bindings = {
  DB: D1Database;
};

const app = new Hono();

app.get('/users', async (c) => {
  const db = drizzle(c.env.DB);
  const users = await db.select().from(userTable);
  return c.json(users);
});

app.post('/users', async (c) => {
  const body = await c.req.json();
  const db = drizzle(c.env.DB);
  const newUser = await db.insert(userTable).values({
    name: body.name
  }).returning();
  return c.json(newUser);
});

export default app;

結論

Yellow Volkswagen van on road photo (Calpa Liu)

Drizzle ORM 代表了現代 TypeScript 數據庫工具的發展方向。它通過提供類 SQL 的語法和強大的類型安全性，在不犧牲 SQL 熟悉度的同時提升了開發體驗，並因對 Cloudflare D1 等無服務器數據庫的支持而成為建構現代 Web 應用的絕佳選擇。Drizzle 不僅僅是一個 ORM，更是一種體驗，憑藉其輕量級、零依賴、類型安全以及與現代無服務器平台的深度集成，成為 TypeScript 開發者的必備工具。使用 Drizzle 構建數據庫模式，能有效提升開發效率、代碼品質與應用性能，無論是簡單 API 還是複雜 Web 應用，Drizzle 都能提供所需的工具與靈活性。