plain.models 0.52.0__tar.gz → 0.53.0__tar.gz

{plain_models-0.52.0 → plain_models-0.53.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.models
-Version: 0.52.0
+Version: 0.53.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE

{plain_models-0.52.0 → plain_models-0.53.0}/plain/models/CHANGELOG.md

@@ -1,5 +1,18 @@
 # plain-models changelog
 
+## [0.53.0](https://github.com/dropseed/plain/releases/plain-models@0.53.0) (2025-10-12)
+
+### What's changed
+
+- Added new `plain models prune-migrations` command to identify and remove stale migration records from the database ([998aa49](https://github.com/dropseed/plain/commit/998aa49140))
+- The `--prune` option has been removed from `plain migrate` command in favor of the dedicated `prune-migrations` command ([998aa49](https://github.com/dropseed/plain/commit/998aa49140))
+- Added new preflight check `models.prunable_migrations` that warns about stale migration records in the database ([9b43617](https://github.com/dropseed/plain/commit/9b4361765c))
+- The `show-migrations` command no longer displays prunable migrations in its output ([998aa49](https://github.com/dropseed/plain/commit/998aa49140))
+
+### Upgrade instructions
+
+- Replace any usage of `plain migrate --prune` with the new `plain models prune-migrations` command
+
 ## [0.52.0](https://github.com/dropseed/plain/releases/plain-models@0.52.0) (2025-10-10)
 
 ### What's changed

{plain_models-0.52.0 → plain_models-0.53.0}/plain/models/backends/base/creation.py

@@ -59,7 +59,6 @@ class BaseDatabaseCreation:
             plan=False,
             check_unapplied=False,
             backup=False,
-            prune=False,
             no_input=True,
             atomic_batch=False,  # No need for atomic batch when creating test database
             quiet=verbosity < 2,  # Show migration output when verbosity is 2+

{plain_models-0.52.0 → plain_models-0.53.0}/plain/models/cli.py

@@ -366,11 +366,6 @@ def makemigrations(
     default=None,
     help="Explicitly enable/disable pre-migration backups.",
 )
-@click.option(
-    "--prune",
-    is_flag=True,
-    help="Delete nonexistent migrations from the plainmigrations table.",
-)
 @click.option(
     "--no-input",
     "--noinput",
@@ -395,7 +390,6 @@ def migrate(
     plan: bool,
     check_unapplied: bool,
     backup: bool | None,
-    prune: bool,
     no_input: bool,
     atomic_batch: bool | None,
     quiet: bool,
@@ -519,58 +513,6 @@ def migrate(
     else:
         targets = list(executor.loader.graph.leaf_nodes())
 
-    if prune:
-        if not package_label:
-            raise click.ClickException(
-                "Migrations can be pruned only when a package is specified."
-            )
-        if not quiet:
-            click.secho("Pruning migrations:", bold=True)
-        to_prune = set(executor.loader.applied_migrations) - set(  # type: ignore[arg-type]
-            executor.loader.disk_migrations  # type: ignore[arg-type]
-        )
-        squashed_migrations_with_deleted_replaced_migrations = [
-            migration_key
-            for migration_key, migration_obj in executor.loader.replacements.items()
-            if any(replaced in to_prune for replaced in migration_obj.replaces)
-        ]
-        if squashed_migrations_with_deleted_replaced_migrations:
-            if not quiet:
-                click.echo(
-                    click.style(
-                        "  Cannot use --prune because the following squashed "
-                        "migrations have their 'replaces' attributes and may not "
-                        "be recorded as applied:",
-                        fg="yellow",
-                    )
-                )
-                for migration in squashed_migrations_with_deleted_replaced_migrations:
-                    package, name = migration
-                    click.echo(f"    {package}.{name}")
-                click.echo(
-                    click.style(
-                        "  Re-run `plain migrate` if they are not marked as "
-                        "applied, and remove 'replaces' attributes in their "
-                        "Migration classes.",
-                        fg="yellow",
-                    )
-                )
-        else:
-            to_prune = sorted(
-                migration for migration in to_prune if migration[0] == package_label
-            )
-            if to_prune:
-                for migration in to_prune:
-                    package, name = migration
-                    if not quiet:
-                        click.echo(f"  Pruning {package}.{name}...", nl=False)
-                    executor.recorder.record_unapplied(package, name)
-                    if not quiet:
-                        click.echo(" OK")
-            else:
-                if not quiet:
-                    click.echo("  No migrations to prune.")
-
     migration_plan = executor.migration_plan(targets)
 
     if plan:
@@ -596,9 +538,6 @@ def migrate(
             sys.exit(1)
         return
 
-    if prune:
-        return
-
     # Print some useful info
     if not quiet:
         if target_package_labels_only:
@@ -825,35 +764,6 @@ def show_migrations(
             if not shown:
                 click.secho(" (no migrations)", fg="red")
 
-        # Find recorded migrations that aren't in the graph (prunable)
-        prunable_migrations = [
-            migration
-            for migration in recorded_migrations
-            if (
-                migration not in loader.disk_migrations  # type: ignore[operator]
-                and (not package_names_list or migration[0] in package_names_list)
-            )
-        ]
-
-        if prunable_migrations:
-            click.echo()
-            click.secho(
-                "Recorded migrations not in migration files (candidates for pruning):",
-                fg="yellow",
-                bold=True,
-            )
-            prunable_by_package = {}
-            for migration in prunable_migrations:
-                package, name = migration
-                if package not in prunable_by_package:
-                    prunable_by_package[package] = []
-                prunable_by_package[package].append(name)
-
-            for package in sorted(prunable_by_package.keys()):
-                click.secho(f"  {package}:", fg="yellow")
-                for name in sorted(prunable_by_package[package]):
-                    click.echo(f"    - {name}")
-
     def show_plan(db_connection: Any, package_names: tuple[str, ...]) -> None:
         """
         Show all known migrations (or only those of the specified package_names)
@@ -906,6 +816,108 @@ def show_migrations(
         show_list(db_connection, package_labels)
 
 
+@cli.command()
+@click.option(
+    "--yes",
+    is_flag=True,
+    help="Skip confirmation prompt (for non-interactive use).",
+)
+def prune_migrations(yes: bool) -> None:
+    """Show and optionally remove stale migration records from the database."""
+    # Load migrations from disk and database
+    loader = MigrationLoader(db_connection, ignore_no_migrations=True)
+    recorder = MigrationRecorder(db_connection)
+    recorded_migrations = recorder.applied_migrations()
+
+    # Find all prunable migrations (recorded but not on disk)
+    all_prunable = [
+        migration
+        for migration in recorded_migrations
+        if migration not in loader.disk_migrations  # type: ignore[operator]
+    ]
+
+    if not all_prunable:
+        click.echo("No stale migration records found.")
+        return
+
+    # Separate into existing packages vs orphaned packages
+    existing_packages = set(loader.migrated_packages)
+    prunable_existing: dict[str, list[str]] = {}
+    prunable_orphaned: dict[str, list[str]] = {}
+
+    for migration in all_prunable:
+        package, name = migration
+        if package in existing_packages:
+            if package not in prunable_existing:
+                prunable_existing[package] = []
+            prunable_existing[package].append(name)
+        else:
+            if package not in prunable_orphaned:
+                prunable_orphaned[package] = []
+            prunable_orphaned[package].append(name)
+
+    # Display what was found
+    if prunable_existing:
+        click.secho(
+            "Stale migration records (from existing packages):",
+            fg="yellow",
+            bold=True,
+        )
+        for package in sorted(prunable_existing.keys()):
+            click.secho(f"  {package}:", fg="yellow")
+            for name in sorted(prunable_existing[package]):
+                click.echo(f"    - {name}")
+        click.echo()
+
+    if prunable_orphaned:
+        click.secho(
+            "Orphaned migration records (from removed packages):",
+            fg="red",
+            bold=True,
+        )
+        for package in sorted(prunable_orphaned.keys()):
+            click.secho(f"  {package}:", fg="red")
+            for name in sorted(prunable_orphaned[package]):
+                click.echo(f"    - {name}")
+        click.echo()
+
+    total_count = sum(len(migs) for migs in prunable_existing.values()) + sum(
+        len(migs) for migs in prunable_orphaned.values()
+    )
+
+    if not yes:
+        click.echo(
+            f"Found {total_count} stale migration record{'s' if total_count != 1 else ''}."
+        )
+        click.echo()
+
+        # Prompt for confirmation if interactive
+        if not click.confirm(
+            "Do you want to remove these migrations from the database?"
+        ):
+            return
+
+    # Actually prune the migrations
+    click.secho("Pruning migrations...", bold=True)
+
+    for package, migration_names in prunable_existing.items():
+        for name in sorted(migration_names):
+            click.echo(f"  Pruning {package}.{name}...", nl=False)
+            recorder.record_unapplied(package, name)
+            click.echo(" OK")
+
+    for package, migration_names in prunable_orphaned.items():
+        for name in sorted(migration_names):
+            click.echo(f"  Pruning {package}.{name} (orphaned)...", nl=False)
+            recorder.record_unapplied(package, name)
+            click.echo(" OK")
+
+    click.secho(
+        f"✓ Removed {total_count} stale migration record{'s' if total_count != 1 else ''}.",
+        fg="green",
+    )
+
+
 @cli.command()
 @click.argument("package_label")
 @click.argument("start_migration_name", required=False)

{plain_models-0.52.0 → plain_models-0.53.0}/plain/models/migrations/executor.py

@@ -4,6 +4,8 @@ from collections.abc import Callable
 from contextlib import nullcontext
 from typing import TYPE_CHECKING, Any
 
+from plain.models.connections import DatabaseConnection
+
 from ..transaction import atomic
 from .loader import MigrationLoader
 from .migration import Migration
@@ -22,7 +24,7 @@ class MigrationExecutor:
 
     def __init__(
         self,
-        connection: BaseDatabaseWrapper,
+        connection: BaseDatabaseWrapper | DatabaseConnection,
         progress_callback: Callable[..., Any] | None = None,
     ) -> None:
         self.connection = connection

{plain_models-0.52.0 → plain_models-0.53.0}/plain/models/migrations/loader.py

@@ -5,6 +5,7 @@ import sys
 from importlib import import_module, reload
 from typing import TYPE_CHECKING, Any
 
+from plain.models.connections import DatabaseConnection
 from plain.models.migrations.graph import MigrationGraph
 from plain.models.migrations.recorder import MigrationRecorder
 from plain.packages import packages_registry
@@ -50,7 +51,7 @@ class MigrationLoader:
 
     def __init__(
         self,
-        connection: BaseDatabaseWrapper | None,
+        connection: BaseDatabaseWrapper | DatabaseConnection | None,
         load: bool = True,
         ignore_no_migrations: bool = False,
         replace_migrations: bool = True,
@@ -316,7 +317,9 @@ class MigrationLoader:
             raise
         self.graph.ensure_not_cyclic()
 
-    def check_consistent_history(self, connection: BaseDatabaseWrapper) -> None:
+    def check_consistent_history(
+        self, connection: BaseDatabaseWrapper | DatabaseConnection
+    ) -> None:
         """
         Raise InconsistentMigrationHistory if any applied migrations have
         unapplied dependencies.

{plain_models-0.52.0 → plain_models-0.53.0}/plain/models/migrations/recorder.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from plain import models
+from plain.models.connections import DatabaseConnection
 from plain.models.db import DatabaseError
 from plain.models.meta import Meta
 from plain.models.registry import ModelsRegistry
@@ -59,7 +60,7 @@ class MigrationRecorder:
             cls._migration_class = Migration
         return cls._migration_class
 
-    def __init__(self, connection: BaseDatabaseWrapper) -> None:
+    def __init__(self, connection: BaseDatabaseWrapper | DatabaseConnection) -> None:
         self.connection = connection
 
     @property

{plain_models-0.52.0 → plain_models-0.53.0}/plain/models/preflight.py

@@ -244,3 +244,83 @@ class CheckDatabaseTables(PreflightCheck):
             )
 
         return errors
+
+
+@register_check("models.prunable_migrations")
+class CheckPrunableMigrations(PreflightCheck):
+    """Warns about stale migration records in the database."""
+
+    def run(self) -> list[PreflightResult]:
+        # Import here to avoid circular import issues
+        from plain.models.migrations.loader import MigrationLoader
+        from plain.models.migrations.recorder import MigrationRecorder
+
+        errors = []
+
+        # Load migrations from disk and database
+        loader = MigrationLoader(db_connection, ignore_no_migrations=True)
+        recorder = MigrationRecorder(db_connection)
+        recorded_migrations = recorder.applied_migrations()
+
+        # disk_migrations should not be None after MigrationLoader initialization,
+        # but check to satisfy type checker
+        if loader.disk_migrations is None:
+            return errors
+
+        # Find all prunable migrations (recorded but not on disk)
+        all_prunable = [
+            migration
+            for migration in recorded_migrations
+            if migration not in loader.disk_migrations
+        ]
+
+        if not all_prunable:
+            return errors
+
+        # Separate into existing packages vs orphaned packages
+        existing_packages = set(loader.migrated_packages)
+        prunable_existing: list[tuple[str, str]] = []
+        prunable_orphaned: list[tuple[str, str]] = []
+
+        for migration in all_prunable:
+            package, name = migration
+            if package in existing_packages:
+                prunable_existing.append(migration)
+            else:
+                prunable_orphaned.append(migration)
+
+        # Build the warning message
+        total_count = len(all_prunable)
+        message_parts = [
+            f"Found {total_count} stale migration record{'s' if total_count != 1 else ''} in the database."
+        ]
+
+        if prunable_existing:
+            existing_list = ", ".join(
+                f"{pkg}.{name}" for pkg, name in prunable_existing[:3]
+            )
+            if len(prunable_existing) > 3:
+                existing_list += f" (and {len(prunable_existing) - 3} more)"
+            message_parts.append(f"From existing packages: {existing_list}.")
+
+        if prunable_orphaned:
+            orphaned_list = ", ".join(
+                f"{pkg}.{name}" for pkg, name in prunable_orphaned[:3]
+            )
+            if len(prunable_orphaned) > 3:
+                orphaned_list += f" (and {len(prunable_orphaned) - 3} more)"
+            message_parts.append(f"From removed packages: {orphaned_list}.")
+
+        message_parts.append(
+            "Run 'plain models prune-migrations' to review and remove them."
+        )
+
+        errors.append(
+            PreflightResult(
+                fix=" ".join(message_parts),
+                id="models.prunable_migrations",
+                warning=True,
+            )
+        )
+
+        return errors

{plain_models-0.52.0 → plain_models-0.53.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.models"
-version = "0.52.0"
+version = "0.53.0"
 description = "Model your data and store it in a database."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"