v1 中的变更

此页面展示了从 drizzle-orm@0.x、drizzle-kit@0.x、drizzle-seed@0.x 到最新的 drizzle-orm@1.0、drizzle-kit@1.0、drizzle-seed@1.0 的所有变更

破坏性变更

已移除 Relational Queries v1

RQBv1 已被移除。请改用带有新 defineRelations() API 和新特性的 Relational Queries v2。你可以在 这里 找到更多从 rqb v1 迁移到 v2 的详细信息

一个基于 defineRelations() 构建的新关系系统：

import { defineRelations } from 'drizzle-orm';

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

新的大小写转换 API

旧的 drizzle({ casing: 'camelCase' }) 已被替换为表/视图/模式级别的 API：

import { snakeCase, camelCase } from 'drizzle-orm/pg-core';

export const users = snakeCase.table('users', {
  id: serial().primaryKey(),
  fullName: text(),        // → 数据库中的 full_name
  createdAt: timestamp(),  // → 数据库中的 created_at
});

// 适用于所有实体类型：
snakeCase.table / snakeCase.view / snakeCase.materializedView / snakeCase.schema
camelCase.table / camelCase.view / camelCase.materializedView / camelCase.schema

验证器包已整合到 drizzle-orm

• drizzle-zod -> drizzle-orm/zod
• drizzle-valibot -> drizzle-orm/valibot
• drizzle-typebox -> drizzle-orm/typebox-legacy（使用 @sinclair/typebox）
• drizzle-typebox -> drizzle-orm/typebox（使用 typebox）
• drizzle-arktype -> drizzle-orm/arktype
• 新增 drizzle-orm/effect-schema 包

.array() 不再支持链式调用

多维数组请使用字符串语法：

// ❌ 之前
column.array().array()

// ✅ 之后
column.array('[][]')
column.array('[][][]')

.enableRLS() 已弃用

表上的 .enableRLS() 方法已弃用。请改用 pgTable.withRLS()：

// ❌ 之前
const users = pgTable('users', { ... }).enableRLS();

// ✅ 之后
const users = pgTable.withRLS('users', { ... });

.generatedAlwaysAs() 只接受 SQL

// ❌ 之前 — 接受原始值
.generatedAlwaysAs('some expression')

// ✅ 之后 — 仅接受 sql`` 或 () => sql``
.generatedAlwaysAs(sql`some expression`)
.generatedAlwaysAs(() => sql`some expression`)

getTableColumns 已弃用

请改用 getColumns

// ❌ 之前
import { getTableColumns } from 'drizzle-orm';

const columns = getTableColumns(users);

// ✅ 之后
import { getColumns } from 'drizzle-orm';

const columns = getColumns(users);

新的迁移文件夹结构（v3）

关联讨论：#2832

• 不再有 journal.json
• SQL 文件和快照分组到独立的迁移文件夹中
• 已移除 drizzle-kit drop 命令

这些更改消除了 journal 文件可能带来的 Git 冲突，并简化了删除或修复冲突迁移的流程

schemaFilter 默认行为已更改

drizzle-kit push 和 drizzle-kit pull 现在默认管理所有模式，而不只是 public。它现在也支持 glob 模式。

// ❌ 之前（0.x）— 默认只管理 `public`，仅支持显式列表
export default defineConfig({
  schemaFilter: ['public', 'analytics'],
});

// ✅ 之后（1.0）— 默认管理所有模式，支持 glob 模式
export default defineConfig({
  // 如果你希望管理所有模式，则不需要 schemaFilter
});

// 若要限制为特定模式，你仍然可以使用 schemaFilter：
export default defineConfig({
  schemaFilter: ['public', 'app_*'], // 支持 glob 模式
});

drizzle-kit push --strict 弃用

--strict 标志已被移除——其行为现在是默认行为。drizzle-kit push 在执行可能导致数据丢失的语句时始终会请求确认，除非传入 --force 标志。使用 drizzle-kit push —explain 可以在运行前预览将要执行的 SQL。

其他功能

JIT 映射器（可选启用）

即时编译的行映射器，使映射速度与原始驱动一样快。 你可以在这里了解更多

const db = drizzle({ ..., jit: true });

编解码器

这是一个面向驱动的转换层，用于规范化与数据库之间的请求/响应。它可解决常规 select、JSON 对象和数组上下文中的数据映射不一致问题。 你可以在这里了解更多

新的 MSSQL 方言

已新增对 MSSQL 方言的支持。你可以在这里了解更多

新的 CockroachDB 方言

已新增对 CockroachDB 方言的支持。你可以在这里了解更多

新的 NetlifyDB 驱动

已新增对 NetlifyDB 驱动的支持。你可以在这里了解更多

Effect 集成

• 新增 @effect/sql-pg 驱动支持。你可以在这里了解更多
• 通过 drizzle-orm/effect-schema 提供 Effect Schema 验证。你可以在这里了解更多

SQLcommenter 支持

为查询添加自定义标签。标签会作为 SQL 注释放在每个查询末尾。你可以在这里了解更多

db.select().from(users).comment("my_first_tag");
// select "id", "name" from "users" /*my_first_tag*/

通过 .as() 设置列别名

你可以在这里了解更多别名信息

const query = db
  .select({ age: users.age.as('ageOfUser'), id: users.id.as('userId') })
  .from(users)
  .orderBy(asc(users.id.as('userId')));

预编译查询

.prepare(name) 中的 name 现在是可选的

drizzle-kit 全面重写

该工具已在架构层面重新设计：

• 从数据库快照迁移为 DDL 快照
• 重写了 diff 检测与应用逻辑
• 模式内省时间从约 10 秒降至不到 1 秒
• 为 push 添加了查询提示和 explain 支持

drizzle-kit pull --init

创建 drizzle 迁移表，并将首次拉取的迁移标记为已应用。你可以在这里了解更多

drizzle-kit push --explain

显示将要执行但不会实际运行的 SQL。你可以在这里了解更多

drizzle-kit check — 交换性检查

检测跨分支的不可交换迁移——例如，两个分支修改同一列，或一个分支重命名表而另一个分支正在修改该表。

其工作方式：

• 基于快照 prevIds 构建 DAG，以理解分支结构
• 找到分支分叉的节点
• 计算从父快照到每个分支叶节点的 DDL diff
• 使用 footprint map 检查哪些 DDL 语句类型可能产生冲突

如果发现冲突，报告会准确告诉你哪些分支上的哪些迁移不兼容

drizzle-kit --ignore-conflicts 标志

当你知道这些冲突是预期行为时，可绕过交换性检查。

drizzle-kit generate：迁移冲突检测

drizzle-kit generate 现在会识别迁移分支之间的不兼容更改。使用 --ignore-conflicts 可绕过。

迁移表更新

当你运行 drizzle-kit up 时，迁移表会自动升级。新增两个列：

• name — 完整的迁移文件夹名称（例如 20250220153045_brave_wolverine）
• applied_at — 迁移执行时间戳（之前的记录会回填为 NULL）

迁移现在通过完整文件夹名称而不是时间戳进行匹配。即使两个迁移在同一秒生成，名称后缀也能保证唯一性。

在升级过程中，现有记录会通过多步策略进行回填：

1. 毫秒匹配 — 将存储的毫秒截断到秒，并与本地文件夹时间戳匹配
2. 哈希判别 — 如果多个迁移共享同一秒，则通过 SQL 哈希进行区分
3. 仅哈希回退 — 如果毫秒匹配完全失败，则仅通过哈希匹配

这意味着升级可处理所有边缘情况：普通的单开发者项目、迁移时间非常接近的团队，甚至旧的 journal 数据与新的文件夹名称并不完全一致的情况。

Migrator 会应用所有缺失的迁移

以前 migrator 只会查找创建时间晚于最后一次已应用迁移的本地迁移。现在它会检测并应用每一个缺失的迁移，不受时间戳顺序影响。所有迁移都通过完整文件夹名称（14 位 UTC 时间戳 + 名称后缀）进行匹配。

drizzle 配置文件中的顶层 await

现在在 Node.js 上，drizzle.config.ts 和 schema 文件支持顶层 await。

Drizzle-kit：构建系统改进

• 从 esbuild-register 迁移到 tsx loader —— 无缝支持 ESM 和 CJS
• 原生支持 Bun 和 Deno 启动

TS Schema 文件处理

仅处理以下扩展名的文件：.js、.mjs、.cjs、.jsx、.ts、.mts、.cts、.tsx。所有其他文件类型都会被忽略。