Metadata-Version: 2.5
Name: mongomig
Version: 0.1.0
Summary: Alembic-style schema evolution and migrations for MongoDB.
Project-URL: Homepage, https://github.com/anon-000/mongomig
Project-URL: Issues, https://github.com/anon-000/mongomig/issues
Author: aurosmruti
License-Expression: MIT
License-File: LICENSE
Keywords: alembic,fastapi,migrations,mongodb,pydantic,pymongo,schema
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.6
Requires-Dist: pymongo>=4.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: beanie
Requires-Dist: beanie>=1.26; extra == 'beanie'
Provides-Extra: dev
Requires-Dist: beanie>=1.26; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# MongoMig

**Alembic-style schema evolution and migrations for MongoDB.**

Change your models, see exactly what changed, generate a migration, review its impact, and
run it safely. Built for Python services (FastAPI, Flask, workers) on PyMongo or Beanie.

```console
$ mongomig diff
USERS
  + status: string = 'active'                    REQUIRES_DATA_MIGRATION  backfill existing documents with 'active'
  + age: int | null = None                       SAFE  defaults to None: existing documents need no backfill
  + given_name: string                           MANUAL_REVIEW  required, with no default: choose a value for existing documents
  - first_name                                   WARNING  removed from the model; existing data is kept (not deleted)
  + index users_email_unique (email ↑, unique)   WARNING  fails if existing documents contain duplicates

Possible rename: users.first_name → given_name (85% similar). If so, pass --rename users.first_name:given_name

$ mongomig revision --autogenerate -m "evolve users" --rename users.first_name:given_name
Generated b91baf4fd592 → migrations/versions/20260925_1115_b91baf4fd592_evolve_users.py

$ mongomig plan
b91baf4fd592  evolve users   Risk: HIGH
  users  rename_field  $rename first_name           ~4,218,901 docs · collection scan
  users  backfill      $set status                  ~4,218,901 docs · collection scan
  users  create_index  users_email_unique (unique)  4,218,901 docs
         ⚠ will fail: duplicate values exist, e.g. {'email': 'sam@example.com'}

$ mongomig upgrade
```

## Why MongoMig

- **Autogenerate from your models**: plain Pydantic (`@collection`) or Beanie documents, no
  extra declarations. Backfills with your defaults, renames, indexes, `$jsonSchema` validators.
- **Every change is classified**: SAFE, WARNING, REQUIRES_DATA_MIGRATION or MANUAL_REVIEW.
  Risky changes become commented `TODO(review)` blocks, and data is never deleted
  automatically.
- **Deterministic diffs**: models are compared with a committed schema snapshot rather than a
  sampled database, so results are the same on every machine and in CI.
- **Knows how you store data**: `model_dump()` vs `jsonable_encoder` stores dates as different
  BSON types, and MongoMig warns about types PyMongo can't store.
- **Production-grade execution**: distributed lock, idempotent batched operations with
  progress and ETA, retries, failure tracking, checksums, confirmation before destructive
  migrations, and restorable backups.
- **See the impact first**: `plan` / `--dry-run` estimate documents touched and collection
  scans, and predict unique-index failures and validator rejections against real data.
- **Built for CI**: `mongomig validate`, `--json` output everywhere, documented exit codes.

## Install

```bash
pip install mongomig            # add [beanie] for Beanie support
```

Python 3.11+, MongoDB 6.0+ (tested on 6.0, 7.0, 8.0).

## Quick start

```bash
mongomig init                                   # mongomig.yaml + migrations/
export MONGODB_URI="mongodb://localhost:27017"
# register your models in migrations/env.py (see below), then:
mongomig revision --autogenerate -m "initial"   # new project
mongomig baseline                               # ...or an existing database
mongomig upgrade
```

```python
# app/models.py
from pydantic import BaseModel
from mongomig import collection, Index

@collection("users", indexes=[Index("email", unique=True)])
class User(BaseModel):
    name: str
    email: str
    status: str = "active"
```

```python
# migrations/env.py
from mongomig import MongoMetadata

import app.models  # noqa: F401

target_metadata = MongoMetadata.default(storage="python")   # or "json"; Beanie: register_beanie(...)
```

**Everyday loop:** edit models → `mongomig diff` → `mongomig revision --autogenerate -m "..."` →
review and commit → CI `mongomig validate` → deploy `mongomig plan` + `mongomig upgrade`.

## Documentation

- [Getting started](docs/getting-started.md)
- [Concepts](docs/concepts.md): snapshots, storage profiles, classifications
- [Writing migrations](docs/writing-migrations.md): `ctx` and `ctx.ops` reference
- [Autogenerate](docs/autogenerate.md): what gets generated and how to review it
- [Production guide](docs/production.md): permissions, plan, locking, backups, recovery
- [CLI reference](docs/cli.md) · [Python API](docs/python-api.md) ·
  [Troubleshooting](docs/troubleshooting.md)

Examples: [FastAPI + Pydantic](examples/fastapi_pydantic) ·
[FastAPI + Beanie](examples/fastapi_beanie)

## Status

The MVP is complete (config, revisions, upgrade/downgrade, schema inspection, diff,
autogenerate, plan/dry-run, locking, batching, backups, CI checks). Planned next: drift
detection (models vs live data), resumable checkpoints, transaction helpers, migration
squashing.

## Development

```bash
make install        # uv venv + editable install with dev extras
make mongo-up       # MongoDB 7 single-node replica set in Docker
make check          # ruff + mypy --strict + pytest
```

Integration tests skip when MongoDB isn't running. To test another MongoDB version, run
`MONGO_VERSION=8.0 make mongo-up`.

### Releasing

1. Bump `src/mongomig/_version.py` and update `CHANGELOG.md`, then merge to `main`.
2. Create a GitHub Release with tag `v<version>` and publish it. The release workflow checks the
   version, builds and smoke-tests the wheel, and publishes to PyPI via Trusted Publishing.

## License

MIT
