Metadata-Version: 2.1
Name: mongrade
Version: 0.1.0a5
Summary: 轻量、可验证、可恢复的 MongoDB 版本迁移工具
Project-URL: Repository, https://github.com/deepaint-ai/mongrade
Keywords: mongodb,migration,pymongo,database
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: dev

# Mongrade

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

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

## 安装和使用

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

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

## 项目初始化（0.1.0a4）

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

## 公共 API

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

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

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

## 边界

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

## 开发与发布

```console
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；认证和首次发布设置见 [发布指南](docs/publishing.md)。仓库私有不代表 PyPI 包私有。许可证尚待所有者确定，本次迁移不擅自授予开源许可。

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

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

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

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