Immich 数据库迁移全链路：从 generate 到 revert 的 5 个关键动作

Immich 数据库迁移全链路从 generate 到 revert 的 5 个关键动作【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher在 Immich 里做数据库迁移最容易翻车的场景不在单分支而在合并两个分支各自新增一个迁移文件合并后服务重启Postgres 报 DDL 错误进程直接挂掉。文件时间戳互不冲突字典序也排得整整齐齐但两个分支静默地以错误顺序合并了——后执行的 DDL 依赖的表根本还不存在。这个问题在合并前无法被肉眼发现因为目录里只有带时间戳的文件没有任何显式的顺序约定。答案是一份被 git 跟踪的 ORDER 清单server/src/schema/migrations/ORDER每个迁移文件名去掉 .ts 后缀后占清单一行新迁移必须显式登记进去。两个分支各自新增迁移时冲突会落在清单文件上强制开发者亲手决定先后顺序。这是用冲突噪音换顺序确定性的设计。sql-tools 在中间做了什么Immich 服务端的表结构全部用 TypeScript 声明位于 server/src/schema分三部分tables/声明式 API 描述的表定义约 64 个文件描述数据库应该长什么样、enums.ts 与 functions.ts枚举与数据库函数、migrations/按时间戳排序的迁移文件加 ORDER 清单。声明定义本身不动数据库真正执行变更的是迁移文件里的 up() 函数——把已有数据库改成目标形态的执行单元。两侧由 immich/sql-toolsImmich 自研的迁移工具链下文简称 sql-tools桥接它比对声明式 schema 与真实数据库的差异自动生成迁移 SQL再按 ORDER 清单顺序执行。一次真实迁移AddUserAvatarColorColumn给 users 表加列并把存量数据从 JSON 元数据回填到新列长这样export async function up(db: Kyselyany): Promisevoid { await sqlALTER TABLE users ADD avatarColor varchar;.execute(db); // 随后 UPDATE把存量数据从 user_metadata 的 JSON 回填到新列 } export async function down(db: Kyselyany): Promisevoid { await sqlALTER TABLE users DROP COLUMN avatarColor;.execute(db); }迁移文件统一命名为 毫秒时间戳-PascalCase 名称.ts从 1744910873969-InitialMigration 排到最新的业务迁移。时间戳前缀保证同目录内字典序即执行序——改动前缀等于篡改执行历史。另有一类 up/down 都是空操作的占位迁移文件它的存在只是为了维持 ORDER 清单与磁盘文件的一一对应审阅时不必纠结内容。服务启动流程本身就包含运行所有未应用的迁移开发环境重启 server 后新迁移会自动落到本地库无需手动 run。改 → 验 → 落 → 提交改声明先行generate 出差异 DDL先改 server/src/schema/tables 里的声明式定义再让 sql-tools 比对差异、生成迁移# 前置本地 Docker 已跑起 Postgres默认连接 localhost:5432/immich可用 DB_URL 覆盖 mise //server:migrations generate AddUserAvatarColorColumnmise 是仓库统一的开发任务运行器//server:前缀表示在 monorepo 根目录执行 server 包任务实际展开为 sql-tools -u 连接串 migrations generate。生成文件带时间戳前缀、落在 server 目录下还不算最终产物。验人眼过一遍 up 与 down整条链路里最容易踩坑的其实是这一步——机器生成的 DDL 只保证结构差异不保证业务正确。核对三件事DDL 是否符合预期列类型、默认值、索引down() 是否真的可安全回退加列好回退改类型丢数据数据回填逻辑有没有漏存量数据是否被搬进新结构。落移入 migrations 目录并在本地库应用把生成文件手动移入 server/src/schema/migrations——该目录当前有 97 个迁移文件命名全部是统一的时间戳格式——然后应用到本地库看结果# 前置迁移文件已移入 migrations/本地 Postgres 可达 mise //server:migrations run开发环境里也可以靠 server 重启自动应用run 是手动等价物。提交sync-order 与 verify-order 一起过先登记顺序再提交# 前置迁移文件已在 migrations/ 内且本地验证通过 mise //server:migrations sync-order # 把新迁移追加进 ORDER 清单 mise //server:migrations verify-order # 校验磁盘文件与清单完全一致迁移文件与 ORDER 必须同一提交进 git。漏掉 sync-orderverify-order 会在 CI 的 checklist 里被拦下来。出事了怎么办先定位再动手。schema-check 是服务内置命令实现见 server/src/commands/schema-check.ts它把每个迁移归为三态applied已应用正常路径deleted数据库里已应用磁盘上文件不见了missing磁盘上有还没应用到数据库。漂移指磁盘声明与数据库实际状态之间的偏离。检测到漂移时命令会列出漂移项并附一段自动生成的修复 SQL——源码标注 Use at your own risk!执行前必须人工确认。三个处置手段命令适用场景生产环境mise //server:migrations revert执行最新一条迁移的 down()验证回滚逻辑是否可逆⚠️ 禁止schema-check服务命令核对三态输出漂移清单与修复 SQL⚠️ 禁止schema-dropschema-resetserver/mise.toml 任务本地库与迁移历史脱节时DROP SCHEMA public CASCADE 后按 ORDER 重放全部迁移会清空数据⚠️ 禁止revert 适合验证 down 逻辑schema-reset 是清空后重放全部 97 个迁移本地状态彻底混乱手工改过表、误删过迁移文件时用它恢复最快。以上命令一律不要指向生产库生产环境的回滚应走备份恢复而不是迁移回退。速查以下命令都假设本地可达的 Postgreslocalhost:5432/immich 或 DB_URL//server:前缀表示在 monorepo 根目录执行。server 目录内也可用等价的 npm scriptsmigrations:generate 等见 server/package.json。命令作用mise //server:migrations create name创建空迁移骨架up/down 占位mise //server:migrations generate name比对声明式 schema 与数据库自动生成迁移 DDLmise //server:migrations run执行所有未应用的迁移mise //server:migrations revert回滚最近一次迁移执行其 downmise //server:migrations sync-order把新迁移登记进 ORDER 清单mise //server:migrations verify-order校验清单与磁盘文件一致CI checklist 会执行【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考