drizzle-orm 0.32.0-beta 新特性实战PostgreSQL 序列与 Identity 列、全方言 Generated 列及 Drizzle Kit 迁移增强【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm本篇文章以drizzle-orm0.32.0与drizzle-kit0.23.0的预览版preview变更日志见 changelogs/drizzle-orm/0.32.0-beta.md为核心系统梳理本次版本带来的三大能力PostgreSQL 序列Sequences与 Identity 列、PostgreSQL/MySQL/SQLite 三种方言的生成列Generated Columns以及 Drizzle Kit 新增的迁移功能增强--force与prefix配置。读完本文你将掌握这些新 API 的完整参数用法、适用场景与数据库层面的限制并能直接基于仓库源码理解其底层实现。版本提醒两个包并不强制要求同时升级但若想在查询与迁移两端同时使用新特性需要同时升级drizzle-orm与drizzle-kit。本文所有代码与参数均以当前仓库实际源码为准。PostgreSQL Sequences在任何 Schema 中定义序列在 0.32.0 之前Drizzle ORM 无法在 schema 层面直接声明 PostgreSQL 序列对象。本次版本新增了pgSequence构建器允许你在任意 schema 中指定序列并定义其全部可用属性。三种典型用法import { pgSchema, pgSequence } from drizzle-orm/pg-core; // 1. 不传任何参数仅声明序列名称 export const customSequence pgSequence(name); // 2. 携带完整序列参数 export const customSequence pgSequence(name, { startWith: 100, maxValue: 10000, minValue: 100, cycle: true, cache: 10, increment: 2 }); // 3. 将序列放入自定义 schema export const customSchema pgSchema(custom_schema); export const customSequence customSchema.sequence(name);从源码看序列的全部可用选项定义在 drizzle-orm/src/pg-core/sequence.ts 的PgSequenceOptions类型中选项类型含义incrementnumber \| string序列步长每次递增的值默认 1minValuenumber \| string序列最小值maxValuenumber \| string序列最大值startWithnumber \| string序列起始值cachenumber \| string预分配的序列缓存个数用于提升性能cycleboolean是否循环达到maxValue后回到minValue重新开始序列参数同时支持number与string两种形态方便在需要时直接书写任意 SQL 表达式。pgSequence(name, options)实际是内部函数pgSequenceWithSchema(name, options, undefined)的无 schema 形态而customSchema.sequence(name)则会把 schema 名绑定到序列对象上见 pg-core/sequence.ts最终在迁移时生成CREATE SEQUENCE schema.name ...语句。PostgreSQL Identity Columns替代 serial 的推荐方案PostgreSQL 社区普遍认为serial类型已经过时官方推荐使用 Identity 列来替代。本次版本为 PostgreSQL 整数类型引入了 identity 能力。基础用法import { pgTable, integer, text } from drizzle-orm/pg-core export const ingredients pgTable(ingredients, { id: integer(id).primaryKey().generatedAlwaysAsIdentity({ startWith: 1000 }), name: text(name).notNull(), description: text(description), });.generatedAlwaysAsIdentity()接受一个可选参数对象你可以指定序列支持的全部属性即上文PgSequenceOptions中的startWith、maxValue、minValue、cycle、cache、increment同时还可以通过额外的name字段为序列指定自定义名称。源码层面的实现细节identity 能力的实现位于 drizzle-orm/src/pg-core/columns/int.common.tsgeneratedAlwaysAsIdentity(sequence?)生成GENERATED ALWAYS AS IDENTITY约束对应type: always同文件还提供了generatedByDefaultAsIdentity(sequence?)对应 PostgreSQL 的GENERATED BY DEFAULT AS IDENTITY——二者的区别在于byDefault模式允许应用显式插入自定义 id 值而always模式会拒绝显式写入除非使用OVERRIDING SYSTEM VALUE无论哪种模式调用后都会自动设置hasDefault true与notNull true这与 PostgreSQL 对 identity 列隐含 NOT NULL的语义保持一致传入的参数对象会被拆解为sequenceName自定义名称与sequenceOptions其余序列参数两部分存储。PostgreSQL Generated Columns在任意列上声明生成表达式0.32.0 允许你在 PostgreSQL 支持的任意列上声明生成列generated column表达式既可以是返回SQL的闭包也可以直接使用sql模板或普通字符串。示例基于 tsvector 的全文检索列import { SQL, sql } from drizzle-orm; import { customType, index, integer, pgTable, text } from drizzle-orm/pg-core; const tsVector customType{ data: string }({ dataType() { return tsvector; }, }); export const test pgTable( test, { id: integer(id).primaryKey().generatedAlwaysAsIdentity(), content: text(content), contentSearch: tsVector(content_search, { dimensions: 3, }).generatedAlwaysAs( (): SQL sqlto_tsvector(english, ${test.content}) ), }, (t) ({ idx: index(idx_content_search).using(gin, t.contentSearch), }) );该示例完整展示了生成列与索引的联动contentSearch列由to_tsvector(english, content)表达式自动生成并通过.using(gin, ...)建立 GIN 索引以加速全文检索。闭包形式可以引用同表其他列如${test.content}适合表达式较为复杂、需要类型检查的场景。注预览版中tsVector列类型尚未内置需要借助customType自定义正式版发布前会补充原生tsVector类型。不引用其他列时的简写形式如果生成表达式不需要引用本表任何列可以直接传sql模板或普通字符串export const users pgTable(users, { id: integer(id), name: text(name), generatedName: text(gen_name).generatedAlwaysAs(sqlhello world!), generatedName1: text(gen_name1).generatedAlwaysAs(hello world!), });PostgreSQL 方言下.generatedAlwaysAs()的默认存储模式为stored见 pg-core/columns/common.ts即表达式的计算结果会物理存储在表中。MySQL Generated Columnsstored 与 virtual 双模式MySQL 方言同样支持在任意受支持的列上声明生成列并可通过配置项指定stored或virtual模式MySQL 文档中二者语义为virtual不占用物理存储、读取时实时计算stored在写入时计算并落盘。用法示例export const users mysqlTable(users, { id: int(id), id2: int(id2), name: text(name), generatedName: text(gen_name).generatedAlwaysAs( (): SQL sql${schema2.users.name} || hello, { mode: stored } ), generatedName1: text(gen_name1).generatedAlwaysAs( (): SQL sql${schema2.users.name} || hello, { mode: virtual } ), });与 PostgreSQL 不同MySQL 生成列的默认模式是virtual——源码中.generatedAlwaysAs(as, config?)在未传入config.mode时回退为virtual见 mysql-core/columns/common.ts模式类型定义在 mysql-core/columns/common.ts 的MySqlGeneratedColumnConfig。与 PostgreSQL 一致当表达式不引用本表列时同样可以直接传sql模板或字符串给.generatedAlwaysAs()。Drizzle Kit 对 MySQL 生成列的push限制MySQL 的生成列在数据库端会自行规范化表达式字符串导致你写的表达式与数据库回读的表达式文本可能不一致。因此 Drizzle Kit 对push命令做出如下约束无法通过push修改生成约束表达式与类型——Drizzle Kit 会忽略这类变更。正确的操作流程是先drop该列 →push→ 再用新表达式add该列。之所以如此设计是因为数据库端 schema 表达式会被改写、introspection 拿到的字符串与用户书写不同Drizzle 无法可靠判断你改了表达式还是数据库格式化后的结果。好在push主要用于本地数据库的原型验证drop 后重建生成列很快且生成列的数据可自动恢复无需人工补数据。generate命令没有此类限制可以正常生成包含表达式变更的迁移 SQL。SQLite Generated Columnsstored 与 virtual 及迁移限制SQLite 方言同样支持生成列且默认模式为virtual见 sqlite-core/columns/common.ts 与SQLiteGeneratedColumnConfig定义于同文件第 34 行。其语法与 MySQL 一致.generatedAlwaysAs(expression, { mode: stored | virtual })。Drizzle Kit 对 SQLite 的push/generate限制由于 SQLite 在已有表上对生成列的支持非常有限不支直接修改表达式Drizzle Kit 针对 SQLite 方言明确了如下四条行为约束不能修改已有表中stored类型生成列的表达式——必须删除整张表再重建。SQLite 无法直接修改此类约束Drizzle 计划在后续版本通过建新表 数据迁移的方式自动处理。不能为已有列新增stored生成表达式原因同上但可以给已有列新增virtual表达式。不能修改已有列上stored生成表达式但可以修改virtual表达式。不能把生成约束从virtual改为stored反向从stored改为virtual则允许。总结一句便于记忆在 SQLite 中stored模式牵一发动全身涉及stored的结构性变更基本都要重建表virtual模式则相对宽松可以在已有列上灵活增改。Drizzle Kit 新特性迁移对全部新 ORM 特性的支持本次预览版中Drizzle Kit 的迁移生成generate已完整支持上述所有新特性PostgreSQL 序列、identity 列以及三个方言PostgreSQL/MySQL/SQLite的生成列均能正确产出对应的 DDL 语句。新 flagdrizzle-kit push --forcepush命令新增--force参数用于自动接受所有涉及数据丢失data-loss的语句无需再逐条交互确认。它只在 CLI 参数中可用且应仅在你明确接受数据丢失风险、愿意对数据库执行破坏性语句时使用。新配置migrations 的prefixdefineConfig中新增migrations.prefix选项用于自定义迁移文件的命名前缀使其适配不同的迁移工具生态。可选值与对应效果如下取值文件命名效果适用场景index默认0001_name.sql默认行为序号递增supabase20240627123900_name.sql与 Supabase 迁移格式一致timestamp20240627123900_name.sql与supabase完全等价unix1719481298_name.sqlUnix 秒级时间戳前缀nonename.sql完全省略前缀这五个合法取值在源码中定义于 drizzle-kit/src/cli/validations/common.ts 的prefixes常量并通过 zod 枚举校验prefixMode会在迁移生成与执行阶段被读取使用见 drizzle-kit/src/cli/commands/migrate.ts。示例Supabase 迁移格式import { defineConfig } from drizzle-kit; export default defineConfig({ dialect: postgresql, migrations: { prefix: supabase } });按此配置生成的迁移文件将以形如20240627123900_name.sql的时间戳命名可直接与 Supabase 平台的迁移文件管理方式对接。小结drizzle-orm0.32.0-beta/drizzle-kit0.23.0预览版的核心增量可归纳为三条主线PostgreSQL 序列体系pgSequence任意 schema 建序列 generatedAlwaysAsIdentity/generatedByDefaultAsIdentity替代serial序列参数increment、minValue、maxValue、startWith、cache、cycle全部透传全方言生成列PostgreSQL默认stored、MySQL默认virtual可选stored、SQLite默认virtual可选stored表达式支持闭包、sql模板与字符串三种写法同时必须牢记 MySQL/SQLite 在push/generate上的结构性限制迁移工具链增强push --force跳过数据丢失确认、migrations.prefix支持index/timestamp/supabase/unix/none五种前缀策略。升级建议若你同时使用 Drizzle ORM 编写查询 schema 与 Drizzle Kit 管理迁移请将两个包一并升级以获得端到端一致的新特性体验若仅使用其一则按需升级即可。【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
drizzle-orm 0.32.0-beta 新特性实战PostgreSQL 序列与 Identity 列、全方言 Generated 列及 Drizzle Kit 迁移增强【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm本篇文章以drizzle-orm0.32.0与drizzle-kit0.23.0的预览版preview变更日志见 changelogs/drizzle-orm/0.32.0-beta.md为核心系统梳理本次版本带来的三大能力PostgreSQL 序列Sequences与 Identity 列、PostgreSQL/MySQL/SQLite 三种方言的生成列Generated Columns以及 Drizzle Kit 新增的迁移功能增强--force与prefix配置。读完本文你将掌握这些新 API 的完整参数用法、适用场景与数据库层面的限制并能直接基于仓库源码理解其底层实现。版本提醒两个包并不强制要求同时升级但若想在查询与迁移两端同时使用新特性需要同时升级drizzle-orm与drizzle-kit。本文所有代码与参数均以当前仓库实际源码为准。PostgreSQL Sequences在任何 Schema 中定义序列在 0.32.0 之前Drizzle ORM 无法在 schema 层面直接声明 PostgreSQL 序列对象。本次版本新增了pgSequence构建器允许你在任意 schema 中指定序列并定义其全部可用属性。三种典型用法import { pgSchema, pgSequence } from drizzle-orm/pg-core; // 1. 不传任何参数仅声明序列名称 export const customSequence pgSequence(name); // 2. 携带完整序列参数 export const customSequence pgSequence(name, { startWith: 100, maxValue: 10000, minValue: 100, cycle: true, cache: 10, increment: 2 }); // 3. 将序列放入自定义 schema export const customSchema pgSchema(custom_schema); export const customSequence customSchema.sequence(name);从源码看序列的全部可用选项定义在 drizzle-orm/src/pg-core/sequence.ts 的PgSequenceOptions类型中选项类型含义incrementnumber \| string序列步长每次递增的值默认 1minValuenumber \| string序列最小值maxValuenumber \| string序列最大值startWithnumber \| string序列起始值cachenumber \| string预分配的序列缓存个数用于提升性能cycleboolean是否循环达到maxValue后回到minValue重新开始序列参数同时支持number与string两种形态方便在需要时直接书写任意 SQL 表达式。pgSequence(name, options)实际是内部函数pgSequenceWithSchema(name, options, undefined)的无 schema 形态而customSchema.sequence(name)则会把 schema 名绑定到序列对象上见 pg-core/sequence.ts最终在迁移时生成CREATE SEQUENCE schema.name ...语句。PostgreSQL Identity Columns替代 serial 的推荐方案PostgreSQL 社区普遍认为serial类型已经过时官方推荐使用 Identity 列来替代。本次版本为 PostgreSQL 整数类型引入了 identity 能力。基础用法import { pgTable, integer, text } from drizzle-orm/pg-core export const ingredients pgTable(ingredients, { id: integer(id).primaryKey().generatedAlwaysAsIdentity({ startWith: 1000 }), name: text(name).notNull(), description: text(description), });.generatedAlwaysAsIdentity()接受一个可选参数对象你可以指定序列支持的全部属性即上文PgSequenceOptions中的startWith、maxValue、minValue、cycle、cache、increment同时还可以通过额外的name字段为序列指定自定义名称。源码层面的实现细节identity 能力的实现位于 drizzle-orm/src/pg-core/columns/int.common.tsgeneratedAlwaysAsIdentity(sequence?)生成GENERATED ALWAYS AS IDENTITY约束对应type: always同文件还提供了generatedByDefaultAsIdentity(sequence?)对应 PostgreSQL 的GENERATED BY DEFAULT AS IDENTITY——二者的区别在于byDefault模式允许应用显式插入自定义 id 值而always模式会拒绝显式写入除非使用OVERRIDING SYSTEM VALUE无论哪种模式调用后都会自动设置hasDefault true与notNull true这与 PostgreSQL 对 identity 列隐含 NOT NULL的语义保持一致传入的参数对象会被拆解为sequenceName自定义名称与sequenceOptions其余序列参数两部分存储。PostgreSQL Generated Columns在任意列上声明生成表达式0.32.0 允许你在 PostgreSQL 支持的任意列上声明生成列generated column表达式既可以是返回SQL的闭包也可以直接使用sql模板或普通字符串。示例基于 tsvector 的全文检索列import { SQL, sql } from drizzle-orm; import { customType, index, integer, pgTable, text } from drizzle-orm/pg-core; const tsVector customType{ data: string }({ dataType() { return tsvector; }, }); export const test pgTable( test, { id: integer(id).primaryKey().generatedAlwaysAsIdentity(), content: text(content), contentSearch: tsVector(content_search, { dimensions: 3, }).generatedAlwaysAs( (): SQL sqlto_tsvector(english, ${test.content}) ), }, (t) ({ idx: index(idx_content_search).using(gin, t.contentSearch), }) );该示例完整展示了生成列与索引的联动contentSearch列由to_tsvector(english, content)表达式自动生成并通过.using(gin, ...)建立 GIN 索引以加速全文检索。闭包形式可以引用同表其他列如${test.content}适合表达式较为复杂、需要类型检查的场景。注预览版中tsVector列类型尚未内置需要借助customType自定义正式版发布前会补充原生tsVector类型。不引用其他列时的简写形式如果生成表达式不需要引用本表任何列可以直接传sql模板或普通字符串export const users pgTable(users, { id: integer(id), name: text(name), generatedName: text(gen_name).generatedAlwaysAs(sqlhello world!), generatedName1: text(gen_name1).generatedAlwaysAs(hello world!), });PostgreSQL 方言下.generatedAlwaysAs()的默认存储模式为stored见 pg-core/columns/common.ts即表达式的计算结果会物理存储在表中。MySQL Generated Columnsstored 与 virtual 双模式MySQL 方言同样支持在任意受支持的列上声明生成列并可通过配置项指定stored或virtual模式MySQL 文档中二者语义为virtual不占用物理存储、读取时实时计算stored在写入时计算并落盘。用法示例export const users mysqlTable(users, { id: int(id), id2: int(id2), name: text(name), generatedName: text(gen_name).generatedAlwaysAs( (): SQL sql${schema2.users.name} || hello, { mode: stored } ), generatedName1: text(gen_name1).generatedAlwaysAs( (): SQL sql${schema2.users.name} || hello, { mode: virtual } ), });与 PostgreSQL 不同MySQL 生成列的默认模式是virtual——源码中.generatedAlwaysAs(as, config?)在未传入config.mode时回退为virtual见 mysql-core/columns/common.ts模式类型定义在 mysql-core/columns/common.ts 的MySqlGeneratedColumnConfig。与 PostgreSQL 一致当表达式不引用本表列时同样可以直接传sql模板或字符串给.generatedAlwaysAs()。Drizzle Kit 对 MySQL 生成列的push限制MySQL 的生成列在数据库端会自行规范化表达式字符串导致你写的表达式与数据库回读的表达式文本可能不一致。因此 Drizzle Kit 对push命令做出如下约束无法通过push修改生成约束表达式与类型——Drizzle Kit 会忽略这类变更。正确的操作流程是先drop该列 →push→ 再用新表达式add该列。之所以如此设计是因为数据库端 schema 表达式会被改写、introspection 拿到的字符串与用户书写不同Drizzle 无法可靠判断你改了表达式还是数据库格式化后的结果。好在push主要用于本地数据库的原型验证drop 后重建生成列很快且生成列的数据可自动恢复无需人工补数据。generate命令没有此类限制可以正常生成包含表达式变更的迁移 SQL。SQLite Generated Columnsstored 与 virtual 及迁移限制SQLite 方言同样支持生成列且默认模式为virtual见 sqlite-core/columns/common.ts 与SQLiteGeneratedColumnConfig定义于同文件第 34 行。其语法与 MySQL 一致.generatedAlwaysAs(expression, { mode: stored | virtual })。Drizzle Kit 对 SQLite 的push/generate限制由于 SQLite 在已有表上对生成列的支持非常有限不支直接修改表达式Drizzle Kit 针对 SQLite 方言明确了如下四条行为约束不能修改已有表中stored类型生成列的表达式——必须删除整张表再重建。SQLite 无法直接修改此类约束Drizzle 计划在后续版本通过建新表 数据迁移的方式自动处理。不能为已有列新增stored生成表达式原因同上但可以给已有列新增virtual表达式。不能修改已有列上stored生成表达式但可以修改virtual表达式。不能把生成约束从virtual改为stored反向从stored改为virtual则允许。总结一句便于记忆在 SQLite 中stored模式牵一发动全身涉及stored的结构性变更基本都要重建表virtual模式则相对宽松可以在已有列上灵活增改。Drizzle Kit 新特性迁移对全部新 ORM 特性的支持本次预览版中Drizzle Kit 的迁移生成generate已完整支持上述所有新特性PostgreSQL 序列、identity 列以及三个方言PostgreSQL/MySQL/SQLite的生成列均能正确产出对应的 DDL 语句。新 flagdrizzle-kit push --forcepush命令新增--force参数用于自动接受所有涉及数据丢失data-loss的语句无需再逐条交互确认。它只在 CLI 参数中可用且应仅在你明确接受数据丢失风险、愿意对数据库执行破坏性语句时使用。新配置migrations 的prefixdefineConfig中新增migrations.prefix选项用于自定义迁移文件的命名前缀使其适配不同的迁移工具生态。可选值与对应效果如下取值文件命名效果适用场景index默认0001_name.sql默认行为序号递增supabase20240627123900_name.sql与 Supabase 迁移格式一致timestamp20240627123900_name.sql与supabase完全等价unix1719481298_name.sqlUnix 秒级时间戳前缀nonename.sql完全省略前缀这五个合法取值在源码中定义于 drizzle-kit/src/cli/validations/common.ts 的prefixes常量并通过 zod 枚举校验prefixMode会在迁移生成与执行阶段被读取使用见 drizzle-kit/src/cli/commands/migrate.ts。示例Supabase 迁移格式import { defineConfig } from drizzle-kit; export default defineConfig({ dialect: postgresql, migrations: { prefix: supabase } });按此配置生成的迁移文件将以形如20240627123900_name.sql的时间戳命名可直接与 Supabase 平台的迁移文件管理方式对接。小结drizzle-orm0.32.0-beta/drizzle-kit0.23.0预览版的核心增量可归纳为三条主线PostgreSQL 序列体系pgSequence任意 schema 建序列 generatedAlwaysAsIdentity/generatedByDefaultAsIdentity替代serial序列参数increment、minValue、maxValue、startWith、cache、cycle全部透传全方言生成列PostgreSQL默认stored、MySQL默认virtual可选stored、SQLite默认virtual可选stored表达式支持闭包、sql模板与字符串三种写法同时必须牢记 MySQL/SQLite 在push/generate上的结构性限制迁移工具链增强push --force跳过数据丢失确认、migrations.prefix支持index/timestamp/supabase/unix/none五种前缀策略。升级建议若你同时使用 Drizzle ORM 编写查询 schema 与 Drizzle Kit 管理迁移请将两个包一并升级以获得端到端一致的新特性体验若仅使用其一则按需升级即可。【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
