Metadata-Version: 2.1
Name: mongrade
Version: 0.1.0a17
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'

## checks弃用与切换门禁（a17候选补充，未发布）

- 已执行的revision允许原字节保留checks；verify/启动不执行它，诊断以deprecated_checks.applied列出版本。CommonLib启动记录一次警告，不因此阻止启动，不要求重算历史摘要。
- 未首次执行的revision只要存在checks字段（包括None或空列表）就不能执行。plan仍只读预览并列出deprecated_checks.pending；preflight/migrate在本批第一个revision写入前检查整个待执行范围。目标以外的未来脚本不阻断当前目标。
- 新脚本将必要验证写在upgrade/resume内部。作者发布前运行`mongrade validate --project mongrade/project.ini --revision-id <新版本>`，CommonLib作者角色对应`python migration.py --backend mongo validate --revision-id <新版本>`。必须明确指定版本，不拿全图离线校验强迫改写历史；此命令只校验静态元数据，不证明业务逻辑正确。
- 已中断的旧脚本同样不能改字节；若含checks，recover在新写入前拒绝，须先用原发行包恢复或由作者审核专项处理。没有running、仅需释放已完成版本的锁时不执行脚本，不适用首次执行门禁。
- 外部已完成的旧历史可经明确来源证明adopt登记，保留原脚本；adopt不执行这些revision，不能用停用checks替代外部完成证明。
- 不笼统禁止业务验证。只取消框架自动调度；必要检查应范围明确、按需使用索引，避免无意义计数和全量扫描。

> 🧭 **0.1.0a17本地候选，未发布**：版本管理仅依据迁移元数据；自动checks及业务快照退役，初始化统一走revision。兼容与切换要求见[指南](docs/guide.md)。

> 🔧 **0.1.0a16**：创建索引前转换列表键对，兼容 PyMongo3.7.1；不改 revision 摘要、键顺序、方向或索引选项，保留锁与恢复门禁。见[兼容说明](docs/guide.md#旧驱动的索引键对兼容010a16)。

> ⚡ **0.1.0a15**：无过滤数量后检达到精确判定上限即停止；过滤查询完整执行，账本、索引、锁与前后复核保持。详见[数量检查](docs/guide.md#数量检查的有限精确计数010a15)。

> 🏥 **0.1.0a14**：支持[显式空库初始化](docs/initialization.md)与可验证来源恢复；长任务等待策略可配置，提供结构化执行阶段事件，并加固计划摘要和准入会话。存量库 destructive 门禁保持。

> 🧪 **0.1.0a13**：已有业务集合或索引不再强制adopt；首次正常执行revision并登记历史，保留计划、锁、摘要、后检与恢复。外部旧完成记录仍由调用方核验并承接。

> ✅ **0.1.0a12已发布**：线上11组Windows/Linux/macOS兼容矩阵全部通过，GitHub/PyPI同批wheel与sdist已回下载核验。Collation创建、声明及simple等价后检见[指南](docs/guide.md)；准确发行证据见docs/release-0.1.0a12.json。下方旧版记录保留历史含义。

> 🔤 **0.1.0a12**：新增 collation 索引创建、声明校验与后检；省略字段和显式 simple 等价，保留非 simple 冲突及锁/恢复门禁。见 [Collation API](docs/guide.md#collation-索引010a12)。

> 🧭 多资源协议2为 **0.1.0a11未发布候选**，见[接口与兼容边界](docs/multi-resource.md)；正式a10状态及历史说明保留。

> **0.1.0a10 预览版已发布**：支持单字段普通索引的 `expireAfterSeconds=0..2147483647`，包括0；创建与声明共用校验，后检精确比较字段存在性及值。见 [TTL API](docs/guide.md#ttl-索引010a10)。

> ✅ **0.1.0a10已发布**：TTL创建与严格后检；Windows/Linux 18组本地安装矩阵通过，GitHub/PyPI同批制品已核验。Actions账单阻断，macOS本次未执行。正式回执见docs/release-0.1.0a10.json。

# Mongrade

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

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

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

## 安装和使用

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

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

## 项目初始化

a8起可用`mongrade init --database app_data`初始化；域、认证库和控制库默认业务库，省略资源声明管理全部业务集合（排除元数据/系统集合/声明的保留集合）。高级范围仍可显式配置。旧系统历史解释由调用方负责，工具不提供业务历史兼容或执行者清单。工具提供首个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.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)`；诊断不导入或执行脚本。完整格式和恢复边界见 [接入指南](docs/guide.md) 与 [设计](docs/design.md)。

## 边界

- a4起独立CLI/API不包含角色模型；CommonLib的author/deploy仅由migration.py实施。数据库写入仍须维护证据、锁和资源归属；a17的必要业务验证由upgrade/resume内部承担。
- 失败保留锁与运行状态，必须经过受审的恢复流程；没有自动降级或跨数据库原子事务。
- 迁移脚本是受信发布代码，上下文不是安全沙箱；禁止业务 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.0a8-py3-none-any.whl`。包体跨平台不代表 PyMongo 的二进制依赖可跨平台复用。

业务目录 `mongrade/` 与安装包同名但不是Python包：只放project.ini、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和非交互命令保持兼容。

副本集冷启动身份与旧成功账本的受控兼容路径见 [目标身份维护](docs/target-identity.md)；不自动改写既有历史或接管锁。
