Immich 数据库迁移踩坑实录改了 schemaPostgres 为什么纹丝不动【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-PatcherImmich 数据库迁移的核心是声明与落库解耦表结构写在代码里真正改数据库的是迁移文件。改完server/src/schema/tables/之后必须用 sql-tools 生成迁移并登记 ORDER 清单Postgres 才会有变化。改了表字段Postgres 里为什么查不到先做 sql-tools 迁移生成在 Immich 里全部表结构都在server/src/schema/tables/中以声明式 API 定义枚举和数据库函数也在同目录。这里有个反直觉的点这些文件无论怎么改Postgres 都不会动一下。它们只是图纸真正执行的是迁移文件而迁移文件要靠 sql-tools 显式生成mise //server:migrations generate AddUserAvatarColorColumn # 产出带毫秒时间戳前缀的 .ts 文件如 1745244781846-AddUserAvatarColorColumn.ts//server:前缀表示在 monorepo 根目录下执行 server 包的任务任务本质是把sql-tools -u 连接串 migrations 子命令包了一层连接串默认指向本地 Docker 里的 Postgres可用DB_URL覆盖。生成的迁移文件里有两个函数up负责加列等 DDL 并把存量数据回填进新列down负责反向操作。真实的回填 SQL 长这样UPDATE users SET avatarColor user_metadata.value - avatar - color FROM user_metadata WHERE users.id user_metadata.userId AND user_metadata.key preferences;你会发现生成的文件并不直接落在最终目录需要手动把它挪进server/src/schema/migrations/。当前已有 90 多个文件清一色毫秒时间戳-名称命名目录内字典序就是执行顺序。这是第一个坑生成这一步完全靠手工。只改表定义的话服务照常启动、代码照常编译但数据库里并没有新列直到某个功能去查这列才报错。两个分支各加一个迁移合并后起不来ORDER 清单在防什么你可能会问文件名都带时间戳了顺序自动就能排还需要一个清单文件干嘛答案藏在合并场景里。A、B 两个分支各加一个迁移合并后真正的冲突发生在server/src/schema/migrations/ORDER上——每行是一个迁移名像排队叫号的小票。它被故意设计成会产生 git 冲突逼你显式决定谁先谁后。只靠时间戳文件的话两个分支会静默地以错误顺序合并后执行的 DDL 若引用了先执行才该创建的表服务直接起不来而且合并时没有任何预警。代价是几行冲突噪音买到的是顺序的确定性。所以新增迁移后必须执行这条命令mise //server:migrations sync-order # 把新迁移追加登记到 ORDER 清单末尾提交代码时一定把 ORDER 清单一起提交。因为执行流程严格按清单走清单里没有的迁移文件等于不存在。想撤销刚才的加列操作Immich 迁移回滚怎么做想验证down是否真的可逆或者迁移写错了不用手写 SQL 删列mise //server:migrations revert这条命令执行最近一次已应用迁移的down()数据库回到迁移前的状态。在server目录里也能直接跑npm run migrations:xxx脚本最常用的三个是migrations:run执行全部未应用的、migrations:revert回滚最近一次、migrations:sync-order登记进清单。两个提醒。其一revert 只该在本地开发、测试库上用生产库动手前务必人工核对down逻辑并先备份。其二生成的down不保证无损——加列若伴随数据回填回滚会丢掉新回填的数据DDL 可逆性本来就是单向的。本地库被改乱了schema 漂移检测怎么查怎么一键重建实际会碰到调试时手改过一张表、切完分支本地库和代码对不上、误删了迁移文件。这时别从日志一条条查先用仓库内置的 schema-check 服务命令实现在server/src/commands/schema-check.ts做一次 schema 漂移检测它把每个迁移分成三种状态已应用、已删除数据库里有、磁盘文件没了、缺失磁盘有、还没应用。检测到漂移会列出漂移项并附上修复 SQL——源码里标着 Use at your own risk人工确认后再用。本地库已经没法精确定位问题时别花时间排查直接跑mise //server:schema-reset重建。该任务先执行DROP SCHEMA public CASCADE清空 public 库再按 ORDER 清单重放全部 90 多个迁移得到一份与代码完全一致的干净库。命令会清空全部数据仅限本地开发环境生产库千万别碰。看到 deleted 状态时先找回丢失的迁移文件别急着改数据库。CI 上 verify-order 报错你漏了 sync-orderserver 的 checklist 任务在单测与中测之后跑 verify-order核对磁盘迁移文件与 ORDER 清单是否完全一致。CI 上它挂了原因几乎只有一个迁移文件提交了清单没提交也就是漏了 sync-order。补救很简单补跑mise //server:migrations sync-order把清单提交上去。开发环境其实很宽容——server 会监听*.ts文件变更自动重启启动流程本身就包含执行所有未应用迁移。本地改完只要重启/重载一次新迁移就会立刻落到本地数据库不用手动 run。整条链路长这样如果你只记住三件事改完表定义必须生成迁移代码里的 schema 不会自己落到数据库。新迁移要立刻 sync-order 并把 ORDER 清单一起提交别赌合并不冲突。本地库乱了dev 库放心 schema-reset生产库永远先备份再谈操作。【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Immich 数据库迁移踩坑实录：改了 schema，Postgres 为什么纹丝不动
Immich 数据库迁移踩坑实录改了 schemaPostgres 为什么纹丝不动【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-PatcherImmich 数据库迁移的核心是声明与落库解耦表结构写在代码里真正改数据库的是迁移文件。改完server/src/schema/tables/之后必须用 sql-tools 生成迁移并登记 ORDER 清单Postgres 才会有变化。改了表字段Postgres 里为什么查不到先做 sql-tools 迁移生成在 Immich 里全部表结构都在server/src/schema/tables/中以声明式 API 定义枚举和数据库函数也在同目录。这里有个反直觉的点这些文件无论怎么改Postgres 都不会动一下。它们只是图纸真正执行的是迁移文件而迁移文件要靠 sql-tools 显式生成mise //server:migrations generate AddUserAvatarColorColumn # 产出带毫秒时间戳前缀的 .ts 文件如 1745244781846-AddUserAvatarColorColumn.ts//server:前缀表示在 monorepo 根目录下执行 server 包的任务任务本质是把sql-tools -u 连接串 migrations 子命令包了一层连接串默认指向本地 Docker 里的 Postgres可用DB_URL覆盖。生成的迁移文件里有两个函数up负责加列等 DDL 并把存量数据回填进新列down负责反向操作。真实的回填 SQL 长这样UPDATE users SET avatarColor user_metadata.value - avatar - color FROM user_metadata WHERE users.id user_metadata.userId AND user_metadata.key preferences;你会发现生成的文件并不直接落在最终目录需要手动把它挪进server/src/schema/migrations/。当前已有 90 多个文件清一色毫秒时间戳-名称命名目录内字典序就是执行顺序。这是第一个坑生成这一步完全靠手工。只改表定义的话服务照常启动、代码照常编译但数据库里并没有新列直到某个功能去查这列才报错。两个分支各加一个迁移合并后起不来ORDER 清单在防什么你可能会问文件名都带时间戳了顺序自动就能排还需要一个清单文件干嘛答案藏在合并场景里。A、B 两个分支各加一个迁移合并后真正的冲突发生在server/src/schema/migrations/ORDER上——每行是一个迁移名像排队叫号的小票。它被故意设计成会产生 git 冲突逼你显式决定谁先谁后。只靠时间戳文件的话两个分支会静默地以错误顺序合并后执行的 DDL 若引用了先执行才该创建的表服务直接起不来而且合并时没有任何预警。代价是几行冲突噪音买到的是顺序的确定性。所以新增迁移后必须执行这条命令mise //server:migrations sync-order # 把新迁移追加登记到 ORDER 清单末尾提交代码时一定把 ORDER 清单一起提交。因为执行流程严格按清单走清单里没有的迁移文件等于不存在。想撤销刚才的加列操作Immich 迁移回滚怎么做想验证down是否真的可逆或者迁移写错了不用手写 SQL 删列mise //server:migrations revert这条命令执行最近一次已应用迁移的down()数据库回到迁移前的状态。在server目录里也能直接跑npm run migrations:xxx脚本最常用的三个是migrations:run执行全部未应用的、migrations:revert回滚最近一次、migrations:sync-order登记进清单。两个提醒。其一revert 只该在本地开发、测试库上用生产库动手前务必人工核对down逻辑并先备份。其二生成的down不保证无损——加列若伴随数据回填回滚会丢掉新回填的数据DDL 可逆性本来就是单向的。本地库被改乱了schema 漂移检测怎么查怎么一键重建实际会碰到调试时手改过一张表、切完分支本地库和代码对不上、误删了迁移文件。这时别从日志一条条查先用仓库内置的 schema-check 服务命令实现在server/src/commands/schema-check.ts做一次 schema 漂移检测它把每个迁移分成三种状态已应用、已删除数据库里有、磁盘文件没了、缺失磁盘有、还没应用。检测到漂移会列出漂移项并附上修复 SQL——源码里标着 Use at your own risk人工确认后再用。本地库已经没法精确定位问题时别花时间排查直接跑mise //server:schema-reset重建。该任务先执行DROP SCHEMA public CASCADE清空 public 库再按 ORDER 清单重放全部 90 多个迁移得到一份与代码完全一致的干净库。命令会清空全部数据仅限本地开发环境生产库千万别碰。看到 deleted 状态时先找回丢失的迁移文件别急着改数据库。CI 上 verify-order 报错你漏了 sync-orderserver 的 checklist 任务在单测与中测之后跑 verify-order核对磁盘迁移文件与 ORDER 清单是否完全一致。CI 上它挂了原因几乎只有一个迁移文件提交了清单没提交也就是漏了 sync-order。补救很简单补跑mise //server:migrations sync-order把清单提交上去。开发环境其实很宽容——server 会监听*.ts文件变更自动重启启动流程本身就包含执行所有未应用迁移。本地改完只要重启/重载一次新迁移就会立刻落到本地数据库不用手动 run。整条链路长这样如果你只记住三件事改完表定义必须生成迁移代码里的 schema 不会自己落到数据库。新迁移要立刻 sync-order 并把 ORDER 清单一起提交别赌合并不冲突。本地库乱了dev 库放心 schema-reset生产库永远先备份再谈操作。【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
