Back to Details

drizzle-v1

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Drizzle ORM v1 RC Upgrade Guide

Drizzle ORM v1 RC 升级指南

Installation

安装

bash
npm i drizzle-orm@beta drizzle-kit@beta -D
bash
npm i drizzle-orm@beta drizzle-kit@beta -D

Upgrade Steps

升级步骤

Step 1: Run 
drizzle-kit up

步骤1：运行
drizzle-kit up

Migrate previous migrations folder to new format (removes 
journal.json
, groups SQL files and snapshots):
bash
npx drizzle-kit up
将之前的迁移文件夹迁移为新格式（移除
journal.json
，对SQL文件和快照进行分组）：
bash
npx drizzle-kit up

Step 2: Update Relational Queries to v2

步骤2：将Relational Queries更新至v2版本

See references/relational-queries-v2.md for complete migration patterns.
完整的迁移方案请查看references/relational-queries-v2.md。

Quick Reference: Key Changes

快速参考：主要变更

Relations Definition

关联定义

v1 - Separate 
relations()
calls for each table:
typescript
import { relations } from "drizzle-orm/_relations"; // Note: moved import
export const usersRelation = relations(users, ({ one, many }) => ({
  posts: many(posts),
}));
v2 - Single 
defineRelations()
for all tables:
typescript
import { defineRelations } from "drizzle-orm";
import * as schema from "./schema";

export const relations = defineRelations(schema, (r) => ({
  users: {
    posts: r.many.posts({
      from: r.users.id,
      to: r.posts.authorId,
    }),
  },
}));
v1版本 - 每个表单独调用
relations()
：
typescript
import { relations } from "drizzle-orm/_relations"; // 注意：导入路径已变更
export const usersRelation = relations(users, ({ one, many }) => ({
  posts: many(posts),
}));
v2版本 - 为所有表调用一次
defineRelations()
：
typescript
import { defineRelations } from "drizzle-orm";
import * as schema from "./schema";

export const relations = defineRelations(schema, (r) => ({
  users: {
    posts: r.many.posts({
      from: r.users.id,
      to: r.posts.authorId,
    }),
  },
}));

Database Instance

数据库实例

v1:
typescript
const db = drizzle(url, { schema, mode: "planetscale" });
v2 - No 
mode
needed, use 
relations
:
typescript
import { relations } from './relations';
const db = drizzle(url, { relations });
v1版本：
typescript
const db = drizzle(url, { schema, mode: "planetscale" });
v2版本 - 无需
mode
，使用
relations
：
typescript
import { relations } from './relations';
const db = drizzle(url, { relations });

Queries

查询语句

v1 - Function-based 
where
/
orderBy
:
typescript
await db.query.users.findMany({
  where: (users, { eq }) => eq(users.id, 1),
  orderBy: (users, { asc }) => [asc(users.id)],
});
v2 - Object-based syntax:
typescript
await db.query.users.findMany({
  where: { id: 1 },
  orderBy: { id: "asc" },
});
v1版本 - 基于函数的
where
/
orderBy
：
typescript
await db.query.users.findMany({
  where: (users, { eq }) => eq(users.id, 1),
  orderBy: (users, { asc }) => [asc(users.id)],
});
v2版本 - 基于对象的语法：
typescript
await db.query.users.findMany({
  where: { id: 1 },
  orderBy: { id: "asc" },
});

Many-to-Many with 
through

使用
through
实现多对多关联

v2 (new feature):
typescript
export const relations = defineRelations(schema, (r) => ({
  users: {
    groups: r.many.groups({
      from: r.users.id.through(r.usersToGroups.userId),
      to: r.groups.id.through(r.usersToGroups.groupId),
    }),
  },
}));
v2版本（新功能）：
typescript
export const relations = defineRelations(schema, (r) => ({
  users: {
    groups: r.many.groups({
      from: r.users.id.through(r.usersToGroups.userId),
      to: r.groups.id.through(r.usersToGroups.groupId),
    }),
  },
}));

Partial Upgrade (Keep RQB v1)

部分升级（保留RQB v1版本）

Use old syntax while migrating gradually:
  1. Import from 
    drizzle-orm/_relations
  2. Use 
    db._query
    instead of 
    db.query
逐步迁移时可继续使用旧语法：
  1. 从
    drizzle-orm/_relations
    导入
  2. 使用
    db._query
    替代
    db.query

v2 Filter Operators

v2版本过滤操作符

Object-based filters with 
AND
, 
OR
, 
NOT
, 
RAW
:
typescript
await db.query.users.findMany({
  where: {
    AND: [
      { OR: [{ name: { like: "John%" } }, { name: { ilike: "jane%" } }] },
      { age: { gt: 18 } },
      { NOT: { status: "banned" } },
      { RAW: (t) => sql`${t.createdAt} > NOW() - INTERVAL '30 days'` },
    ],
  },
});
支持
AND
、
OR
、
NOT
、
RAW
的基于对象的过滤：
typescript
await db.query.users.findMany({
  where: {
    AND: [
      { OR: [{ name: { like: "John%" } }, { name: { ilike: "jane%" } }] },
      { age: { gt: 18 } },
      { NOT: { status: "banned" } },
      { RAW: (t) => sql`${t.createdAt} > NOW() - INTERVAL '30 days'` },
    ],
  },
});

New Features in v2

v2版本新功能

  • optional: false
     - Make relation required at type level
  • through
     - Direct many-to-many without manual junction table queries
  • Predefined filters - 
    where
    in relation definition
  • Relation filtering - Filter parent by child properties
  • Offset on related objects - Pagination in nested relations
  • optional: false
     - 在类型层面强制关联为必填项
  • through
     - 无需手动查询关联表即可直接实现多对多关联
  • 预定义过滤器 - 在关联定义中设置
    where
    条件
  • 关联过滤 - 通过子属性过滤父对象
  • 关联对象偏移量 - 嵌套关联中的分页功能