跳到正文
Drizzle

多 Schema 组织

用 pgSchema 与 mysqlSchema 把表、枚举、序列组织进独立命名空间,并配置 drizzle-kit 的 schemaFilter。

PostgreSQL 的 schema 是数据库内的命名空间(默认是 public);MySQL 中 schema 与 database 是同义词。Drizzle 通过 pgSchema('name') / mysqlSchema('name') 声明命名空间,再用 .table()、.enum()、.sequence() 等方法在其中创建对象。SQLite 没有 schema 概念(ATTACH 的库不在 Drizzle 建模范围内)。

声明与使用

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

// 声明命名空间
export const billing = pgSchema('billing');

// 枚举、序列、表都挂在 schema 上
export const invoiceStatus = billing.enum('invoice_status', ['draft', 'paid']);
export const invoiceSeq = billing.sequence('invoice_seq', { startWith: 1000 });

export const invoices = billing.table('invoices', {
  id: serial('id').primaryKey(),
  status: invoiceStatus('status').default('draft').notNull(),
  memo: text('memo'),
});

生成的迁移会先建 schema,再建其中的对象:

CREATE SCHEMA "billing";
CREATE TYPE "billing"."invoice_status" AS ENUM ('draft', 'paid');
CREATE SEQUENCE "billing"."invoice_seq" START WITH 1000;
CREATE TABLE "billing"."invoices" (
  "id" serial PRIMARY KEY,
  "status" "billing"."invoice_status" DEFAULT 'draft' NOT NULL,
  "memo" text
);

查询:自动带上限定名

schema 中的表在查询时会自动生成 "billing"."invoices" 这样的限定名,不依赖连接的 search_path:

import { eq } from 'drizzle-orm';
import { invoices } from './schema';

// SQL: select ... from "billing"."invoices" where "billing"."invoices"."id" = $1
const rows = await db.select().from(invoices).where(eq(invoices.id, 1));

跨 schema 的外键与 join 也没问题——直接引用不同 schema 导出的表对象即可:

import { pgTable, serial, integer } from 'drizzle-orm/pg-core';
import { invoices } from './schema'; // billing schema 中的表

// public 中的表引用 billing 中的表
export const payments = pgTable('payments', {
  id: serial('id').primaryKey(),
  invoiceId: integer('invoice_id')
    .notNull()
    .references(() => invoices.id), // 生成 references "billing"."invoices"("id")
});

与默认 public 的关系

  • pgTable(...) 声明的表不带 schema 前缀,落在连接 search_path 的第一个可写 schema,通常是 public。
  • pgSchema('public') 也可以显式声明 public,生成 "public"."users" 这样的限定名。两种写法在 drizzle-kit 眼里是不同实体,混用会导致 generate 反复生成删表/建表,一个项目里只选一种。
  • 同一个 pgSchema('billing') 可以在多个文件里重复调用(同名即同一命名空间),便于按业务拆分文件:
// src/db/billing/invoices.ts 与 src/db/billing/refunds.ts 各自:
export const billing = pgSchema('billing');

drizzle-kit 的 schemaFilter

默认情况下 introspect(pull)与 push 只处理 public。要管理其他 schema,必须在 drizzle.config.ts 里配置 schemaFilter:

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  dialect: 'postgresql',
  schema: './src/db/schema.ts',
  out: './drizzle',
  dbCredentials: { url: process.env.DATABASE_URL! },
  // introspect / push 时纳入这些 schema
  schemaFilter: ['public', 'billing'],
});

schemaFilter 缺失的后果

如果 schema 里有表但 schemaFilter 没包含它,push 会认为数据库里“多出了”这些表并可能提议删除;introspect 则会漏掉它们。管理多 schema 时这是最常见的事故来源。generate 不受 schemaFilter 影响——它只看 schema 文件。

Supabase 等项目还常用 entities、extensionsFilters 等配置排除托管对象,参见 扩展 与 drizzle-kit。

search_path 注意事项

Drizzle 生成的 SQL 都带限定名,但手写 sql 片段不会自动加前缀:

import { sql } from 'drizzle-orm';

// 危险:依赖 search_path,换个连接配置可能查错表
await db.execute(sql`select * from invoices`);

// 安全:显式限定
await db.execute(sql`select * from billing.invoices`);

同理,列默认值里的 nextval('invoice_seq')、函数调用、CHECK 约束中的裸对象名都受 search_path 影响。托管数据库(Supabase、Neon 等)的默认 search_path 各不相同,写原生 SQL 时一律带 schema 限定最稳妥。

迁移行为小结

  • 新增 pgSchema 会生成 CREATE SCHEMA;从 schema 文件中移除声明会生成 DROP SCHEMA(连带对象),删 schema 前务必确认数据去向。
  • 把表从 public 挪进 schema(pgTable 改为 schema.table)会被视为删旧表 + 建新表,不是 ALTER … SET SCHEMA,数据会丢失——这类重构必须手写自定义迁移(见 迁移)。
  • 序列、枚举、视图(schema.view(...))都可以挂在 schema 下,行为与 public 中一致。