plain.models 0.51.1__tar.gz → 0.53.0__tar.gz

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

@@ -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 → plain_models-0.53.0}/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-0.51.1 → plain_models-0.53.0}/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-0.51.1 → plain_models-0.53.0}/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-0.51.1 → plain_models-0.53.0}/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)