ruflo-migrations 插件实战：使用 migrate 命令管理 Agent 数据库 Schema 迁移

ruflo-migrations 插件实战：使用 migrate 命令管理 Agent 数据库 Schema 迁移

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo

导读

本文以 ruflo 仓库中ruflo-migrations插件的migrate命令文档为骨架，系统讲解在 Claude Code / Codex 等 Agent 环境中如何创建、应用、回滚、校验与审查数据库迁移。你将掌握migrate create / up / down / status / validate / history六个子命令的完整用法，理解顺序编号迁移文件的格式约定、up/down 成对 SQL 的回滚安全模型，以及迁移元数据如何在 AgentDB 的migrations命名空间中持久化，并学会用插件的 smoke 契约完成验证。

插件概览：Schema 迁移管理

ruflo-migrations是 ruflo 生态中的数据库 Schema 迁移管理插件，负责生成、校验、预演（dry-run）与回滚数据库迁移。它的核心设计目标有三点：

• 顺序编号：迁移文件按NNN_name.up.sql/NNN_name.down.sql成对生成，支持安全回滚；
• dry-run 预演：在不执行 SQL 的前提下预览待应用迁移的内容；
• 历史追踪：迁移的元数据、执行结果与校验报告统一写入 AgentDB 的migrations命名空间，由memory_*工具族按命名空间路由读写。

插件由 1 个 Agent（migration-engineer）、2 个 Skill（migrate-create、migrate-validate）和 1 个命令（migrate，含 6 个子命令）构成，当前版本为 v0.2.1，声明在 plugins/ruflo-migrations/.claude-plugin/plugin.json，keywords 为ruflo, migrations, database, schema, rollback, mcp, dry-run, up-down-pairs。

安装

在 Claude Code 中通过插件目录加载：

claude --plugin-dir plugins/ruflo-migrations

插件通过ruflo-core注册的rufloMCP 服务器（314 个工具）访问底层能力，其中与本插件相关的工具族包括memory_*（命名空间路由的读写）、agentdb_pattern-*（ReasoningBank 路由的模式存储）等，详见 plugins/ruflo-core/README.md。

migrate 命令的六个子命令

migrate命令提供 6 个子命令，覆盖迁移的完整生命周期：

migrate create <name> # 创建 NNN_name.up.sql 和 NNN_name.down.sql migrate up [--dry-run] # 应用待执行迁移（或仅预览 SQL） migrate down [--steps N] # 回滚最近 N 个迁移（默认 1） migrate status # 展示已应用/待应用迁移状态 migrate validate # 校验待应用迁移的安全性 migrate history # 展示完整迁移执行历史

命令入口文件为 plugins/ruflo-migrations/commands/migrate.md，其 frontmatter 声明description: Database migration operations — create, apply, rollback, validate, and inspect migration history。

migrate create<name>— 创建带顺序编号的新迁移

创建迁移的核心是顺序编号的自动推导，执行步骤：

1. 扫描迁移目录：找出已有迁移文件中的最高编号；
2. 计算下一个编号：加 1 后按 3 位零填充（zero-padded，如001）；
3. 生成文件对：产出NNN_<name>.up.sql和NNN_<name>.down.sql两个文件；
4. 填充 SQL 模板：根据<name>选择对应的模板（建表、加列、加索引）；
5. 存储迁移元数据：通过mcp__plugin_ruflo-core_ruflo__memory_store --namespace migrations记录编号、名称、状态（pending）与文件路径；
6. 报告结果：输出创建的文件路径、迁移编号与使用的模板。

路由要点：迁移元数据必须走memory_*工具族（按命名空间路由）。agentdb_hierarchical-*系列按tier（working|episodic|semantic）路由，并不认命名空间参数——这是 ADR-0001 修复的一类真实缺陷（见下文"命名空间协调"）。

模板选择规则（来自 plugins/ruflo-migrations/skills/migrate-create/SKILL.md）：

生成的 UP 语句使用IF NOT EXISTS保证幂等，DOWN 语句使用IF EXISTS保证安全逆操作。迁移号与命名规范（来自 migration-engineer）：

• 格式：NNN_descriptive_name，如001_create_users；
• 每个迁移两个文件：NNN_name.up.sql与NNN_name.down.sql；
• 编号 3 位零填充；名称 snake_case，简洁描述变更。

标准 SQL 模板示例（见 migration-engineer.md）：

建表：

-- UP CREATE TABLE IF NOT EXISTS table_name ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() ); -- DOWN DROP TABLE IF EXISTS table_name;

加列：

-- UP ALTER TABLE table_name ADD COLUMN column_name TYPE NOT NULL DEFAULT value; -- DOWN ALTER TABLE table_name DROP COLUMN IF EXISTS column_name;

加索引：

-- UP CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_table_column ON table_name (column_name); -- DOWN DROP INDEX CONCURRENTLY IF EXISTS idx_table_column;

创建完成后，可调用agentdb_pattern-search检索过往相似迁移模式（注意：pattern-*工具按 ReasoningBank 路由，不要传namespace参数）。CLI 等效操作：

npx @claude-flow/cli@latest memory store --namespace migrations --key "migration-NNN_NAME" --value '{"number": NNN, "name": "NAME", "status": "pending"}'

migrate up [--dry-run] — 应用待执行迁移

up负责把未应用的迁移按顺序执行：

1. 回顾迁移历史：确定哪些迁移已被应用；
2. 找出待应用迁移：按顺序列出所有未应用的迁移；
3. dry-run 模式：若带--dry-run，仅展示每个待应用迁移的 SQL，不执行；
4. 执行：非 dry-run 时按顺序执行每个.up.sql文件并记录结果；
5. 存储执行结果：将成功/失败与耗时写入migrations命名空间；
6. 报告：输出已应用迁移数、总耗时与任何错误。

dry-run 是 CI 前预览变更的最安全方式——它把"将要执行什么"完整呈现给审查者，避免未经审查的 DDL 直接落库。

migrate down [--steps N] — 回滚最近 N 个迁移

回滚方向与up严格相反：

1. 回顾迁移历史，找到最近应用的迁移；
2. 按逆序执行对应的.down.sql文件；
3. 将回滚结果记录到migrations命名空间；
4. 报告已回滚的迁移与错误。

默认只回滚最近 1 个迁移（--steps 1），可通过--steps N指定回滚数量。up/down 成对设计保证了每个迁移都可以精确逆操作——这正是"回滚安全"（rollback safety）的基石。

migrate status — 展示迁移状态

status是迁移进度的只读快照：

1. 列出迁移目录中发现的全部迁移文件；
2. 与已应用的迁移历史交叉比对；
3. 展示每个迁移的：编号、名称、状态（applied/pending）、应用日期与耗时。

通过一次status即可判断当前 Schema 处于哪个版本、还有哪些迁移待执行。

migrate validate — 校验待应用迁移的安全性

validate在应用之前发现隐患，检查项覆盖引用完整性、回滚完备性与命名规范：

1. 解析 SQL：解析所有待应用的.up.sql与.down.sql；
2. 外键目标检查：确认REFERENCES目标存在于当前 Schema 或之前的迁移中；
3. NOT NULL 默认值检查：确认ADD COLUMN ... NOT NULL均带DEFAULT；
4. 破坏性操作标记：标记DROP TABLE、DROP COLUMN等破坏性操作；
5. UP/DOWN 对应检查：确认每个 UP 语句都有对应的 DOWN 语句；
6. 命名规范检查：表名复数、列名 snake_case、索引名遵循idx_table_column约定；
7. 报告：输出 errors（必须修复）、warnings（应当修复）、info（建议）三级结果，并附文件路径与行号。

校验逻辑的完整清单（来自 migrate-validate SKILL 与 migration-engineer.md）：

校验结果的存储采用双路径设计（对齐 ruflo-cost-tracker ADR-0001 的 dual-path 模式）：

• 模式存储（推荐，类型化）：mcp__plugin_ruflo-core_ruflo__agentdb_pattern-store，type: 'migration-validation'，不传 namespace——由 ReasoningBank 路由；
• 普通存储（可按命名空间路由）：mcp__plugin_ruflo-core_ruflo__memory_store --namespace migrations，将校验结果关联到具体迁移编号。

CLI 等效查询：

npx @claude-flow/cli@latest memory search --query "migration validation results" --namespace migrations

migrate history — 查看完整迁移执行历史

history输出所有迁移的执行轨迹：

1. 回顾migrations命名空间中的全部条目；
2. 展示：编号、名称、方向（up/down）、时间戳、耗时、状态；
3. 高亮失败迁移，提示需要人工关注。

命名空间协调：为什么必须用 memory_* 工具族

本插件独占AgentDB 的migrations命名空间（与federation相同，插件名即意图时 kebab-case 隐含成立），遵循 ruflo-agentdb ADR-0001 §"Namespace convention" 的约定。三个保留命名空间（pattern、claude-memories、default）不得被遮蔽。

这里有一个容易踩坑的路由细节（也是 ADR-0001 — ruflo-migrations plugin contract 修复的核心 bug）：

• memory_*工具族（memory_store、memory_search、memory_list）按命名空间路由——传--namespace migrations即写入/读取migrations空间；
• agentdb_hierarchical-*与agentdb_pattern-*工具族分别按tier（working/episodic/semantic）与 ReasoningBank路由，会忽略命名空间字符串；
• 早期版本在 Skill 中对agentdb_hierarchical-*传命名空间参数，导致读写被静默忽略，这是 ADR-0001 记录的一类真实缺陷，与ruflo-cost-tracker、ruflo-market-data属同一 bug 类。

修复后两个 Skill 均已改为memory_*访问：migrate-create用memory_store --namespace migrations写元数据，migrate-validate用memory_search/memory_list --namespace migrations读历史。

迁移文件格式约定

迁移目录的标准形态（见 README.md）：

migrations/ 001_create_users.up.sql 001_create_users.down.sql 002_add_email_index.up.sql 002_add_email_index.down.sql

每个迁移编号对应一对 up/down 文件，保证任意时刻都可以正向推进或逆向回滚。

验证契约：smoke.sh

插件的可验证契约是 plugins/ruflo-migrations/scripts/smoke.sh，运行方式：

bash plugins/ruflo-migrations/scripts/smoke.sh # Expected: "10 passed, 0 failed"

10 项结构性检查覆盖（与 ADR-0001 的决策一一对应）：

1. plugin.json声明 v0.2.1 且包含mcp、dry-run、up-down-pairs关键词；
2. 两个 Skill + Agent + Command 均存在且 frontmatter 合法（name:/description:/allowed-tools:）；
3. migrate命令覆盖 6 个子命令（create/up/down/status/validate/history）；
4. migrate-create使用memory_store，不再残留agentdb_hierarchical-store ... migrations的错用模式；
5. migrate-validate使用memory_search/memory_list，不再残留agentdb_hierarchical-recall ... migrations；
6. migrate-validate文档化双路径（ReasoningBank +memory_store --namespace migrations）；
7. README 将 CLI 锁定在@claude-flow/cliv3.6 大版本；
8. README 引用 ruflo-agentdb 的命名空间约定；
9. ADR-0001 存在且状态为 Accepted；
10. Skill 的allowed-tools无通配符授权（安全底线）。

兼容性说明：插件将 CLI 锁定到 v3.6 的 major+minor（README.md Compatibility 节）。插件的验证机制即 smoke 契约，而非 package.json 版本钉扎——这正是 ruflo 生态"smoke-as-contract"的通用模式。

迁移 Agent：migration-engineer 的职责划分

插件内置的 migration-engineer Agent（模型 sonnet）承担五项职责：生成顺序编号迁移、创建 up/down 对、dry-run 预演、校验迁移（外键一致性、索引覆盖、数据类型兼容）、追踪迁移历史。它同时具备神经网络学习与记忆学习能力：

# 神经学习：任务成功后训练迁移模式 npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true npx @claude-flow/cli@latest neural train --pattern-type migrations --epochs 10 # 记忆学习：存储迁移模式与校验结果 npx @claude-flow/cli@latest memory store --namespace migrations --key "migration-NNN_NAME" --value "MIGRATION_METADATA_JSON" npx @claude-flow/cli@latest memory search --query "migrations adding foreign keys" --namespace migrations

生态协作

ruflo-migrations与周边插件形成 Schema 治理闭环（README.md Related Plugins）：

• ruflo-agentdb：命名空间约定的属主，本插件的路由规则即由其 ADR-0001 定义；
• ruflo-adr：将 Schema 变更决策记录为架构决策记录（ADR）；
• ruflo-ddd：让迁移边界与聚合根、限界上下文对齐；
• ruflo-observability：追踪迁移执行耗时与失败率；
• ruflo-security-audit：检查迁移中的 SQL 注入与权限提升风险（见 migration-engineer.md）。

小结

migrate命令为 Agent 驱动的数据库演进提供了完整闭环：create保证顺序与成对生成，up/down提供可预演、可回滚的执行路径，validate在落库前拦截外键断裂、缺失默认值等隐患，status/history让迁移状态全程可审计。而migrations命名空间 +memory_*工具族的路由约定，确保了迁移元数据在 Agent 长期记忆中的可靠持久化——这套设计既适合单 Agent 的开发场景，也能无缝嵌入多 Agent 协同的 ruflo 工作流。

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo