drizzle-v1

Drizzle ORM v1 (Relations Query v2) 指南

版本信息

• 当前版本: [email protected]（已进入 RC 阶段）
• 官方文档: 所有 drizzle 官方文档已更新为 v1 写法
• 关键变化: Relations 定义方式、查询 API、多对多 through 支持

核心概念

drizzle() 初始化

传入 relations 而非 schema：

import { drizzle } from "drizzle-orm/postgres-js";
import { relations } from "./relations";

const db = drizzle({
  client: getQueryClient(),
  relations,
  casing: "snake_case",
});

Relations 定义

基本结构

使用 defineRelations 在一处定义所有关系：

// src/db/relations/index.ts
import { defineRelations } from "drizzle-orm";
import * as schema from "@/db/schema";

export const relations = defineRelations(schema, (r) => ({
  // 每个表的关系定义
  users: {
    posts: r.many.posts(),
  },
  posts: {
    author: r.one.users({
      from: r.posts.authorId,
      to: r.users.id,
    }),
  },
}));

本项目的分片模式

本项目使用 defineRelationsPart + spread 方式拆分关系定义：

// src/db/relations/index.ts
import { defineRelations } from "drizzle-orm";
import * as schema from "@/db/schema";
import { userRolesRelations } from "./admin/user-roles";

export const relations = defineRelations(schema, (r) => ({
  ...userRolesRelations(r),
}));

// src/db/relations/admin/user-roles.ts
import type { ExtractTablesFromSchema, RelationsBuilder } from "drizzle-orm";
import type * as schema from "@/db/schema";

type Schema = ExtractTablesFromSchema<typeof schema>;

export const userRolesRelations = (r: RelationsBuilder<Schema>) => ({
  systemUsers: {
    roles: r.many.systemRoles({
      from: r.systemUsers.id.through(r.systemUserRoles.userId),
      to: r.systemRoles.id.through(r.systemUserRoles.roleId),
    }),
    enabledRoles: r.many.systemRoles({
      from: r.systemUsers.id.through(r.systemUserRoles.userId),
      to: r.systemRoles.id.through(r.systemUserRoles.roleId),
      where: { status: Status.ENABLED },
    }),
  },
  systemRoles: {
    users: r.many.systemUsers(),
  },
});

关键模式：

• 类型使用 ExtractTablesFromSchema<typeof schema> + RelationsBuilder<Schema>
• 返回对象直接 spread 到 defineRelations 中
• 按 src/db/relations/{tier}/{feature}.ts 组织文件