跳到正文
Drizzle

SQLite 列类型

drizzle-orm/sqlite-core 列类型参考:integer、real、text、blob、numeric 与 mode 选项(timestamp、boolean、json),存储类映射及枚举/数组的替代方案。

SQLite 只有五种存储类:NULL、INTEGER、REAL、TEXT、BLOB。列的「类型名」只决定类型亲和性(affinity),实际存什么由值本身决定。Drizzle 据此只提供五个列构造函数,全部从 drizzle-orm/sqlite-core 导入,丰富的语义(布尔、时间戳、JSON、大整数)通过 mode 选项实现。

import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';

export const users = sqliteTable('users', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  name: text('name').notNull(),
});

存储类与构造函数对照

构造函数声明的列类型存储类TS 类型(默认)
integer()integerINTEGERnumber
real()realREALnumber
text()textTEXTstring
blob()blobBLOBunknown(JSON 模式)
numeric()numericNUMERIC 亲和string

integer 与 mode

integer 的 mode 决定应用层如何解释这个 64 位整数:

modeTS 类型存储内容典型用途
'number'(默认)number整数原值计数、外键
'boolean'boolean0 / 1布尔标志
'timestamp'DateUnix 秒创建/更新时间
'timestamp_ms'DateUnix 毫秒需要毫秒精度的时间
import { integer, sqliteTable } from 'drizzle-orm/sqlite-core';

export const posts = sqliteTable('posts', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  published: integer('published', { mode: 'boolean' }).notNull().default(false),
  createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
  updatedAtMs: integer('updated_at_ms', { mode: 'timestamp_ms' }),
});

自增主键

SQLite 的自增写法是 integer('id').primaryKey({ autoIncrement: true }),对应 INTEGER PRIMARY KEY AUTOINCREMENT。只有 integer 主键支持自增;不加 autoIncrement 时 INTEGER PRIMARY KEY 本身就是 rowid 别名,通常已够用且更快。

mode: 'number' 下超过 Number.MAX_SAFE_INTEGER(2 的 53 次方减 1)的值会丢精度;需要完整 64 位整数时用 blob({ mode: 'bigint' })。

real

real() 对应 8 字节 IEEE 浮点数,无选项。金额等精确小数场景 SQLite 没有原生 decimal,常见做法是以最小单位(分)存 integer,或用 text / numeric 存字符串并在应用层用十进制库运算。

text 与 mode

text 支持三个选项:

选项作用
length声明 text(length),SQLite 本身不强制长度
enum收窄 TS 类型为字面量联合,不做运行时校验
mode: 'json'TS 类型变为结构化对象,读写自动 JSON 序列化
import { sqliteTable, text } from 'drizzle-orm/sqlite-core';

export const articles = sqliteTable('articles', {
  slug: text('slug', { length: 128 }).notNull(),
  status: text('status', { enum: ['draft', 'published'] }).default('draft'),
  meta: text('meta', { mode: 'json' }).$type<{ views: number; tags: string[] }>(),
});

JSON 请用 text 而不是 blob

官方建议 JSON 数据使用 text({ mode: 'json' }):SQLite 的 JSON 函数(json_extract 等)不接受 BLOB 输入,存成 blob 会让这些函数失效。

blob 与 mode

blob 的 mode 决定 TS 类型与编码方式:

modeTS 类型说明
'json'(默认)unknown,可用 .$type<T>()JSON 序列化后存入 BLOB
'buffer'Buffer原始二进制
'bigint'bigint完整 64 位整数
import { blob, sqliteTable } from 'drizzle-orm/sqlite-core';

export const assets = sqliteTable('assets', {
  thumbnail: blob('thumbnail', { mode: 'buffer' }),
  bigCounter: blob('big_counter', { mode: 'bigint' }),
});

numeric

numeric() 声明 NUMERIC 亲和性:能无损转成整数或浮点的文本会被转换存储。mode 可选 'string'(默认)、'number'、'bigint',适合需要保留十进制文本的场景。

import { numeric, sqliteTable } from 'drizzle-orm/sqlite-core';

export const ledger = sqliteTable('ledger', {
  amount: numeric('amount', { mode: 'string' }).notNull(), // 保留十进制文本
});

默认值与运行时钩子

  • .default(value):常量默认值,写入 DDL。
  • .default(sql`...`):表达式默认值,如 sql`(CURRENT_TIMESTAMP)` (注意 SQLite 的 CURRENT_TIMESTAMP 产生 UTC 文本,配 timestamp 模式时需自行约定格式)。
  • .$defaultFn(() => ...):插入时在应用端计算,不写入 DDL,适合 crypto.randomUUID() 之类。
  • .$onUpdateFn(() => ...):每次 update 时在应用端重算,适合 updatedAt。
import { sql } from 'drizzle-orm';
import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';

export const notes = sqliteTable('notes', {
  id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
  body: text('body').notNull().default(''),
  createdAt: integer('created_at', { mode: 'timestamp' })
    .notNull()
    .$defaultFn(() => new Date()),
  updatedAt: integer('updated_at', { mode: 'timestamp' })
    .$defaultFn(() => new Date())
    .$onUpdateFn(() => new Date()),
});

数据库端时间默认值也可以写成 text('created_at').default(sql`(CURRENT_TIMESTAMP)`),存 ISO 风格文本;应用端钩子则存 Unix 秒,两者不要混用在同一列。

日期时间的存储方式对比

SQLite 没有日期类型,官方支持三种存储形态,Drizzle 都能映射:

存储形态Drizzle 写法优点缺点
Unix 秒 / 毫秒integer({ mode: 'timestamp' }) / 'timestamp_ms'紧凑、比较快、时区无歧义可读性差
ISO 8601 文本text() 存 '2025-01-01 00:00:00'可读、date() 等函数直接可用占空间、需约定时区
儒略日real()官方日期函数的内部格式应用层几乎不用

同一张表内保持一种约定;跨时区应用推荐 Unix 时间戳或统一 UTC 文本。

类型亲和性规则

建表时写的类型名按以下顺序决定亲和性(SQLite 官方规则):

类型名包含亲和性
INTINTEGER
CHAR、CLOB 或 TEXTTEXT
BLOB,或未写类型BLOB
REAL、FLOA 或 DOUBREAL
其他(如 NUMERIC、DECIMAL、BOOLEAN)NUMERIC

因此 text('x') 声明为 TEXT 亲和,写入数字会转成文本存储;numeric 则尽量把文本转成数值。Drizzle 的五个构造函数已覆盖全部亲和性,mode 只影响应用层编解码,不改变存储类。

声明的类型名会原样写入 DDL(如 text(128)),便于与既有数据库工具或 dump 文件对照。

没有原生类型时的替代方案

SQLite 没有独立的布尔、日期时间、枚举、数组类型,Drizzle 的对应做法:

需求推荐写法说明
布尔integer({ mode: 'boolean' })存 0/1
日期时间integer({ mode: 'timestamp' }) 或 text 存 ISO 字符串秒/毫秒时间戳或 mode: 'string' 文本
大整数blob({ mode: 'bigint' })避免 number 精度损失
枚举text({ enum: [...] }) 加 check 约束enum 只管 TS 类型,取值约束靠数据库
数组 / JSONtext({ mode: 'json' })可配合 SQLite JSON 函数查询
多值关系关联表需要按元素过滤/索引时优于 JSON 数组

枚举加 check 的完整示例(check 详见 索引与约束):

import { sql } from 'drizzle-orm';
import { check, sqliteTable, text } from 'drizzle-orm/sqlite-core';

export const tickets = sqliteTable(
  'tickets',
  {
    status: text('status', { enum: ['open', 'closed'] }).notNull().default('open'),
  },
  (t) => [check('status_check', sql`${t.status} in ('open', 'closed')`)],
);

接下来