Immich 数据库 schema 迁移实战指南：从加一列到回滚、漂移检测的完整流程

Immich 数据库 schema 迁移实战指南从加一列到回滚、漂移检测的完整流程【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher本文覆盖 Immich 一次完整数据库迁移的闭环如何生成迁移、ORDER 清单的设计动机、服务启动时的自动应用、最近一次迁移回滚、数据库漂移检测schema-check以及本地库重建。前置条件本机有一个可达的 Postgres默认连接postgres://postgres:postgreslocalhost:5432/immich即开发用 Docker Compose 起的那个并已按仓库开发文档把服务跑起来。场景给 users 表加一列为什么库纹丝不动假设你要在users表上新增一列avatarColor。改完 server/src/schema/tables/ 里的表定义、提交代码本地库的\d users却毫无变化——这是第一次接触 Immich 迁移机制的人几乎必踩的认知坑改了 schema 代码 ≠ 数据库变了。仓库里其实存在两套真相server/src/schema/tables/ 下有 64 个*.table.ts文件配合enums.ts与functions.ts用immich/sql-tools提供的声明式 API 描述数据库应该长什么样server/src/schema/migrations/ 下的迁移文件才是把已有数据库改成那样的执行单元。两者由immich/sql-toolsworkspace 中锁定为0.6.3见 pnpm-lock.yaml桥接它比对声明式 schema 与真实数据库的差异自动生成迁移 SQL并在服务启动或测试时按 ORDER 清单顺序执行。所以启动流程本身就包含运行所有未应用的新迁移这一环——开发环境里只要重启/重载 server新迁移会立即落库通常不需要手动run。机制先行up()/down() 的分工与 ORDER 清单为什么必须入库每个迁移文件命名统一为毫秒时间戳-PascalCase名称.ts导出up()与down()两个异步函数内部用 kysely 的sql标签模板执行原生 SQLup是正向变更down是反向回退。原理点拨为什么还要维护一份 ORDER 清单而不是直接扫目录时间戳前缀保证了同目录内字典序即执行顺序——server/src/schema/migrations/ 当前共 96 个迁移文件从1744910873969-InitialMigration.ts一直排到1787148183730-DeleteMismatchedMemoryAssets.ts。但扫目录无法解决跨分支协作的问题两个分支各自新增迁移时如果只靠目录里的时间戳文件合并后会静默地以某个顺序执行——先跑的 DDL 可能依赖后跑迁移才创建的表最终服务启动才失败排查成本极高。而 migrations/ORDER 是一份被 git 跟踪的清单每行一个迁移名去掉.ts后缀两个分支的新迁移必然在该文件上产生合并冲突强制开发者显式决定先后顺序。这是用冲突噪音换取顺序确定性的有意设计因此ORDER的变更必须连同迁移文件一起提交。操作主线从生成命令到清单登记跑通生成命令在仓库根目录执行mise //server:migrations generate migration-name//server:前缀表示在 monorepo 根目录根 mise.toml 声明了monorepo_root true下执行server包的任务。该任务在 server/mise.toml 中定义为[tasks.migrations] env._.path ./node_modules/.bin run sql-tools -u ${DB_URL:-postgres://postgres:postgreslocalhost:5432/immich} migrations即mise //server:migrations 子命令展开为sql-tools -u 连接串 migrations 子命令。输入迁移名预期在server目录下得到一个带时间戳前缀的.ts文件——它来自当前数据库 vs 声明式 schema的 diff而不是模板空壳。若生成结果不符合预期用migrations:debug即generate --debug观察 diff 过程。盯着 up 和 down 两件事以真实迁移 1745244781846-AddUserAvatarColorColumn.ts 为例import { Kysely, sql } from kysely; export async function up(db: Kyselyany): Promisevoid { await sqlALTER TABLE users ADD avatarColor character varying;.execute(db); await sql UPDATE users SET avatarColor user_metadata.value-avatar-color FROM user_metadata WHERE users.id user_metadata.userId AND user_metadata.key preferences;.execute(db); } export async function down(db: Kyselyany): Promisevoid { await sqlALTER TABLE users DROP COLUMN avatarColor;.execute(db); }up先加列再把存量数据从user_metadata的 JSON 元数据里回填进新列down执行DROP COLUMN。审阅只看三件事生成的 DDL 是否符合预期down是否真的可安全回退例如DROP COLUMN之后列内数据找不回来这属于结构可逆、数据不可逆有没有遗漏数据回填逻辑。另有一类迁移是up/down均为空操作的占位文件如1750323941566-UnsetPrewarmDimParameter.ts它们存在的意义仅是维持 ORDER 清单与磁盘文件的对应关系。把迁移文件移入 migrations/ 并登记清单generate的产物并不直接落在最终目录需要在代码编辑器中把它移入 server/src/schema/migrations/然后mise //server:migrations sync-order预期看到 migrations/ORDER 末尾多出一行新迁移名。这一步漏提交是最高频的翻车点提交时文件与清单要一起上。两个入口对照mise 任务在仓库根目录执行npm scripts 在server目录内执行定义于 server/package.json操作mise 任务npm script比对 schema 生成迁移 DDLmise //server:migrations generatepnpm run migrations:generate生成迁移带调试输出—pnpm run migrations:debug创建空迁移骨架mise //server:migrations createpnpm run migrations:create执行所有未应用的迁移mise //server:migrations runpnpm run migrations:run回滚最近一次迁移mise //server:migrations revertpnpm run migrations:revert登记进 ORDER 清单mise //server:migrations sync-orderpnpm run migrations:sync-order校验清单与文件一致性CI 用mise //server:migrations verify-orderpnpm run migrations:verify-order清空并重建 public schema仅本地mise //server:schema-droppnpm run schema:drop一键重建仅本地mise //server:schema-resetpnpm run schema:reset原理点拨为什么sync-order/verify-order不连数据库看 server/package.json 会发现这两条脚本不带-u连接串——它们只核对磁盘上的文件与清单文本是否一致是纯文件系统操作generate/run/revert才需要真实连接。这解释了 CI 里verify-order为什么能在不起 Postgres 的轻量任务里跑。回滚与验证revert、schema-check 三态、verify-order 的 CI 角色用 revert 确认 down() 真的可逆mise //server:migrations revert该命令执行最新一条迁移的down()把 schema 恢复到迁移前状态。它是验证回滚可逆性的标准动作改完 schema 后先run、再revert、再run比只看down代码更能暴露问题尤其带数据回填的迁移。用 schema-check 做迁移回滚后的漂移检测schem【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考