Drizzle ORM 0.31.3 版本解析：Prisma-Drizzle 扩展、同表名多 Schema 修复与 RDS Data API 类型提示修复

Drizzle ORM 0.31.3 版本解析Prisma-Drizzle 扩展、同表名多 Schema 修复与 RDS Data API 类型提示修复【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm本篇技术指南聚焦 Drizzle ORM 0.31.3 版本的三个核心变化全新推出的 Prisma-Drizzle 扩展让你能在 Prisma Client 中直接使用 Drizzle 的查询构建器、关系查询构建器RQB对不同 Schema 下同名表的行为修复以及 RDS Data API 驱动下类型提示不匹配的缺陷修复issue #2097。读完本文你将理解 Prisma 与 Drizzle 共存的使用方式、同名表冲突的底层成因与修复策略以及 Data API 查询执行链路的类型处理原理。版本概览Drizzle ORM 0.31.3对应 changelogchangelogs/drizzle-orm/0.31.3.md是一个以修复稳定性 新增集成能力为主的版本主要包含Bug 修复修复关系查询构建器RQB在不同 Schema 中存在同名表时的行为修复使用 RDS Data API 时的类型提示不匹配问题issue #2097 相关。新功能新增Prisma-Drizzle 扩展允许通过 Prisma 官方的$extends机制在 PrismaClient 上挂载一个$drizzle数据库实例从而在同一连接上同时使用两套 ORM。后续的 0.31.4 版本则进一步将 prisma 客户端相关包标记为可选依赖见 changelogs/drizzle-orm/0.31.4.md可见该集成的依赖设计也在持续打磨。新增Prisma-Drizzle 扩展解决什么问题Prisma 与 Drizzle 是两种设计取向不同的 ORMPrisma 强调 schema 驱动、类型安全的声明式客户端Drizzle 则强调贴近 SQL、轻量且构建粒度细。现实中不少团队希望渐进式迁移——保留既有 Prisma 基础设施同时在需要复杂查询的地方使用 Drizzle 的查询能力。0.31.3 提供的方案不是另起炉灶的连接管理而是基于 Prisma 官方的 Client Extension 机制Prisma.defineExtensionclient.$extends把 Drizzle 数据库实例注入到 PrismaClient 实例上实现一个连接、两套 API。快速上手官方 changelog 中给出的最小示例以 PostgreSQL 为例import { PrismaClient } from prisma/client; import { drizzle } from drizzle-orm/prisma/pg; import { User } from ./drizzle; const prisma new PrismaClient().$extends(drizzle()); const users await prisma.$drizzle.select().from(User);关键点拆解drizzle()返回一个 Prisma Extension它不是直接创建一个数据库实例而是通过Prisma.defineExtension包装需要配合$extends()使用。$drizzle是挂载后的访问入口扩展将 Drizzle 数据库实例挂到 client 的$drizzle属性上源码见 drizzle-orm/src/prisma/pg/driver.ts之后即可使用标准的 Drizzle 查询构建 API。schema 表定义仍然来自 Drizzle 侧示例中User是从./drizzle导入的 Drizzle 表定义由drizzle-kit生成Drizzle 查询基于这些表对象构建 SQL。底层实现原理从源码看整个集成非常轻量。以 PostgreSQL 为例drizzle-orm/src/prisma/pg/driver.tsexport function drizzle(config: PrismaPgConfig {}) { let logger: Logger | undefined; if (config.logger true) { logger new DefaultLogger(); } else if (config.logger ! false) { logger config.logger; } return Prisma.defineExtension((client) { return client.$extends({ name: drizzle, client: { $drizzle: new PrismaPgDatabase(client, logger), }, }); }); }PrismaPgDatabase继承自 Drizzle 的PgDatabase内部用PgDialect构建 SQLdriver.ts。真正执行 SQL 的是PrismaPgSession与PrismaPgPreparedQuerydrizzle-orm/src/prisma/pg/session.ts。PrismaPgPreparedQuery.execute()的核心只有一行return this.prisma.$queryRawUnsafe(this.query.sql, ...params);即Drizzle 负责生成 SQL 与参数绑定Prisma 负责实际发送查询。这样无论 Prisma 侧配置的是连接池还是代理Drizzle 查询都天然复用同一套底层连接无需额外的驱动配置。配置项PrismaPgConfig是OmitDrizzleConfig, schema目前主要用于控制日志logger: true启用DefaultLogger传入自定义 Logger 实例也可driver.ts。其他数据库支持该扩展并非 PostgreSQL 独有仓库中同时提供了三套实现数据库入口模块说明PostgreSQLdrizzle-orm/prisma/pg基于PgDatabase/PgDialect如上述分析MySQLdrizzle-orm/prisma/mysql基于MySqlDatabase/MySqlDialectdrizzle-orm/src/prisma/mysql/driver.tsSQLitedrizzle-orm/prisma/sqlite基于BaseSQLiteDatabaseasync 模式与SQLiteAsyncDialectdrizzle-orm/src/prisma/sqlite/driver.ts三者的实现模式完全一致drizzle(config)返回Prisma.defineExtension$extends后暴露$drizzle实例。MySQL 与 SQLite 版同样支持logger配置。使用边界与注意事项事务以 PostgreSQL 的PrismaPgSession.transaction()为例当前实现直接抛出Method not implemented.session.ts。也就是说目前通过$drizzle发起的事务尚未实现建议事务性操作仍走 Prisma 侧 API 或显式使用其他 Drizzle 驱动。依赖关系drizzle()需要项目已安装prisma/client0.31.4 起该客户端包被标记为可选依赖见 0.31.4 变更记录即不安装 Prisma 的项目不会因引入drizzle-orm而强制拉取 Prisma 依赖。适合场景渐进式迁移、混合查询Prisma 管理 CRUD、Drizzle 承担复杂聚合/子查询以及希望在既有 Prisma 连接上直接使用 Drizzle API 的团队。修复RQB 对不同 Schema 同名表的处理背景与问题PostgreSQL 等数据库支持多个 Schema如public、folder不同 Schema 下可以存在同名表例如folder.users与public.users。在 Drizzle 的关系查询构建器Relational Query BuilderRQB内部表以扁平 key-value 形式存放在关系配置中当两张同名表来自不同 Schema 时若内部 key 仅以表名命名就会发生键冲突导致关系配置错乱。仓库中的回归测试tables with same name in different schemas精确复现了该场景drizzle-orm/tests/relation.test.tsconst folder pgSchema(folder); const schema { folder: { usersInFolder: folder.table(users, {}), }, public: { users: pgTable(users, {}), }, }; const relationalSchema { ...Object.fromEntries( Object.entries(schema) .flatMap(([key, val]) { // have unique keys across schemas const mappedTableEntries Object.entries(val).map((tableEntry) { return [__${key}__.${tableEntry[0]}, tableEntry[1]]; }); return mappedTableEntries; }), ), };修复策略为跨 Schema 表生成唯一 key从测试可见修复的核心思路是在扁平化关系配置时为来自不同 Schema 的表生成全局唯一的内部 key——形如__folder__.users与__public__.users以 Schema 名为前缀加以区分避免覆盖同一 Schema 内的表仍可用短名表名作为 key跨 Schema 场景下key 自动升级为__schema__.table形式保证唯一性。测试随后调用extractTablesRelationalConfig(relationalSchema, createTableRelationsHelpers)实现位于 drizzle-orm/src/relations.ts并断言关系配置最终包含 2 个表expect(Object.keys(relationsConfig)).toHaveLength(2)——即两张同名表都被正确识别、不再互相覆盖。对使用者的影响升级到 0.31.3 及以上后多 Schema 项目中不同 Schema 下的同名表可以同时参与关系查询构建不会再出现其中一张表的关系配置被静默丢失的情况。命名冲突检测的逻辑同时覆盖了pgSchema(...)创建的自定义 Schema 与默认publicSchema 的组合场景见测试中folderSchema 与默认 public Schema 的对照。修复RDS Data API 的类型提示不匹配#2097问题定位RDS Data APIAWS Aurora Serverless 的无状态 SQL API不直接返回数据库原生类型而是通过aws-sdk/client-rds-data的Field结构把值编码为字符串、长整型、布尔等若干种字段类型。若驱动在字段 → 行的映射过程中对类型处理不一致就会导致 TS 类型提示type hints与实际返回数据错位——这正是 issue #2097 报告的mismatched type hints。底层执行链路仓库中对应驱动位于 drizzle-orm/src/aws-data-api其 PostgreSQL 实现的关键代码在 drizzle-orm/src/aws-data-api/pg/session.ts查询构造AwsDataApiPreparedQuery将 Drizzle 生成的 SQL 与参数组装成 AWS 的ExecuteStatementCommand并携带secretArn、resourceArn、database等会话选项session.ts。参数编码values()中把占位符填充后的参数逐一通过toValueParam(param, this.typings[index])转换为 Data API 的字段格式session.ts转换逻辑集中在 drizzle-orm/src/aws-data-api/common/index.ts。结果解码响应中的records逐行、逐字段调用getValueFromDataApi(field)还原为 JS 值当 Drizzle 侧提供fields列映射或自定义结果映射器时再交给mapResultRow完成裸行 → 类型化对象的转换session.ts。从源码结构可以推断0.31.3 的修复落点在于让字段解码与行映射两阶段的类型信息保持一致查询执行结果以AwsDataApiPgQueryResultT ExecuteStatementCommandOutput { rows: T[] }形式承载rowssession.ts并在execute/all/values三个出口统一返回类型化的rows从而修复类型提示与实际数据不匹配的问题。对使用者的影响使用drizzle-orm/aws-data-api/pg驱动Aurora Serverless v1 Data API的项目升级到 0.31.3 后查询返回结果的 TS 类型提示应与真实数据结构保持一致不再出现提示与实际字段错位的情况。若仍遇到类型异常可核对aws-sdk/client-rds-data的版本与 Drizzle 驱动是否配套更新。升级建议若你正在使用RQB 且项目存在多 Schema 同名表或正在使用aws-data-api/pg 驱动建议升级到 0.31.3 及以上以获取上述修复。若你计划在 Prisma 项目中引入 Drizzle 查询能力可从 0.31.3 开始使用drizzle-orm/prisma/{pg,mysql,sqlite}模块注意事务能力当前尚未实现复杂事务请继续走 Prisma 或专用驱动。本仓库当前完整实现均可在 drizzle-orm/src/prisma 与 drizzle-orm/src/aws-data-api 目录下查阅回归测试见 drizzle-orm/tests/relation.test.ts便于深入理解行为细节。【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考