plain.models 0.51.1__py3-none-any.whl → 0.53.0__py3-none-any.whl

plain/models/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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
+
+- The `plain migrate` command now shows detailed operation descriptions and SQL statements for each migration step, replacing the previous verbosity levels with a cleaner `--quiet` flag ([d6b041bd24](https://github.com/dropseed/plain/commit/d6b041bd24))
+- Migration output format has been improved to display each operation's description and the actual SQL being executed, making it easier to understand what changes are being made to the database ([d6b041bd24](https://github.com/dropseed/plain/commit/d6b041bd24))
+- The `-v/--verbosity` option has been removed from `plain migrate` in favor of the simpler `--quiet` flag for suppressing output ([d6b041bd24](https://github.com/dropseed/plain/commit/d6b041bd24))
+
+### Upgrade instructions
+
+- Replace any usage of `-v` or `--verbosity` flags in `plain migrate` commands with `--quiet` if you want to suppress migration output
+
 ## [0.51.1](https://github.com/dropseed/plain/releases/plain-models@0.51.1) (2025-10-08)
 
 ### What's changed

plain/models/backends/base/creation.py

@@ -52,9 +52,6 @@ class BaseDatabaseCreation:
         settings.DATABASE["NAME"] = test_database_name
         self.connection.settings_dict["NAME"] = test_database_name
 
-        # We report migrate messages at one level lower than that
-        # requested. This ensures we don't get flooded with messages during
-        # testing (unless you really ask to be flooded).
         migrate.callback(
             package_label=None,
             migration_name=None,
@@ -62,10 +59,9 @@ class BaseDatabaseCreation:
             plan=False,
             check_unapplied=False,
             backup=False,
-            prune=False,
             no_input=True,
-            verbosity=max(verbosity - 1, 0),
             atomic_batch=False,  # No need for atomic batch when creating test database
+            quiet=verbosity < 2,  # Show migration output when verbosity is 2+
         )
 
         # Ensure a connection for the side effect of initializing the test database.

plain/models/backends/base/schema.py

@@ -159,19 +159,16 @@ class BaseDatabaseSchemaEditor:
     def __init__(
         self,
         connection: BaseDatabaseWrapper,
-        collect_sql: bool = False,
         atomic: bool = True,
     ):
         self.connection = connection
-        self.collect_sql = collect_sql
-        if self.collect_sql:
-            self.collected_sql: list[str] = []
         self.atomic_migration = self.connection.features.can_rollback_ddl and atomic
 
     # State-managing methods
 
     def __enter__(self) -> BaseDatabaseSchemaEditor:
         self.deferred_sql: list[Any] = []
+        self.executed_sql: list[str] = []
         if self.atomic_migration:
             self.atomic = atomic()
             self.atomic.__enter__()
@@ -190,11 +187,8 @@ class BaseDatabaseSchemaEditor:
         self, sql: str | Statement, params: tuple[Any, ...] | list[Any] | None = ()
     ) -> None:
         """Execute the given SQL statement, with optional parameters."""
-        # Don't perform the transactional DDL check if SQL is being collected
-        # as it's not going to be executed anyway.
         if (
-            not self.collect_sql
-            and self.connection.in_atomic_block
+            self.connection.in_atomic_block
             and not self.connection.features.can_rollback_ddl
         ):
             raise TransactionManagementError(
@@ -207,17 +201,16 @@ class BaseDatabaseSchemaEditor:
         logger.debug(
             "%s; (params %r)", sql, params, extra={"params": params, "sql": sql}
         )
-        if self.collect_sql:
-            ending = "" if sql.rstrip().endswith(";") else ";"
-            if params is not None:
-                self.collected_sql.append(
-                    (sql % tuple(map(self.quote_value, params))) + ending
-                )
-            else:
-                self.collected_sql.append(sql + ending)
+
+        # Track executed SQL for display in migration output
+        # Store the SQL for display (interpolate params for readability)
+        if params:
+            self.executed_sql.append(sql % tuple(map(self.quote_value, params)))
         else:
-            with self.connection.cursor() as cursor:
-                cursor.execute(sql, params)
+            self.executed_sql.append(sql)
+
+        with self.connection.cursor() as cursor:
+            cursor.execute(sql, params)
 
     def quote_name(self, name: str) -> str:
         return self.connection.ops.quote_name(name)

plain/models/cli.py

@@ -15,7 +15,7 @@ from plain.utils.text import Truncator
 
 from . import migrations
 from .backups.cli import cli as backups_cli
-from .backups.cli import create_backup
+from .backups.core import DatabaseBackups
 from .db import OperationalError
 from .db import db_connection as _db_connection
 from .migrations.autodetector import MigrationAutodetector
@@ -34,6 +34,7 @@ from .registry import models_registry
 
 if TYPE_CHECKING:
     from .backends.base.base import BaseDatabaseWrapper
+    from .migrations.operations.base import Operation
 
     db_connection = cast("BaseDatabaseWrapper", _db_connection)
 else:
@@ -365,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",
@@ -377,18 +373,16 @@ def makemigrations(
     is_flag=True,
     help="Tells Plain to NOT prompt the user for input of any kind.",
 )
-@click.option(
-    "-v",
-    "--verbosity",
-    type=int,
-    default=1,
-    help="Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output",
-)
 @click.option(
     "--atomic-batch/--no-atomic-batch",
     default=None,
     help="Run migrations in a single transaction (auto-detected by default)",
 )
+@click.option(
+    "--quiet",
+    is_flag=True,
+    help="Suppress migration output (used for test database creation).",
+)
 def migrate(
     package_label: str | None,
     migration_name: str | None,
@@ -396,28 +390,43 @@ def migrate(
     plan: bool,
     check_unapplied: bool,
     backup: bool | None,
-    prune: bool,
     no_input: bool,
-    verbosity: int,
     atomic_batch: bool | None,
+    quiet: bool,
 ) -> None:
     """Updates database schema. Manages both packages with migrations and those without."""
 
     def migration_progress_callback(
-        action: str, migration: Migration | None = None, fake: bool = False
+        action: str,
+        *,
+        migration: Migration | None = None,
+        fake: bool = False,
+        operation: Operation | None = None,
+        sql_statements: list[str] | None = None,
     ) -> None:
-        if verbosity >= 1:
-            if action == "apply_start":
-                click.echo(f"  Applying {migration}...", nl=False)
-            elif action == "apply_success":
-                if fake:
-                    click.echo(click.style(" FAKED", fg="green"))
-                else:
-                    click.echo(click.style(" OK", fg="green"))
-            elif action == "render_start":
-                click.echo("  Rendering model states...", nl=False)
-            elif action == "render_success":
-                click.echo(click.style(" DONE", fg="green"))
+        if quiet:
+            return
+
+        if action == "apply_start":
+            click.echo()  # Always add newline between migrations
+            if fake:
+                click.secho(f"{migration} (faked)", fg="cyan")
+            else:
+                click.secho(f"{migration}", fg="cyan")
+        elif action == "apply_success":
+            pass  # Already shown via operations
+        elif action == "operation_start":
+            click.echo(f"  {operation.describe()}", nl=False)
+            click.secho("... ", dim=True, nl=False)
+        elif action == "operation_success":
+            # Show SQL statements (no OK needed, SQL implies success)
+            if sql_statements:
+                click.echo()  # newline after "..."
+                for sql in sql_statements:
+                    click.secho(f"    {sql}", dim=True)
+            else:
+                # No SQL: just add a newline
+                click.echo()
 
     def describe_operation(operation: Any) -> tuple[str, bool]:
         """Return a string that describes a migration operation for --plan."""
@@ -504,74 +513,22 @@ 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 verbosity > 0:
-            click.secho("Pruning migrations:", fg="cyan")
-        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:
-            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 verbosity > 0:
-                        click.echo(
-                            click.style(f"  Pruning {package}.{name}", fg="yellow"),
-                            nl=False,
-                        )
-                    executor.recorder.record_unapplied(package, name)
-                    if verbosity > 0:
-                        click.echo(click.style(" OK", fg="green"))
-            elif verbosity > 0:
-                click.echo("  No migrations to prune.")
-
     migration_plan = executor.migration_plan(targets)
 
     if plan:
-        click.secho("Planned operations:", fg="cyan")
-        if not migration_plan:
-            click.echo("  No planned migration operations.")
-        else:
-            for migration in migration_plan:
-                click.secho(str(migration), fg="cyan")
-                for operation in migration.operations:
-                    message, is_error = describe_operation(operation)
-                    if is_error:
-                        click.secho("    " + message, fg="yellow")
-                    else:
-                        click.echo("    " + message)
+        if not quiet:
+            click.secho("Planned operations:", fg="cyan")
+            if not migration_plan:
+                click.echo("  No planned migration operations.")
+            else:
+                for migration in migration_plan:
+                    click.secho(str(migration), fg="cyan")
+                    for operation in migration.operations:
+                        message, is_error = describe_operation(operation)
+                        if is_error:
+                            click.secho("    " + message, fg="yellow")
+                        else:
+                            click.echo("    " + message)
         if check_unapplied:
             sys.exit(1)
         return
@@ -581,33 +538,24 @@ def migrate(
             sys.exit(1)
         return
 
-    if prune:
-        return
-
     # Print some useful info
-    if verbosity >= 1:
-        click.secho("Operations to perform:", fg="cyan")
-
+    if not quiet:
         if target_package_labels_only:
-            click.secho(
-                "  Apply all migrations: "
-                + (", ".join(sorted({a for a, n in targets})) or "(none)"),
-                fg="yellow",
-            )
+            packages = ", ".join(sorted({a for a, n in targets})) or "(none)"
+            click.secho("Packages: ", bold=True, nl=False)
+            click.secho(packages, dim=True)
+            click.echo()  # Add newline after packages
         else:
-            click.secho(
-                f"  Target specific migration: {targets[0][1]}, from {targets[0][0]}",
-                fg="yellow",
-            )
+            click.secho("Target: ", bold=True, nl=False)
+            click.secho(f"{targets[0][1]} from {targets[0][0]}", dim=True)
+            click.echo()  # Add newline after target
 
     pre_migrate_state = executor._create_project_state(with_applied_migrations=True)
 
-    # sql = executor.loader.collect_sql(migration_plan)
-    # pprint(sql)
-
     if migration_plan:
         # Determine whether to use atomic batch
         use_atomic_batch = False
+        atomic_batch_message = None
         if len(migration_plan) > 1:
             # Check database capabilities
             can_rollback_ddl = db_connection.features.can_rollback_ddl
@@ -632,58 +580,62 @@ def migrate(
                         f"--atomic-batch requested but these migrations have atomic=False: {names}"
                     )
                 use_atomic_batch = True
-                if verbosity >= 1:
-                    click.echo(
-                        f"  Running {len(migration_plan)} migrations in atomic batch (all-or-nothing)"
-                    )
+                atomic_batch_message = (
+                    f"Running {len(migration_plan)} migrations in atomic batch"
+                )
             elif atomic_batch is False:
                 # User explicitly disabled atomic batch
                 use_atomic_batch = False
-                if verbosity >= 1:
-                    click.echo(f"  Running {len(migration_plan)} migrations separately")
+                if len(migration_plan) > 1:
+                    atomic_batch_message = (
+                        f"Running {len(migration_plan)} migrations separately"
+                    )
             else:
                 # Auto-detect (atomic_batch is None)
                 if can_rollback_ddl and not non_atomic_migrations:
                     use_atomic_batch = True
-                    if verbosity >= 1:
-                        click.echo(
-                            f"  Running {len(migration_plan)} migrations in atomic batch (all-or-nothing)"
-                        )
+                    atomic_batch_message = (
+                        f"Running {len(migration_plan)} migrations in atomic batch"
+                    )
                 else:
                     use_atomic_batch = False
-                    if verbosity >= 1:
+                    if len(migration_plan) > 1:
                         if not can_rollback_ddl:
-                            click.echo(
-                                f"  Running {len(migration_plan)} migrations separately ({db_connection.vendor} doesn't support batch transactions)"
-                            )
+                            atomic_batch_message = f"Running {len(migration_plan)} migrations separately ({db_connection.vendor} doesn't support batch)"
                         elif non_atomic_migrations:
-                            click.echo(
-                                f"  Running {len(migration_plan)} migrations separately (some migrations have atomic=False)"
-                            )
+                            atomic_batch_message = f"Running {len(migration_plan)} migrations separately (some have atomic=False)"
                         else:
-                            click.echo(
-                                f"  Running {len(migration_plan)} migrations separately"
+                            atomic_batch_message = (
+                                f"Running {len(migration_plan)} migrations separately"
                             )
 
         if backup or (backup is None and settings.DEBUG):
             backup_name = f"migrate_{time.strftime('%Y%m%d_%H%M%S')}"
-            click.secho(
-                f"Creating backup before applying migrations: {backup_name}",
-                bold=True,
-            )
-            # Can't use ctx.invoke because this is called by the test db creation currently,
-            # which doesn't have a context.
-            create_backup.callback(
-                backup_name=backup_name,
-                pg_dump=os.environ.get(
-                    "PG_DUMP", "pg_dump"
-                ),  # Have to pass this in manually
+            if not quiet:
+                click.secho("Creating backup: ", bold=True, nl=False)
+                click.secho(f"{backup_name}", dim=True, nl=False)
+                click.secho("... ", dim=True, nl=False)
+
+            backups_handler = DatabaseBackups()
+            backups_handler.create(
+                backup_name,
+                pg_dump=os.environ.get("PG_DUMP", "pg_dump"),
             )
-            print()
 
-        if verbosity >= 1:
-            click.secho("Running migrations:", fg="cyan")
+            if not quiet:
+                click.echo(click.style("OK", fg="green"))
+                click.echo()  # Add blank line after backup output
+        else:
+            if not quiet:
+                click.echo()  # Add blank line after packages/target info
 
+        if not quiet:
+            if atomic_batch_message:
+                click.secho(
+                    f"Applying migrations ({atomic_batch_message.lower()}):", bold=True
+                )
+            else:
+                click.secho("Applying migrations:", bold=True)
         post_migrate_state = executor.migrate(
             targets,
             plan=migration_plan,
@@ -712,31 +664,24 @@ def migrate(
             ]
         )
 
-    elif verbosity >= 1:
-        click.echo("  No migrations to apply.")
-        # If there's changes that aren't in migrations yet, tell them
-        # how to fix it.
-        autodetector = MigrationAutodetector(
-            executor.loader.project_state(),
-            ProjectState.from_models_registry(models_registry),
-        )
-        changes = autodetector.changes(graph=executor.loader.graph)
-        if changes:
-            click.echo(
-                click.style(
-                    f"  Your models in package(s): {', '.join(repr(package) for package in sorted(changes))} "
-                    "have changes that are not yet reflected in a migration, and so won't be applied.",
-                    fg="yellow",
-                )
+    else:
+        if not quiet:
+            click.echo("No migrations to apply.")
+            # If there's changes that aren't in migrations yet, tell them
+            # how to fix it.
+            autodetector = MigrationAutodetector(
+                executor.loader.project_state(),
+                ProjectState.from_models_registry(models_registry),
             )
-            click.echo(
-                click.style(
-                    "  Run `plain makemigrations` to make new "
-                    "migrations, and then re-run `plain migrate` to "
-                    "apply them.",
-                    fg="yellow",
+            changes = autodetector.changes(graph=executor.loader.graph)
+            if changes:
+                packages = ", ".join(sorted(changes))
+                click.echo(
+                    f"Your models have changes that are not yet reflected in migrations ({packages})."
+                )
+                click.echo(
+                    "Run 'plain makemigrations' to create migrations for these changes."
                 )
-            )
 
 
 @cli.command()
@@ -819,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)
@@ -900,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/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
@@ -126,11 +128,7 @@ class MigrationExecutor:
                         break
                     if migration in migrations_to_run:
                         if "models_registry" not in state.__dict__:
-                            if self.progress_callback:
-                                self.progress_callback("render_start")
                             state.models_registry  # Render all -- performance critical
-                            if self.progress_callback:
-                                self.progress_callback("render_success")
                         state = self.apply_migration(state, migration, fake=fake)
                         migrations_to_run.remove(migration)
 
@@ -145,13 +143,15 @@ class MigrationExecutor:
         """Run a migration forwards."""
         migration_recorded = False
         if self.progress_callback:
-            self.progress_callback("apply_start", migration, fake)
+            self.progress_callback("apply_start", migration=migration, fake=fake)
         if not fake:
             # Alright, do it normally
             with self.connection.schema_editor(
                 atomic=migration.atomic
             ) as schema_editor:
-                state = migration.apply(state, schema_editor)
+                state = migration.apply(
+                    state, schema_editor, operation_callback=self.progress_callback
+                )
                 if not schema_editor.deferred_sql:
                     self.record_migration(migration)
                     migration_recorded = True
@@ -159,7 +159,7 @@ class MigrationExecutor:
             self.record_migration(migration)
         # Report progress
         if self.progress_callback:
-            self.progress_callback("apply_success", migration, fake)
+            self.progress_callback("apply_success", migration=migration, fake=fake)
         return state
 
     def record_migration(self, migration: Migration) -> None:

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.
@@ -370,23 +373,3 @@ class MigrationLoader:
         return self.graph.make_state(
             nodes=nodes, at_end=at_end, real_packages=self.unmigrated_packages
         )
-
-    def collect_sql(self, plan: list[Migration]) -> list[str]:
-        """
-        Take a migration plan and return a list of collected SQL statements
-        that represent the best-efforts version of that plan.
-        """
-        statements = []
-        state = None
-        for migration in plan:
-            with self.connection.schema_editor(
-                collect_sql=True, atomic=migration.atomic
-            ) as schema_editor:
-                if state is None:
-                    state = self.project_state(
-                        (migration.package_label, migration.name), at_end=False
-                    )
-
-                state = migration.apply(state, schema_editor, collect_sql=True)
-            statements.extend(schema_editor.collected_sql)
-        return statements

plain/models/migrations/migration.py

@@ -1,11 +1,16 @@
 from __future__ import annotations
 
 import re
-from typing import Any
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
 
 from plain.models.migrations.utils import get_migration_name_timestamp
 from plain.models.transaction import atomic
 
+if TYPE_CHECKING:
+    from plain.models.backends.base.schema import BaseDatabaseSchemaEditor
+    from plain.models.migrations.state import ProjectState
+
 
 class Migration:
     """
@@ -86,8 +91,11 @@ class Migration:
         return new_state
 
     def apply(
-        self, project_state: Any, schema_editor: Any, collect_sql: bool = False
-    ) -> Any:
+        self,
+        project_state: ProjectState,
+        schema_editor: BaseDatabaseSchemaEditor,
+        operation_callback: Callable[..., Any] | None = None,
+    ) -> ProjectState:
         """
         Take a project_state representing all migrations prior to this one
         and a schema_editor for a live database and apply the migration
@@ -97,18 +105,11 @@ class Migration:
         Migrations.
         """
         for operation in self.operations:
-            # If this operation cannot be represented as SQL, place a comment
-            # there instead
-            if collect_sql:
-                schema_editor.collected_sql.append("--")
-                schema_editor.collected_sql.append(f"-- {operation.describe()}")
-                schema_editor.collected_sql.append("--")
-                if not operation.reduces_to_sql:
-                    schema_editor.collected_sql.append(
-                        "-- THIS OPERATION CANNOT BE WRITTEN AS SQL"
-                    )
-                    continue
-                collected_sql_before = len(schema_editor.collected_sql)
+            # Clear any previous SQL statements before starting this operation
+            schema_editor.executed_sql = []
+
+            if operation_callback:
+                operation_callback("operation_start", operation=operation)
             # Save the state before the operation has run
             old_state = project_state.clone()
             operation.state_forwards(self.package_label, project_state)
@@ -128,8 +129,13 @@ class Migration:
                 operation.database_forwards(
                     self.package_label, schema_editor, old_state, project_state
                 )
-            if collect_sql and collected_sql_before == len(schema_editor.collected_sql):
-                schema_editor.collected_sql.append("-- (no-op)")
+            if operation_callback:
+                # Pass the accumulated SQL statements for this operation
+                operation_callback(
+                    "operation_success",
+                    operation=operation,
+                    sql_statements=schema_editor.executed_sql,
+                )
         return project_state
 
     def suggest_name(self) -> str:

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/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.51.1.dist-info → plain_models-0.53.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.models
-Version: 0.51.1
+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.51.1.dist-info → plain_models-0.53.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
 plain/models/AGENTS.md,sha256=xQQW-z-DehnCUyjiGSBfLqUjoSUdo_W1b0JmwYmWieA,209
-plain/models/CHANGELOG.md,sha256=Wr9ULasjvH3Shkr1jN75_KeNkRd_ZR8gCzR63-TWvps,23160
+plain/models/CHANGELOG.md,sha256=opeamIL3UOaX7RoG3reojlYb9W0O9k6Yf6SWCuj0cwc,25083
 plain/models/README.md,sha256=BW4a56bKkf2r-fkfK4SIU92th8h1geBNZ6j-XCv9yE4,8190
 plain/models/__init__.py,sha256=S0HNxIS4PQ0mSNpo3PNOXExVnHXFmODQvdPhTCVrW-E,2903
 plain/models/aggregates.py,sha256=z6AjlPlMI-henws9DYPwylL91sfrBPPHR7f9MNb2cjw,8043
 plain/models/base.py,sha256=uB1OHfyd9hDDqEHck481MCUeXsiwuYmyM7lkS2uQ7ts,64448
-plain/models/cli.py,sha256=cI323H4xEKLl1Q62zZQtl_UZBfuE6JMXsq5kSr7Ai0c,41031
+plain/models/cli.py,sha256=SUcDnRL6QT9nCduK_F6cdD4wgoe3TVcCpw8XK5mVGCc,41376
 plain/models/config.py,sha256=vrrGZnmT0TCR_B-YF0VWZgG3iQ5syijaab2BW7Xfr7A,390
 plain/models/connections.py,sha256=8DVH6Rl47wbfY_4wO6bGSoTuyJKoKz3tMB8fpe1cpqE,2937
 plain/models/constants.py,sha256=ndnj9TOTKW0p4YcIPLOLEbsH6mOgFi6B1-rIzr_iwwU,210
@@ -23,7 +23,7 @@ plain/models/lookups.py,sha256=A-3rs3a2Obb-gQPs5RsQiCq-Shj21tznk2LwOeD4RXs,29447
 plain/models/meta.py,sha256=alEKxzgwxmCRddq9Wonl1bjglDk1-x3CtEwWL3cGy6A,19942
 plain/models/options.py,sha256=gTso-rRXxV6qbuAprsA1qflkQfsRqmcoETEQJmP0dGk,8593
 plain/models/otel.py,sha256=6xsu5BhNhGXWRPNQVj0yzhsn1SryOhtCq_qzP8XL-qo,8010
-plain/models/preflight.py,sha256=VIiNdWady7uHAEB_XT4_Vkt4M--vGVYL7QEdNMW8Tko,9818
+plain/models/preflight.py,sha256=QmLr51J2GNtvm5y45SQ7oxdqq585VoifgHGgsm1unSM,12695
 plain/models/query.py,sha256=-ZDJlt7aM5d3Sms_1Eu53h1UGnQvtKinFIhhLBgnfkY,98481
 plain/models/query_utils.py,sha256=m_3FCbFZJjqkN6tcDuLrgA2n63RxUHOaXb_bJyQsS9k,16171
 plain/models/registry.py,sha256=dIsgZolh7senbPil6xW_qLFIeIXkCtzysPcrpWdGAAY,8903
@@ -35,11 +35,11 @@ plain/models/backends/utils.py,sha256=wn4U_qrzGQxecJtcXS5VFds2Tg6VoJrs1TB_l8LN9A
 plain/models/backends/base/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/models/backends/base/base.py,sha256=465KAc8J2R8eIy3NmJSnrgMPK0K2DwDsylGKEzUkpsI,29099
 plain/models/backends/base/client.py,sha256=xuMk4iXQjDju5cUspmOSpv6w2JnsB-gJa3RDvoP5I9I,1230
-plain/models/backends/base/creation.py,sha256=A3cBPzxjmzEUIrsiuxoI4M3mi-Y9sGcVHoCa-TpQRtM,9857
+plain/models/backends/base/creation.py,sha256=xNrYqxheUiK1-CaKEQa-CGFcVzme0CpApqU--SY9a-4,9667
 plain/models/backends/base/features.py,sha256=iRfB346Z9Ng3LIMvJAwr-8KxQthlSuvcdo9zBklE1-8,8067
 plain/models/backends/base/introspection.py,sha256=3yeluBm6UHOlKikgVzGlKnDqBhyaqP-1FoSO4y_c-Hc,7613
 plain/models/backends/base/operations.py,sha256=8m5XDZ5LtALaXbUX10QPSGDFKce17V5UeJDMkbSZdCs,29324
-plain/models/backends/base/schema.py,sha256=t5U45noXOGxQkadh-EBz7BLIdPDg-uai3qUxXYHAkiU,70546
+plain/models/backends/base/schema.py,sha256=H8Fdl4Gqyhc6aLifwYa5PsuPK3i-4oN6NTCR_61tBRs,70206
 plain/models/backends/base/validation.py,sha256=Ok-TbVVi84zdPprKI--tUxYgoDl2PaxfNDiuYqZQBLM,1341
 plain/models/backends/mysql/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/models/backends/mysql/base.py,sha256=6yNw8m4LpnNOOBVGzGZDPZGDAZKDnDbAWBO62Xg4yJY,14786
@@ -90,13 +90,13 @@ plain/models/functions/window.py,sha256=7rzVWpRMZ-1FptAWN_xPt-onh-tErL5sGfss63IL
 plain/models/migrations/__init__.py,sha256=ZAQUGrfr_OxYMIO7vUBIHLs_M3oZ4iQSjDzCHRFUdtI,96
 plain/models/migrations/autodetector.py,sha256=Aack1d0nGPx8UPRea0ZcSouMwE9hsXltOK6LIdlPAVs,62565
 plain/models/migrations/exceptions.py,sha256=yfimKFZJpyw4IpH2LqZR7hL3J41PBSmXd1HbuWWayWY,1143
-plain/models/migrations/executor.py,sha256=zfqQ0cNtoo-UEBAmenuO1_Mfyinj3fSELfKJsduC35Y,7611
+plain/models/migrations/executor.py,sha256=6_BzYIxSf2ayN7ITFo5Yxj0xdoiLAu1kv8TpE-dTttw,7546
 plain/models/migrations/graph.py,sha256=SFSk2QxG8ni9LxtnfuMHeN2qQeI3lv4jD-R-y_i2VL0,14101
-plain/models/migrations/loader.py,sha256=PzbEL_9XxU3XcQAb5O9mH22nuBjvJhr_bkOkYJfglbA,17515
-plain/models/migrations/migration.py,sha256=2lLS9XFPPktpwhCUWcWx6eFkPHZQE_KYnIMRSm0CvWo,6896
+plain/models/migrations/loader.py,sha256=vr717xlnahSzmEkAGnIJp9_FFoOIilS_2nwH7Ww-vd4,16837
+plain/models/migrations/migration.py,sha256=I2Nsu-8YlTKXZBGCufzK50XeCIsEMSz-I5Vg3r6Hf9s,6953
 plain/models/migrations/optimizer.py,sha256=Kk8-KBB51mYiR96hp8F7ZhFvdVg7DYyujpKmp8b9T6A,3385
 plain/models/migrations/questioner.py,sha256=1uhQqPooxAaJuXe_W_B9X5df8MOoO_G7IFcubQxd6lE,12980
-plain/models/migrations/recorder.py,sha256=4rxOUmwJRkyKt5WVTQtnfsXnesV5Ue--1MpXYFltbto,4175
+plain/models/migrations/recorder.py,sha256=e268sBTptmYVqRitlkza_mTdmWklUk-jjpMCMrn6zIY,4252
 plain/models/migrations/serializer.py,sha256=QWz5PvDSWKgHjae1McEIPwahQTm17ZES2Kf6aVebrr0,13410
 plain/models/migrations/state.py,sha256=3wmARJZ8XgCnkW-xvg2r2VWrhl1GoLRQmBFIh2EFa3w,35795
 plain/models/migrations/utils.py,sha256=MkrO_ZHCLQVlhgJPVxIlkZ7tqpQ_BDa6i07T-OCORnE,4796
@@ -116,8 +116,8 @@ plain/models/sql/where.py,sha256=GeTopzVmvZTqm2NTS32ok0rHbNgoEREUVtsD7usrlCA,138
 plain/models/test/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/models/test/pytest.py,sha256=sZtHzmNoqIFb7csZ8fqbRwljQ0vWrcMcDm6Wk_0g-uk,3924
 plain/models/test/utils.py,sha256=eduH039cMVixWORfsUr7qkk0YDkTHPXFZklm9lzY474,540
-plain_models-0.51.1.dist-info/METADATA,sha256=KnNRGQxkypz9IZdzymjZYxCqAeKAfnNJfI7bU886uRc,8502
-plain_models-0.51.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-plain_models-0.51.1.dist-info/entry_points.txt,sha256=IYJAW9MpL3PXyXFWmKmALagAGXC_5rzBn2eEGJlcV04,112
-plain_models-0.51.1.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
-plain_models-0.51.1.dist-info/RECORD,,
+plain_models-0.53.0.dist-info/METADATA,sha256=EiyfdHYM2rkhwORfwuTzZQBmq7js5m7vqWmITs43UHA,8502
+plain_models-0.53.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain_models-0.53.0.dist-info/entry_points.txt,sha256=IYJAW9MpL3PXyXFWmKmALagAGXC_5rzBn2eEGJlcV04,112
+plain_models-0.53.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
+plain_models-0.53.0.dist-info/RECORD,,