跳到正文
Drizzle

PostgreSQL 列类型

drizzle-orm/pg-core 列类型完整参考:整数、浮点、精确小数、字符串、日期时间、JSON、UUID、枚举、数组、几何、网络与向量类型及常用选项。

所有 PostgreSQL 列构造函数都从 drizzle-orm/pg-core 导入。每个构造函数对应一个原生 PG 类型,并通过配置对象与链式方法控制精度、时区、默认值等行为。本页按类别给出完整速查表;约束与索引见 索引与约束,自定义映射见 自定义类型。

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

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow(),
});

整数与自增整数

构造函数PG 类型TS 类型说明
integer()(别名 int()、int4())integernumber32 位有符号整数
smallint()(别名 int2())smallintnumber16 位有符号整数
bigint()(别名 int8())bigintbigint(默认)或 number64 位,mode 可选
serial()serialnumber自增 32 位,隐含 NOT NULL
smallserial()smallserialnumber自增 16 位
bigserial()bigserialbigint(默认)或 number自增 64 位,mode 可选

bigint 与 bigserial 的 mode: 'number' 会把值转成 JS number,超出 Number.MAX_SAFE_INTEGER 时会丢失精度;需要完整 64 位范围时保持默认的 bigint 模式。

import { bigint, bigserial, integer, pgTable } from 'drizzle-orm/pg-core';

export const counters = pgTable('counters', {
  id: bigserial('id', { mode: 'number' }).primaryKey(),
  views: bigint('views', { mode: 'bigint' }).notNull(), // 保持 bigint
  score: integer('score').default(0),
});

serial 还是 identity?

serial 底层是序列加默认值;PG 10+ 更推荐 SQL 标准的 identity 列:integer('id').generatedAlwaysAsIdentity() 或 .generatedByDefaultAsIdentity({ startWith: 1000 })。序列的独立管理见 序列。

浮点与精确小数

构造函数PG 类型TS 类型选项
real()real(float4)number无
doublePrecision()double precision(float8)number无
numeric()(别名 decimal())numericstring(默认)、number 或 bigintprecision、scale、mode

numeric 的 precision 是总位数,scale 是小数位数。mode 决定查询结果的 JS 类型:默认 'string' 最安全,'number' 有精度风险,'bigint' 只适合无小数的场景。

import { doublePrecision, numeric, pgTable, real } from 'drizzle-orm/pg-core';

export const products = pgTable('products', {
  price: numeric('price', { precision: 10, scale: 2 }).notNull(), // string
  weight: real('weight'),
  ratio: doublePrecision('ratio'),
});

金额不要用浮点

real 与 doublePrecision 是近似类型,金额、计费等场景请使用 numeric 并保持字符串模式,在应用层用十进制库运算。

字符串与文本

构造函数PG 类型TS 类型选项
text()textstringenum
varchar()varcharstringlength、enum
char()charstringlength、enum

varchar 不传 length 时等价于无长度限制;char 会按长度补空格。enum 选项只收窄 TypeScript 类型(联合字面量),不会在数据库或运行时做校验——需要真正的枚举约束请用 pgEnum 或 check。

import { char, pgTable, text, varchar } from 'drizzle-orm/pg-core';

export const articles = pgTable('articles', {
  slug: varchar('slug', { length: 128 }).notNull(),
  countryCode: char('country_code', { length: 2 }),
  status: text('status', { enum: ['draft', 'published'] }).default('draft'),
});

布尔与二进制

构造函数PG 类型TS 类型说明
boolean()booleanboolean无选项
bytea()byteastring二进制数据,十六进制字符串表示

bytea 的版本差异

bytea() 见于官方列类型文档,但部分 drizzle-orm 发行版未导出该构造函数。若导入报错,可用 customType 映射 bytea,或升级 drizzle-orm 后再试。

日期与时间

构造函数PG 类型TS 类型选项
date()dateDate(默认)或 stringmode: 'date' 或 'string'
time()time / timetzstringprecision(0–6)、withTimezone
timestamp()timestamp / timestamptzDate(默认)或 stringprecision(0–6)、withTimezone、mode
interval()intervalstringfields(如 'day to second')、precision

withTimezone: true 生成 timestamptz,存储 UTC 时刻并按会话时区展示;mode: 'string' 让驱动原样返回字符串,避免 Date 转换。timestamp 支持 .defaultNow()(生成 now())。

import { date, interval, pgTable, time, timestamp } from 'drizzle-orm/pg-core';

export const events = pgTable('events', {
  day: date('day', { mode: 'string' }).notNull(), // '2025-01-01'
  startsAt: time('starts_at', { precision: 0, withTimezone: true }),
  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
  duration: interval('duration', { fields: 'hour to second' }),
});

JSON

构造函数PG 类型TS 类型说明
json()jsonunknown,可用 .$type<T>() 收窄保留原文本格式
jsonb()jsonbunknown,可用 .$type<T>() 收窄二进制存储,支持索引与丰富操作符

绝大多数场景选 jsonb。.$type<T>() 只影响 TypeScript 类型,不做运行时校验。

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

export const settings = pgTable('settings', {
  prefs: jsonb('prefs').$type<{ theme: 'light' | 'dark'; pageSize: number }>(),
  tags: jsonb('tags').$type<string[]>().default([]),
});

UUID

uuid() 对应 PG uuid,TS 类型为 string。.defaultRandom() 生成数据库端默认值 gen_random_uuid()(PG 13+ 内置)。

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

export const sessions = pgTable('sessions', {
  id: uuid('id').primaryKey().defaultRandom(),
});

枚举:pgEnum

PostgreSQL 的枚举是独立的数据库类型,用 pgEnum 声明后像列构造函数一样使用,迁移时会生成 CREATE TYPE。

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

export const mood = pgEnum('mood', ['sad', 'ok', 'happy']);

export const diary = pgTable('diary', {
  today: mood('today').notNull(),
  history: mood('history').array(), // 枚举数组
});
CREATE TYPE "mood" AS ENUM ('sad', 'ok', 'happy');

数组

任意列构造函数都可链式调用 .array() 变成数组列,可选传入尺寸上限 .array(n)。TS 类型相应变为元素类型的数组。

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

export const posts = pgTable('posts', {
  tags: text('tags').array().notNull(), // text[]
  scores: integer('scores').array(3), // integer[3]
});

几何、网络与向量

构造函数PG 类型TS 类型选项
point()point[number, number] 或 { x, y }mode: 'tuple' 或 'xy'
line()line[number, number, number] 或 { a, b, c }mode: 'tuple' 或 'abc'
geometry()PostGIS geometry元组或 { x, y }type、mode、srid
inet()inetstringIPv4/IPv6 主机地址
cidr()cidrstring网段
macaddr() / macaddr8()macaddr / macaddr8stringMAC 地址

geometry() 来自 PostGIS 扩展,需先启用扩展(见 扩展):

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

export const places = pgTable('places', {
  location: point('location', { mode: 'xy' }), // { x: 1, y: 2 }
  geo: geometry('geo', { type: 'point', mode: 'xy', srid: 4326 }),
});

pgvector 扩展提供向量列(同样从 drizzle-orm/pg-core 导入,需先 CREATE EXTENSION vector):

构造函数PG 类型TS 类型选项
vector()vectornumber[]dimensions 必填
halfvec()halfvecnumber[]dimensions 必填
sparsevec()sparsevecstringdimensions 必填
bit()bit(pgvector 二进制向量)stringdimensions 必填

bit 不是传统位串

这里的 bit({ dimensions }) 是 pgvector 的二进制向量类型。传统 SQL 位串 BIT(n) / BIT VARYING(n) 没有专用构造函数,请用 customType 映射。

类型收窄与运行时钩子

  • .$type<T>():为 json/jsonb/text 等列标注更精确的 TS 类型,也可用于 branded 类型(如 .$type<UserId>())。
  • .$defaultFn(() => ...)(别名 $default()):插入时在应用端计算默认值,不写入数据库 DDL。
  • .$onUpdateFn(() => ...)(别名 $onUpdate()):每次 update 时在应用端重算该列,同样不影响迁移。

数据库端的默认值请用 .default() / .defaultNow() / .defaultRandom();生成列见 生成列。

接下来