Immich 数据库迁移完整指南如何走完 schema 变更、回滚与漂移检测全流程【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher给 Immich 改表结构光改 TypeScript 声明不够还要生成迁移、登记 ORDER 清单再让服务把变更应用到 PostgreSQL。本文带你走通 Immich 数据库迁移全流程生成迁移文件、登记 ORDER、自动应用、回滚最近一次迁移以及 schema 漂移检测与本地重置。 先分清两层schema 声明 vs 迁移执行Immich 的全部表结构以 TypeScript 定义在 server/src/schema 目录分三块tables/约 64 个表定义文件如asset.table.ts、album.table.ts用immich/sql-tools的声明式 API 描述表结构enums.ts与functions.ts枚举、数据库函数与触发器定义migrations/按时间戳排序的迁移文件外加一份ORDER清单。这两层的关系像盖楼tables/是设计图只声明库应该长什么样本身不碰任何数据migrations/里每条迁移的up()函数才是施工单负责把已存在的数据库真正改成目标状态。把设计图落成现实的是迁移工具immich/sql-toolsworkspace 锁定 0.6.3版本记录在 pnpm-lock.yaml它比对声明式 schema 与真实数据库的差异自动生成迁移 SQL并在服务启动或测试时按 ORDER 顺序执行。所以结论很直接改了声明不等于改了数据库必须再走一遍生成迁移 → 登记 → 应用。️ 一条迁移的诞生从 generate 到登记 ORDER整条主线四步全部由 server/mise.toml 中的任务驱动。生成迁移文件在 monorepo 根目录执行mise //server:migrations generate migration-name//server:前缀表示运行server包的任务mise.toml 声明了monorepo_root true对应任务定义为[tasks.migrations] env._.path ./node_modules/.bin run sql-tools -u ${DB_URL:-postgres://postgres:postgreslocalhost:5432/immich} migrations展开后就是sql-tools -u 连接串 migrations 子命令连接串来自DB_URL环境变量缺省值为postgres://postgres:postgreslocalhost:5432/immich即本地 Docker 开发环境里的 Postgres。人工审阅 up 与 downgenerate产出毫秒时间戳-PascalCase名称.ts导出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); }审阅盯三件事DDL 是否符合预期、down能否安全回退、数据回填是否遗漏。它的up就是典型写法——先加列再把存量数据从user_metadata的 JSON 元数据回填进新列。另有空操作占位迁移如1750323941566-UnsetPrewarmDimParameter.tsup/down均为 noop只为维持 ORDER 清单与磁盘文件的对应关系。移入 migrations 并登记 ORDERgenerate的文件不会直接落在最终目录需手动移进server/src/schema/migrations。目前该目录共 97 个迁移文件时间戳前缀保证字典序即执行顺序从1744910873969-InitialMigration.ts一路排到最新的1787148183730-DeleteMismatchedMemoryAssets.ts。随后执行mise //server:migrations sync-order把新迁移追加进 server/src/schema/migrations/ORDER 清单每行记录一个去掉.ts后缀的迁移名。ORDER 为什么非提交不可这是有意为之。ORDER 被 git 跟踪两个分支各自新增迁移时必然在这个文件上撞出合并冲突逼你当场拍板先后顺序若只靠目录里的时间戳文件分支会静默地按错误顺序合并——某条 DDL 可能依赖另一条尚未创建的表服务直接起不来。ORDER 清单本质是冲突制造机多花一次解冲突的功夫换回执行顺序的确定。 跑起来自动应用与回滚重启即自动应用开发环境下迁移应用是顺带完成的。server 监听*.ts变更并自动重启而启动流程本身就包含运行所有未应用的迁移。重载 server 后新迁移立刻落到本地库无需手动run。CI 侧的把关在 server/mise.toml 的 checklist 任务单测与中测之后追加执行verify-order确认磁盘迁移文件与 ORDER 完全一致防止漏交登记步骤。回滚最近一次迁移要验证down逻辑是否真可逆mise //server:migrations revert它执行最新一条迁移的down()把 schema 恢复到迁移前的状态。npm scripts 等价对照server/package.json 暴露了一组等价脚本在 server 目录内可直接使用脚本作用migrations:create创建空迁移骨架migrations:generate比对 schema 自动生成迁移 DDLmigrations:debug同 generate附带调试输出migrations:run执行所有未应用的迁移migrations:revert回滚最近一次迁移migrations:sync-order将新迁移登记进 ORDER 清单migrations:verify-order校验清单与文件一致性CI 使用 跑挂了schema 漂移检测与本地重置schema-check三种状态定位问题仓库内置schema-check服务命令实现见 server/src/commands/schema-check.ts核对磁盘迁移与数据库实际状态把每个迁移归入三种状态applied已应用正常路径deleted数据库已应用磁盘文件却不见了missing磁盘上存在尚未应用到数据库。发现漂移时命令用immich/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重建空 schema再按 ORDER 顺序重放全部 97 个迁移得到一个与代码完全一致的干净库。当本地库被手工改过表、误删过迁移文件导致schema-check报错时这是最可靠的恢复手段。✅ 提交前自检清单修改 server/src/schema 下的声明式定义tables/等generate name生成迁移人工审阅up/downDDL 符合预期、可回退、回填没漏迁移文件已移入 server/src/schema/migrations执行sync-orderORDER 清单随代码一起提交重启本地 server 验证自动应用必要时用revert测回滚、schema-check确认无漂移提交前确认verify-order通过——CI checklist 会执行同一校验。前提本地有可达的 Postgres默认DB_URL指向开发用 Docker Compose 的localhost:5432/immich且使用当前仓库锁定的immich/sql-tools 0.6.3。生产环境不要照搬schema-drop这类本地操作。【免费下载链接】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-Patcher给 Immich 改表结构光改 TypeScript 声明不够还要生成迁移、登记 ORDER 清单再让服务把变更应用到 PostgreSQL。本文带你走通 Immich 数据库迁移全流程生成迁移文件、登记 ORDER、自动应用、回滚最近一次迁移以及 schema 漂移检测与本地重置。 先分清两层schema 声明 vs 迁移执行Immich 的全部表结构以 TypeScript 定义在 server/src/schema 目录分三块tables/约 64 个表定义文件如asset.table.ts、album.table.ts用immich/sql-tools的声明式 API 描述表结构enums.ts与functions.ts枚举、数据库函数与触发器定义migrations/按时间戳排序的迁移文件外加一份ORDER清单。这两层的关系像盖楼tables/是设计图只声明库应该长什么样本身不碰任何数据migrations/里每条迁移的up()函数才是施工单负责把已存在的数据库真正改成目标状态。把设计图落成现实的是迁移工具immich/sql-toolsworkspace 锁定 0.6.3版本记录在 pnpm-lock.yaml它比对声明式 schema 与真实数据库的差异自动生成迁移 SQL并在服务启动或测试时按 ORDER 顺序执行。所以结论很直接改了声明不等于改了数据库必须再走一遍生成迁移 → 登记 → 应用。️ 一条迁移的诞生从 generate 到登记 ORDER整条主线四步全部由 server/mise.toml 中的任务驱动。生成迁移文件在 monorepo 根目录执行mise //server:migrations generate migration-name//server:前缀表示运行server包的任务mise.toml 声明了monorepo_root true对应任务定义为[tasks.migrations] env._.path ./node_modules/.bin run sql-tools -u ${DB_URL:-postgres://postgres:postgreslocalhost:5432/immich} migrations展开后就是sql-tools -u 连接串 migrations 子命令连接串来自DB_URL环境变量缺省值为postgres://postgres:postgreslocalhost:5432/immich即本地 Docker 开发环境里的 Postgres。人工审阅 up 与 downgenerate产出毫秒时间戳-PascalCase名称.ts导出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); }审阅盯三件事DDL 是否符合预期、down能否安全回退、数据回填是否遗漏。它的up就是典型写法——先加列再把存量数据从user_metadata的 JSON 元数据回填进新列。另有空操作占位迁移如1750323941566-UnsetPrewarmDimParameter.tsup/down均为 noop只为维持 ORDER 清单与磁盘文件的对应关系。移入 migrations 并登记 ORDERgenerate的文件不会直接落在最终目录需手动移进server/src/schema/migrations。目前该目录共 97 个迁移文件时间戳前缀保证字典序即执行顺序从1744910873969-InitialMigration.ts一路排到最新的1787148183730-DeleteMismatchedMemoryAssets.ts。随后执行mise //server:migrations sync-order把新迁移追加进 server/src/schema/migrations/ORDER 清单每行记录一个去掉.ts后缀的迁移名。ORDER 为什么非提交不可这是有意为之。ORDER 被 git 跟踪两个分支各自新增迁移时必然在这个文件上撞出合并冲突逼你当场拍板先后顺序若只靠目录里的时间戳文件分支会静默地按错误顺序合并——某条 DDL 可能依赖另一条尚未创建的表服务直接起不来。ORDER 清单本质是冲突制造机多花一次解冲突的功夫换回执行顺序的确定。 跑起来自动应用与回滚重启即自动应用开发环境下迁移应用是顺带完成的。server 监听*.ts变更并自动重启而启动流程本身就包含运行所有未应用的迁移。重载 server 后新迁移立刻落到本地库无需手动run。CI 侧的把关在 server/mise.toml 的 checklist 任务单测与中测之后追加执行verify-order确认磁盘迁移文件与 ORDER 完全一致防止漏交登记步骤。回滚最近一次迁移要验证down逻辑是否真可逆mise //server:migrations revert它执行最新一条迁移的down()把 schema 恢复到迁移前的状态。npm scripts 等价对照server/package.json 暴露了一组等价脚本在 server 目录内可直接使用脚本作用migrations:create创建空迁移骨架migrations:generate比对 schema 自动生成迁移 DDLmigrations:debug同 generate附带调试输出migrations:run执行所有未应用的迁移migrations:revert回滚最近一次迁移migrations:sync-order将新迁移登记进 ORDER 清单migrations:verify-order校验清单与文件一致性CI 使用 跑挂了schema 漂移检测与本地重置schema-check三种状态定位问题仓库内置schema-check服务命令实现见 server/src/commands/schema-check.ts核对磁盘迁移与数据库实际状态把每个迁移归入三种状态applied已应用正常路径deleted数据库已应用磁盘文件却不见了missing磁盘上存在尚未应用到数据库。发现漂移时命令用immich/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重建空 schema再按 ORDER 顺序重放全部 97 个迁移得到一个与代码完全一致的干净库。当本地库被手工改过表、误删过迁移文件导致schema-check报错时这是最可靠的恢复手段。✅ 提交前自检清单修改 server/src/schema 下的声明式定义tables/等generate name生成迁移人工审阅up/downDDL 符合预期、可回退、回填没漏迁移文件已移入 server/src/schema/migrations执行sync-orderORDER 清单随代码一起提交重启本地 server 验证自动应用必要时用revert测回滚、schema-check确认无漂移提交前确认verify-order通过——CI checklist 会执行同一校验。前提本地有可达的 Postgres默认DB_URL指向开发用 Docker Compose 的localhost:5432/immich且使用当前仓库锁定的immich/sql-tools 0.6.3。生产环境不要照搬schema-drop这类本地操作。【免费下载链接】OpenCore-Legacy-PatcherExperience macOS just like before项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考