索引与约束
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 迁移默认逐语句执行时需注意;大表加唯一约束前先用普通索引验证无重复数据。修改列类型或约束时,先检查既有数据是否满足新约束。