mongrator 0.1.0__tar.gz

mongrator-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.3
+Name: mongrator
+Version: 0.1.0
+Summary: Lightweight MongoDB schema migration tool
+Author: Sasha Gerrand
+Author-email: Sasha Gerrand <mongrator@sgerrand.dev>
+Requires-Dist: pymongo>=4.10
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# mongrator
+
+[![CI](https://github.com/sgerrand/pymongrator/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/sgerrand/pymongrator/actions/workflows/ci.yml)
+
+Lightweight MongoDB schema migration tool with synchronous and asynchronous PyMongo support.
+
+## Installation
+
+```sh
+pip install mongrator
+```
+
+## Quick start
+
+```sh
+# Create config and migrations directory
+mongrator init
+
+# Generate a new migration file
+mongrator create add_users_email_index
+
+# Check migration status
+mongrator status
+
+# Apply pending migrations
+mongrator up
+
+# Roll back the last migration
+mongrator down
+```
+
+## Configuration
+
+`mongrator init` creates a `mongrator.toml` stub:
+
+```toml
+uri = "mongodb://localhost:27017"
+database = "mydb"
+migrations_dir = "migrations"
+collection = "mongrator_migrations"  # optional
+```
+
+Alternatively, configure via environment variables:
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `MONGRATOR_URI` | MongoDB connection URI | yes |
+| `MONGRATOR_DB` | Database name | yes |
+| `MONGRATOR_MIGRATIONS_DIR` | Path to migrations directory | no (default: `migrations`) |
+| `MONGRATOR_COLLECTION` | Tracking collection name | no (default: `mongrator_migrations`) |
+
+## Writing migrations
+
+Migration files are plain Python named `{timestamp}_{slug}.py` (e.g. `20260408_143022_add_users_email_index.py`). Each file must define an `up(db)` function. A `down(db)` function is optional but enables rollback.
+
+### Using the ops helpers (recommended)
+
+The `ops` helpers record their own inverses, so `down()` is generated automatically:
+
+```python
+from mongrator import ops
+
+def up(db):
+    return [
+        ops.create_index("users", {"email": 1}, unique=True),
+        ops.rename_field("users", "username", "handle"),
+        ops.add_field("users", "verified", default_value=False),
+    ]
+```
+
+### Using plain PyMongo
+
+For complex logic, write directly against the `db` argument and define `down()` manually:
+
+```python
+def up(db):
+    db["orders"].update_many(
+        {"status": {"$exists": False}},
+        {"$set": {"status": "pending"}},
+    )
+
+def down(db):
+    db["orders"].update_many({}, {"$unset": {"status": ""}})
+```
+
+### Available ops helpers
+
+| Helper | Reversible | Description |
+|--------|-----------|-------------|
+| `ops.create_index(collection, keys, **kwargs)` | yes | Create an index |
+| `ops.drop_index(collection, index_name)` | no | Drop an index by name |
+| `ops.rename_field(collection, old, new, filter=None)` | yes | Rename a field across documents |
+| `ops.add_field(collection, field, default_value, filter=None)` | yes | Add a field with a default value |
+
+## CLI reference
+
+```
+mongrator init                        create migrations dir and mongrator.toml
+mongrator create <name>               generate a new migration file
+mongrator status                      show applied/pending migrations
+mongrator up [--target ID]            apply pending migrations
+mongrator up --async [--target ID]    apply using async runner
+mongrator down [--steps N]            roll back N migrations (default: 1)
+mongrator down --async [--steps N]    roll back using async runner
+mongrator validate                    verify checksums of applied migrations
+mongrator --config PATH <command>     use an alternate config file
+```
+
+## Async usage
+
+Pass `--async` to `up` or `down` to use the async runner (backed by `pymongo.AsyncMongoClient`):
+
+```sh
+mongrator up --async
+```
+
+To use the runners programmatically:
+
+```python
+# Synchronous
+from pathlib import Path
+import pymongo
+from mongrator.config import MigratorConfig
+from mongrator.runner import SyncRunner
+
+config = MigratorConfig(uri="mongodb://localhost:27017", database="mydb", migrations_dir=Path("migrations"))
+runner = SyncRunner(pymongo.MongoClient(config.uri), config)
+runner.up()
+
+# Asynchronous
+from pymongo import AsyncMongoClient
+from mongrator.runner import AsyncRunner
+
+runner = AsyncRunner(AsyncMongoClient(config.uri), config)
+await runner.up()
+```
+
+## Migration tracking
+
+Applied migrations are recorded in the `mongrator_migrations` collection (configurable) within the target database. Each document stores:
+
+- `_id` — migration file stem
+- `applied_at` — UTC timestamp
+- `checksum` — SHA-256 of the migration file at time of application
+- `direction` — `"up"` or `"down"`
+- `duration_ms` — execution time in milliseconds
+
+Running `mongrator validate` compares current file checksums against recorded values and reports any modifications.

mongrator-0.1.0/README.md

@@ -0,0 +1,148 @@
+# mongrator
+
+[![CI](https://github.com/sgerrand/pymongrator/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/sgerrand/pymongrator/actions/workflows/ci.yml)
+
+Lightweight MongoDB schema migration tool with synchronous and asynchronous PyMongo support.
+
+## Installation
+
+```sh
+pip install mongrator
+```
+
+## Quick start
+
+```sh
+# Create config and migrations directory
+mongrator init
+
+# Generate a new migration file
+mongrator create add_users_email_index
+
+# Check migration status
+mongrator status
+
+# Apply pending migrations
+mongrator up
+
+# Roll back the last migration
+mongrator down
+```
+
+## Configuration
+
+`mongrator init` creates a `mongrator.toml` stub:
+
+```toml
+uri = "mongodb://localhost:27017"
+database = "mydb"
+migrations_dir = "migrations"
+collection = "mongrator_migrations"  # optional
+```
+
+Alternatively, configure via environment variables:
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `MONGRATOR_URI` | MongoDB connection URI | yes |
+| `MONGRATOR_DB` | Database name | yes |
+| `MONGRATOR_MIGRATIONS_DIR` | Path to migrations directory | no (default: `migrations`) |
+| `MONGRATOR_COLLECTION` | Tracking collection name | no (default: `mongrator_migrations`) |
+
+## Writing migrations
+
+Migration files are plain Python named `{timestamp}_{slug}.py` (e.g. `20260408_143022_add_users_email_index.py`). Each file must define an `up(db)` function. A `down(db)` function is optional but enables rollback.
+
+### Using the ops helpers (recommended)
+
+The `ops` helpers record their own inverses, so `down()` is generated automatically:
+
+```python
+from mongrator import ops
+
+def up(db):
+    return [
+        ops.create_index("users", {"email": 1}, unique=True),
+        ops.rename_field("users", "username", "handle"),
+        ops.add_field("users", "verified", default_value=False),
+    ]
+```
+
+### Using plain PyMongo
+
+For complex logic, write directly against the `db` argument and define `down()` manually:
+
+```python
+def up(db):
+    db["orders"].update_many(
+        {"status": {"$exists": False}},
+        {"$set": {"status": "pending"}},
+    )
+
+def down(db):
+    db["orders"].update_many({}, {"$unset": {"status": ""}})
+```
+
+### Available ops helpers
+
+| Helper | Reversible | Description |
+|--------|-----------|-------------|
+| `ops.create_index(collection, keys, **kwargs)` | yes | Create an index |
+| `ops.drop_index(collection, index_name)` | no | Drop an index by name |
+| `ops.rename_field(collection, old, new, filter=None)` | yes | Rename a field across documents |
+| `ops.add_field(collection, field, default_value, filter=None)` | yes | Add a field with a default value |
+
+## CLI reference
+
+```
+mongrator init                        create migrations dir and mongrator.toml
+mongrator create <name>               generate a new migration file
+mongrator status                      show applied/pending migrations
+mongrator up [--target ID]            apply pending migrations
+mongrator up --async [--target ID]    apply using async runner
+mongrator down [--steps N]            roll back N migrations (default: 1)
+mongrator down --async [--steps N]    roll back using async runner
+mongrator validate                    verify checksums of applied migrations
+mongrator --config PATH <command>     use an alternate config file
+```
+
+## Async usage
+
+Pass `--async` to `up` or `down` to use the async runner (backed by `pymongo.AsyncMongoClient`):
+
+```sh
+mongrator up --async
+```
+
+To use the runners programmatically:
+
+```python
+# Synchronous
+from pathlib import Path
+import pymongo
+from mongrator.config import MigratorConfig
+from mongrator.runner import SyncRunner
+
+config = MigratorConfig(uri="mongodb://localhost:27017", database="mydb", migrations_dir=Path("migrations"))
+runner = SyncRunner(pymongo.MongoClient(config.uri), config)
+runner.up()
+
+# Asynchronous
+from pymongo import AsyncMongoClient
+from mongrator.runner import AsyncRunner
+
+runner = AsyncRunner(AsyncMongoClient(config.uri), config)
+await runner.up()
+```
+
+## Migration tracking
+
+Applied migrations are recorded in the `mongrator_migrations` collection (configurable) within the target database. Each document stores:
+
+- `_id` — migration file stem
+- `applied_at` — UTC timestamp
+- `checksum` — SHA-256 of the migration file at time of application
+- `direction` — `"up"` or `"down"`
+- `duration_ms` — execution time in milliseconds
+
+Running `mongrator validate` compares current file checksums against recorded values and reports any modifications.

mongrator-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "mongrator"
+version = "0.1.0"
+description = "Lightweight MongoDB schema migration tool"
+readme = "README.md"
+authors = [
+    { name = "Sasha Gerrand", email = "mongrator@sgerrand.dev" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "pymongo>=4.10",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "testcontainers[mongodb]>=4.0",
+    "ty",
+    "ruff>=0.9",
+]
+
+[project.scripts]
+mongrator = "mongrator:main"
+
+[build-system]
+requires = ["uv_build>=0.8.20,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

mongrator-0.1.0/src/mongrator/__init__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+__all__ = ["main"]

mongrator-0.1.0/src/mongrator/_templates/migration.py.tmpl

@@ -0,0 +1,40 @@
+"""Migration: {slug}
+
+Generated by mongrator on {timestamp}.
+
+Use the ops helpers for common reversible operations, or write plain PyMongo
+calls directly against the `db` argument for anything more complex.
+
+Example using ops helpers (auto-rollback supported):
+
+    from mongrator import ops
+
+    def up(db):
+        return [
+            ops.create_index("my_collection", {{"field": 1}}, unique=True),
+        ]
+
+Example using plain PyMongo (define down() for rollback):
+
+    def up(db):
+        db["my_collection"].update_many({{}}, {{"$set": {{"new_field": None}}}})
+
+    def down(db):
+        db["my_collection"].update_many({{}}, {{"$unset": {{"new_field": ""}}}})
+"""
+
+
+# Uncomment to use the ops helpers:
+# from mongrator import ops
+
+
+def up(db):
+    pass
+    # return [
+    #     ops.create_index("my_collection", {{"field": 1}}),
+    # ]
+
+
+# def down(db):
+#     """Optional: define rollback logic here if not using ops helpers."""
+#     pass

mongrator-0.1.0/src/mongrator/cli.py

@@ -0,0 +1,256 @@
+"""Command-line interface for mongrator.
+
+Subcommands:
+    init     — create the migrations directory and a mongrator.toml stub
+    create   — generate a new timestamped migration file
+    status   — show applied/pending migration table
+    up       — apply pending migrations
+    down     — roll back applied migrations
+    validate — verify checksums of applied migrations
+"""
+
+import argparse
+import asyncio
+import sys
+from datetime import UTC, datetime
+from importlib.resources import files
+from pathlib import Path
+
+from .config import MigratorConfig
+from .exceptions import MigratorError
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mongrator",
+        description="Lightweight MongoDB schema migration tool",
+    )
+    parser.add_argument(
+        "--config",
+        metavar="PATH",
+        default="mongrator.toml",
+        help="path to config file (default: mongrator.toml)",
+    )
+
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    sub.required = True
+
+    # init
+    sub.add_parser("init", help="create migrations directory and config stub")
+
+    # create
+    p_create = sub.add_parser("create", help="generate a new migration file")
+    p_create.add_argument("name", help="short description, e.g. add_users_email_index")
+
+    # status
+    sub.add_parser("status", help="show applied/pending migration table")
+
+    # up
+    p_up = sub.add_parser("up", help="apply pending migrations")
+    p_up.add_argument("--target", metavar="ID", help="apply only up to this migration ID")
+    p_up.add_argument("--async", dest="use_async", action="store_true", help="use async runner")
+
+    # down
+    p_down = sub.add_parser("down", help="roll back applied migrations")
+    p_down.add_argument(
+        "--steps", type=int, default=1, metavar="N", help="number of migrations to roll back (default: 1)"
+    )
+    p_down.add_argument("--async", dest="use_async", action="store_true", help="use async runner")
+
+    # validate
+    sub.add_parser("validate", help="verify checksums of applied migration files")
+
+    return parser
+
+
+def _load_config(args: argparse.Namespace) -> MigratorConfig:
+    config_path = Path(args.config)
+    if config_path.exists():
+        return MigratorConfig.from_toml(config_path)
+    return MigratorConfig.from_env()
+
+
+# ---------------------------------------------------------------------------
+# Subcommand handlers
+# ---------------------------------------------------------------------------
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    config_path = Path(args.config)
+    if not config_path.exists():
+        config_path.write_text(
+            '[mongrator]\nuri = "mongodb://localhost:27017"\ndatabase = "mydb"\n'
+            'migrations_dir = "migrations"\ncollection = "mongrator_migrations"\n'
+        )
+        print(f"Created {config_path}")
+
+    migrations_dir = Path("migrations")
+    migrations_dir.mkdir(exist_ok=True)
+    print(f"Created {migrations_dir}/")
+    return 0
+
+
+def _cmd_create(args: argparse.Namespace) -> int:
+    config = _load_config(args)
+    config.migrations_dir.mkdir(parents=True, exist_ok=True)
+
+    slug = args.name.strip().replace(" ", "_").lower()
+    timestamp = datetime.now(tz=UTC).strftime("%Y%m%d_%H%M%S")
+    filename = f"{timestamp}_{slug}.py"
+    dest = config.migrations_dir / filename
+
+    template_text = files("mongrator._templates").joinpath("migration.py.tmpl").read_text(encoding="utf-8")
+    content = template_text.format(slug=slug, timestamp=timestamp)
+    dest.write_text(content, encoding="utf-8")
+    print(f"Created {dest}")
+    return 0
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    from .runner import SyncRunner
+
+    config = _load_config(args)
+    try:
+        import pymongo
+    except ImportError:
+        print("error: pymongo is required. Install with: pip install pymongo", file=sys.stderr)
+        return 1
+
+    client = pymongo.MongoClient(config.uri)
+    runner = SyncRunner(client, config)
+    statuses = runner.status()
+
+    if not statuses:
+        print("No migrations found.")
+        return 0
+
+    col_width = max(len(s.id) for s in statuses) + 2
+    print(f"{'Migration':<{col_width}} {'Status':<10} {'Applied At'}")
+    print("-" * (col_width + 30))
+    for s in statuses:
+        state = "applied" if s.applied else "pending"
+        if s.applied and not s.checksum_ok:
+            state = "MODIFIED"
+        applied_at = s.applied_at.isoformat() if s.applied_at else "-"
+        print(f"{s.id:<{col_width}} {state:<10} {applied_at}")
+    return 0
+
+
+def _cmd_up(args: argparse.Namespace) -> int:
+    config = _load_config(args)
+    if args.use_async:
+        return asyncio.run(_async_up(config, args.target))
+    import pymongo
+
+    from .runner import SyncRunner
+
+    client = pymongo.MongoClient(config.uri)
+    runner = SyncRunner(client, config)
+    applied = runner.up(target=args.target)
+    if applied:
+        for mid in applied:
+            print(f"  applied  {mid}")
+    else:
+        print("Nothing to apply.")
+    return 0
+
+
+async def _async_up(config: MigratorConfig, target: str | None) -> int:
+    from pymongo import AsyncMongoClient
+
+    from .runner import AsyncRunner
+
+    client = AsyncMongoClient(config.uri)
+    runner = AsyncRunner(client, config)
+    applied = await runner.up(target=target)
+    if applied:
+        for mid in applied:
+            print(f"  applied  {mid}")
+    else:
+        print("Nothing to apply.")
+    return 0
+
+
+def _cmd_down(args: argparse.Namespace) -> int:
+    config = _load_config(args)
+    if args.use_async:
+        return asyncio.run(_async_down(config, args.steps))
+    import pymongo
+
+    from .runner import SyncRunner
+
+    client = pymongo.MongoClient(config.uri)
+    runner = SyncRunner(client, config)
+    rolled_back = runner.down(steps=args.steps)
+    if rolled_back:
+        for mid in rolled_back:
+            print(f"  rolled back  {mid}")
+    else:
+        print("Nothing to roll back.")
+    return 0
+
+
+async def _async_down(config: MigratorConfig, steps: int) -> int:
+    from pymongo import AsyncMongoClient
+
+    from .runner import AsyncRunner
+
+    client = AsyncMongoClient(config.uri)
+    runner = AsyncRunner(client, config)
+    rolled_back = await runner.down(steps=steps)
+    if rolled_back:
+        for mid in rolled_back:
+            print(f"  rolled back  {mid}")
+    else:
+        print("Nothing to roll back.")
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    import pymongo
+
+    from .runner import SyncRunner
+
+    config = _load_config(args)
+    client = pymongo.MongoClient(config.uri)
+    runner = SyncRunner(client, config)
+    errors = runner.validate()
+
+    if not errors:
+        print("All applied migrations have valid checksums.")
+        return 0
+
+    eg = ExceptionGroup("Checksum mismatches detected", errors)
+    print(f"error: {eg}", file=sys.stderr)
+    for e in errors:
+        print(f"  {e}", file=sys.stderr)
+    return 1
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    dispatch = {
+        "init": _cmd_init,
+        "create": _cmd_create,
+        "status": _cmd_status,
+        "up": _cmd_up,
+        "down": _cmd_down,
+        "validate": _cmd_validate,
+    }
+
+    try:
+        rc = dispatch[args.command](args)
+    except MigratorError as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+    sys.exit(rc)

mongrator-0.1.0/src/mongrator/config.py

@@ -0,0 +1,61 @@
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Self
+
+from .exceptions import ConfigurationError
+
+_DEFAULT_COLLECTION = "mongrator_migrations"
+_DEFAULT_MIGRATIONS_DIR = Path("migrations")
+
+
+@dataclass(frozen=True)
+class MigratorConfig:
+    """Immutable configuration for a migrator instance."""
+
+    uri: str
+    database: str
+    migrations_dir: Path
+    collection: str = _DEFAULT_COLLECTION
+
+    @classmethod
+    def from_toml(cls, path: Path) -> Self:
+        """Load configuration from a TOML file (e.g. mongrator.toml)."""
+        try:
+            with open(path, "rb") as f:
+                data = tomllib.load(f)
+        except FileNotFoundError:
+            raise ConfigurationError(f"Config file not found: {path}")
+        except tomllib.TOMLDecodeError as e:
+            raise ConfigurationError(f"Invalid TOML in {path}: {e}")
+
+        try:
+            uri: str = data["uri"]
+            database: str = data["database"]
+        except KeyError as e:
+            raise ConfigurationError(f"Missing required config key: {e}")
+
+        migrations_dir = Path(data.get("migrations_dir", str(_DEFAULT_MIGRATIONS_DIR)))
+        collection: str = data.get("collection", _DEFAULT_COLLECTION)
+        return cls(uri=uri, database=database, migrations_dir=migrations_dir, collection=collection)
+
+    @classmethod
+    def from_env(cls) -> Self:
+        """Load configuration from environment variables.
+
+        Variables:
+            MONGRATOR_URI         — MongoDB connection URI (required)
+            MONGRATOR_DB          — database name (required)
+            MONGRATOR_MIGRATIONS_DIR — path to migrations directory (default: migrations)
+            MONGRATOR_COLLECTION  — tracking collection name (default: mongrator_migrations)
+        """
+        uri = os.environ.get("MONGRATOR_URI")
+        database = os.environ.get("MONGRATOR_DB")
+        if not uri:
+            raise ConfigurationError("MONGRATOR_URI environment variable is not set")
+        if not database:
+            raise ConfigurationError("MONGRATOR_DB environment variable is not set")
+        migrations_dir = Path(os.environ.get("MONGRATOR_MIGRATIONS_DIR", str(_DEFAULT_MIGRATIONS_DIR)))
+        collection = os.environ.get("MONGRATOR_COLLECTION", _DEFAULT_COLLECTION)
+        return cls(uri=uri, database=database, migrations_dir=migrations_dir, collection=collection)