Mongrade

轻量、可验证、可恢复的 MongoDB 版本化迁移工具。

Mongrade 使用 PyMongo，最低支持 Python 3.7。引擎独立于服务框架，提供单链版本管理、静态迁移计划、并发互斥、后置验证、checkpoint 恢复及旧库显式承接。它是纯 Python 包，目标制品为 py3-none-any wheel 和 sdist。

本次版本为 0.1.0a6 预览版，配置使用 project.ini。a5及更早版本使用JSON项目配置，请查看对应tag；不要用a5运行本文INI示例。

安装和使用

python -m pip install mongrade==0.1.0a6
mongrade --version
mongrade graph
mongrade diagnose
mongrade plan --evidence files/maintenance.json

本次预览版本为 0.1.0a6，默认业务迁移目录为 mongrade/；离线环境使用经过校验的wheel。已发布的0.1.0a1仍使用旧目录。预览版不承诺生产就绪。python -m mongrade 与控制台入口相同。连接通过运行时环境变量 MONGRADE_URI 注入，URI 必须声明与项目一致的业务库及 authSource；不要将凭据写入项目或日志。

项目初始化（0.1.0a4）

工具提供通用init、首个root/后续revision创建；交互由CommonLib migration.py提供；公开a3不包含这些能力。初始化不连接数据库，显式配置目标和归属，不覆盖已有目录。详见项目初始化指南。业务部署仍需完整非空版本链、受审计划和显式迁移，不由公共升级器生成或激活。

公共 API

from mongrade import connect, load_catalog, plan, migrate, verify

catalog = load_catalog("mongrade/project.ini")
with connect(uri, catalog) as client:
    approved = plan(client, catalog, evidence=evidence)
    # 在独立的发布审核阶段固定 approved.sha256 及本次维护材料。
    migrate(client, catalog, approved, evidence)
    verify(client, catalog)

业务服务自行发布 mongrade/project.ini 和 versions/，脚本实现 upgrade(context)；诊断不导入或执行脚本。完整格式和恢复边界见 接入指南 与 设计。

边界

• a4起独立CLI/API不包含角色模型；CommonLib的author/deploy仅由migration.py实施。维护证据、锁、资源归属及后检仍是数据库写入前提。
• 失败保留锁与运行状态，必须经过受审的恢复流程；没有自动降级或跨数据库原子事务。
• 迁移脚本是受信发布代码，上下文不是安全沙箱；禁止业务 HTTP、UAC、DataSearch、MQ 调用。
• 首版拒绝多物理业务库和分片写入，备份恢复材料由 DBA 审核，引擎复核文件摘要、时效及范围。
• 本包不包含 CommonLib 的 SQL 后端、服务启动器或混合数据库部署编排。

开发与发布

python -m pip install ".[dev]"
python -m pytest
python -m ruff format --check src test
python -m ruff check src test
python -m mypy
python -m build

使用独立虚拟环境，测试临时产物统一写入 tmp/。发布工作流检出Release（含预发布）对应 tag，版本检查、质量检查、构建和兼容性验证全部通过后，先将同一批 wheel/sdist 上传到当次 GitHub Release，再上传 PyPI；认证和首次发布设置见 发布指南。仓库私有不代表 PyPI 包私有。许可证尚待所有者确定，本次迁移不擅自授予开源许可。

离线部署应预先为目标解释器和操作系统准备 PyMongo 依赖；已有匹配依赖时可用 python -m pip install --no-index --no-deps ./mongrade-0.1.0a4-py3-none-any.whl。包体跨平台不代表 PyMongo 的二进制依赖可跨平台复用。

业务目录 mongrade/ 与安装包同名但不是Python包：只放project.ini、versions和迁移材料，不放 __init__.py 或 __main__.py，不要把它加入PYTHONPATH。CLI仍从服务根目录运行，不切换进该目录；不自动发现或回退旧mongo_migrations目录。

项目配置使用format=2，默认元数据集合为 _mongrade，内部区分coordination与domain:<域>文档。旧两集合状态不可直接改名；显式切换、执行权确认及恢复见元数据切换指南。

0.1.0a5移除内置TUI，仅保留Python API和非交互CLI。菜单、输入、纠错、展示及服务角色均由CommonLib migration.py负责；a4历史行为见对应tag文档。升级前请调整原有mongrade tui调用；API和非交互命令保持兼容。