mongomig 0.1.0.dev0__py3-none-any.whl

mongomig/__init__.py

@@ -0,0 +1,26 @@
+"""MongoMig — Alembic-style schema evolution and migrations for MongoDB."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from mongomig._version import __version__
+
+if TYPE_CHECKING:
+    from mongomig.errors import MongoMigError
+
+__all__ = ["MongoMigError", "__version__"]
+
+# Public names are resolved lazily so `import mongomig` (and the CLI) stays fast.
+_LAZY: dict[str, str] = {
+    "MongoMigError": "mongomig.errors",
+}
+
+
+def __getattr__(name: str) -> Any:
+    module_path = _LAZY.get(name)
+    if module_path is None:
+        raise AttributeError(f"module 'mongomig' has no attribute {name!r}")
+    import importlib
+
+    return getattr(importlib.import_module(module_path), name)

mongomig/__main__.py

@@ -0,0 +1,4 @@
+from mongomig.cli.app import main
+
+if __name__ == "__main__":
+    main()

mongomig/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0.dev0"

mongomig/cli/app.py

@@ -0,0 +1,135 @@
+"""CLI entry point.
+
+Only the command *signatures* live here. Each implementation is in ``cli/commands/<name>.py``
+and is imported when the command runs, keeping ``mongomig --help`` fast.
+"""
+
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from mongomig._version import __version__
+from mongomig.cli.context import GlobalOptions
+
+app = typer.Typer(
+    name="mongomig",
+    help="Alembic-style schema evolution and migrations for MongoDB.",
+    no_args_is_help=True,
+    add_completion=False,
+    pretty_exceptions_enable=False,
+    rich_markup_mode=None,
+)
+
+JsonOpt = Annotated[bool, typer.Option("--json", help="Machine-readable JSON output.")]
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"mongomig {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _global(
+    ctx: typer.Context,
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            "-c",
+            envvar="MONGOMIG_CONFIG",
+            help="Path to mongomig.yaml.",
+            dir_okay=False,
+        ),
+    ] = None,
+    env: Annotated[
+        str | None,
+        typer.Option(
+            "--env",
+            "-e",
+            envvar="MONGOMIG_ENV",
+            help="Environment overlay to apply (mongomig.<env>.yaml).",
+        ),
+    ] = None,
+    json_: JsonOpt = False,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="More detail.")] = False,
+    _version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_version_callback, is_eager=True, help="Show version and exit."
+        ),
+    ] = False,
+) -> None:
+    ctx.obj = GlobalOptions(config=config, env=env, json=json_, verbose=verbose)
+
+
+def _run(ctx: typer.Context, command: str, *, json_: bool = False, **kwargs: Any) -> None:
+    from mongomig.errors import MongoMigError
+    from mongomig.output.console import Output
+
+    opts: GlobalOptions = ctx.obj
+    out = Output(json_mode=opts.json or json_, verbose=opts.verbose)
+    module = importlib.import_module(f"mongomig.cli.commands.{command}")
+    try:
+        module.run(opts, out, **kwargs)
+    except MongoMigError as err:
+        out.error(err)
+        raise typer.Exit(int(err.exit_code)) from None
+
+
+@app.command()
+def init(
+    ctx: typer.Context,
+    directory: Annotated[
+        Path, typer.Argument(help="Project directory to initialise.", file_okay=False)
+    ] = Path("."),
+    migrations_dir: Annotated[
+        str, typer.Option("--migrations-dir", help="Name of the migrations directory.")
+    ] = "migrations",
+    json_: JsonOpt = False,
+) -> None:
+    """Create mongomig.yaml and the migrations/ directory."""
+    _run(ctx, "init", json_=json_, directory=directory, migrations_dir=migrations_dir)
+
+
+@app.command()
+def revision(
+    ctx: typer.Context,
+    message: Annotated[str, typer.Option("--message", "-m", help="Short description.")],
+    head: Annotated[
+        str | None,
+        typer.Option("--head", help="Parent revision (required when there are several heads)."),
+    ] = None,
+    rev_id: Annotated[
+        str | None, typer.Option("--rev-id", help="Use this revision id instead of a random one.")
+    ] = None,
+    json_: JsonOpt = False,
+) -> None:
+    """Create a new, empty revision file."""
+    _run(ctx, "revision", json_=json_, message=message, head=head, rev_id=rev_id)
+
+
+@app.command()
+def heads(ctx: typer.Context, json_: JsonOpt = False) -> None:
+    """Show the head revision(s)."""
+    _run(ctx, "heads", json_=json_)
+
+
+@app.command()
+def history(ctx: typer.Context, json_: JsonOpt = False) -> None:
+    """List all revisions, newest first."""
+    _run(ctx, "history", json_=json_)
+
+
+@app.command()
+def current(ctx: typer.Context, json_: JsonOpt = False) -> None:
+    """Show which revisions are applied to the database, and what is pending."""
+    _run(ctx, "current", json_=json_)
+
+
+def main() -> None:
+    app()

mongomig/cli/commands/current.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mongomig.cli.context import GlobalOptions, load_config, load_graph
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from mongomig.output.console import Output
+
+
+def run(opts: GlobalOptions, out: Output) -> None:
+    from mongomig.database.client import create_client, get_database, ping
+    from mongomig.migrations.tracker import MigrationTracker, compute_state
+
+    config = load_config(opts, out)
+    graph = load_graph(config)
+
+    client = create_client(config)
+    try:
+        ping(client, config)
+        db = get_database(client, config)
+        # Read-only: never creates the tracking collection.
+        tracker = MigrationTracker(db, config.settings.migrations.tracking_collection)
+        records = tracker.records()
+    finally:
+        client.close()
+
+    state = compute_state(graph, records)
+
+    def describe(rev: str) -> dict[str, str]:
+        script = graph.scripts.get(rev)
+        return {"revision": rev, "message": script.message if script else ""}
+
+    current = [describe(r) for r in state.applied_heads]
+    pending = [describe(r) for r in state.pending]
+    data = {
+        "database": db.name,
+        "environment": config.environment,
+        "current": current,
+        "pending": pending,
+        "failed": state.failed,
+        "unknown": state.unknown,
+    }
+
+    def render(con: Console) -> None:
+        env = f" [dim]({config.environment})[/dim]" if config.environment else ""
+        con.print(f"Database: [bold]{db.name}[/bold]{env}")
+        if state.applied_heads:
+            for item in current:
+                con.print(f"Current:  [bold]{item['revision']}[/bold]  {item['message']}")
+        else:
+            con.print("Current:  [dim]<base> (no revisions applied)[/dim]")
+
+        if state.pending:
+            con.print(f"Pending:  [yellow]{len(state.pending)}[/yellow]")
+            for item in pending:
+                con.print(f"  - {item['revision']}  {item['message']}")
+        else:
+            con.print("Pending:  [green]none — up to date[/green]")
+
+        for rev in state.failed:
+            con.print(f"[red]Failed:[/red]   {rev} (last run did not complete)")
+        if state.unknown:
+            con.print(
+                f"[yellow]Unknown:[/yellow]  {', '.join(state.unknown)} "
+                "— applied in the database but no revision file here. "
+                "Is this code older than the database?"
+            )
+
+    out.result(data, render)

mongomig/cli/commands/heads.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mongomig.cli.context import GlobalOptions, load_config, load_graph, relpath
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from mongomig.output.console import Output
+
+
+def run(opts: GlobalOptions, out: Output) -> None:
+    config = load_config(opts, out)
+    graph = load_graph(config)
+    heads = graph.heads()
+    data = [
+        {
+            "revision": rev,
+            "message": graph.scripts[rev].message,
+            "path": relpath(graph.scripts[rev].path, config),
+        }
+        for rev in heads
+    ]
+
+    def render(con: Console) -> None:
+        if not heads:
+            con.print('No revisions yet. Create one with: mongomig revision -m "initial"')
+            return
+        for item in data:
+            con.print(f"[bold]{item['revision']}[/bold] (head)  {item['message']}")
+            if out.verbose:
+                con.print(f"  [dim]{item['path']}[/dim]")
+        if len(heads) > 1:
+            con.print(
+                f"\n[yellow]{len(heads)} heads:[/yellow] the history has diverged "
+                "(e.g. two branches each added a revision). Merge them before upgrading."
+            )
+
+    out.result({"heads": data}, render)

mongomig/cli/commands/history.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from mongomig.cli.context import GlobalOptions, load_config, load_graph, relpath
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from mongomig.output.console import Output
+
+
+def run(opts: GlobalOptions, out: Output) -> None:
+    config = load_config(opts, out)
+    graph = load_graph(config)
+    heads = set(graph.heads())
+
+    data: list[dict[str, Any]] = []
+    for rev in reversed(graph.topological_order()):
+        script = graph.scripts[rev]
+        data.append(
+            {
+                "revision": rev,
+                "down_revisions": list(script.down_revisions),
+                "message": script.message,
+                "is_head": rev in heads,
+                "is_base": script.is_base,
+                "is_merge": script.is_merge,
+                "reversible": script.reversible,
+                "path": relpath(script.path, config),
+            }
+        )
+
+    def render(con: Console) -> None:
+        if not data:
+            con.print("No revisions yet.")
+            return
+        for item in data:
+            parents = ", ".join(item["down_revisions"]) or "<base>"
+            tags = [t for t, on in (("head", item["is_head"]), ("merge", item["is_merge"])) if on]
+            if not item["reversible"]:
+                tags.append("irreversible")
+            tag_text = f" [cyan]({', '.join(tags)})[/cyan]" if tags else ""
+            con.print(f"{parents} -> [bold]{item['revision']}[/bold]{tag_text}, {item['message']}")
+            if out.verbose:
+                con.print(f"    [dim]{item['path']}[/dim]")
+
+    out.result({"revisions": data}, render)

mongomig/cli/commands/init.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import re
+from importlib.resources import files
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from mongomig.cli.context import GlobalOptions
+from mongomig.config.models import (
+    DEFAULT_CONFIG_FILENAME,
+    ENV_FILENAME,
+    SNAPSHOT_FILENAME,
+    VERSIONS_DIRNAME,
+)
+from mongomig.errors import ConfigError
+from mongomig.schema.snapshot import canonical_json, empty_snapshot
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from mongomig.output.console import Output
+
+_DIR_NAME_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_.-]*$")
+
+
+def _template(name: str) -> str:
+    return files("mongomig").joinpath(f"templates/{name}").read_text(encoding="utf-8")
+
+
+def run(opts: GlobalOptions, out: Output, *, directory: Path, migrations_dir: str) -> None:
+    if not _DIR_NAME_RE.match(migrations_dir):
+        raise ConfigError(
+            f"Invalid migrations directory name {migrations_dir!r}.",
+            suggestion="Use a simple directory name such as 'migrations'.",
+        )
+    root = directory.expanduser().resolve()
+    mig = root / migrations_dir
+    planned: dict[Path, str | None] = {
+        root / DEFAULT_CONFIG_FILENAME: _template("mongomig.yaml.tmpl").replace(
+            "{{migrations_dir}}", migrations_dir
+        ),
+        mig / ENV_FILENAME: _template("env.py.tmpl"),
+        mig / SNAPSHOT_FILENAME: canonical_json(empty_snapshot()),
+        mig / VERSIONS_DIRNAME / ".gitkeep": "",
+    }
+
+    existing = [p for p in planned if p.exists()]
+    if existing:
+        raise ConfigError(
+            "MongoMig is already initialised here: "
+            + ", ".join(str(p.relative_to(root)) for p in existing),
+            suggestion="Remove those files first if you really want to start over.",
+        )
+
+    for path, content in planned.items():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content or "", encoding="utf-8")
+
+    created = [str(p.relative_to(root)) for p in planned if p.name != ".gitkeep"]
+    created.insert(3, f"{migrations_dir}/{VERSIONS_DIRNAME}/")
+
+    def render(con: Console) -> None:
+        con.print(f"[green]Initialised MongoMig in[/green] {root}")
+        for item in created:
+            con.print(f"  [green]+[/green] {item}")
+        con.print("\nNext steps:")
+        con.print("  1. export MONGODB_URI=mongodb://localhost:27017")
+        con.print('  2. mongomig revision -m "initial"')
+        con.print("  3. mongomig current")
+
+    out.result({"root": str(root), "created": created}, render)

mongomig/cli/commands/revision.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mongomig.cli.context import GlobalOptions, load_config, load_graph, relpath
+from mongomig.errors import RevisionConflictError
+from mongomig.migrations.revision import write_revision
+from mongomig.schema.snapshot import snapshot_hash
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from mongomig.output.console import Output
+
+
+def run(
+    opts: GlobalOptions, out: Output, *, message: str, head: str | None, rev_id: str | None
+) -> None:
+    config = load_config(opts, out)
+    graph = load_graph(config)
+
+    parent = graph.resolve(head) if head else graph.single_head()
+    if head and parent is not None and graph.children[parent]:
+        out.warn(f"{parent} already has children; this creates a new branch (a second head).")
+    if rev_id and rev_id in graph:
+        raise RevisionConflictError(f"Revision id {rev_id!r} already exists.")
+
+    new_id, path = write_revision(
+        config.versions_dir,
+        message=message,
+        down_revision=parent,
+        snapshot_hash=snapshot_hash(config.snapshot_path),
+        rev_id=rev_id,
+    )
+    shown = relpath(path, config)
+
+    def render(con: Console) -> None:
+        con.print(f"[green]Created revision[/green] [bold]{new_id}[/bold] → {shown}")
+        con.print(f"  revises: {parent or '<base>'}")
+
+    out.result({"revision": new_id, "down_revision": parent, "path": shown}, render)

mongomig/cli/context.py

@@ -0,0 +1,47 @@
+"""State shared by all commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mongomig.config.models import LoadedConfig
+    from mongomig.migrations.graph import RevisionGraph
+    from mongomig.output.console import Output
+
+
+@dataclass(frozen=True)
+class GlobalOptions:
+    config: Path | None = None
+    env: str | None = None
+    json: bool = False
+    verbose: bool = False
+
+
+def load_config(opts: GlobalOptions, out: Output) -> LoadedConfig:
+    from mongomig.config.loader import load_config as _load
+
+    config = _load(opts.config, environment=opts.env)
+    for warning in config.warnings:
+        out.warn(warning)
+    out.info(
+        f"config: {config.config_path}"
+        + (f" (environment: {config.environment})" if config.environment else "")
+    )
+    return config
+
+
+def load_graph(config: LoadedConfig) -> RevisionGraph:
+    from mongomig.migrations.graph import RevisionGraph
+    from mongomig.migrations.script import load_scripts
+
+    return RevisionGraph(load_scripts(config.versions_dir))
+
+
+def relpath(path: Path, config: LoadedConfig) -> str:
+    try:
+        return str(path.relative_to(config.root_dir))
+    except ValueError:
+        return str(path)

mongomig/config/envpy.py

@@ -0,0 +1,58 @@
+"""Load the project's ``migrations/env.py`` and read ``target_metadata`` from it."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+import traceback
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from mongomig.config.models import LoadedConfig
+from mongomig.errors import ConfigError
+
+ENV_MODULE_NAME = "_mongomig_env"
+
+
+def load_env_module(path: Path, project_root: Path) -> ModuleType:
+    """Execute ``env.py`` as a fresh module with ``project_root`` importable.
+
+    The project root goes on ``sys.path`` so ``import app.models`` works from env.py, the same
+    way Alembic's env.py imports application code.
+    """
+    if not path.is_file():
+        raise ConfigError(
+            f"{path.name} not found at {path}",
+            suggestion="Run `mongomig init` or restore migrations/env.py.",
+        )
+    root = str(project_root)
+    if root not in sys.path:
+        sys.path.insert(0, root)
+
+    spec = importlib.util.spec_from_file_location(ENV_MODULE_NAME, path)
+    if spec is None or spec.loader is None:
+        raise ConfigError(f"Cannot load {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[ENV_MODULE_NAME] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception as exc:
+        sys.modules.pop(ENV_MODULE_NAME, None)
+        last = traceback.extract_tb(exc.__traceback__)[-1]
+        raise ConfigError(
+            f"Error while executing {path.name}: {type(exc).__name__}: {exc}",
+            suggestion="Fix the error in env.py (often an import of your application models).",
+            details={"path": str(path), "line": f"{last.filename}:{last.lineno}"},
+        ) from exc
+    return module
+
+
+def load_target_metadata(config: LoadedConfig) -> Any:
+    module = load_env_module(config.env_py_path, config.root_dir)
+    if not hasattr(module, "target_metadata"):
+        raise ConfigError(
+            f"{config.env_py_path.name} does not define `target_metadata`.",
+            suggestion="Add `target_metadata = ...` to migrations/env.py (None is allowed).",
+        )
+    return module.target_metadata