Immich 数据库迁移完整流程生成、ORDER 清单、自动应用与回滚【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immichImmich 服务端把全部表结构以 TypeScript 形式维护在server/src/schema下改完这些定义文件后数据库并不会随之变化——必须走一次迁移migration流程新结构才会真正落到 PostgreSQL 里。本文按一次变更的时间线把整条链路走一遍工具链怎么准备、迁移文件如何生成和审阅、ORDER 清单为什么值得单独提交、重启后迁移如何自动生效以及回滚和漂移排查怎么做。1. 动手之前先看清 schema 的目录结构所有表结构代码集中在 server/src/schema由四类内容组成位置内容tables/64 个表定义文件如asset.table.ts、album.table.ts、plugin.table.ts用声明式 API 描述表应该长什么样enums.ts、functions.ts枚举、数据库函数与触发器定义migrations/按时间戳命名的.ts迁移文件 一个ORDER清单文件immich/sql-tools版本 0.6.3见 pnpm-lock.yaml迁移工具比对声明式 schema 与真实库的差异生成迁移 SQL并按 ORDER 顺序执行可以这样理解两者的分工tables/是目标蓝图migrations/里每个文件的up()才是把旧库改造成蓝图的施工单元。sql-tools 负责把图纸翻译成施工单。2. 工具链mise 任务与数据库连接串仓库根目录的 mise.toml 声明了monorepo_root true所以//server:前缀表示在 monorepo 根下执行 server 包的任务。server/mise.toml 中的核心任务长这样[tasks.migrations] env._.path ./node_modules/.bin run sql-tools -u ${DB_URL:-postgres://postgres:postgreslocalhost:5432/immich} migrations description Run database migration commands (create, generate, run, sync-order, verify-order, ...)也就是说mise //server:migrations 子命令会展开成sql-tools -u 连接串 migrations 子命令你输入的子命令直接拼在末尾。这里有两个要点目标库由DB_URL环境变量决定没设置时回落到默认值postgres://postgres:postgreslocalhost:5432/immich即本地 Docker 开发环境里的 Postgres。3. 生成迁移文件四步走官方文档 docs/docs/developer/database-migrations.md 给出的流程一共四步。第 1 步生成文件mise //server:migrations generate migration-name这条命令让 sql-tools 比对声明式 schema 与当前数据库产出一个带毫秒时间戳前缀的.ts文件命名形如1745244781846-AddUserAvatarColorColumn.ts时间戳 PascalCase 名称。第 2 步人工审阅生成的迁移导出up()与down()两个异步函数内部通过 kysely 的sql模板执行原生 SQL。仓库里真实的例子 1745244781846-AddUserAvatarColorColumn.tsimport { 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则负责把这一切撤掉。审阅时重点看三件事DDL 是否符合预期、down能否安全退回、有没有漏掉数据回填。另有一类占位迁移例如 1750323941566-UnsetPrewarmDimParameter.tsup/down全是 noop。这类文件本身不做任何事存在的意义只是维持 ORDER 清单与磁盘文件一一对应。第 3 步把文件挪进server/src/schema/migrationsgenerate的产物不会直接落在最终目录需要你在编辑器里手动移入 server/src/schema/migrations。该目录现有 96 个迁移文件从1744910873969-InitialMigration初始迁移排到1787148183730-DeleteMismatchedMemoryAssets。时间戳前缀保证目录内字典序就等于执行顺序。第 4 步sync-order 登记清单mise //server:migrations sync-order这一步把新迁移追加到 migrations/ORDER 清单每行一个迁移名去掉.ts后缀1744910873969-InitialMigration 1744991379464-AddNotificationsTable 1745244781846-AddUserAvatarColorColumn 1745902563899-AddAssetVisibilityColumn4. 为什么 ORDER 必须和迁移文件一起提交这是整个流程里最容易省、也最不能省的一步。ORDER 是纳入 git 跟踪的清单文件假设两个分支各自新增了迁移合并时必然在 ORDER 上撞出冲突逼着开发者当面裁定先后。反过来想如果没有 ORDER两个分支只会凭目录里的时间戳静默合并顺序谁说了算完全看运气——一旦某条迁移先于它所依赖的表执行DDL 直接报错服务再也起不来。ORDER 机制等于用一次显式的合并冲突换回执行顺序的确定性。这也是 CI 会盯着它的原因server/mise.toml 的checklist任务在跑完单测和中测之后还会执行{ task :migrations, args [verify-order] }确认磁盘文件与 ORDER 完全对得上防止谁漏交了第 4 步。5. 迁移的自动应用与回滚开发环境里服务端会监听*.ts的变更并自动重启而启动流程本身就包含执行所有尚未应用的迁移这一环节。所以只要本地 server 重启新迁移立刻落到库上你不必手动run。需要撤销最近一次已应用的迁移时比如想验证down真的可逆mise //server:migrations revert它会执行最新一条迁移的down()把库回退到迁移前的状态。server/package.json 里还有一组等价 npm scripts方便直接在server目录下操作脚本作用migrations:create创建空迁移骨架migrations:generate比对 schema 自动生成迁移 DDLmigrations:debuggenerate 的调试版附带额外输出migrations:run执行所有未应用的迁移migrations:revert回滚最近一次迁移migrations:sync-order把新迁移登记进 ORDERmigrations:verify-order校验清单与文件一致CI 使用6. 进阶排查schema-check 与 schema-resetschema-check一眼看清迁移状态与漂移仓库内置schema-check服务命令实现在 server/src/commands/schema-check.ts。它核对磁盘迁移与库内实际状态是否一致把每个迁移归入三种状态之一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; } [tasks.schema-reset] run [ { task :schema-drop }, { task migrations run }, ]流程是先DROP SCHEMA public CASCADE清空再重建随后migrations run按 ORDER 顺序把 96 个迁移从头重放得到一个与代码完全对齐的干净库。当你手工改过表、误删过迁移文件导致schema-check持续报漂移时这就是最省心的恢复路径。注意schema-drop会清空数据生产环境绝不该照搬。7. 命令速查与提交前检查清单 场景命令生成迁移mise //server:migrations generate name登记 ORDERmise //server:migrations sync-order校验清单mise //server:migrations verify-order手动执行迁移mise //server:migrations run回滚最近一次mise //server:migrations revert查漂移服务命令schema-check本地重建mise //server:schema-drop/mise //server:schema-reset提交前的完整清单✅ 修改server/src/schema/tables等声明式定义generate产出迁移人工审阅up/down重点数据回填、可回退性把文件移入server/src/schema/migrationssync-order并把 ORDER 清单一起提交重启本地 server确认迁移自动生效必要时用revert试回滚、用schema-check确认无漂移verify-order通过后再推送——CI 的 checklist 也会跑这一步。整套流程的前提只有一个本地有可达的 Postgres默认DB_URL指向开发用 Docker Compose 里的localhost:5432/immich且使用当前仓库锁定的immich/sql-tools 0.6.3工具链。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考