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

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 migrateTSchema extends Recordstring, unknown( db: BetterSQLite3DatabaseTSchema, config: MigrationConfig, ) { const migrations readMigrationFiles(config); db.dialect.migrate(migrations, db.session, config); }它接收两个参数db通过drizzle(client)创建的BetterSQLite3Database实例configMigrationConfig定义在 drizzle-orm/src/migrator.tsexport interface MigrationConfig { migrationsFolder: string; migrationsTable?: string; migrationsSchema?: string; }配置项类型必填说明migrationsFolderstring是存放迁移文件的目录需包含meta/_journal.json与对应的.sql文件migrationsTablestring否记录已执行迁移的元数据表名默认__drizzle_migrationsmigrationsSchemastring否迁移元数据表所在的 schemaSQLite 场景通常不需要一个完整的调用示例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执行流程如下创建迁移元数据表默认__drizzle_migrations字段为id、hash、created_at查询最后一条已执行迁移的created_at在单个事务中BEGIN/COMMIT依次执行所有folderMillis大于已执行记录时间的迁移语句并将hash与时间戳写入元数据表任一语句失败则整体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)——传入文件路径字符串内部自行构造Clientdrizzle({ 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 及以上版本时可按下表逐项核对变更点旧写法新写法数据库初始化new SQLiteConnector(client).connect()drizzle(client)迁移功能导入从主包导入migrateimport { migrate } from drizzle-orm-sqlite/better-sqlite3/migrate驱动入口导入import { SQLiteConnector } from drizzle-orm-sqliteimport { drizzle } from drizzle-orm-sqlite/better-sqlite3升级后建议立即运行一次类型检查与一条真实的查询语句确认导入路径、迁移执行和查询结果均正常对存量数据库迁移元数据表默认__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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考