MongoDB迁移工具

蒙古人

一个轻量级的MongoDB迁移引擎、CLI和MCP就绪工具集，可让您保持迁移、更改流和脚本操作与集群同步。二进制文件显示为 mongo （别名 mmo, mt，以及 mmt)因此，您可以使用单个可执行文件运行status、up/down和oplog命令。

亮点

• 状态迁移引擎： 分布式锁定、校验和验证和平滑 Up/Down 流使模式注册表在团队之间保持同步。
• Mongo命令行界面： mongo 封装了迁移引擎以及模式、oplog和MCP帮助程序。这 oplog --follow --resume-file flag将恢复令牌保存到磁盘，这样您在网络故障期间就不会丢失事件。
• 泡泡茶控制台： mongo ui 为您提供了一个交互式仪表板，用于迁移时间线、实时流事件、MCP活动和剧本检查点。
• MCP桥： CLI可以作为MCP服务器运行(mongo mcp --with-examples)因此，AI代理可以查询迁移状态或为您申请工作。
• 零停机剧本： examples/practical/... 提供多阶段扩展/收缩场景（添加列、重命名字段、拆分集合、目录回填），包括批处理、检查点和README指南。

安装

1. 自制（macOS/Linux） – brew tap drewjocham/mongork 然后 brew install mongo.
2. 码头工人 – docker pull ghcr.io/drewjocham/mongork:latest 并运行 docker run --rm -v "$(pwd)":/workspace ghcr.io/drewjocham/mongork:latest --help.
3. Go工具（开发） – go install github.com/drewjocham/mongork/cmd@latest.

需要更多设置帮助？看 install.md.

快速开始

1. 复制 .env.example 到 .env 并配置 MONGO_URL、凭据和覆盖 MONGO_DATABASE/MIGRATIONS_COLLECTION.
2. 跑 mongo status, mongo up，或 mongo down --target <version> 检查和改进您的模式。
3. 尾部迁移 mongo oplog --follow --resume-file /tmp/oplog.tokenCLI将最后一次看到的恢复令牌保存在磁盘上，因此重新连接永远不会跳过oplog间隙。
4. 使用以下命令启动MCP端点 mongo mcp （添加 --with-examples 以播种样品迁移）。
5. 启动泡泡茶界面 mongo ui （别名： mongo tui, mongo bubbletea).

如何使用

1） 安全运行迁移

• 检查当前状态：
  • mongo status
• 执行前预览更改：
  • mongo up --dry-run
  • mongo down --dry-run --target <version>
• 应用或回滚：
  • mongo up
  • mongo down --target <version>

2） 尾部实时变化而不丢失位置

• 使用持久恢复令牌启动直播流：
  • mongo oplog --follow --resume-file /tmp/oplog.token
• 重新启动相同的命令将从保存的令牌中恢复。

3） 使用交互式Bubble Tea仪表板

• 启动：
  • mongo ui --resume-file .mongork.resume
  • mongo ui --help-keys （打印密钥绑定而不启动TUI）
• 全局控制：
  • TAB / SHIFT+TAB 切换选项卡
  • h / l 切换选项卡
  • 1 / 2 / 3 / 4 直接跳转到选项卡
  • R 立即强制刷新
  • ? 切换应用程序内热键帮助面板
  • q 退出
• 迁移选项卡：
  • ↑/↓ 或 j/k 选择迁移
  • g / G 跳到第一次/最后一次迁移
  • r 启动所选应用迁移的回滚确认
  • y 确认回滚， n/esc 取消
• 实时流选项卡：
  • ↑/↓ 或 j/k 选择事件
  • g / G 跳到第一个/最后一个事件
  • p 暂停/恢复流更新
  • i/u/d 切换插入/更新/删除筛选器
  • enter 切换JSON检查器模式
• 播放手册选项卡：
  • K 设置停车信号 migration_control

4） 启动人工智能工具的MCP模式

• 启动MCP服务器：
  • mongo mcp
• 种子实验示例：
  • mongo mcp --with-examples

CLI概述

命令	目的
mongo status	显示迁移状态和时间戳。
mongo up	应用挂起的迁移（使用 --dry-run 预览）。
mongo down	回滚迁移(--target 限制了距离）。
mongo create <name>	构建一个新的迁移存根。
mongo oplog	查询和尾部更改流事件（使用 --resume-file 以持久化令牌）。
mongo ui	打开交互式Bubble Tea仪表板，查看迁移、流活动和剧本状态。
mongo schema indexes	打印在Go中注册的架构索引。
mongo schema diff	将注册的索引/验证器与实时MongoDB进行比较。
mongo mcp	启动模型上下文协议服务器。

建筑工具箱

• 发动机 管理分布式锁，通过注册应用迁移 migration.Migration 实现，并跟踪Mongo迁移集合中的版本。
• 处理器 在 cmd/examples 和 internal/mcp 展示了如何对脚本工作进行批处理，例如 ReassignAssets.
• CLI 公开这些功能，使用磁盘支持的令牌恢复oplog尾部，并为AI工具提供MCP端点。

文件

• 顶级文档 – doc.go 包含为文档部分提供信息的叙述 pkg.go.dev。每次添加概念时都要保持更新，以便生成的文档部分保持准确。
• 图书馆指南 – library.md 展示了如何将迁移引擎嵌入到另一个Go项目中。
• MCP指南 – mcp.md 解释了如何连接MCP服务器和注册AI工具。
• MCP架构 – docs/mcp-architecture.md 记录MCP生命周期、锁管理和故障恢复图。
• 贡献与测试 – contributing.md 文档工作流、发布步骤以及如何运行 make lint, make test，以及 make integration-test.
• 安装 – install.md 详细介绍特定于平台的安装、Docker组合设置以及每个支持的入口点。

支持与社区

• 问题/功能请求： github/drewjocham/mongork/oissues
• RFC和讨论： github/drewjocham/mongork/讨论
• 迁移示例： internal/migrations/

许可证

MIT。看 许可证.