跳到正文
Drizzle

动态查询构建

用 $dynamic() 解除查询构建器方法只能调用一次的限制,编写可复用的分页、过滤与 join 增强函数。

Drizzle 的查询构建器默认贴近 SQL 语义:一条 select 只有一个 where,所以大多数方法只能调用一次。这适合一次性写完整条查询,但当你想把查询传给共享函数逐步增强时就成了障碍。.$dynamic() 就是为此而生。本页示例假设已有 db 实例与 users、posts 等表。

默认限制

const query = db
  .select()
  .from(users)
  .where(eq(users.id, 1))
  .where(eq(users.name, 'John')); // ❌ 类型错误:where() 只能调用一次

Drizzle 不会把多次 .where() 合并成一个条件——直接禁止,避免歧义。

开启动态模式

调用 .$dynamic() 后,方法可以重复调用(后写的覆盖/追加,视方法而定):

function withPagination<T extends PgSelect>(
  qb: T,
  page: number = 1,
  pageSize: number = 10,
) {
  return qb.limit(pageSize).offset((page - 1) * pageSize);
}

const query = db.select().from(users).where(eq(users.id, 1));
withPagination(query, 1); // ❌ 类型错误:不是动态模式

const dynamicQuery = query.$dynamic();
withPagination(dynamicQuery, 1); // ✅ OK

泛型保留结果类型

withPagination 使用泛型 T extends PgSelect,返回类型与传入类型一致。增强函数甚至可以改变结果形状,例如追加 join:

import type { PgSelect } from 'drizzle-orm/pg-core';

function withFriends<T extends PgSelect>(qb: T) {
  return qb.leftJoin(friends, eq(friends.userId, users.id));
}

let query = db.select().from(users).where(eq(users.id, 1)).$dynamic();
query = withFriends(query); // 返回类型包含 join 后的字段

可用的泛型约束类型

查询类型
SelectPgSelect / PgSelectQueryBuilder
InsertPgInsert
UpdatePgUpdate
DeletePgDelete

MySQL / SQLite 对应 MySqlSelect、SQLiteSelect 等同名系列。...QueryBuilder 类型用于独立查询构建器(new QueryBuilder(),不绑定 db);db 上的构建器是其子类,两者都可用:

import { QueryBuilder } from 'drizzle-orm/pg-core';

function withFriends<T extends PgSelectQueryBuilder>(qb: T) {
  return qb.leftJoin(friends, eq(friends.userId, users.id));
}

const qb = new QueryBuilder();
let query = qb.select().from(users).where(eq(users.id, 1)).$dynamic();
query = withFriends(query);

类型只能用于动态模式

PgSelect 等类型专为动态构建设计,只有 $dynamic() 之后的构建器才能赋给它们。

实战:可选过滤条件

典型的列表接口:过滤参数都是可选的。动态模式让「有则追加」变得自然:

import { and, eq, ilike, type SQL } from 'drizzle-orm';

function searchUsers(filters: { name?: string; verified?: boolean }) {
  let query = db.select().from(users).$dynamic();

  const conditions: SQL[] = [];
  if (filters.name) conditions.push(ilike(users.name, `%${filters.name}%`));
  if (filters.verified !== undefined) conditions.push(eq(users.verified, filters.verified));

  if (conditions.length > 0) query = query.where(and(...conditions));
  return query;
}

const result = await searchUsers({ name: 'dan' });

不要拼接用户输入

ilike 等运算符会把值参数化,安全;但不要把用户输入拼进 sql.raw()。详见 sql`` 模板运算符。

另一种不改查询形状的做法:先把条件收集到数组,最后一次性 .where(and(...))——无需动态模式,适合条件都在同一处组装的场景。动态模式的价值在于跨函数、分步骤地增强查询。

实战:可组合的排序与分页

function withOrder<T extends PgSelect>(qb: T, sort?: 'newest' | 'oldest') {
  if (sort === 'newest') return qb.orderBy(desc(users.id));
  if (sort === 'oldest') return qb.orderBy(asc(users.id));
  return qb;
}

const list = await withOrder(
  withPagination(db.select().from(users).$dynamic(), 2, 20),
  'newest',
);

小结

  • 一次性查询:直接用构建器,享受「方法只能调一次」带来的正确性保障。
  • 共享增强函数:参数约束为 T extends PgSelect 等类型,调用方先 .$dynamic()。
  • 可选条件:动态模式 + 条件数组,或集中组装 and(...conditions)。

延伸阅读:Select 查询、条件运算符、sql`` 模板运算符。