drizzle-kit 0.31.4 修复解析：`halfvec`、`bit`、`sparsevec` 类型生成 bug 与 pgvector 向量列支持详解

drizzle-kit 0.31.4 修复解析halfvec、bit、sparsevec类型生成 bug 与 pgvector 向量列支持详解【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-ormdrizzle-kit 0.31.4 是一个聚焦性的修复版本其核心变更只有一条修复了halfvec、bit、sparsevec三种 PostgreSQL 类型在 drizzle-kit 中的类型生成 bug。本文以该变更说明changelogs/drizzle-kit/0.31.4.md为骨架结合 drizzle-orm、drizzle-kit 仓库源码说明这几种类型在 schema 定义、introspect 逆向生成与 SQL 生成中的实际行为以及升级 0.31.4 后如何在项目里正确使用它们。变更概览一条修复背后的三个类型0.31.4 的 changelog 全文如下Fixedhalfvec,bitandsparsevectype generation bug in drizzle-kit这句话描述的是三类来自 pgvector 及 PostgreSQL 内置位串类型的列类型halfvecpgvector 提供的半精度浮点向量类型使用 16 位浮点存储每个维度用于在保证召回率的前提下大幅压缩向量占用的磁盘与内存空间sparsevecpgvector 提供的稀疏向量类型只存储非零维度及其值适合高维但大多数维度为零的向量例如 TF-IDF、词袋类特征bitPostgreSQL 内置的定长位串类型配合 pgvector 的bit_hamming_ops、bit_jaccard_ops操作符类可做二进制向量的汉明距离、Jaccard 距离检索。这三类类型都属于非内建、依赖用户安装扩展才能使用的类型而 drizzle-kit 的 introspect数据库结构逆向流程此前在处理这类用户自定义类型时存在生成错误0.31.4 正是针对这一问题的修复。修复的核心introspect 中对 USER-DEFINED 类型的判定要理解这个 bug 的根因需要看 drizzle-kit 逆向数据库结构时对列类型的分流逻辑。在 drizzle-kit/src/serializer/pgSerializer.ts 中表列第 1491-1498 行与视图列第 1786-1793 行的类型归属使用了同一套判定type: // filter vectors, but in future we should filter any extension that was installed by user columnAdditionalDT USER-DEFINED ![vector, geometry, halfvec, sparsevec, bit].includes(enumType) ? enumType : columnTypeMapped,从源码结构可以推断出 bug 的成因当数据库中的列被 PostgreSQL 元数据标记为USER-DEFINED类型时drizzle-kit 会优先把它当作用户自定义枚举类型走enumType分支写入生成的 schema但对于halfvec、sparsevec、bit这类同样以自定义类型形态存在、实则是 pgvector 扩展类型或内置位串类型的列这种误判会把它们错误地当作 enum 处理导致 introspect 生成的 schema 类型不正确。代码注释也明确写着 filter vectors, but in future we should filter any extension that was installed by user说明该修复策略是先对已知的扩展类型vector、geometry、halfvec、sparsevec、bit做白名单排除使其回落到columnTypeMapped分支按原生类型名生成。同时drizzle-kit/src/sqlgenerator.ts 第 137-141 行将vector、geometry、halfvec、sparsevec、bit一并收录进 PostgreSQL 原生类型白名单pgNativeTypesvector, geometry, halfvec, sparsevec, bit,该白名单的用途在于生成 SQLpush / generate / migrate时只有命中白名单的类型才不会被强制加 schema 前缀和双引号包裹。也就是说halfvec、sparsevec、bit只有被识别为原生类型才会以halfvec(768)、bit(64)这种干净的形式出现在生成的 SQL 中而不是被错误地引用为带引号的用户自定义类型。三种类型在 drizzle-orm 中的 schema 定义方式修复的前提是 drizzle-orm 早已为这三种类型提供了完整的一等公民 API均位于 drizzle-orm/src/pg-core/columns/vector_extension/ 目录下并在 drizzle-orm/src/pg-core/columns/index.ts 中统一导出。halfvec半精度向量列halfvec的构造函数定义在 halfvec.ts其列的数据类型为PgHalfVector数据映射为number[]driver 参数为字符串。在 schema 中使用方式与vector完全一致import { pgTable, halfvec } from drizzle-orm/pg-core; export const embeddings pgTable(embeddings, { id: integer(id).primaryKey(), embedding: halfvec(embedding, { dimensions: 768 }), });参数说明dimensions必填声明向量的维度数。pgvector 对halfvec的维度上限较vector更宽松可到数千维但 schema 声明时仍应明确给出方便 drizzle-kit 生成准确的halfvec(768)DDL。sparsevec稀疏向量列sparsevec的构造函数定义在 sparsevec.ts存在重载签名以兼容名称 维度配置与仅名称使用默认维度 0两种调用形式。其数据映射同样为number[]import { pgTable, sparsevec } from drizzle-orm/pg-core; export const docs pgTable(docs, { id: integer(id).primaryKey(), features: sparsevec(features, { dimensions: 4096 }), });参数说明dimensions声明稀疏向量的最大维度数。注意 pgvector 对sparsevec的维度限制取决于所用版本早期版本限制为 1600新版放宽声明时应以实际安装的 pgvector 版本为准稀疏向量的实际存储只会记录非零维度因此即使维度声明很大只要数据稀疏存储成本依然可控。bit定长位串列bit的构造函数定义在 bit.ts同样支持带维度配置或不带的调用形式数据映射为字符串位串import { pgTable, bit } from drizzle-orm/pg-core; export const binaryVecs pgTable(binary_vecs, { id: integer(id).primaryKey(), code: bit(code, { dimensions: 64 }), });参数说明dimensions位串长度声明后生成的 DDL 为bit(64)若不声明则为无约束的bit位串类型常配合 pgvector 的bit_hamming_ops汉明距离与bit_jaccard_opsJaccard 距离操作符类建立索引用于二进制哈希向量的近邻检索。三类类型可用的操作符类drizzle-kit/src/extensions/vector.ts 中集中维护了 drizzle-kit 认可的向量扩展操作符类export const vectorOps [ vector_l2_ops, vector_ip_ops, vector_cosine_ops, vector_l1_ops, bit_hamming_ops, bit_jaccard_ops, halfvec_l2_ops, sparsevec_l2_ops, ];从中可以确认halfvec支持halfvec_l2_opsL2 距离索引sparsevec支持sparsevec_l2_opsL2 距离索引bit支持bit_hamming_ops与bit_jaccard_ops。也就是说在 drizzle-kit 0.31.4 中这三类列不仅能被正确 introspect 和生成类型还能在 drizzle-orm/src/pg-core/indexes.ts 对应的索引语法中被正确识别例如import { pgTable, halfvec, index } from drizzle-orm/pg-core; export const embeddings pgTable(embeddings, { id: integer(id).primaryKey(), embedding: halfvec(embedding, { dimensions: 768 }), }, (t) [ index(embedding_idx).using(hnsw, t.embedding.op(halfvec_l2_ops)), ]);该修复覆盖的完整工作流结合源码可以确认0.31.4 的修复贯穿 drizzle-kit 的三条主链路introspect 逆向drizzle-kit introspect读取数据库元数据时halfvec、sparsevec、bit不再被误判为自定义枚举类型而是生成正确的列类型见 pgSerializer.ts 表列与视图列两处分流SQL 生成push / generate / migrate 生成 DDL 时这三类类型命中pgNativeTypes白名单sqlgenerator.ts以无引号、无 schema 前缀的原生类型形式输出schema 定义配合 drizzle-orm 侧halfvec、sparsevec、bit列构造器vector_extension开发者手写 schema 与数据库结构保持一致。升级到 drizzle-kit 0.31.4 后建议回归验证一次针对 pgvector 相关表的 introspect 与 generate 流程确认生成的列类型与索引操作符类符合预期。需要说明的是这三类类型均依赖 PostgreSQL 侧安装对应扩展pgvector 提供halfvec、sparsevec及bit的操作符类bit本身是 PostgreSQL 内置类型drizzle-kit 只负责在 ORM 与迁移层正确表达它们扩展的安装仍需在数据库层面完成。【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考