Immich 数据库迁移指南从 schema 变更到一键回滚【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-PatcherImmich 数据库迁移最容易踩的坑往往发生在你改完server/src/schema/tables/就重启 server 的那一刻。你信心满满地改了表定义启动日志却还你一句relation user_metadata does not exist。别慌不是你的问题是少做了一步。改完表定义就重启为什么报“表不存在”在 Immich 里tables/这类文件只是规格书描述“数据库应该长什么样”本身不是 DDL。真正动手改库的是migrations/目录下的迁移文件。中间搭桥的是immich/sql-tools工具链它把声明式 schema 和真实数据库做差异比对生成迁移 SQL服务启动时再按 ORDER 清单的顺序把没跑过的迁移挨个执行掉。所以规矩很简单只要动了声明式定义就必须配一次迁移。否则你的改动永远停在代码里库纹丝不动。三个东西怎么配合声明式 schema、迁移文件与 ORDER 清单三者分工很清楚各一句话声明式 schematables/、enums.ts等规格书只描述目标状态迁移文件migrations/下带毫秒时间戳的.ts每个带up()/down()一个负责“改过去”一个负责“改回来”ORDER 清单migrations/ORDER一行一个迁移名记录全局执行顺序。关系画成一行就是声明式 schema ──差异比对── 迁移文件 ──按 ORDER 顺序── PostgreSQL前一个箭头归工具链管后一个箭头归服务启动流程管。一次 PostgreSQL schema 变更怎么走通走一遍。假设给users表加一列先确认本地 Postgres 可达——DB_URL没设时工具默认连localhost:5432/immich就是开发用 Docker Compose 里那个库。然后跑mise //server:migrations generate name。这次 sql-tools 迁移生成干的就是差异比对拿声明式 schema 对照当前数据库产出一个带时间戳前缀的迁移文件形如1745244781846-AddUserAvatarColorColumn.ts。生成完别急着提交打开文件看三处up()里的 DDL 是不是预期、down()能否安全回退、存量数据回填有没有漏。这里有个坑generate 不会把文件直接放进最终目录你得自己把它归档到server/src/schema/migrations下。时间戳前缀保证同目录里字典序就是执行顺序。最后跑一次mise //server:migrations sync-order它负责把新迁移登记进 ORDER 清单。注意这一步必须和迁移文件一起提交清单被 git 跟踪两个分支各自新增迁移时会在 ORDER 上撞出合并冲突逼你显式排好先后只靠目录里的时间戳分支会静默地按错误顺序合并先跑的 DDL 可能就踩在一张不存在的表上。拿冲突当警报器换顺序的确定性是有意的设计。这一串命令各自干了什么命令作用mise //server:migrations generate name比对声明式 schema 与真实数据库生成带时间戳的迁移文件mise //server:migrations sync-order把新迁移登记进 ORDER 清单需随代码一起提交mise //server:migrations verify-order校验清单与磁盘文件一一对应CI 拿它当最后一道闸开发时甚至不用手动migrations runserver 监听*.ts变更自动重启而启动流程本身就包含“跑掉所有未应用的迁移”本地重启一下新迁移就生效了。迁移回滚与漂移排查先轻后重的三招迁移搞砸了也别慌恢复手段按力度从轻到重排最轻的一招是 revertmise //server:migrations revert执行最新一条迁移的down()把库退回到迁移前的状态。你拿不准自己写的down()是不是真可逆就用它试。再往上是诊断schema-check是 server 内置命令实现在server/src/commands/schema-check.ts它把“磁盘迁移”和“数据库实际状态”对账每条迁移归入三态之一状态含义applied已应用正常路径deleted库里已应用磁盘文件却不见了missing磁盘上有还没应用到数据库检测到漂移时它会列出漂移项并附一段自动生成的修复 SQL。注意源码里明明白白标着 “Use at your own risk!”——这段 SQL 仅供参考执行前必须人工确认。最重的一招是 schema-resetmise //server:schema-reset先DROP SCHEMA public CASCADE清空 public再按 ORDER 清单把全部 97 个迁移重放一遍得到一个和代码完全对齐的干净库。数据会被清空仅限开发环境。本地库状态和迁移历史对不上、schema-check反复报错时这是最稳的找回方式。上生产前的两句忠告以上全部——默认DB_URL、revert、schema-reset——都是开发环境打法前提是你手里这个本地 Postgres 随时可以拆掉重建。进了生产schema-drop/schema-reset 这类操作想都别想schema-check 吐出的修复 SQL 只是线索不是执行令。【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Immich 数据库迁移指南：从 schema 变更到一键回滚
Immich 数据库迁移指南从 schema 变更到一键回滚【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-PatcherImmich 数据库迁移最容易踩的坑往往发生在你改完server/src/schema/tables/就重启 server 的那一刻。你信心满满地改了表定义启动日志却还你一句relation user_metadata does not exist。别慌不是你的问题是少做了一步。改完表定义就重启为什么报“表不存在”在 Immich 里tables/这类文件只是规格书描述“数据库应该长什么样”本身不是 DDL。真正动手改库的是migrations/目录下的迁移文件。中间搭桥的是immich/sql-tools工具链它把声明式 schema 和真实数据库做差异比对生成迁移 SQL服务启动时再按 ORDER 清单的顺序把没跑过的迁移挨个执行掉。所以规矩很简单只要动了声明式定义就必须配一次迁移。否则你的改动永远停在代码里库纹丝不动。三个东西怎么配合声明式 schema、迁移文件与 ORDER 清单三者分工很清楚各一句话声明式 schematables/、enums.ts等规格书只描述目标状态迁移文件migrations/下带毫秒时间戳的.ts每个带up()/down()一个负责“改过去”一个负责“改回来”ORDER 清单migrations/ORDER一行一个迁移名记录全局执行顺序。关系画成一行就是声明式 schema ──差异比对── 迁移文件 ──按 ORDER 顺序── PostgreSQL前一个箭头归工具链管后一个箭头归服务启动流程管。一次 PostgreSQL schema 变更怎么走通走一遍。假设给users表加一列先确认本地 Postgres 可达——DB_URL没设时工具默认连localhost:5432/immich就是开发用 Docker Compose 里那个库。然后跑mise //server:migrations generate name。这次 sql-tools 迁移生成干的就是差异比对拿声明式 schema 对照当前数据库产出一个带时间戳前缀的迁移文件形如1745244781846-AddUserAvatarColorColumn.ts。生成完别急着提交打开文件看三处up()里的 DDL 是不是预期、down()能否安全回退、存量数据回填有没有漏。这里有个坑generate 不会把文件直接放进最终目录你得自己把它归档到server/src/schema/migrations下。时间戳前缀保证同目录里字典序就是执行顺序。最后跑一次mise //server:migrations sync-order它负责把新迁移登记进 ORDER 清单。注意这一步必须和迁移文件一起提交清单被 git 跟踪两个分支各自新增迁移时会在 ORDER 上撞出合并冲突逼你显式排好先后只靠目录里的时间戳分支会静默地按错误顺序合并先跑的 DDL 可能就踩在一张不存在的表上。拿冲突当警报器换顺序的确定性是有意的设计。这一串命令各自干了什么命令作用mise //server:migrations generate name比对声明式 schema 与真实数据库生成带时间戳的迁移文件mise //server:migrations sync-order把新迁移登记进 ORDER 清单需随代码一起提交mise //server:migrations verify-order校验清单与磁盘文件一一对应CI 拿它当最后一道闸开发时甚至不用手动migrations runserver 监听*.ts变更自动重启而启动流程本身就包含“跑掉所有未应用的迁移”本地重启一下新迁移就生效了。迁移回滚与漂移排查先轻后重的三招迁移搞砸了也别慌恢复手段按力度从轻到重排最轻的一招是 revertmise //server:migrations revert执行最新一条迁移的down()把库退回到迁移前的状态。你拿不准自己写的down()是不是真可逆就用它试。再往上是诊断schema-check是 server 内置命令实现在server/src/commands/schema-check.ts它把“磁盘迁移”和“数据库实际状态”对账每条迁移归入三态之一状态含义applied已应用正常路径deleted库里已应用磁盘文件却不见了missing磁盘上有还没应用到数据库检测到漂移时它会列出漂移项并附一段自动生成的修复 SQL。注意源码里明明白白标着 “Use at your own risk!”——这段 SQL 仅供参考执行前必须人工确认。最重的一招是 schema-resetmise //server:schema-reset先DROP SCHEMA public CASCADE清空 public再按 ORDER 清单把全部 97 个迁移重放一遍得到一个和代码完全对齐的干净库。数据会被清空仅限开发环境。本地库状态和迁移历史对不上、schema-check反复报错时这是最稳的找回方式。上生产前的两句忠告以上全部——默认DB_URL、revert、schema-reset——都是开发环境打法前提是你手里这个本地 Postgres 随时可以拆掉重建。进了生产schema-drop/schema-reset 这类操作想都别想schema-check 吐出的修复 SQL 只是线索不是执行令。【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
