Immich 数据库迁移实战:5 个环节讲透 schema 变更、ORDER 清单与回滚【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher你改完 Immich 的 schema 定义,重启服务端,数据库为什么纹丝不动?本文围绕 sql-tools 迁移工具链,把 schema 变更的生成、ORDER 清单、自动应用、回滚与漂移检测五个环节一次讲清,帮你把第一次数据库迁移做对。改完 schema 定义,数据库为什么纹丝不动先还原一个新手必踩的场景:你在server/src/schema/tables/下给某张表加了一列,保存。开发模式下服务端监听到*.ts变更,自动重启了。然后你去查库——新列不存在,也没有任何报错。这不是环境坏了,而是 Immich 的 schema 是两态结构,三件套都住在server/src/schema/:tables/:每张表的声明式定义,描述数据库应该长什么样;enums.ts、functions.ts:枚举,以及数据库函数/触发器;migrations/:按时间戳排序的迁移文件,外加一份ORDER清单(下文细讲)。关键区别:声明是目标态,up()才是执行单元。tables/里的定义本身不触发任何 DDL;真正对数据库动刀的是迁移文件里的up()函数。两者之间的桥是immich/sql-tools(当前仓库锁定的版本见pnpm-lock.yaml):它比对声明与真实库的差异,生成迁移 SQL,再按ORDER顺序执行。一句话记住:你写的是图纸,up()才是施工队;没有迁移文件,数据库纹丝不动。ORDER 清单为什么必须提交进 gitORDER是server/src/schema/migrations/ORDER里的一份清单,每行一个迁移名(去掉.ts),前几行长这样:1744910873969-InitialMigration 1744991379464-AddNotificationsTable 1745244781846-AddUserAvatarColorColumn你可能会问:迁移文件本身就有毫秒时间戳前缀,目录按字典序排就是执行顺序,清单不是多余吗?它防的是并行分支。两个分支各自加了迁移,只靠时间戳的话,合并后谁先跑完全取决于两台机器的时钟,且不会有任何提示;若后合入的 DDL 依赖先合入分支里还没跑的表,服务启动直接失败——而且错序是静默发生的。把ORDER提交进 git 后,两个分支更新清单时一定会产生 git 合并冲突,逼你显式拍板先后。这是有意的设计:用合并冲突噪音换顺序确定性。一句话记住:ORDER的价值在合并期——冲突响一下,胜过线上炸一次。一次迁移的四个动作generate:一条命令生成骨架mise //server:migrations generate migration-name//server:前缀 在 monorepo 根目录执行server包的任务(server/mise.toml声明了monorepo_root);实际展开为sql-tools -u DB_URL migrations generate ...,DB_URL未设置时默认连本地 Docker 的postgres://postgres:postgreslocalhost:5432/immich;产物是带毫秒时间戳前缀的.ts文件,如1745244781846-AddUserAvatarColorColumn.ts(时间戳 PascalCase 名称)。审阅 up()/down():加列只是开始每个迁移导出up()与down()两个异步函数,内部用 kysely 的sql模板写原生 SQL。以仓库里的 AddUserAvatarColorColumn 为例:export async function up(db: Kyselyany): Promisevoid { await sqlALTER TABLE users ADD avatarColor varchar;.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); }审阅盯三处:DDL 是否符合预期、down能否安全回退、数据回填有没有漏——这个例子里up先加列,再把存量数据从 JSON 元数据里抽出来回填;down只做反向删除。仓库里也有 up/down 都是 noop 的占位迁移(如 UnsetPrewarmDimParameter),它的作用仅是维持ORDER与磁盘文件的对应关系。落位:移进 migrations 目录generate的产物不会直接落在最终目录,需要你在编辑器里把它挪进server/src/schema/migrations/。当前该目录下近百个迁移文件,从1744910873969-InitialMigration.ts排到最新,字典序即执行顺序。sync-order:清单要跟着一起提交mise //server:migrations sync-order把新迁移追加进ORDER,并连同ORDER文件一起提交——只交迁移文件不交清单,是 CI 上最常见的挂法。一句话记住:生成 → 审阅 → 落位 → 登记,四步少一步,CI 或线上就会还账。新迁移怎么被自动跑起来开发环境不需要手动run:服务端启动流程本身就包含执行所有未应用的新迁移,dev 模式还会监听*.ts变更自动重启——文件一保存,新迁移就应用到本地库。CI 侧由server/mise.toml的checklist任务兜底:单测与中测跑完后,追加执行mise //server:migrations verify-order,校验磁盘文件与ORDER清单完全一致,专门拦截忘了 sync-order。一句话记住:本地靠重启自动应用,CI 靠 verify-order 对账。如何安全回滚一次迁移验证down是否真的可逆,一条命令:mise //server:migrations revert它执行最新一条迁移的down(),把 schema 恢复到迁移前。server/package.json里还有一组等价 npm scripts,在server目录内可直接用:脚本作用migrations:create创建空迁移骨架migrations:generate比对 schema 自动生成迁移 DDLmigrations:debug同 generate,附调试输出migrations:run执行所有未应用的迁移migrations:revert回滚最近一次迁移migrations:sync-order将新迁移登记进ORDER清单migrations:verify-order校验清单与文件一致性(CI 用)一句话记住:revert只回滚最近一次,是复验down可逆性的最快路径。漂移怎么查,本地库脏了怎么洗schema-check:先给迁移分三种状态。server/src/commands/schema-check.ts里的服务命令核对磁盘迁移与数据库实际状态,每个迁移归入其一:applied:已应用,正常路径;deleted:数据库里跑过,磁盘上文件却不见了;missing:磁盘上有,数据库还没应用。检测到漂移时,它会列出漂移项,并附一段自动生成的修复 SQL——源码里对这段 SQL 标着 Use at your own risk!。它仅供参考,执行前必须人工逐条确认,别直接复制粘贴跑。schema-drop / schema-reset:仅限本地。server/mise.toml里还定义了本地重建任务:schema-drop用DROP SCHEMA public CASCADE重建空 schema,schema-reset则 drop 之后按ORDER顺序重放全部迁移,得到与代码完全一致的干净库。本地库被手工改过、schema-check 报出一堆漂移时,这是最省事的恢复手段。⚠️ 再强调:这两个任务会清空全部数据,只配在开发环境用;生产环境禁止照搬,任何 drop 级操作都不该进生产流程。一句话记住:漂移用 schema-check 定位,脏库用 schema-reset 重建——但只在本地。提交前自查清单tables/等声明式定义与迁移 DDL 描述的是同一个目标态;up()的数据回填完整,down()已本地跑通;迁移文件已移入server/src/schema/migrations/;mise //server:migrations sync-order已执行,ORDER与迁移文件同一次提交;mise //server:migrations verify-order通过;重启本地 server 确认自动应用,必要时revert复验回滚。【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考