drizzle-kit 0.24.0 升级指南SQLite 组合主键列顺序修复与数组默认值系列 Bug 修复【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-ormdrizzle-kit 0.24.0 是一次面向 SQLite 用户的破坏性升级Breaking Change它修复了组合主键在数据库中的列顺序与 Drizzle Schema 不一致的问题同时集中修复了 double 类型列导入缺失、char 类型数字默认值、以及 PostgreSQL 数组默认值迁移 SQL 错误等一系列高频 Bug。本文以官方变更日志为主体结合仓库源码sqliteSerializer.ts说明问题根因、升级影响与应对方案帮助你在升级前评估风险、升级后平滑迁移。一、版本概览一次聚焦 SQLite 的破坏性升级0.24.0 版本的核心变更集中在两个方向一个 Breaking Change修复 SQLite 组合主键列顺序不一致问题对应 drizzle-team/drizzle-kit-mirror#342修复方式是移除 SQLite 中的sort排序逻辑使其与 PostgreSQL、MySQL 的实现保持一致。一批 Bug 修复涵盖类型导入、默认值序列化、数组默认值生成等 8 个已确认问题。对于使用组合主键Composite Primary Key的 SQLite 项目本次升级可能触发 schema 差异提示需要你主动处理对于其他用户则是一版质量修复为主的常规升级。二、Breaking ChangeSQLite 组合主键列顺序不再被排序2.1 问题背景在使用任意 SQLite 驱动better-sqlite3、libsql、d1、bun-sqlite 等且表中存在组合主键多列主键时数据库中的列顺序可能与 Drizzle Schema 中声明的顺序不一致。问题根因在于旧版 drizzle-kit 在序列化 SQLite 主键时对列名执行了sort()排序导致写入快照snapshot的列顺序与用户在 Schema 中定义、以及数据库中实际创建的顺序脱节从而在push或generate时反复产生无意义的差异。2.2 修复方式移除 sort对齐 PG/MySQL 逻辑修复的核心是移除 SQLite 序列化路径上的排序逻辑。从当前源码看SQLite 快照生成generateSqliteSnapshot在处理组合主键时严格保留列的定义顺序// drizzle-kit/src/serializer/sqliteSerializer.ts#L263-L282 primaryKeys.forEach((it) { if (it.columns.length 1) { const originalColumnNames it.columns.map((c) c.name); const columnNames it.columns.map((c) getColumnCasing(c, casing)); ... primaryKeysObject[name] { columns: columnNames, // 按 Schema 声明顺序原样保留 name, }; } else { columnsObject[getColumnCasing(it.columns[0], casing)].primaryKey true; } });与之对应数据库 introspection逆向解析路径同样按实际列顺序收集主键列tableToPk并以表名_列名1_列名2_pk的形式生成主键名其中列名拼接顺序即数据库真实顺序// drizzle-kit/src/serializer/sqliteSerializer.ts#L669-L681 for (const [key, value] of Object.entries(tableToPk)) { if (value.length 1) { result[key].compositePrimaryKeys { [${key}_${value.join(_)}_pk]: { columns: value, // 按数据库实际顺序 name: ${key}_${value.join(_)}_pk, }, }; } else if (value.length 1) { result[key].columns[value[0]].primaryKey true; } }而 PostgreSQL 与 MySQL 的序列化路径如 pgSerializer.ts 与 gelSerializer.ts 中的mappedTo.sort()早已采用一致的顺序语义。本次变更就是让 SQLite 回归这一统一逻辑。2.3 对 push 的影响与应对升级后执行drizzle-kit push时你可能会收到更新表结构调整组合主键列顺序的提示原因即新旧快照中主键列顺序不一致。官方给出的处理方式有两种在数据库中手动调整组合主键的列顺序使数据库与 Drizzle Schema 保持一致接受推送更改push 该变更但请注意SQLite 重建表的过程可能带来数据丢失等风险务必在操作前做好备份。2.4 对 generate 的影响与应对升级后执行drizzle-kit generate时你也可能收到同样的表结构变更提示并生成一条调整组合主键列顺序的迁移 SQL。官方建议二选一保留该迁移照常执行迁移流程跳过该迁移直接清空生成的 SQL 迁移文件内容避免执行无实际意义的表重建。2.5 仍然受阻时的处理变更日志特别说明如果以上方案都无法解决你遇到的问题可以联系维护者 AndriiSherman 寻求帮助例如涉及特殊驱动或极端 Schema 组合的情况。从仓库结构看本次变更相关逻辑集中在 drizzle-kit/src/serializer/sqliteSerializer.ts 与 drizzle-kit/src/snapshotsDiffer.ts排查时可重点关注这两处。三、Bug 修复详解3.1 使用 double 类型列时import 未正确生成#403修复前当 SQLite 表中存在double类型列时introspect/生成代码时对应的 import 语句缺失导致生成的代码无法直接编译。从源码看SQLite 类型映射函数 mapSqlToSqliteType 将real、double、double precision、float统一归一化为real// drizzle-kit/src/serializer/sqliteSerializer.ts#L452-L455 } else if ( [real, double, double precision, float].some((it) lowered.startsWith(it)) ) { return real; }0.24.0 确保这一归一化路径下real类型的 import 声明被正确写入生成文件感谢 Karibash 的贡献。3.2 char 类型列使用数字默认值时处理错误#404修复前char类型列如果以数字作为默认值drizzle-kit 在序列化默认值时会生成错误结果。本次修复统一了 char 默认值的处理逻辑确保数字默认值被正确包裹和输出同样由 Karibash 提交。3.3 数组默认值系列问题迁移 SQL 生成错误#2621 等这是 0.24.0 修复规模最大的一类问题L-Mario564 一次性处理了 6 个相关 issueIssue 编号问题描述drizzle-orm#2621数组默认值在迁移中生成错误drizzle-orm#2709更简洁的数组默认值字段写法featuredrizzle-orm#2432generate成功但对default([])生成了非法 SQLPostgreSQLdrizzle-orm#2334数组列默认值类型推断错误drizzle-orm#2224column is of type integer[] but default expression is of type integer报错drizzle-orm#1003数组默认值生成错误的迁移文件drizzle-orm#1564枚举作为数组元素不可用这组问题集中在同一根因数组默认值的序列化与类型标注。旧版本在把 Drizzle Schema 中的数组默认值如$default、default([...])翻译成 PostgreSQL 迁移 SQL 时未能生成正确的数组字面量与类型转换表达式例如缺少ARRAY[...]或显式::type[]转换从而出现类型不匹配或非法 SQL两类报错。0.24.0 重写了数组默认值的生成路径使default([])生成合法的空数组默认值 SQLinteger[]等数组列的默认值携带正确的类型信息消除integer[]与integer的类型冲突报错枚举数组如enum[]列带默认值可以正常生成。提示如果你此前因为数组默认值问题被迫在迁移文件中手工改写 SQL升级到 0.24.0 后建议重新生成一次迁移进行对比验证。四、升级建议与验证清单升级前对 SQLite 数据库做完整备份push可能触发表重建。定位组合主键表用 introspection 或直接查看 DDL找出使用多列主键的表提前确认 Schema 列顺序与数据库列顺序是否一致。选择处理策略主键列顺序在数据库与 Schema 间确实不一致 → 手动在数据库修正或接受push/generate生成的重建变更注意数据风险一致但被提示差异 → 按第 2.4 节方案generate后清空迁移文件跳过即可。回归验证重点复测 double/real 列、char 数字默认值、PostgreSQL 数组默认值与枚举数组这几类此前出问题的场景。观察新生成代码确认 double 列生成代码包含正确的realimport数组默认值迁移 SQL 不再报类型错误。五、小结drizzle-kit 0.24.0 的核心价值在于两点统一 SQLite 与 PostgreSQL/MySQL 的组合主键顺序语义以及系统性修复数组默认值的迁移生成质量。前者需要 SQLite 用户升级时主动评估并处理 schema 差异后者则让generate生成的迁移 SQL 更加可靠、开箱即用。建议升级前仔细阅读 0.24.0 变更日志并结合 sqliteSerializer.ts 的序列化实现理解行为变化平稳完成这次升级。【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考