Immich 数据库迁移实战5 条命令搞定 schema 变更、回滚与漂移检测【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher改完 Immich 的表定义、重启服务端查询却还在报字段不存在——问题多半出在 Immich 数据库迁移这一步没走对。这篇文章用 5 条 mise migrations 命令带你覆盖 sql-tools 迁移生成、ORDER 清单登记、启动自动应用、迁移回滚与 schema 漂移检测的完整路径。改完表定义、重启服务查询为何还报字段不存在先说一个几乎每个 Immich 贡献者都踩过的坑你在 server/src/schema/tables 里给 asset 表加了一列保存、重启服务端满怀期待地发一条新查询——报错column does not exist。数据库没坏代码也没写错。真相是代码里写的 schema 和 Postgres 里真实存在的 schema是两套东西。前者只描述应该长什么样后者只认真正执行过的 DDL。你改了图纸但没人去工地施工楼当然不会自己长出新楼层。官方文档 database-migrations.md 的全部篇幅都在讲怎么把图纸变成工地。下面按你动手的顺序拆。声明式表定义与迁移文件sql-tools 如何生成 DDLImmich 的 schema 代码分两层职责互不重叠。第一层是声明式表定义集中在 server/src/schema/tables约 64 个表定义文件外加 enums.ts、functions.ts 负责枚举和数据库函数。它回答数据库应该长什么样——类比装修图纸尺寸、水电都画好了但图纸本身盖不起房子。第二层是迁移文件放在 server/src/schema/migrations每个文件导出 up() 和 down() 两个异步函数用 kysely 的 sql 标签模板执行原生 SQL。它回答怎么把旧库改到位——这是施工单加哪根梁、拆哪堵墙、拆错了怎么复原。而把图纸和施工单对起来的是 immich/sql-tools它比对声明式定义与真实数据库的差异自动产出 DDL 写进迁移文件。换句话说你只负责改图纸工具负责出具施工单你再把关执行。一次迁移的完整走位从 generate 到 sync-order一次迁移有四个动作生成、审阅、落位、登记。生成。仓库根目录执行mise //server:migrations generate migration-name//server:前缀表示在 monorepo 根目录执行 server 包的任务定义在 server/mise.toml最终展开为sql-tools -u 连接串 migrations generate ...。连接串看环境变量 DB_URL不设置就默认连本地 Docker 里的开发库 postgres://postgres:postgreslocalhost:5432/immich。产出的文件带毫秒时间戳前缀例如 1745244781846-AddUserAvatarColorColumn.ts——时间戳的作用就是让字典序等于执行顺序。审阅。打开文件重点看三处up() 生成的 DDL 是否符合预期、存量数据回填有没有漏、down() 能否安全走回去。举个例子AddUserAvatarColorColumn 的 up 除了加列还要把老数据从 user_metadata 的 JSON 字段回填进新列down 只负责删列。落位。generate 不会把文件直接放进最终目录需要手动移到 server/src/schema/migrations。那里已有近百个迁移从 1744910873969-InitialMigration 一路排到最新命名统一为毫秒时间戳-PascalCase名称.ts。登记。移完文件补上最后一条命令mise //server:migrations sync-order它把新迁移追加进 ORDER 清单。这份清单为什么值得单独一节往下看。ORDER 清单一份故意制造冲突的文件举个例子你拉了 feature-a 给 asset 表加索引同事拉了 feature-b 新建 plugin 表两边各生成一个带时间戳的迁移文件。如果顺序只靠目录里的文件名两个分支合并时 git 一声不吭——文件互不冲突但执行顺序可能错了先跑的迁移若引用了对方还没建的表服务启动直接失败而且这种失败往往要等部署后才暴露。Immich 的解法是把顺序写进一份 git 跟踪的清单 migrations/ORDER每行一个迁移名去掉 .ts 后缀新迁移靠 sync-order 追加。于是两个分支各自改了 ORDER 文件合并时必然冲突逼你亲自拍板谁先谁后。说白了这是用冲突噪音换顺序确定性的有意取舍多花三十秒解冲突换来合并后迁移顺序 100% 可预期。所以 ORDER 必须和迁移文件放在同一个 commit 提交漏掉它下一关 CI 会拦住你。生效、校验与迁移回滚revert 回滚最近一次变更先说结论贯穿日常的其实就 5 条命令——generate、run、revert、sync-order、verify-order前两条上面已经见过。迁移怎么生效开发环境什么都不用手动做。服务端监听 *.ts 变更自动重启而启动流程本身就包含运行所有未应用的迁移——改完 schema、登记完 ORDER重启 server新迁移就落到本地库了。想显式跑一次run 子命令会执行全部未应用的迁移。这里容易踩坑的是校验CI 的 checklist 任务会在单测、中测之后执行 verify-order核对磁盘文件与 ORDER 清单是否完全一致专抓文件移过去了、忘 sync-order这类漏提交。回滚用 revertmise //server:migrations revert它执行最新一条迁移的 down()把 schema 恢复到迁移前。开发新迁移时这是检验 down 逻辑的标准姿势先 run 再 revert确认结构和数据都能复原。server/package.json 里还有一组等价的 npm scripts措辞不同但一一对应子命令什么时候用generate比对 schema 与数据库差异自动产出迁移 DDLrun执行所有未应用的迁移revert回滚最近一次迁移检验 down()sync-order把新迁移登记进 ORDER 清单verify-order校验清单与磁盘文件一致CI 使用排错工具箱schema 漂移检测与本地重置本地库被改乱了吗仓库内置 schema-check 服务命令实现见 schema-check 源码逻辑像一份体检报告核对磁盘迁移历史与数据库真实状态给每个迁移判三种状态之一——applied已应用正常路径deleted数据库里执行过磁盘上文件却没了missing磁盘上有数据库里还没执行。发现漂移时它列出漂移项借 sql-tools 的 asHuman 渲染并附上一段自动生成的修复 SQL。源码特意标了 Use at your own risk!——那段 SQL 仅供参考涉及删表删列时执行前必须人工确认。再往下就是核按钮schema-drop 与 schema-reset 两个任务同样定义在 server/mise.toml。[tasks.schema-drop] run { task migrations query DROP schema public cascade; CREATE schema public; }schema-reset 则是先 drop、再 migrations run按 ORDER 重放全部迁移得到与代码完全一致的干净库。⚠️ 两个任务都会清空全部数据仅限本地开发环境使用生产环境严禁照搬——生产要改 schema只有正规的迁移流程一条路。提交前自查6 条快速核对项声明式定义tables 等改完并保存跑过 generateup()/down() 逐行审过含数据回填与可回退性迁移文件已移入 server/src/schema/migrationssync-order 已执行ORDER 与迁移文件同 commit 提交重启本地 server 验证自动应用必要时 revert 回滚、schema-check 查漂移verify-order 通过【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Immich 数据库迁移实战：5 条命令搞定 schema 变更、回滚与漂移检测
Immich 数据库迁移实战5 条命令搞定 schema 变更、回滚与漂移检测【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher改完 Immich 的表定义、重启服务端查询却还在报字段不存在——问题多半出在 Immich 数据库迁移这一步没走对。这篇文章用 5 条 mise migrations 命令带你覆盖 sql-tools 迁移生成、ORDER 清单登记、启动自动应用、迁移回滚与 schema 漂移检测的完整路径。改完表定义、重启服务查询为何还报字段不存在先说一个几乎每个 Immich 贡献者都踩过的坑你在 server/src/schema/tables 里给 asset 表加了一列保存、重启服务端满怀期待地发一条新查询——报错column does not exist。数据库没坏代码也没写错。真相是代码里写的 schema 和 Postgres 里真实存在的 schema是两套东西。前者只描述应该长什么样后者只认真正执行过的 DDL。你改了图纸但没人去工地施工楼当然不会自己长出新楼层。官方文档 database-migrations.md 的全部篇幅都在讲怎么把图纸变成工地。下面按你动手的顺序拆。声明式表定义与迁移文件sql-tools 如何生成 DDLImmich 的 schema 代码分两层职责互不重叠。第一层是声明式表定义集中在 server/src/schema/tables约 64 个表定义文件外加 enums.ts、functions.ts 负责枚举和数据库函数。它回答数据库应该长什么样——类比装修图纸尺寸、水电都画好了但图纸本身盖不起房子。第二层是迁移文件放在 server/src/schema/migrations每个文件导出 up() 和 down() 两个异步函数用 kysely 的 sql 标签模板执行原生 SQL。它回答怎么把旧库改到位——这是施工单加哪根梁、拆哪堵墙、拆错了怎么复原。而把图纸和施工单对起来的是 immich/sql-tools它比对声明式定义与真实数据库的差异自动产出 DDL 写进迁移文件。换句话说你只负责改图纸工具负责出具施工单你再把关执行。一次迁移的完整走位从 generate 到 sync-order一次迁移有四个动作生成、审阅、落位、登记。生成。仓库根目录执行mise //server:migrations generate migration-name//server:前缀表示在 monorepo 根目录执行 server 包的任务定义在 server/mise.toml最终展开为sql-tools -u 连接串 migrations generate ...。连接串看环境变量 DB_URL不设置就默认连本地 Docker 里的开发库 postgres://postgres:postgreslocalhost:5432/immich。产出的文件带毫秒时间戳前缀例如 1745244781846-AddUserAvatarColorColumn.ts——时间戳的作用就是让字典序等于执行顺序。审阅。打开文件重点看三处up() 生成的 DDL 是否符合预期、存量数据回填有没有漏、down() 能否安全走回去。举个例子AddUserAvatarColorColumn 的 up 除了加列还要把老数据从 user_metadata 的 JSON 字段回填进新列down 只负责删列。落位。generate 不会把文件直接放进最终目录需要手动移到 server/src/schema/migrations。那里已有近百个迁移从 1744910873969-InitialMigration 一路排到最新命名统一为毫秒时间戳-PascalCase名称.ts。登记。移完文件补上最后一条命令mise //server:migrations sync-order它把新迁移追加进 ORDER 清单。这份清单为什么值得单独一节往下看。ORDER 清单一份故意制造冲突的文件举个例子你拉了 feature-a 给 asset 表加索引同事拉了 feature-b 新建 plugin 表两边各生成一个带时间戳的迁移文件。如果顺序只靠目录里的文件名两个分支合并时 git 一声不吭——文件互不冲突但执行顺序可能错了先跑的迁移若引用了对方还没建的表服务启动直接失败而且这种失败往往要等部署后才暴露。Immich 的解法是把顺序写进一份 git 跟踪的清单 migrations/ORDER每行一个迁移名去掉 .ts 后缀新迁移靠 sync-order 追加。于是两个分支各自改了 ORDER 文件合并时必然冲突逼你亲自拍板谁先谁后。说白了这是用冲突噪音换顺序确定性的有意取舍多花三十秒解冲突换来合并后迁移顺序 100% 可预期。所以 ORDER 必须和迁移文件放在同一个 commit 提交漏掉它下一关 CI 会拦住你。生效、校验与迁移回滚revert 回滚最近一次变更先说结论贯穿日常的其实就 5 条命令——generate、run、revert、sync-order、verify-order前两条上面已经见过。迁移怎么生效开发环境什么都不用手动做。服务端监听 *.ts 变更自动重启而启动流程本身就包含运行所有未应用的迁移——改完 schema、登记完 ORDER重启 server新迁移就落到本地库了。想显式跑一次run 子命令会执行全部未应用的迁移。这里容易踩坑的是校验CI 的 checklist 任务会在单测、中测之后执行 verify-order核对磁盘文件与 ORDER 清单是否完全一致专抓文件移过去了、忘 sync-order这类漏提交。回滚用 revertmise //server:migrations revert它执行最新一条迁移的 down()把 schema 恢复到迁移前。开发新迁移时这是检验 down 逻辑的标准姿势先 run 再 revert确认结构和数据都能复原。server/package.json 里还有一组等价的 npm scripts措辞不同但一一对应子命令什么时候用generate比对 schema 与数据库差异自动产出迁移 DDLrun执行所有未应用的迁移revert回滚最近一次迁移检验 down()sync-order把新迁移登记进 ORDER 清单verify-order校验清单与磁盘文件一致CI 使用排错工具箱schema 漂移检测与本地重置本地库被改乱了吗仓库内置 schema-check 服务命令实现见 schema-check 源码逻辑像一份体检报告核对磁盘迁移历史与数据库真实状态给每个迁移判三种状态之一——applied已应用正常路径deleted数据库里执行过磁盘上文件却没了missing磁盘上有数据库里还没执行。发现漂移时它列出漂移项借 sql-tools 的 asHuman 渲染并附上一段自动生成的修复 SQL。源码特意标了 Use at your own risk!——那段 SQL 仅供参考涉及删表删列时执行前必须人工确认。再往下就是核按钮schema-drop 与 schema-reset 两个任务同样定义在 server/mise.toml。[tasks.schema-drop] run { task migrations query DROP schema public cascade; CREATE schema public; }schema-reset 则是先 drop、再 migrations run按 ORDER 重放全部迁移得到与代码完全一致的干净库。⚠️ 两个任务都会清空全部数据仅限本地开发环境使用生产环境严禁照搬——生产要改 schema只有正规的迁移流程一条路。提交前自查6 条快速核对项声明式定义tables 等改完并保存跑过 generateup()/down() 逐行审过含数据回填与可回退性迁移文件已移入 server/src/schema/migrationssync-order 已执行ORDER 与迁移文件同 commit 提交重启本地 server 验证自动应用必要时 revert 回滚、schema-check 查漂移verify-order 通过【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考