实用工具 - Drizzle ORM 中文文档

Type API

使用 Drizzle 的类型辅助工具，从 PostgreSQL 表结构中推断 select 和 insert 模型。

import { serial, text, pgTable } from 'drizzle-orm/pg-core';
import { type InferSelectModel, type InferInsertModel } from 'drizzle-orm';

const users = pgTable('users', {
  id: serial().primaryKey(),
  name: text().notNull(),
});

type SelectUser = typeof users.$inferSelect;
type InsertUser = typeof users.$inferInsert;

type SelectUserAlt = InferSelectModel<typeof users>;
type InsertUserAlt = InferInsertModel<typeof users>;

日志记录

通过向 drizzle 传递 { logger: true } 来启用默认查询日志记录。

import { drizzle } from "drizzle-orm/...";

const db = drizzle(process.env.DB_URL, { logger: true });

你可以通过创建一个 DefaultLogger 实例并向其提供自定义 writer 来更改日志输出目标：

import { DefaultLogger, type LogWriter } from "drizzle-orm/logger";
import { drizzle } from "drizzle-orm/...";

class MyLogWriter implements LogWriter {
  write(message: string) {
    // 写入文件、标准输出等。
  }
}

const logger = new DefaultLogger({ writer: new MyLogWriter() });
const db = drizzle(process.env.DB_URL, { logger });

你也可以提供自定义日志记录器。

import type { Logger } from 'drizzle-orm/logger';
import { drizzle } from "drizzle-orm/...";

class MyLogger implements Logger {
  logQuery(query: string, params: unknown[]): void {
    console.log({ query, params });
  }
}

const db = drizzle(process.env.DB_URL, { logger: new MyLogger() });

多项目 schema

当多个项目共享一个数据库时，使用 pgTableCreator 自定义表名。

import { serial, text, pgTableCreator } from 'drizzle-orm/pg-core';

const pgTable = pgTableCreator((name) => `project1_${name}`);

export const users = pgTable('users', {
  id: serial().primaryKey(),
  name: text().notNull(),
});

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/schema/*',
  out: './drizzle',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
  tablesFilter: ['project1_*'],
});

CREATE TABLE "project1_users" (
	"id" serial PRIMARY KEY,
	"name" text NOT NULL
);

打印 SQL 查询

使用 .toSQL() 打印查询生成的 SQL。

const query = db
  .select({ id: users.id, name: users.name })
  .from(users)
  .groupBy(users.id)
  .toSQL();

原始 SQL 查询

使用 db.execute 执行原始参数化 SQL。

import { sql } from 'drizzle-orm';

const statement = sql`select * from ${users} where ${users.id} = ${userId}`;
const result = await db.execute(statement);

独立查询构建器

无需创建数据库实例即可使用 PostgreSQL 查询构建器。

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

const qb = new QueryBuilder();
const query = qb.select().from(users).where(eq(users.name, 'Dan'));
const { sql, params } = query.toSQL();

获取类型化列

使用 getColumns 获取类型化列映射，这在从选择中排除字段时很有用。

index.ts

schema.ts

import { getColumns } from 'drizzle-orm';
import { users } from './schema';

const { password, role, ...rest } = getColumns(users);

await db.select({ ...rest }).from(users);

import { serial, text, pgTable } from "drizzle-orm/pg-core";

export const user = pgTable("user", {
  id: serial().primaryKey(),
  name: text(),
  email: text(),
  password: text(),
  role: text().$type<"admin" | "customer">(),
});

获取表信息

使用 getTableConfig 检查 PostgreSQL 表元数据。

import { getTableConfig, pgTable } from 'drizzle-orm/pg-core';

export const table = pgTable(...);

const { columns, indexes, foreignKeys, checks, primaryKeys, name, schema } =
  getTableConfig(table);

比较对象类型

使用 is() 而不是 instanceof 来检查 Drizzle 对象类型。

import { Column, is } from 'drizzle-orm';

if (is(value, Column)) {
  // value 被缩小为 Column
}

模拟驱动

当你需要一个带类型的数据库对象，但不需要真实的 PostgreSQL 连接时，请使用 drizzle.mock()。

import { drizzle } from 'drizzle-orm/node-postgres';
import { relations } from './relations';

const db = drizzle.mock({ relations });