⚡

DrizzleORM模式指南Skill drizzle-orm-patterns

Drizzle ORM模式指南是一个完整的PostgreSQL数据库操作参考手册，专门针对边缘计算环境优化。该技能提供类型安全的ORM查询模式、事务管理、关系处理、数据库迁移和性能优化方案。适用于使用TypeScript进行后端开发、云原生应用部署、边缘函数开发和PostgreSQL数据库管理的开发者。关键词：Drizzle ORM、PostgreSQL、TypeScript、边缘计算、Vercel Edge Runtime、数据库迁移、事务管理、性能优化、云原生、后端开发。

后端开发 0 次安装 0 次浏览 更新于 3/2/2026

name: drizzle-orm-patterns description: 该技能提供完整的Drizzle ORM模式，支持PostgreSQL和Vercel Edge Runtime。Drizzle是Quetrex选择的ORM，因为它具有边缘优先、类型安全并支持所有部署目标…

Drizzle ORM模式 - 完整的PostgreSQL参考

使用场景： 在Quetrex中进行数据库操作、模式设计、迁移或查询时使用。

概述

该技能提供完整的Drizzle ORM模式，支持PostgreSQL和Vercel Edge Runtime。Drizzle是Quetrex选择的ORM，因为它具有边缘优先、类型安全并支持所有部署目标。

为什么选择Drizzle？

  • 边缘运行时兼容： 适用于Vercel Edge Functions、Cloudflare Workers
  • 类型安全： 无需代码生成即可获得完整的TypeScript类型推断
  • 零依赖： 无需繁重的Node.js运行时要求
  • 类SQL API： 熟悉SQL的开发者易于上手
  • 轻量级： 约7.4kb压缩大小（对比Prisma约300kb）

技能结构

本技能按模块组织：

1. queries-complete.md

完整查询模式：选择、插入、更新、删除、连接、分页、过滤、聚合、子查询、CTE。

使用场景：

  • 构建任何数据库查询
  • 使用过滤器获取数据
  • 插入/更新/删除记录
  • 分页或排序
  • 聚合数据（计数、求和、平均值）
  • 复杂连接或子查询

2. transactions.md

事务模式：隔离级别、回滚、嵌套事务、错误处理、死锁预防。

使用场景：

  • 必须同时成功的多个操作
  • 金融操作（支付、转账）
  • 数据一致性要求
  • 竞态条件预防
  • 复杂多步骤工作流

3. relations.md

关系模式：一对一、一对多、多对多、自引用、级联删除、嵌套查询。

使用场景：

  • 定义模式关系
  • 查询相关数据
  • 设置级联操作
  • 处理分层数据
  • 优化相关数据获取

4. migrations.md

迁移模式：模式演进、数据迁移、零停机部署、回滚策略。

使用场景：

  • 添加/修改数据库模式
  • 在模式间迁移数据
  • 部署模式变更
  • 回滚有问题的迁移
  • 安全重命名表/列

5. edge-runtime.md

边缘部署模式：Vercel Edge Functions、Neon无服务器、连接池、基于HTTP的连接。

使用场景：

  • 部署到Vercel Edge Runtime
  • 使用Neon无服务器PostgreSQL
  • 优化边缘函数性能
  • 配置连接池
  • 了解边缘限制

6. performance.md

性能模式：索引、查询优化、N+1预防、批量操作、缓存。

使用场景：

  • 慢查询
  • 高数据库负载
  • N+1查询问题
  • 大数据集
  • 需要性能优化

7. type-inference.md

TypeScript推断模式：InferModel、InferSelect、InferInsert、模式类型、自定义类型。

使用场景：

  • 从模式定义TypeScript类型
  • 创建API类型
  • 类型安全查询构建器
  • 自定义类型映射器
  • 确保类型安全

8. common-mistakes.md

常见陷阱和修复：SQL注入风险、N+1查询、缺失索引、事务死锁、类型错误。

使用场景：

  • 调试数据库问题
  • 代码审查
  • 学习最佳实践
  • 避免常见错误
  • 安全审计

9. validate-queries.py

Python脚本，用于验证Drizzle查询的常见安全和性能问题。

使用场景：

  • 预提交验证
  • 安全审计
  • 性能审查
  • 发现SQL注入风险
  • 检测N+1模式

快速开始

安装

# 核心包
npm install drizzle-orm @neondatabase/serverless

# 开发工具
npm install -D drizzle-kit

基本设置

// src/lib/db.ts
import { drizzle } from 'drizzle-orm/neon-http';
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);
export const db = drizzle(sql);

定义模式

// src/lib/schema.ts
import { pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core';

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

基本查询

// src/services/user-service.ts
import { db } from '@/lib/db';
import { users } from '@/lib/schema';
import { eq } from 'drizzle-orm';

export async function getUserByEmail(email: string) {
  return await db.select().from(users).where(eq(users.email, email)).limit(1);
}

常见模式

1. 带过滤的选择

import { db } from '@/lib/db';
import { users } from '@/lib/schema';
import { eq, and, gte } from 'drizzle-orm';

const activeUsers = await db
  .select()
  .from(users)
  .where(
    and(
      eq(users.status, 'active'),
      gte(users.createdAt, new Date('2024-01-01'))
    )
  );

2. 带返回的插入

const [newUser] = await db
  .insert(users)
  .values({
    email: 'test@example.com',
    name: 'Test User',
  })
  .returning();

3. 带返回的更新

const [updatedUser] = await db
  .update(users)
  .set({ name: 'Updated Name' })
  .where(eq(users.id, 1))
  .returning();

4. 事务

await db.transaction(async (tx) => {
  const [user] = await tx.insert(users).values({ email, name }).returning();
  await tx.insert(profiles).values({ userId: user.id, bio });
});

5. 连接查询

const usersWithProfiles = await db
  .select({
    userId: users.id,
    userName: users.name,
    bio: profiles.bio,
  })
  .from(users)
  .leftJoin(profiles, eq(users.id, profiles.userId));

测试要求

所有数据库代码必须包含：

  • 使用模拟数据库的单元测试（覆盖率90%以上）
  • 使用测试数据库的集成测试
  • 事务回滚测试
  • 错误处理测试
  • 类型安全验证

安全检查清单

提交数据库代码前：

  • [ ] 没有使用字符串插值的原始SQL
  • [ ] 所有用户输入使用参数化查询
  • [ ] 外键上有适当的索引
  • [ ] 生产代码中没有select *
  • [ ] 对更改的文件运行python validate-queries.py
  • [ ] 事务隔离级别适合使用场景
  • [ ] 数据库操作前进行输入验证

性能检查清单

提交数据库代码前：

  • [ ] 只选择需要的字段（避免select *）
  • [ ] 所有外键上都有索引
  • [ ] 频繁查询的列上有索引
  • [ ] 没有N+1查询（使用连接或批量加载）
  • [ ] 批量插入操作
  • [ ] 配置连接池
  • [ ] 复杂查询的查询分析

官方资源

从Prisma迁移

如果您从Prisma迁移，请参阅决策记录ADR-002-DRIZZLE-ORM-MIGRATION.md。

主要区别：

  • 没有客户端生成步骤（类型从模式推断）
  • 类SQL查询构建器（不是Prisma的流畅API）
  • 边缘运行时兼容（Prisma 6.19.0不兼容）
  • 手动关系查询（没有自动包含）

后续步骤

  1. 阅读queries-complete.md了解所有查询模式
  2. 阅读transactions.md了解事务安全
  3. 阅读relations.md了解关系模式
  4. 在您的代码上运行validate-queries.py
  5. 查看common-mistakes.md了解常见陷阱

支持

Drizzle相关问题：

Quetrex相关问题：

  • 查看CLAUDE.md项目文档
  • 查看/docs/architecture/中的架构文档
  • 在团队Slack频道中提问

最后更新： 2025-11-23，由Glen Barnhardt在Claude Code的帮助下完成