[!info] related notes

• 相关主题:
• 相关 MOC:
• 相关 howto:

Drizzle ORM

定位

Drizzle ORM 是 TypeScript 生态中的数据库访问工具。它强调：

TypeScript schema
+ SQL-like query builder
+ inferred types
+ migration tooling

它不像 Active Record 风格 ORM 那样把数据库隐藏成“对象世界”，而是尽量保留表、列、JOIN、约束和 SQL 的可见性。

核心组成

Drizzle ORM
├─ schema declarations
├─ typed query / SQL builder
├─ relations query API
├─ transaction API
└─ driver integration

Drizzle Kit
├─ generate migrations
├─ migrate
├─ push / introspect 等 schema 工具
└─ migration metadata

要区分：运行时查询库是 drizzle-orm，schema 演进工具主要由 Drizzle Kit 负责。

Schema 是什么

以 PostgreSQL 为例，代码可以声明表、列、约束和索引：

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

这里 TypeScript 定义既服务于：

• 查询时的类型推导
• migration diff / generation
• 代码中的表列引用

但真正的数据合法性最终仍依赖数据库中实际存在的 constraint。

Query 风格

Drizzle 支持两类常见表达：

SQL-like select / join / where
→ 明确表达关系查询

Relational Query API
→ 按已声明 relation 读取嵌套对象

两者最终都应根据生成 SQL、索引和查询计划评估，而不是因为 TypeScript 类型安全就默认高效。

Driver 不是 Drizzle 自己发明的数据库连接

Drizzle 可以接不同 PostgreSQL driver，例如 pg、postgres.js 或适配 serverless 环境的 driver。

因此：

Drizzle
→ query/schema abstraction

Driver
→ protocol / connection implementation

Connection pool / platform
→ runtime resource management

不要把这三层混成一个东西。

与 Prisma 的直觉差异

可以先用一个非常粗的学习模型：

Prisma
→ 更强的独立 schema / generated client 心智

Drizzle
→ TypeScript schema + 更贴近 SQL 的 API

两者都不是“有 ORM 就不用懂 SQL”。复杂查询、索引、事务、N+1、migration compatibility 仍然是数据库知识。

在 Next.js 中的位置

Server Component
Server Action
Route Handler
      ↓
server-only data / repository
      ↓
Drizzle
      ↓
PostgreSQL driver
      ↓
Database

Drizzle 不应该进入 Client Component bundle，也不应该成为绕过 owning backend 的理由。

Query Logging

开发阶段应保留观察实际 SQL 的能力：

ORM call
→ generated SQL
→ params
→ query count / duration

它用于发现：

• N+1
• 多余 query
• JOIN 错误
• 没有命中预期索引
• ORM projection 过宽

ORM 的类型安全和数据库性能是两个独立维度。

最短记忆

Drizzle = typed SQL-oriented data access
Drizzle Kit = schema/migration tooling
Schema type safety ≠ database constraint disappears
ORM convenience ≠ SQL knowledge disappears
Drizzle ≠ connection pool