OpenRig数据库迁移管理指南：92个migration编号演进与版本兼容策略全解析

OpenRig数据库迁移管理指南92个migration编号演进与版本兼容策略全解析【免费下载链接】openrigBuild your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.项目地址: https://gitcode.com/GitHub_Trending/op/openrigOpenRig开源 Agent 协作网络工具使用一套编号递增的 SQLite 数据库迁移migration体系管理数据库结构演进001 → 092每条迁移只增不改、已应用即跳过并通过fixture 对齐守卫保证测试与生产 schema 永远一致。本文用通俗的方式讲透这套数据库迁移机制的编号规则、执行流程与版本兼容策略帮你安全升级而不丢数据。一、迁移机制总览单文件、可追溯、自动执行OpenRig 的守护进程daemon把团队拓扑、会话、队列、工作流等所有状态都存进一个本地 SQLite 数据库。每当产品功能新增字段或表开发者就追加一条编号迁移文件启动时自动补齐。核心就三个文件执行引擎migrate.ts —— 决定怎么跑迁移清单all-migrations.ts —— 决定按什么顺序跑迁移本体migrations/ 目录下 001 到 092 共 92 个编号文件每文件一个功能主题二、migration 编号演进从 001 核心表到 092 的演进脉络每个迁移文件命名格式为三位编号_功能名.ts编号只增不复用天然形成演进时间线。梳理全量编号可以清楚看到 OpenRig 的功能成长史编号段主题代表迁移001–006基础 schema001_core_schema.ts 建 rigs / nodes / edges 三张核心表007–022会话与运行时014_agentspec_reboot.ts、020_rig_services.ts023–037消息队列与工作流024_queue_items.ts、033_workflow_specs.ts041–058策略与归档041_rig_policy.ts、055_node_permission_policy.ts059–071身份与生命周期061_daemon_lifecycle.ts、067_i3_identity_provenance.ts072–092通知与最新能力091_human_questions.ts、092_node_effort.ts编号背后有两条铁律新迁移只往清单末尾追加all-migrations.ts 开头注释明确写着Append new migrations to the END, in order禁止中间插入或修改已发布条目。001 是地基 rigs、nodes、edges 三张表和同 rig 内连线触发器约束都在此处建立后续 91 个迁移全部在其上生长。三、执行引擎如何保证版本兼容阅读 migrate.ts兼容策略其实只有四步但环环相扣记账表首次运行创建schema_migrations表记录每个迁移的名称与应用时间查账读回已应用迁移集合已存在的直接跳过幂等排序按名称字典序排列——因为编号是定长三位数字典序恰好等于编号顺序事务落库每条迁移包在一个事务里执行SQL 成功才登记账本失败则整体回滚数据库永远停在某个完整版本上不会出现半迁移状态。这套机制意味着老数据库升级新 OpenRig 版本时只需启动一次缺失的迁移会自动按序补齐而新版本永远兼容旧库文件因为迁移只加不删。数据库连接层同样为兼容做了铺垫——connection.ts 默认开启 WAL 模式与外键约束保证读写并发安全。四、Fixture 对齐守卫防止测试与生产 schema 脱节这是 OpenRig 迁移管理中最有工程智慧的部分。如果测试只跑部分迁移新迁移加入后测试可能漏列、报出莫名其妙的缺列错误。项目用三道保险解决单一事实源all-migrations.ts 注释强调守护进程启动路径和所有测试都从同一个数组迁移数据库杜绝手抄子集声明式子集守卫migration-subset-guard.ts 强制要求——任何精选测试迁移清单中的每一条要么出现在清单里要么在排除表中写明为什么不需要并附可复查的理由失败必须响亮migration-fixture-parity.test.ts 专门验证守卫本身会开火新迁移被遗忘时测试直接点名报错并给出修复方案而不是在无关测试深处埋雷。注释里甚至记录了团队曾为此付出的064/066/067 学费——三个迁移漏进测试清单引发的连环排查这也解释了为什么守卫要教学式报错。五、升级实操普通用户的三步检查清单作为使用者你几乎不需要动手但升级后可用以下清单验证迁移健康看版本号迁移清单当前到 092_node_effort.ts对照 all-migrations.ts 可确认完整收录查启动日志daemon 启动即跑迁移正常启动本身即证明账本补齐成功事务失败会拒绝启动而非带病运行查账本用任意 SQLite 工具打开数据库文件SELECT name FROM schema_migrations ORDER BY name应能列出 001 起的全部条目。六、小结迁移编号演进的设计哲学OpenRig 的数据库迁移管理可以浓缩为三句话编号即时间线001 → 092 只增不改每条迁移都是一个可追溯的功能决策账本即兼容性schema_migrations让任意旧库都能一键升级到最新版本事务保证中间态不存在守卫即纪律fixture 对齐守卫把忘记同步测试这类隐患从线上问题提前消灭在 CI 里。对于想学习迁移系统设计的开发者packages/daemon/src/db/ 目录是一个干净、克制、可直接参考的范本对于 OpenRig 用户只需记住一点放心升级你的 Agent 团队状态都由这 92 条迁移安全守护着。【免费下载链接】openrigBuild your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.项目地址: https://gitcode.com/GitHub_Trending/op/openrig创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考