企业官网建设流程全解析

drizzle-orm-sqlite 0.14.1 迁移指南：独立 migrate 导入、drizzle() 工厂函数与驱动导入路径变更

【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm

导读

drizzle-orm-sqlite 0.14.1 是一次以"API 收敛"为核心的版本更新，对使用 better-sqlite3 的 SQLite 项目带来了三处直接影响日常写法的变更：迁移功能被拆分为独立的子路径导入、初始化数据库的方式从显式构造SQLiteConnector改为统一的drizzle(client)工厂函数、驱动模块的导入路径随之调整。读完本文，你将清楚知道旧代码需要如何迁移到新 API，并理解这些变更在源码层的真实含义与背后设计动机。

变更一：迁移功能被拆分为独立导入

0.14.1 将迁移（migrations）功能从主包路径中拆出，需要从专门的子路径导入：

import { migrate } from 'drizzle-orm-sqlite/better-sqlite3/migrate';

这一拆分的直接好处是：不再使用迁移功能的项目可以避免加载迁移相关代码（包括对fs、crypto等 Node 内置模块的依赖），从而获得更小的打包体积，也让主入口的职责更加单一。

migrate 的签名与配置项

在源码中，migrate函数位于 drizzle-orm/src/better-sqlite3/migrator.ts，其实现非常简洁：

export function migrate<TSchema extends Record<string, unknown>>( db: BetterSQLite3Database<TSchema>, config: MigrationConfig, ) { const migrations = readMigrationFiles(config); db.dialect.migrate(migrations, db.session, config); }

它接收两个参数：

• db：通过drizzle(client)创建的BetterSQLite3Database实例；
• config：MigrationConfig，定义在 drizzle-orm/src/migrator.ts：

export interface MigrationConfig { migrationsFolder: string; migrationsTable?: string; migrationsSchema?: string; }

一个完整的调用示例：

import { drizzle } from 'drizzle-orm-sqlite/better-sqlite3'; import { migrate } from 'drizzle-orm-sqlite/better-sqlite3/migrate'; import Database from 'better-sqlite3'; const sqlite = new Database('sqlite.db'); const db = drizzle(sqlite); migrate(db, { migrationsFolder: 'drizzle' });

迁移执行的底层链路

migrate内部先调用readMigrationFiles读取迁移文件（drizzle-orm/src/migrator.ts）。它会定位migrationsFolder/meta/_journal.json，按 journal 中记录的entries顺序逐个读取对应.sql文件，并以--> statement-breakpoint为分隔符将 SQL 拆分为语句数组，同时记录每个迁移的时间戳（folderMillis）和基于 SHA-256 的内容哈希（hash）。

随后由SQLiteSyncDialect.migrate执行（drizzle-orm/src/sqlite-core/dialect.ts），执行流程如下：

1. 创建迁移元数据表（默认__drizzle_migrations），字段为id、hash、created_at；
2. 查询最后一条已执行迁移的created_at；
3. 在单个事务中（BEGIN/COMMIT）依次执行所有folderMillis大于已执行记录时间的迁移语句，并将hash与时间戳写入元数据表；
4. 任一语句失败则整体ROLLBACK并抛出异常。

这也是为什么迁移文件必须按时间顺序生成、且不能随意改动已执行过的迁移内容——一旦哈希与记录不一致，后续增量判断就会出错。

变更二：用drizzle(client)取代SQLiteConnector.connect()

0.14.1 移除了旧的连接器写法：

// 旧写法（0.14.1 起不再使用） const connector = new SQLiteConnector(client); const db = await connector.connect();

取而代之的是统一的工厂函数：

import Database from 'better-sqlite3'; import { drizzle } from 'drizzle-orm-sqlite/better-sqlite3'; const client = new Database('sqlite.db'); const db = drizzle(client);

这一变更的价值在于：所有方言/驱动的初始化入口被收敛为同一个drizzle()命名空间，心智负担更低，也便于未来统一扩展参数。从源码看，drizzle函数（drizzle-orm/src/better-sqlite3/driver.ts）是一个支持多种调用形态的重载：

• drizzle()——不传参数时内部自动new Client()，创建一个内存数据库实例；
• drizzle(client)——直接传入better-sqlite3的Database实例；
• drizzle(connectionString)——传入文件路径字符串，内部自行构造Client；
• drizzle({ client })或drizzle({ connection: { source, ...options } })——以配置对象形式传入，并可与schema、logger、casing等 Drizzle 配置合并。

其内部会创建SQLiteSyncDialect、BetterSQLiteSession与BetterSQLite3Database三层结构，并额外挂载$client属性以便直接访问底层驱动实例。例如同时开启日志：

const db = drizzle(client, { logger: true });

或直接传入配置对象并指定数据库文件：

const db = drizzle({ connection: { source: 'sqlite.db' }, logger: true, });

对于测试场景，还可以使用drizzle.mock()（见 drizzle-orm/src/better-sqlite3/driver.ts）构造一个不连接真实数据库的实例。

变更三：导入路径统一为驱动子路径

0.14.1 同时统一了导入路径。旧代码中的：

import { SQLiteConnector } from 'drizzle-orm-sqlite';

应替换为：

import { drizzle } from 'drizzle-orm-sqlite/better-sqlite3';

需要说明的是，原版更新日志中这一条写作import { drizzle } from 'drizzle-orm-pg/better-sqlite3'，结合上下文与当前仓库的目录结构（drizzle-orm/src/better-sqlite3）判断，这应为drizzle-orm-sqlite/better-sqlite3的笔误——SQLite 的 better-sqlite3 驱动并不存在于drizzle-orm-pg包中，实际代码应以drizzle-orm-sqlite/better-sqlite3为准。

drizzle-orm-sqlite/better-sqlite3子路径导出driver.ts与session.ts两个模块（见 drizzle-orm/src/better-sqlite3/index.ts），其中driver.ts提供drizzle工厂函数与BetterSQLite3Database类型，session.ts提供会话、事务与预编译查询的同步实现。若你的代码里显式引用了BetterSQLite3Database、BetterSQLiteSession等类型，也应一并从该子路径导入。

迁移清单速查

将旧项目升级到 drizzle-orm-sqlite 0.14.1 及以上版本时，可按下表逐项核对：

升级后建议立即运行一次类型检查与一条真实的查询语句，确认导入路径、迁移执行和查询结果均正常；对存量数据库，迁移元数据表（默认__drizzle_migrations）会被自动复用，已执行的迁移不会被重复执行。

小结

drizzle-orm-sqlite 0.14.1 的三项变更是典型的"API 规范化"重构：迁移模块独立成子路径、数据库初始化统一走drizzle()工厂函数、驱动导入路径按方言子目录收敛。它们不改变查询 API 的使用方式，但显著改善了模块边界与导入语义。理解这些变更背后的源码结构（migrator.ts的文件读取与事务执行、driver.ts的重载分发、dialect.ts的迁移元数据管理），能让你在升级时更从容，也能在后续排查迁移问题时更快定位到关键代码。

【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm