Drizzle ORM：轻量级数据库工具

Drizzle ORM：轻量级数据库工具

在上一章中，我们探究了 Cloudflare D1 如何作为一款高性能、低本钱的边缘数据库办理方案，彻底改变了我们对数据库架构的认知.

但一般来说，我们很少在项目里裸写sql，以是我们需要一个能简化操作和开辟的ORM工具，但市面上绝大多数的ORM对于这种ServerLess数据库的适配很差，需要办理各种依赖问题。 那么在尝试了一圈后，发现Drizzle是最好的搭配方案，选择它最焦点的理由是：它没有三方依赖、且对ServerLess这个场景非常友好。 [Drizzle地点](https://orm.drizzle.team/)，建议看文档，中文只是阅读起来快一点，精简一点。
Schema：数据模子定义

Schema 是 Drizzle ORM 的基础，它定义了数据库表的结构和关系。
根本表定义

以下是一个简朴的表定义示例：

1. import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
3. // 定义用户表
4. export const users = sqliteTable('users', {
5.   id: integer('id').primaryKey(),
6.   name: text('name').notNull(),
7.   email: text('email').notNull().unique(),
8.   createdAt: integer('created_at', { mode: 'timestamp' }).notNull().defaultNow()
9. })

复制代码

Schema 组织方式

Drizzle 允许你机动组织 Schema 文件，可以选择单文件或多文件方式：
单文件方式

得当小型项目，将所有表定义放在一个 schema.ts 文件中：

1. // src/db/schema.ts
2. import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
4. export const users = sqliteTable('users', {
5.   /* 列定义 */
6. })
7. export const posts = sqliteTable('posts', {
8.   /* 列定义 */
9. })

复制代码

多文件方式

对于大型项目，可以将表定义分散到多个文件中：

1. 📦 src
2. └ 📂 db
3.     └ 📂 schema
4.        ├ 📜 users.ts
5.        ├ 📜 posts.ts
6.        └ 📜 comments.ts

复制代码

命名约定转换

TypeScript 通常利用驼峰命名法（camelCase），而数据库常用蛇形命名法（snake_case）。Drizzle 提供了自动转换功能：

1. // schema.ts
2. export const users = sqliteTable('users', {
3.   id: integer('id'),
4.   firstName: text('first_name') // 显式指定数据库列名
5. })
7. // 或使用自动转换
8. const db = drizzle(sqlite, {
9.   schema: { users },
10.   // 自动将 camelCase 转换为 snake_case
11.   casing: 'snake_case'
12. })

复制代码

关系定义

Drizzle 支持定义表之间的关系：

1. export const posts = sqliteTable('posts', {
2.   id: integer('id').primaryKey(),
3.   title: text('title').notNull(),
4.   content: text('content'),
5.   userId: integer('user_id').references(() => users.id)
6. })

复制代码

复用列定义

对于常见的列模式（如时间戳字段），可以创建可复用的定义：

1. // 通用时间戳字段
2. const timestamps = {
3.   createdAt: integer('created_at', { mode: 'timestamp' }).notNull().defaultNow(),
4.   updatedAt: integer('updated_at', { mode: 'timestamp' })
5. }
7. // 在多个表中复用
8. export const users = sqliteTable('users', {
9.   id: integer('id').primaryKey(),
10.   // ...其他字段
11.   ...timestamps
12. })

复制代码

通过这种方式定义 Schema，Drizzle 不仅提供了类型安全的数据访问，还能自动生成迁移脚本，大大简化了数据库管理工作。
数据库连接

Drizzle ORM 通过数据库驱动执行 SQL 查询。

数据库驱动就是指的一个中心层，负责将查询哀求发送到数据库并处理处罚返回的结果。Drizzle 支持多种数据库驱动，使其可以或许与各种数据库系统无缝集成。

根本连接方式

1. import { drizzle } from 'drizzle-orm/node-postgres'
2. import { users } from './schema'
4. // 创建数据库连接
5. const db = drizzle(process.env.DATABASE_URL)
7. // 使用连接执行查询
8. const usersCount = await db.$count(users)

复制代码

Drizzle 的工作流程如下：

• 你的查询（如 db.$count(users)）被转换为 SQL 语句（SELECT COUNT(*) FROM users）
  
• SQL 语句通过数据库驱动发送到数据库
  
• 数据库返回结果，驱动将其转换为 JavaScript 对象
  
• Drizzle 将结果返回给你的应用
  

访问底层驱动

如果需要，你可以直接访问底层数据库驱动：

1. import { drizzle } from 'drizzle-orm/node-postgres'
3. const db = drizzle(process.env.DATABASE_URL)
4. const pool = db.$client // 访问底层 node-postgres 驱动

复制代码

ServerLess 环境支持

Drizzle 原生支持各种边缘计算和 ServerLess 环境，这也是它与 Cloudflare D1 完善配合的缘故原由：

1. // Neon 数据库（ServerLess PostgreSQL）
2. import { drizzle } from 'drizzle-orm/neon-http'
3. const db = drizzle(process.env.DATABASE_URL)
5. // Cloudflare D1
6. import { drizzle } from 'drizzle-orm/d1'
7. export default {
8.   async fetch(request, env) {
9.     const db = drizzle(env.DB)
10.     // 使用 db 执行查询
11.   }
12. }

复制代码

特定运行时支持

Drizzle 还支持特定运行时的数据库驱动：

1. // Bun SQLite
2. import { drizzle } from 'drizzle-orm/bun-sqlite'
3. const db = drizzle() // 创建内存数据库
4. // 或
5. const db = drizzle('./sqlite.db') // 连接文件数据库

复制代码

连接 URL 格式

数据库连接 URL 通常依照以下格式：

1. postgresql://username:password@hostname/database_name

复制代码

例如：

1. postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname

复制代码

其中：

• username: 数据库用户名
  
• password: 数据库暗码
  
• hostname: 数据库服务器地点
  
• database_name: 数据库名称
  

通过这种简朴的连接方式，Drizzle 让你可以或许快速开始利用数据库，而不必担心复杂的配置和设置。
数据库查询

Drizzle 提供了两种主要的查询方式：SQL 风格语法和关系式 API。这两种方式各有优势，可以根据不同场景选择利用。
SQL 风格查询

Drizzle 的焦点理念是"如果你懂 SQL，你就懂 Drizzle"。与其他 ORM 不同，Drizzle 不会抽象掉 SQL，而是拥抱它，提供类似 SQL 的 API：

1. // 查询示例
2. const result = await db.select().from(posts).leftJoin(comments, eq(posts.id, comments.postId)).where(eq(posts.id, 10))
4. // 生成的 SQL
5. // SELECT *
6. // FROM posts
7. // LEFT JOIN comments ON posts.id = comments.post_id
8. // WHERE posts.id = 10

复制代码

根本 CRUD 操作

• 查询数据
  

1.     // 查询所有用户
2.     const allUsers = await db.select().from(users)
3.    
4.     // 查询特定字段
5.     const userNames = await db.select({ id: users.id, name: users.name }).from(users)
6.    
7.     // 条件查询
8.     import { eq, like } from 'drizzle-orm'
9.     const filteredUsers = await db.select().from(users).where(eq(users.email, 'test@example.com'))

复制代码

• 插入数据
  

1. // 插入单条记录
2. await db.insert(users).values({
3.   name: '张三',
4.   email: 'zhangsan@example.com'
5. })
7. // 插入多条记录
8. await db.insert(users).values([
9.   { name: '李四', email: 'lisi@example.com' },
10.   { name: '王五', email: 'wangwu@example.com' }
11. ])

复制代码

• 更新数据
  

1. // 更新记录
2. await db.update(users).set({ name: '张三丰' }).where(eq(users.id, 1))

复制代码

• 删除数据
  

1. // 删除记录
2. await db.delete(users).where(eq(users.id, 1))

复制代码

关系式查询 API

对于需要获取嵌套关系数据的场景，Drizzle 提供了更简洁的关系式 API：

1. // 获取用户及其所有文章
2. const usersWithPosts = await db.query.users.findMany({
3.   with: {
4.     posts: true
5.   }
6. })
8. // 结果格式
9. // [
10. //   { id: 1, name: '张三', posts: [{ id: 1, title: '文章1' }, ...] },
11. //   ...
12. // ]

复制代码

这种方式特别得当获取嵌套数据，Drizzle 会自动处理处罚关联和数据映射，同时保证只生成一条 SQL 查询，避免 N+1 查扣问题。
高级查询技巧

Drizzle 支持查询组合和分区，让你可以或许构建复杂而机动的查询：

• 组合条件查询
  

1. // 动态构建查询条件
2. function getProductsBy({ name, category, maxPrice }) {
3.   const filters = []
4.   if (name) filters.push(like(products.name, `%${name}%`))
5.   if (category) filters.push(eq(products.category, category))
6.   if (maxPrice) filters.push(lte(products.price, maxPrice))
8.   return db
9.     .select()
10.     .from(products)
11.     .where(filters.length ? and(...filters) : undefined)
12. }

复制代码

• 子查询
  

1. // 使用子查询
2. const subquery = db.select().from(staff).leftJoin(users, eq(staff.userId, users.id)).as('staff_users')
4. const result = await db.select().from(tickets).leftJoin(subquery, eq(subquery.staff_users.userId, tickets.assignedTo))

复制代码

通过这些机动的查询方式，Drizzle 既保持了 SQL 的强大表达本领，又提供了更简洁的 API 来处理处罚常见的数据访问模式，让数据库操作变得既直观又高效。
数据库迁移

数据库迁移是开辟过程中的重要环节，Drizzle 通过 Drizzle Kit 工具提供了完整的迁移办理方案。
Drizzle Kit 简介

Drizzle Kit 是一个命令行工具，用于管理 SQL 数据库迁移：

1. npm install -D drizzle-kit

复制代码

Drizzle Kit 提供了多种命令来满意不同的迁移需求：
命令功能形貌generate根据 Schema 生成 SQL 迁移文件migrate应用生成的 SQL 迁移文件到数据库push直接将 Schema 变动推送到数据库pull从数据库拉取 Schema 并转换为 Drizzle Schemastudio启动 Drizzle Studio 用于可视化数据库管理check查抄生成的迁移文件是否存在冲突up升级之前生成的迁移快照配置 Drizzle Kit

Drizzle Kit 通过 drizzle.config.ts 文件举行配置：

1. // drizzle.config.ts
2. import { defineConfig } from 'drizzle-kit'
4. export default defineConfig({
5.   dialect: 'postgresql', // 数据库类型
6.   schema: './src/db/schema.ts', // Schema 文件路径
7.   out: './drizzle', // 迁移文件输出目录
8.   dbCredentials: {
9.     // 数据库连接信息（用于 migrate、push、pull 等命令）
10.     url: 'postgresql://user:password@host:port/dbname'
11.   }
12. })

复制代码

主要配置项包括：

• dialect: 数据库类型（'postgresql'、'mysql'、'sqlite' 等）
  
• schema: Schema 文件路径，支持 glob 模式匹配多个文件
  
• out: 迁移文件输出目录，默认为 './drizzle'
  
• dbCredentials: 数据库连接信息
  
• migrations: 迁移相关配置，如迁移记录表名称
  

迁移工作流

1. 生成迁移文件 (generate)

当你修改 Schema 后，可以生成迁移文件：

1. npx drizzle-kit generate

复制代码

这将在 out 目录中生成 SQL 迁移文件，包含从当前数据库状态到新 Schema 的所有必要更改。
你可以通过 --name 参数指定迁移文件的名称：

1. npx drizzle-kit generate --name=init

复制代码

这将生成类似 0000_init.sql 的文件。
对于需要自定义 SQL 操作（如数据填充）的场景，可以生成空缺迁移文件：

1. npx drizzle-kit generate --custom --name=seed-users

复制代码

然后在生成的文件中添加自定义 SQL：

1. -- ./drizzle/0001_seed-users.sql
2. INSERT INTO "users" ("name") VALUES('张三');
3. INSERT INTO "users" ("name") VALUES('李四');

复制代码

2. 应用迁移 (migrate)

生成迁移文件后，可以将其应用到数据库：

1. npx drizzle-kit migrate

复制代码

Drizzle Kit 会在数据库中创建一个名为 __drizzle_migrations 的表，用于记录已应用的迁移。你可以自定义这个表：

1. // drizzle.config.ts
2. export default defineConfig({
3.   // ...其他配置
4.   migrations: {
5.     table: 'my_migrations', // 默认为 __drizzle_migrations
6.     schema: 'public' // PostgreSQL 专用，默认为 drizzle
7.   }
8. })

复制代码

3. 直接推送 Schema (push)

在开辟环境中，可以直接将 Schema 变动推送到数据库，跳过生成迁移文件的步骤：

1. npx drizzle-kit push

复制代码

这个命令会分析当前数据库状态和 Schema 文件的差别，并直接应用变动，得当快速迭代的开辟阶段。
4. 从数据库拉取 Schema (pull)

如果你有一个现有的数据库，可以从中拉取 Schema 并转换为 Drizzle Schema：

1. npx drizzle-kit pull

复制代码

这对于将现有项目迁移到 Drizzle 特别有用。
多环境配置

对于有多个环境（开辟、测试、生产）的项目，可以创建多个配置文件：

1.     📦 项目根目录
2.      ├ 📜 drizzle-dev.config.ts
3.      ├ 📜 drizzle-prod.config.ts

复制代码

利用时指定配置文件：

1. npx drizzle-kit push --config=drizzle-dev.config.ts

复制代码

Drizzle Studio

Drizzle Kit 还提供了一个可视化工具 Drizzle Studio，用于欣赏和管理数据库：

1. npx drizzle-kit studio

复制代码

这将启动一个本地服务器，通过欣赏器界面可以查看表结构、数据记录，并执行根本的 CRUD 操作。
完整迁移流程示例

以下是一个完整的迁移流程示例：

• 定义 Schema：
  

1. // src/schema.ts
2. import { pgTable, serial, text } from 'drizzle-orm/pg-core'
4. export const users = pgTable('users', {
5.   id: serial('id').primaryKey(),
6.   name: text('name').notNull()
7. })

复制代码

• 配置 Drizzle Kit：
  

1. // drizzle.config.ts
2. import { defineConfig } from 'drizzle-kit'
4. export default defineConfig({
5.   dialect: 'postgresql',
6.   schema: './src/schema.ts',
7.   dbCredentials: {
8.     url: 'postgresql://user:password@host:port/dbname'
9.   }
10. })

复制代码

• 生成迁移文件：
  

1. npx drizzle-kit generate --name=init

复制代码

• 应用迁移：
  

1. npx drizzle-kit migrate

复制代码

完整配置示例

以下是一个包含所有可用选项的扩展配置示例：

1. import { defineConfig } from 'drizzle-kit'
3. export default defineConfig({
4.   out: './drizzle', // 迁移文件输出目录
5.   dialect: 'postgresql', // 数据库类型
6.   schema: './src/schema.ts', // Schema 文件路径
7.   driver: 'pglite', // 特定数据库驱动
8.   dbCredentials: {
9.     // 数据库连接信息
10.     url: './database/'
11.   },
12.   extensionsFilters: ['postgis'], // 忽略特定扩展的表
13.   schemaFilter: 'public', // 要管理的 schema
14.   tablesFilter: '*', // 要管理的表
15.   introspect: {
16.     // pull 命令的配置
17.     casing: 'camel' // 列名命名风格
18.   },
19.   migrations: {
20.     // 迁移记录配置
21.     prefix: 'timestamp', // 迁移文件前缀
22.     table: '__drizzle_migrations__', // 迁移记录表名
23.     schema: 'public' // 迁移记录表所在 schema
24.   },
25.   entities: {
26.     // 实体管理配置
27.     roles: {
28.       // 角色管理
29.       provider: '', // 数据库提供商
30.       exclude: [], // 排除的角色
31.       include: [] // 包含的角色
32.     }
33.   },
34.   breakpoints: true, // 是否在 SQL 中添加断点
35.   strict: true, // push 命令是否需要确认
36.   verbose: true // 是否打印详细日志
37. })

复制代码

多配置文件支持

对于管理多个数据库或环境的项目，可以创建多个配置文件：

1. 📦 项目根目录
2. ├ 📜 drizzle-dev.config.ts
3. ├ 📜 drizzle-prod.config.ts

复制代码

利用时指定配置文件：

1. npx drizzle-kit generate --config=drizzle-dev.config.ts

复制代码

主要配置项详解

• dialect：数据库类型
  
  
  
  • 可选值：postgresql、mysql、sqlite、turso、singlestore
    
  • 适用命令：generate、migrate、push、pull、check、up
    
  
  
• schema：Schema 文件路径
  
  
  
  • 类型：string | string[]（支持 glob 模式）
    
  • 适用命令：generate、push
    
  • 示例：'./src/schema.ts' 或 './src/schema/*.ts'
    
  
  
• out：迁移文件输出目录
  
  
  
  • 类型：string
    
  • 默认值：'drizzle'
    
  • 适用命令：generate、migrate、push、pull、check、up
    
  
  
• dbCredentials：数据库连接信息
  
  
  
  • 类型：URL 字符串或连接参数对象
    
  • 适用命令：migrate、push、pull
    
  • 示例：
    1. dbCredentials: {
    2.   url: 'postgresql://user:password@host:port/db'
    3. }
    4. // 或
    5. dbCredentials: {
    6.   host: 'host',
    7.   port: 5432,
    8.   user: 'user',
    9.   password: 'password',
    10.   database: 'dbname',
    11.   ssl: true
    12. }

    复制代码
  
  
• migrations：迁移记录配置
  
  
  
  • 类型：{ table: string, schema: string }
    
  • 默认值：{ table: '__drizzle_migrations', schema: 'drizzle' }
    
  • 适用命令：migrate
    
  
  
• tablesFilter：表过滤器
  
  
  
  • 类型：string | string[]
    
  • 适用命令：generate、push、pull
    
  • 示例：['users', 'posts', 'project1_*']
    
  
  
• schemaFilter：Schema 过滤器
  
  
  
  • 类型：string[]
    
  • 默认值：['public']
    
  • 适用命令：generate、push、pull
    
  
  
• extensionsFilters：扩展过滤器
  
  
  
  • 类型：string[]
    
  • 默认值：[]
    
  • 适用命令：push、pull
    
  • 示例：['postgis']（忽略 PostGIS 扩展创建的表）
    
  
  
• entities.roles：角色管理配置
  
  
  
  • 类型：boolean | { provider: string, include: string[], exclude: string[] }
    
  • 默认值：false
    
  • 适用命令：push、pull、generate
    
  • 示例：
    1. entities: {
    2.   roles: {
    3.     provider: 'supabase',  // 使用 Supabase 预定义角色
    4.     exclude: ['admin']     // 排除 admin 角色
    5.   }
    6. }

    复制代码
  
  
• strict：严格模式
  

1. 2.  类型：`boolean`
2.    
3. 3.  默认值：`false`
4.    
5. 4.  适用命令：`push`
6.    
7. 5.  作用：执行 `push` 命令时是否需要确认 SQL 语句

复制代码

• verbose：具体日志
  

1. 2.  类型：`boolean`
2.    
3. 3.  默认值：`true`
4.    
5. 4.  适用命令：`generate`、`pull`
6.    
7. 5.  作用：是否打印详细的 SQL 语句

复制代码

• breakpoints：SQL 断点
  

1. 2.  类型：`boolean`
2.    
3. 3.  默认值：`true`
4.    
5. 4.  适用命令：`generate`、`pull`
6.    
7. 5.  作用：是否在生成的 SQL 中添加 `--> statement-breakpoint` 断点（对于不支持在一个事务中执行多个 DDL 语句的数据库如 MySQL 和 SQLite 很重要）

复制代码

结束

讲这个的主要目标是为了给各人普及一下外洋批量应用的基础套件的知识，接待更多的相识下。

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。