drizzle-orm-patterns

Drizzle ORM 模式

概述

使用 Drizzle ORM 建立型別安全資料庫應用程式的專家指南。涵蓋所有支援資料庫的結構定義、關聯、查詢、交易與遷移。

使用時機

定義包含資料表、欄位與限制條件的資料庫結構
建立資料表之間的關聯（一對一、一對多、多對多）
撰寫型別安全的 CRUD 查詢
實作複雜的 JOIN 與聚合查詢
管理支援回滾的資料庫交易
使用 Drizzle Kit 設定遷移
使用 PostgreSQL、MySQL、SQLite、MSSQL 或 CockroachDB

快速參考

資料庫	資料表函式	匯入來源
PostgreSQL	`pgTable()`	`drizzle-orm/pg-core`
MySQL	`mysqlTable()`	`drizzle-orm/mysql-core`
SQLite	`sqliteTable()`	`drizzle-orm/sqlite-core`
MSSQL	`mssqlTable()`	`drizzle-orm/mssql-core`

操作	方法	範例
新增	`db.insert()`	`db.insert(users).values({...})`
查詢	`db.select()`	`db.select().from(users).where(eq(...))`
更新	`db.update()`	`db.update(users).set({...}).where(...)`
刪除	`db.delete()`	`db.delete(users).where(...)`
交易	`db.transaction()`	`db.transaction(async (tx) => {...})`

操作說明

確認你的資料庫方言 - 選擇 PostgreSQL、MySQL、SQLite、MSSQL 或 CockroachDB
定義你的結構 - 使用對應的資料表函式（pgTable、mysqlTable 等）
設定關聯 - 使用 relations() 或 defineRelations() 定義關聯
初始化資料庫客戶端 - 使用正確的憑證建立 Drizzle 客戶端
撰寫查詢 - 使用查詢建構器進行型別安全的 CRUD 操作
處理交易 - 必要時將多步驟操作包裝在交易中
設定遷移 - 設定 Drizzle Kit 進行結構管理

範例

範例 1：基本結構與查詢

import { pgTable, serial, text } from 'drizzle-orm/pg-core';
import { drizzle } from 'drizzle-orm/node-postgres';
import { eq } from 'drizzle-orm';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
});

const db = drizzle(process.env.DATABASE_URL);

const [user] = await db.select().from(users).where(eq(users.id, 1));

範例 2：CRUD 操作

import { eq } from 'drizzle-orm';

// 新增
const [newUser] = await db.insert(users).values({
  name: 'John',
  email: 'john@example.com',
}).returning();

// 更新
await db.update(users)
  .set({ name: 'John Updated' })
  .where(eq(users.id, 1));

// 刪除
await db.delete(users).where(eq(users.id, 1));

範例 3：交易與回滾

await db.transaction(async (tx) => {
  const [from] = await tx.select().from(accounts)
    .where(eq(accounts.userId, fromId));

  if (from.balance < amount) {
    tx.rollback();
  }

  await tx.update(accounts)
    .set({ balance: sql`${accounts.balance} - ${amount}` })
    .where(eq(accounts.userId, fromId));
});

更多進階交易模式請參閱 references/transactions.md。

最佳實務

型別安全：務必使用 TypeScript 並善用 $inferInsert / $inferSelect
關聯：使用 relations() API 定義關聯以支援巢狀查詢
交易：對於必須同時成功的多步驟操作，使用交易
遷移：正式環境使用 generate + migrate，開發環境使用 push
索引：在經常查詢的欄位與外鍵上建立索引
軟刪除：盡可能使用 deletedAt 時間戳記取代實體刪除
分頁：大型資料集使用游標分頁
查詢最佳化：使用 .limit() 與 .where() 只取得需要的資料

限制與警告

外鍵限制：務必使用箭頭函式 () => table.column 定義參考，以避免循環相依問題
交易回滾：呼叫 tx.rollback() 會拋出例外 - 必要時使用 try/catch
RETURNING 子句：並非所有資料庫都支援 .returning() - 請確認你的方言相容性
批次操作：大量批次新增可能觸發資料庫限制 - 請分批處理
正式環境遷移：在套用到正式環境前，務必先在測試環境測試遷移

參考資料

核心概念

references/schema-definition.md - 所有資料庫（PostgreSQL、MySQL、SQLite）的完整結構定義、欄位型別、索引與限制條件
references/relations.md - 一對一、一對多、多對多關聯，包含 v1 與 v2 語法
references/queries-joins-aggregations.md - CRUD 操作、查詢運算子、JOIN、聚合與分頁