跳到正文
Drizzle

索引与约束

Drizzle 中主键、自增、notNull、default、unique、check、外键与索引的声明方式,覆盖 PostgreSQL、MySQL、SQLite 三种方言及迁移注意事项。

约束与索引在 Drizzle 中分两层声明:列级链式方法(.notNull()、.unique() 等)和表级第三参数回调(返回数组,放复合约束与索引)。三个方言的 API 形状一致,细节差异在下文标注。

列级约束与默认值

方法作用备注
.notNull()NOT NULL插入类型中变为必填
.default(value)常量默认值写入 DDL,如 DEFAULT 'draft'
.defaultNow()当前时间默认值PG timestamp、MySQL timestamp 等
.primaryKey()单列主键复合主键用表级 primaryKey()
.$defaultFn(fn)应用端默认值只在运行时执行,不写入 DDL

主键与自增

import { integer, pgTable, primaryKey, serial } from 'drizzle-orm/pg-core';

// serial 或 identity 自增
export const a = pgTable('a', { id: serial('id').primaryKey() });
export const b = pgTable('b', {
  id: integer('id').generatedAlwaysAsIdentity().primaryKey(),
});
// 复合主键(表级)
export const c = pgTable('c', {
  bookId: integer('book_id').notNull(),
  authorId: integer('author_id').notNull(),
}, (t) => [primaryKey({ columns: [t.bookId, t.authorId] })]);

复合主键三方言写法一致:表级 primaryKey({ columns: [t.bookId, t.authorId] }),可加 name: 'book_author_pk' 自定义约束名。

unique:列级与复合

import { integer, pgTable, text, unique } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  email: text('email').notNull().unique(), // 自动命名
  handle: text('handle').unique('users_handle_unique'), // 自定义名
  tenantId: integer('tenant_id').notNull(),
  seq: integer('seq').notNull(),
}, (t) => [
  unique('tenant_seq_unique').on(t.tenantId, t.seq), // 复合唯一
]);

PG 15+ 可让多个 NULL 视为重复:列级 .unique('name', { nulls: 'not distinct' }),表级 unique('name').on(...).nullsNotDistinct()。MySQL / SQLite 无此选项。

check

check(name, sql) 在表级声明检查约束,表达式用 sql 模板引用列:

import { sql } from 'drizzle-orm';
import { check, integer, pgTable } from 'drizzle-orm/pg-core';

export const accounts = pgTable('accounts', {
  age: integer('age'),
}, (t) => [check('age_check', sql`${t.age} > 21`)]);

外键

列级 .references(() => other.col, actions) 最常用;onDelete / onUpdate 可选值:'cascade'、'restrict'、'no action'(默认)、'set null'、'set default'。

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

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

export const posts = pgTable('posts', {
  id: serial('id').primaryKey(),
  authorId: integer('author_id').notNull()
    .references(() => users.id, { onDelete: 'cascade' }),
});

复合外键用表级 foreignKey({ columns: [...], foreignColumns: [...], name? })。自引用(如员工表引用上级)需要显式返回类型打破循环推断:PG 用 (): AnyPgColumn => users.managerId,MySQL / SQLite 对应 AnyMySqlColumn / AnySQLiteColumn。

索引

表级 index(name) 与 uniqueIndex(name) 建普通/唯一索引,.on() 接收一列或多列(复合索引),列可链式 .asc() / .desc():

import { index, pgTable, text, uniqueIndex } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  email: text('email').notNull(),
  lastName: text('last_name'),
  firstName: text('first_name'),
}, (t) => [
  uniqueIndex('email_idx').on(t.email),
  index('name_idx').on(t.lastName, t.firstName.desc()), // 复合 + 降序
]);

各方言的高级选项:

import { sql } from 'drizzle-orm';
import { index, pgTable, text } from 'drizzle-orm/pg-core';

export const docs = pgTable('docs', {
  title: text('title'),
  body: text('body'),
}, (t) => [
  index('title_idx')
    .on(t.title.asc().nullsFirst())
    .concurrently() // 不阻塞写入(不能在事务块内执行)
    .where(sql`${t.title} is not null`) // 部分索引
    .with({ fillfactor: '70' }),
  index('body_search_idx').using('gin', t.body), // 指定方法:btree/gin/gist 等
  index('title_ops_idx').using('btree', t.title.op('text_ops')), // opclass
]);

命名与迁移注意事项

显式命名,谨慎变更

复合约束与索引建议始终显式命名,否则 drizzle-kit 生成的自动名在重建表时可能变化,导致迁移反复 drop/create。concurrently 建索引不能包在事务里,drizzle-kit 迁移默认逐语句执行时需注意;大表加唯一约束前先用普通索引验证无重复数据。修改列类型或约束时,先检查既有数据是否满足新约束。