Metadata-Version: 2.1
Name: mongrade
Version: 0.1.0a2
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
Requires-Dist: pymongo <5,>=3.7.1
Provides-Extra: dev
Requires-Dist: build ==0.10.0 ; extra == 'dev'
Requires-Dist: mypy ==1.4.1 ; extra == 'dev'
Requires-Dist: pytest ==7.4.4 ; extra == 'dev'
Requires-Dist: ruff ==0.8.6 ; extra == 'dev'

# Mongrade

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

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

## 安装和使用

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

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

## 公共 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)。

## 边界

- 默认部署角色；生成模板必须显式使用 `--role author`。适配器注入角色后不允许命令行提升角色。
- 失败保留锁与运行状态，必须经过受审的恢复流程；没有自动降级或跨数据库原子事务。
- 迁移脚本是受信发布代码，上下文不是安全沙箱；禁止业务 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.0a2-py3-none-any.whl`。包体跨平台不代表 PyMongo 的二进制依赖可跨平台复用。

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