drizzle-kit 0.31.3 解读：Drizzle Studio 上下文新增 `databaseName` 与 `packageName` 的源码级剖析

drizzle-kit 0.31.3 解读：Drizzle Studio 上下文新增databaseName与packageName的源码级剖析

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

drizzle-kit 0.31.3 是 Drizzle ORM 命令行工具链中的一个内部演进版本，其核心变更是对 Drizzle Studio 上下文（Setup context）的调整：在 Studio 与后端通信的初始化握手数据中新增了databaseName与packageName两个属性。本文以该 changelog 条目为主体，结合 drizzle-kit/src/serializer/studio.ts 与 drizzle-kit/src/cli/schema.ts 等源码，还原这两个属性的定义、来源与消费路径，帮助读者理解 Drizzle Studio 的内部通信协议，并掌握在自建或二次开发 Studio 类工具时如何构造与解析上下文数据。

一、0.31.3 版本变更定位

本版本变更原文只有一句话：

Internal changes to Studio context. AddeddatabaseNameandpackageNameproperties for Studio

翻译过来即：对 Studio 上下文进行了内部变更，为 Studio 新增了databaseName和packageName两个属性。这属于内部协议增强，不涉及 CLI 命令用法或配置文件的破坏性变更，因此升级到 0.31.3 不需要修改drizzle.config.ts或迁移脚本，但对依赖 Studio 初始化数据的下游工具（如浏览器端 Studio 前端、自托管代理）而言，这两个字段是理解连接来源与驱动类型的关键信息。

从 changelog 目录看，它处于 0.31.x 系列的中间位置：

• 0.31.0：PostgreSQL enum DDL 流程改进、esbuild 升级至 0.25.2；
• 0.31.1：修复 relations 提取干扰 Drizzle Studio 的问题；
• 0.31.2：修复使用 Gel extensions 时drizzle-kit pull的 schema 名（如ext::auth）处理 bug；
• 0.31.3：Studio context 内部变更，新增databaseName与packageName；
• 0.31.4：修复halfvec、bit、sparsevec类型生成 bug。

由此可见，0.31.3 是 0.31.x 阶段围绕 Studio 体验持续打磨的一环。

二、Drizzle Studio 的上下文模型：Setup

要理解本次新增的两个属性，首先要弄清"Studio context"到底是什么。在源码中，它对应 drizzle-kit/src/serializer/studio.ts 中导出的Setup类型：

export type Setup = { dbHash: string; dialect: 'postgresql' | 'mysql' | 'sqlite' | 'singlestore'; packageName: | '@aws-sdk/client-rds-data' | 'pglite' | 'pg' | 'postgres' | '@vercel/postgres' | '@neondatabase/serverless' | 'gel' | 'mysql2' | '@planetscale/database' | 'd1-http' | 'd1' | '@libsql/client' | 'better-sqlite3'; driver?: 'aws-data-api' | 'd1-http' | 'd1' | 'turso' | 'pglite'; databaseName?: string; // for planetscale (driver remove database name from connection string) proxy: Proxy; transactionProxy: TransactionProxy; customDefaults: CustomDefault[]; schema: Record<string, Record<string, AnyTable<any>>>; relations: Record<string, Relations>; casing?: CasingType; schemaFiles?: SchemaFile[]; };

这个对象是 Studio 启动时组装的一次性上下文，聚合了：连接指纹（dbHash）、方言（dialect）、驱动包名（packageName）、驱动细分标识（driver）、数据库名（databaseName，可选）、SQL 代理函数（proxy/transactionProxy）、自定义默认值（customDefaults）、表结构（schema）、关系（relations）、大小写策略（casing）以及 schema 源文件（schemaFiles）。

其中databaseName声明为可选（?），并在类型注释中明确其动机：主要服务于 PlanetScale 场景——该驱动会在连接串层面移除数据库名，因此需要单独携带数据库名供 Studio 展示或拼接使用。

三、packageName：驱动包的权威标识

packageName是本次新增的两个属性之一，类型为 13 个取值构成的字符串联合，覆盖了 drizzle-kit 支持的全部驱动：pg、postgres（node-postgres）、@vercel/postgres、@neondatabase/serverless、pglite、gel、mysql2、@planetscale/database、d1、d1-http、@libsql/client、better-sqlite3以及@aws-sdk/client-rds-data（AWS Data API）。

它的赋值来源集中在 drizzle-kit/src/serializer/studio.ts 的各方言工厂函数中，例如：

• drizzleForPostgres：packageName: db.packageName（取自preparePostgresDB的结果，见 drizzle-kit/src/cli/connections.ts 等处）；
• drizzleForMySQL：packageName来自connectToMySQL的返回值；
• drizzleForSQLite：D1 binding 场景直接写死为'd1'，其余场景取自connectToSQLite；
• drizzleForLibSQL：取自connectToLibSQL，即@libsql/client。

也就是说，packageName是由"实际探测到的可用驱动包"决定的：连接层通过checkPackage()检查当前项目安装了哪个 npm 包，就选用哪个驱动并把包名上报给 Studio。这让前端可以据此渲染与驱动能力匹配的 UI（例如区分mysql2与@planetscale/database在事务与数据类型上的差异）。

四、databaseName：连接串之外的数据库名

databaseName由drizzleForMySQL（studio.ts）与drizzleForSingleStore（studio.ts）两个工厂函数设置，均取自已建立的连接对象的database字段：

const { proxy, transactionProxy, database, packageName } = await connectToMySQL(credentials); // ... return { dbHash, dialect: 'mysql', packageName, databaseName: database, proxy, transactionProxy, // ... };

在 drizzle-kit/src/cli/connections.ts 的connectToMySQL返回值中，database来自parseMysqlCredentials(it)解析出的result.database。也就是说，无论用户通过url还是逐字段凭据（host/port/user/password/database）配置连接，解析层都会归一化出数据库名并透传到Setup。

其存在的根本原因在Setup类型注释中已点明：某些驱动（典型如 PlanetScale）在连接串中剥离了数据库名，导致仅凭连接串无法得知目标库名；Studio 需要在界面上展示库名、或在生成 SQL 前缀时用到它，因此必须显式传递。从代码结构看，databaseName是可选字段，PostgreSQL、SQLite 等方言不设置它，依赖这些方言连接串本身携带库信息。

五、两个属性在 init 握手协议中的消费

Setup组装完成后，由prepareServer生成一个基于 Hono 的本地 HTTP 服务（studio.ts），对外提供 POST/接口，接受 4 类消息：

消息类型	用途
init	Studio 前端初始化时请求上下文快照
proxy	执行单条 SQL（支持values/get/all/run/execute方法）
tproxy	批量执行事务 SQL
defaults	获取列的自定义默认值函数运行结果

init分支正是本次两个属性的最终出口（studio.ts）：

return c.json({ version: '6.2', dialect, driver, packageName, schemaFiles, customDefaults: preparedDefaults, relations, dbHash, databaseName, });

init响应携带version: '6.2'协议版本号，以及方言、驱动、包名、schema 文件、自定义默认值、关系、连接哈希与数据库名。可以推断，Studio 前端拿到databaseName后用于展示"当前连接的数据库"，拿到packageName后用于驱动相关的功能开关与提示文案。

该服务的启动入口在 drizzle-kit/src/cli/schema.ts 的studio命令中：CLI 先按dialect分支调用对应的prepare*Schema与drizzleFor*组装Setup，再prepareServer(setup)启动服务，并打印访问地址https://local.drizzle.studio（默认端口 4983、默认 host127.0.0.1，可通过--port与--host覆盖）。同时，Studio 处于 Beta 阶段，启动时会打印反馈提示。

六、从测试与相邻版本看变更意图

尽管 0.31.3 的变更属于"internal"，但可以从邻近版本的修复中推断其工程动机：

• 0.31.1 修复了 relations 提取干扰 Studio 的问题，说明当时 Studio 的关系解析链路正在被加固；
• 0.31.3 进一步为 Studio 补齐数据库名与驱动包名信息，使前端不再依赖猜测或从连接串二次解析，尤其是 PlanetScale、SingleStore 这类"连接串不含库名"的方言；
• 0.31.4 则转向halfvec、bit、sparsevec等 PostgreSQL 向量类型的生成修复，两个版本共同勾勒出 0.31.x 期间 drizzle-kit 在"Studio 上下文完整性"与"类型生成正确性"两条线上的持续投入。

对于集成者，可以直接以 Setup 类型 与 init 响应 为契约，编写自定义 Studio 客户端；若需要复现完整链路，可参考drizzle-kit下的 CLI 测试与配置样例（如 drizzle-kit/tests 目录中的drizzle.config.ts系列文件）。

七、小结

• drizzle-kit 0.31.3 不改变任何 CLI 用法，属 Studio 内部协议增强；
• packageName由连接层探测出的实际驱动包决定，取值集合见 Setup 联合类型；
• databaseName由 MySQL 与 SingleStore 连接流程提供，核心服务于 PlanetScale 这类连接串不含库名的驱动；
• 两者最终经init消息（协议版本6.2）一并返回给 Studio 前端，完整代码位于 drizzle-kit/src/serializer/studio.ts。

对普通用户而言，升级至 0.31.3 后只需照常运行drizzle-kit studio即可享受更准确的库名展示与驱动感知；对希望深挖 Studio 机制的开发者，本版本则是理解其内部上下文的极佳切入点。

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