Drizzle ORM 0.31.2 新特性TiDB Cloud Serverless 驱动接入指南与源码剖析【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-ormDrizzle ORM 在0.31.2版本中正式加入了对TiDB Cloud Serverless的支持为无服务器 MySQL 兼容数据库提供了开箱即用的接入方式。本文以 changelogs/drizzle-orm/0.31.2.md 的发布说明为核心结合仓库中 drizzle-orm/src/tidb-serverless 目录下的完整实现带读者掌握drizzle-orm/tidb-serverless的安装配置、初始化方式、事务模型与底层执行原理可直接用于生产级 TypeScript 项目。版本背景0.31.2 带来了什么在0.31.0PostgreSQL 索引 API 重构、pg_vector / PostGIS 支持与0.31.1Expo SQLite Live Queries之后0.31.2的更新聚焦于新增一种驱动类型——TiDB Cloud Serverless。TiDB Cloud Serverless 是 TiDB 提供的按需伸缩的 MySQL 兼容服务官方维护的tidbcloud/serverless客户端以 HTTP 方式访问数据库天然适合边缘函数、Serverless 函数等无长连接场景。Drizzle 将其封装为drizzle-orm/tidb-serverless子路径使 Drizzle 的全部 MySQL 查询能力可直接复用。快速上手最小可运行示例安装依赖时需同时安装 Drizzle ORM 与 TiDB Cloud Serverless 官方客户端npm install drizzle-orm tidbcloud/serverlesstidbcloud/serverless在 drizzle-orm/package.json 中被声明为可选 peer dependency只有使用该驱动时才需要安装。随后即可按发布说明中的方式初始化import { connect } from tidbcloud/serverless; import { drizzle } from drizzle-orm/tidb-serverless; const client connect({ url: ... }); // 使用你的 TiDB Cloud Serverless 连接串 const db drizzle(client); await db.select().from(...);其中connect返回的是tidbcloud/serverless的Connection实例drizzle()将其包装为 Drizzle 的TiDBServerlessDatabase之后的所有 MySQL 查询构建器select、insert、update、delete、关系查询等均与其它 MySQL 驱动一致。深入drizzle()四种初始化形态源码 driver.ts 中的drizzle()函数通过参数重载支持多种初始化方式// 1. 直接传入连接字符串内部自动调用 connect drizzle(mysql://user:passhost:4000/db?ssltrue) // 2. 连接字符串 配置 drizzle(mysql://..., { schema, logger: true }) // 3. 传入已创建的 client 实例 drizzle(client) // 4. 单一配置对象connection 与 client 二选一 drizzle({ connection: mysql://..., schema, logger: false }) drizzle({ client, schema })内部逻辑为若第一个参数是字符串则自动执行connect({ url })若是配置对象且包含client字段则直接复用包含connection则按其类型字符串或Config调用connect。统一通过construct()driver.ts完成组装。construct()内部值得关注的细节Dialect 复用使用new MySqlDialect({ casing: config.casing })因此casing配置如snake_case映射同样生效Logger 规则logger: true时使用DefaultLoggerfalse时静默传入自定义Logger实现则直接采用Schema 装配传入config.schema时会通过extractTablesRelationalConfig提取关系配置从而支持db.query.users.findMany()等关系查询 API$client与$cache返回的实例上暴露$client属性直接访问底层连接并支持 Drizzle 的缓存配置包括将cache.onMutate回调挂接到缓存失效逻辑上。此外drizzle.mock()driver.ts可以无连接地构造数据库实例方便在单元测试或类型检查中代替真实数据库。底层会话与查询执行原理TiDBServerlessSessionsession.ts继承自MySqlSession是驱动与核心之间的桥梁。它持有ConnectionHTTP 客户端、MySqlDialect、Logger与Cache负责将 Drizzle 的 SQL 语句翻译并提交给 TiDB Cloud Serverless 执行。每次查询都会生成一个TiDBServerlessPreparedQuerysession.ts其execute()的执行路径区分两类场景无字段映射的原始执行使用executeRawConfig { fullResult: true }调用client.execute()返回FullResult。若查询涉及RETURNING场景如自增主键插入则依据lastInsertId与rowsAffected推导返回的行对于$default生成列则直接使用执行前生成的generatedIds有字段映射的常规查询使用queryConfig { arrayMode: true }获取二维数组结果再通过mapResultRow按列元数据映射为对象行或交给customResultMapper处理。execute()之前会先执行fillPlaceholders填充参数占位符并通过logger.logQuery()输出查询日志。事务模型原生事务与嵌套保存点事务支持由两个类协作完成session.tsTiDBServerlessSession.transaction()通过baseClient.begin()发起原生事务成功后commit()异常时rollback()并重新抛出错误事务体内通过db.transaction(async (tx) { ... })使用TiDBServerlessTransaction.transaction()在事务内再次开启事务时并不发起新的原生事务而是执行savepoint spN/release savepoint spN/rollback to savepoint spN实现嵌套事务语义nestedIndex逐层递增。因此你可以在db.transaction()中自由嵌套多层事务调用Drizzle 会以保存点方式保证内层回滚不影响外层事务。已知限制流式查询暂不支持TiDBServerlessPreparedQuery重写了iterator()方法并直接抛出错误session.tsTiDB Cloud Serverless 驱动不支持流式结果迭代。若你的代码依赖.iterate()逐行消费大结果集需要改用普通查询一次性获取或改用支持流式的驱动。这也是文档化的明确边界集成测试中同样将select iterator相关用例标记为不支持。测试与验证仓库如何保证该驱动可用仓库提供了两层测试验证集成测试integration-tests/tests/mysql/tidb-serverless.test.ts通过环境变量TIDB_CONNECTION_STRING提供连接串复用同一套 MySQL 测试套件mysql-common.ts跑完整查询矩阵并将RETURNING、set operations、事务隔离级别等 TiDB 不支持或差异化的用例显式skipTests驱动初始化冒烟测试integration-tests/js-tests/driver-init/module/tidb.test.mjs及 CJS 版本验证import { connect }import { drizzle } from drizzle-orm/tidb-serverless的包入口在 ESM 与 CommonJS 下均能正常加载。这也说明接入该驱动时建议先确认所用功能尤其是RETURNING、集合操作、事务选项在 TiDB Cloud Serverless 上的兼容性必要时参考该测试文件中的 skip 清单规避不支持的用例。数据库迁移migrate 函数与其它驱动一致tidb-serverless子路径同样导出migrate辅助函数migrator.ts它通过readMigrationFiles读取迁移目录再交由db.dialect.migrate()执行import { migrate } from drizzle-orm/tidb-serverless/migrator; await migrate(db, { migrationsFolder: ./drizzle });将drizzle-kit generate生成的 SQL 迁移按序应用到 TiDB Cloud Serverless 数据库。总结drizzle-orm0.31.2新增的 TiDB Cloud Serverless 驱动延续了 Drizzle 一贯的轻量设计它复用 MySQL 核心的 dialect、session 与查询构建器仅以 driver.ts、session.ts、migrator.ts 三个文件完成适配兼顾了完整的查询能力、事务/保存点语义与明确的限制边界。对于使用 TiDB Cloud Serverless 的 Serverless 应用只需安装tidbcloud/serverless并切换导入路径为drizzle-orm/tidb-serverless即可无缝获得类型安全的 ORM 体验。【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考