plain.postgres 0.111.2__tar.gz → 0.113.0__tar.gz

plain_postgres-0.111.2/plain/postgres/README.md → plain_postgres-0.113.0/PKG-INFO

@@ -1,3 +1,16 @@
+Metadata-Version: 2.4
+Name: plain.postgres
+Version: 0.113.0
+Summary: Model your data and store it in a database.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: plain<1.0.0,>=0.134.0
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: psycopg>=3.2
+Description-Content-Type: text/markdown
+
 # plain.postgres
 
 **Model your data and store it in a database.**
@@ -775,6 +788,26 @@ Environment overrides: every setting accepts `PLAIN_POSTGRES_*` env vars, so you
 PLAIN_POSTGRES_MIGRATION_STATEMENT_TIMEOUT=30s plain migrations apply
 ```
 
+### Schema lock
+
+Schema-changing commands — `plain postgres sync`, `plain migrations apply`, `plain postgres converge`, and `plain postgres drop-unknown-tables` — serialize on a single session-level advisory lock, so two deploy processes running at once (a retried migrate job, overlapping release phases) can't interleave schema changes. You don't have to do anything to get this.
+
+A second process warns and waits, retrying until the holder finishes:
+
+```python
+# app/settings.py — defaults shown (waits up to an hour total)
+POSTGRES_SCHEMA_LOCK_RETRY_INTERVAL = 5.0
+POSTGRES_SCHEMA_LOCK_MAX_RETRIES = 720
+```
+
+The wait is generous by default because a legitimate holder can be mid index build. If the budget runs out, the command fails with the holder's `pid` so you can see what's blocking. A crashed holder is not a problem — the lock releases automatically when its database session closes.
+
+The lock is held on its own connection, separate from the one running DDL, so non-transactional operations (`CREATE INDEX CONCURRENTLY`, `VALIDATE CONSTRAINT`) work normally while it's held. Session-level locks don't survive transaction-mode poolers like pgbouncer — if your `POSTGRES_URL` points at one, set [`POSTGRES_MANAGEMENT_URL`](#bypassing-a-connection-pooler-for-management-operations) to a direct connection.
+
+The lock connection sits idle while your DDL runs, so it enables TCP keepalives to survive NAT and load-balancer idle timeouts. A server-side `idle_session_timeout` would still kill it (releasing the lock mid-run) — don't set one for the role that runs migrations. `sync` re-verifies the lock between its migrate and converge phases and stops with a clear error if the session died.
+
+To see the lock live: `SELECT * FROM pg_locks WHERE locktype = 'advisory' AND objid = 1047265496`.
+
 ## Fields
 
 You can use many field types for different data:
@@ -908,6 +941,7 @@ Values are encrypted using Fernet (AES-128-CBC + HMAC-SHA256) with a key derived
 
 - **No lookups** — encrypted values are non-deterministic (same plaintext produces different ciphertext each time), so filtering on encrypted fields doesn't work. Only `isnull` lookups are supported.
 - **No indexes or constraints** — encrypted fields cannot be used in indexes or unique constraints. Preflight checks will catch this.
+- **Only `default=""`** — on `EncryptedTextField` (paired with `required=False`), the empty string is stored as plaintext `''`, so it's the one value expressible as a column `DEFAULT` (declare it to add the field to a populated table). Any other default would need ciphertext, which is non-deterministic. `EncryptedJSONField` accepts no default at all — even `{}` serializes to text that would need ciphertext; use `allow_null=True`.
 
 **Key rotation:**
 
@@ -1459,9 +1493,9 @@ See [`default_settings.py`](./default_settings.py) for more details.
 
 Add the field to your model class, then run `plain migrations create` to create a migration.
 
-If the field is required (no `default=` and not `allow_null=True`), the autodetector refuses to generate the migration, since there's no value to seed existing rows with. You have two options:
+If the field has no `default=` and isn't `allow_null=True`, the autodetector refuses to generate the migration, since there's no value to seed existing rows with — `required=False` alone is not enough (it only affects Python-side validation, not the column). You have two options:
 
-1. Declare a `default=` on the field so the new column has a value for existing rows.
+1. Declare a `default=` on the field so the new column has a value for existing rows. For an optional string field the idiom is `required=False, default=""` (for `BinaryField`, `default=b""`).
 2. Add the field with `allow_null=True`, scaffold a data migration with `plain migrations create --empty --name backfill_<field>` to populate existing rows, then remove `allow_null=True` from the field — convergence applies `NOT NULL` on the next `postgres sync`.
 
 #### How do I make an existing column `NOT NULL`?

{plain_postgres-0.111.2 → plain_postgres-0.113.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,37 @@
 # plain-postgres changelog
 
+## [0.113.0](https://github.com/dropseed/plain/releases/plain-postgres@0.113.0) (2026-08-02)
+
+### What's changed
+
+- **`QuerySet.extra()` has been removed**, along with all of its supporting machinery (`extra_select`, `extra_tables`, `extra_order_by`, `ExtraWhere`). Use `annotate()` with `RawSQL` or other expressions instead. ([3fed0b32f1](https://github.com/dropseed/plain/commit/3fed0b32f1))
+- **`FilteredRelation` has been removed** — it's no longer importable from `plain.postgres` or usable in `annotate()`. Express conditional joins with `Q` filters or subqueries instead. ([434f57852f](https://github.com/dropseed/plain/commit/434f57852f))
+- **`QuerySet.alias()` and logical XOR have been removed** — `Q(...) ^ Q(...)` and `queryset ^ queryset` are no longer supported. Use `annotate()` in place of `alias()`, and compose AND/OR/NOT in place of XOR. ([c12cf81af4](https://github.com/dropseed/plain/commit/c12cf81af4))
+- **Encrypted and binary fields now accept their empty value as a declared `default=`.** `EncryptedTextField` (now a `TextField` subclass) accepts exactly `default=""` and `BinaryField` accepts exactly `default=b""`, each paired with `required=False` — the empty value is stored as plaintext so it's the one default expressible as a column `DEFAULT`, which is what lets the field be added to a populated table. `default=None` requires `allow_null=True` + `required=False`. The `types.pyi` stub overloads encode the same coupling. ([2a86968e5a](https://github.com/dropseed/plain/commit/2a86968e5a))
+- **The migration autodetector no longer waves through `required=False` fields with no declared default.** Adding a non-nullable field without a `default=` now refuses at `plain migrations create` time with a field-accurate remedy (previously these could generate an `AddField` that failed at apply time on any populated table). The optional-string idiom is `required=False, default=""`. ([2a86968e5a](https://github.com/dropseed/plain/commit/2a86968e5a))
+- **`EncryptedJSONField` is now a `JSONField` subclass** and `EncryptedTextField` a `TextField` subclass, instead of parallel `ColumnField` implementations — behavior like max_length validation and JSON encoding now comes from the real base classes. The encrypted lookup surface is still just `exact`/`isnull`, and JSON key transforms are blocked (they'd operate on ciphertext). `EncryptedJSONField` accepts no `default=` at all — even `{}` would need ciphertext; use `allow_null=True`. ([5153ceb106](https://github.com/dropseed/plain/commit/5153ceb106), [2a86968e5a](https://github.com/dropseed/plain/commit/2a86968e5a))
+- Model forms no longer prefill a `BinaryField`'s `b""` default as a text input's initial value (it rendered as the literal `b''`), and encrypted fields now map to form fields through the regular `TextField`/`JSONField` branches. ([2a86968e5a](https://github.com/dropseed/plain/commit/2a86968e5a))
+- M2M prefetches now expose the through-table join column via `annotate(RawSQL(...))` instead of the removed `extra()`, and internal path-info plumbing lost its `filtered_relation` threading. ([3fed0b32f1](https://github.com/dropseed/plain/commit/3fed0b32f1), [434f57852f](https://github.com/dropseed/plain/commit/434f57852f))
+
+### Upgrade instructions
+
+- Replace `QuerySet.extra()` calls: `extra(select=...)` becomes `annotate(name=RawSQL("...", []))`, `extra(where=...)` becomes `filter()` with expressions or `RawSQL`, and `extra(order_by=...)` becomes `order_by()` on an annotation.
+- Replace `FilteredRelation` annotations with filtered subqueries or `Q` conditions, and `QuerySet.alias()` with `annotate()`.
+- Replace `Q(a) ^ Q(b)` / `qs1 ^ qs2` with explicit AND/OR logic: `(Q(a) | Q(b)) & ~(Q(a) & Q(b))`.
+- If `plain migrations create` now refuses a field it previously accepted, follow the error's remedy: declare `required=False, default=""` (or `default=b""` / an appropriate literal) so existing rows get a value, or add it with `allow_null=True` plus a backfill data migration.(https://github.com/dropseed/plain/releases/plain-postgres@0.112.0) (2026-07-21)
+
+### What's changed
+
+- **Schema-changing commands now serialize on an advisory schema lock.** `plain postgres sync`, `plain migrations apply`, `plain postgres converge`, and `plain postgres drop-unknown-tables` take a session-level advisory lock, so two deploy processes running at once (a retried migrate job, overlapping release phases) can't interleave schema changes. A second process warns and waits, retrying up to an hour by default (`POSTGRES_SCHEMA_LOCK_RETRY_INTERVAL`, `POSTGRES_SCHEMA_LOCK_MAX_RETRIES`), and each command re-checks its plan after acquiring the lock — `migrations apply` skips work another process already did, `converge` refuses to execute corrections the operator never approved, and `drop-unknown-tables` skips tables that became known while waiting. The lock is held on its own connection so `CREATE INDEX CONCURRENTLY` still works, and it releases automatically if the holder crashes. ([f12f5f1bd4](https://github.com/dropseed/plain/commit/f12f5f1bd4))
+- **New `plain.postgres.databases` module** for cluster-level database management — `create_database` (with `TEMPLATE` support), `drop_database`, `database_exists`, `list_databases`, database comments, connection counting/termination, and a `maintenance_cursor` helper. It's a development/test capability (it needs `CREATEDB` and a connection to the `postgres` maintenance database) and is what powers plain-dev's managed development databases; test database creation now uses it too. ([0a747b8933](https://github.com/dropseed/plain/commit/0a747b8933))
+- Fixed a stale `rollback_exc` on reused connections: entering an outermost atomic block now clears it, and a rollback caused by an exception inside a non-savepoint block records that exception — so a broken-transaction error chains from the real cause instead of a stale or absent one. ([350f34b291](https://github.com/dropseed/plain/commit/350f34b291))
+- Convergence terminology changed from "fix" to "correction" in CLI output and internals — `plain postgres converge` now reports "N corrections to apply" and `plain postgres schema` marks drift as `(auto-correct)`. ([08da420a9b](https://github.com/dropseed/plain/commit/08da420a9b))
+- The unconfigured-database error now points at `PLAIN_POSTGRES_URL` (or `POSTGRES_URL` in settings) instead of `DATABASE_URL`-first wording. ([8b7aa38e95](https://github.com/dropseed/plain/commit/8b7aa38e95))
+
+### Upgrade instructions
+
+- No changes required. If your migration role's Postgres server sets `idle_session_timeout`, note the schema lock holds an idle session for the duration of a schema command — exempt that role, or the lock can be lost mid-run. If `POSTGRES_URL` points at a transaction-mode pooler (pgbouncer), set `POSTGRES_MANAGEMENT_URL` to a direct connection so the session-level lock works.
+
 ## [0.111.2](https://github.com/dropseed/plain/releases/plain-postgres@0.111.2) (2026-07-15)
 
 ### What's changed

plain_postgres-0.111.2/PKG-INFO → plain_postgres-0.113.0/plain/postgres/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.4
-Name: plain.postgres
-Version: 0.111.2
-Summary: Model your data and store it in a database.
-Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
-License-Expression: BSD-3-Clause
-License-File: LICENSE
-Requires-Python: >=3.13
-Requires-Dist: plain<1.0.0,>=0.134.0
-Requires-Dist: psycopg-pool>=3.2
-Requires-Dist: psycopg>=3.2
-Description-Content-Type: text/markdown
-
 # plain.postgres
 
 **Model your data and store it in a database.**
@@ -788,6 +775,26 @@ Environment overrides: every setting accepts `PLAIN_POSTGRES_*` env vars, so you
 PLAIN_POSTGRES_MIGRATION_STATEMENT_TIMEOUT=30s plain migrations apply
 ```
 
+### Schema lock
+
+Schema-changing commands — `plain postgres sync`, `plain migrations apply`, `plain postgres converge`, and `plain postgres drop-unknown-tables` — serialize on a single session-level advisory lock, so two deploy processes running at once (a retried migrate job, overlapping release phases) can't interleave schema changes. You don't have to do anything to get this.
+
+A second process warns and waits, retrying until the holder finishes:
+
+```python
+# app/settings.py — defaults shown (waits up to an hour total)
+POSTGRES_SCHEMA_LOCK_RETRY_INTERVAL = 5.0
+POSTGRES_SCHEMA_LOCK_MAX_RETRIES = 720
+```
+
+The wait is generous by default because a legitimate holder can be mid index build. If the budget runs out, the command fails with the holder's `pid` so you can see what's blocking. A crashed holder is not a problem — the lock releases automatically when its database session closes.
+
+The lock is held on its own connection, separate from the one running DDL, so non-transactional operations (`CREATE INDEX CONCURRENTLY`, `VALIDATE CONSTRAINT`) work normally while it's held. Session-level locks don't survive transaction-mode poolers like pgbouncer — if your `POSTGRES_URL` points at one, set [`POSTGRES_MANAGEMENT_URL`](#bypassing-a-connection-pooler-for-management-operations) to a direct connection.
+
+The lock connection sits idle while your DDL runs, so it enables TCP keepalives to survive NAT and load-balancer idle timeouts. A server-side `idle_session_timeout` would still kill it (releasing the lock mid-run) — don't set one for the role that runs migrations. `sync` re-verifies the lock between its migrate and converge phases and stops with a clear error if the session died.
+
+To see the lock live: `SELECT * FROM pg_locks WHERE locktype = 'advisory' AND objid = 1047265496`.
+
 ## Fields
 
 You can use many field types for different data:
@@ -921,6 +928,7 @@ Values are encrypted using Fernet (AES-128-CBC + HMAC-SHA256) with a key derived
 
 - **No lookups** — encrypted values are non-deterministic (same plaintext produces different ciphertext each time), so filtering on encrypted fields doesn't work. Only `isnull` lookups are supported.
 - **No indexes or constraints** — encrypted fields cannot be used in indexes or unique constraints. Preflight checks will catch this.
+- **Only `default=""`** — on `EncryptedTextField` (paired with `required=False`), the empty string is stored as plaintext `''`, so it's the one value expressible as a column `DEFAULT` (declare it to add the field to a populated table). Any other default would need ciphertext, which is non-deterministic. `EncryptedJSONField` accepts no default at all — even `{}` serializes to text that would need ciphertext; use `allow_null=True`.
 
 **Key rotation:**
 
@@ -1472,9 +1480,9 @@ See [`default_settings.py`](./default_settings.py) for more details.
 
 Add the field to your model class, then run `plain migrations create` to create a migration.
 
-If the field is required (no `default=` and not `allow_null=True`), the autodetector refuses to generate the migration, since there's no value to seed existing rows with. You have two options:
+If the field has no `default=` and isn't `allow_null=True`, the autodetector refuses to generate the migration, since there's no value to seed existing rows with — `required=False` alone is not enough (it only affects Python-side validation, not the column). You have two options:
 
-1. Declare a `default=` on the field so the new column has a value for existing rows.
+1. Declare a `default=` on the field so the new column has a value for existing rows. For an optional string field the idiom is `required=False, default=""` (for `BinaryField`, `default=b""`).
 2. Add the field with `allow_null=True`, scaffold a data migration with `plain migrations create --empty --name backfill_<field>` to populate existing rows, then remove `allow_null=True` from the field — convergence applies `NOT NULL` on the next `postgres sync`.
 
 #### How do I make an existing column `NOT NULL`?

{plain_postgres-0.111.2 → plain_postgres-0.113.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -79,7 +79,7 @@ Run `uv run plain docs postgres` for full patterns with code examples.
 - Indexes: `{table}_{column(s)}_idx`
 - Constraints: `{table}_{column(s)}_{type}` (e.g., `_unique`, `_check`)
 - Choose `on_delete` deliberately: CASCADE for owned children, RESTRICT for referenced data, SET_NULL for optional references
-- No `allow_null` on string fields — use `default=""`
+- No `allow_null` on string fields — use `default=""`. Optional string fields are `required=False, default=""` — the declared default is what lets the column be added to a populated table (`required=False` alone only affects Python-side validation)
 
 Run `uv run plain docs postgres` for full patterns with code examples.
 

{plain_postgres-0.111.2 → plain_postgres-0.113.0}/plain/postgres/cli/converge.py

@@ -5,7 +5,7 @@ import sys
 import click
 
 from ..convergence import execute_plan, plan_convergence
-from .decorators import database_management_command
+from .decorators import cli_schema_lock, database_management_command
 
 
 @click.command()
@@ -17,16 +17,16 @@ from .decorators import database_management_command
 )
 @database_management_command
 def converge(yes: bool) -> None:
-    """Fix schema mismatches between models and the database.
+    """Correct schema mismatches between models and the database.
 
-    Detects and fixes:
+    Detects and corrects:
     - Missing indexes (using CONCURRENTLY)
     - Missing constraints (check, unique)
     - NOT VALID constraints needing validation
     - Undeclared indexes and constraints (dropped automatically)
 
-    Each fix is applied and committed independently so partial
-    failures don't block subsequent fixes.
+    Each correction is applied and committed independently so partial
+    failures don't block subsequent corrections.
     """
     plan = plan_convergence()
     items = plan.executable()
@@ -34,7 +34,7 @@ def converge(yes: bool) -> None:
 
     if items:
         click.secho(
-            f"{len(items)} fix{'es' if len(items) != 1 else ''} to apply:\n",
+            f"{len(items)} correction{'s' if len(items) != 1 else ''} to apply:\n",
             bold=True,
         )
         for item in items:
@@ -48,7 +48,27 @@ def converge(yes: bool) -> None:
 
         click.echo()
 
-        result = execute_plan(items)
+        with cli_schema_lock():
+            # Re-plan under the lock — another converge or sync may have
+            # already applied (or changed) these corrections while we waited.
+            confirmed = {item.describe() for item in items}
+            plan = plan_convergence()
+            items = plan.executable()
+
+            new_items = [item for item in items if item.describe() not in confirmed]
+            if new_items and not yes:
+                # The plan grew while we waited at the prompt or for the
+                # lock — don't execute work the operator never approved.
+                click.secho(
+                    "The schema changed while waiting — new corrections not in the confirmed plan:",
+                    fg="red",
+                    bold=True,
+                )
+                for item in new_items:
+                    click.secho(f"  {item.describe()}", fg="red")
+                raise click.ClickException("Re-run to review the updated plan.")
+
+            result = execute_plan(items)
 
         for r in result.results:
             if r.ok:
@@ -73,4 +93,4 @@ def converge(yes: bool) -> None:
     if not success:
         sys.exit(1)
     elif not items:
-        click.secho("Schema is converged — nothing to fix.", fg="green")
+        click.secho("Schema is converged — nothing to correct.", fg="green")

{plain_postgres-0.111.2 → plain_postgres-0.113.0}/plain/postgres/cli/core.py

@@ -16,7 +16,7 @@ from ..database_url import postgres_cli_args, postgres_cli_env
 from ..db import get_connection
 from ..dialect import quote_name
 from .converge import converge
-from .decorators import database_management_command
+from .decorators import cli_schema_lock, database_management_command
 from .diagnose import diagnose
 from .schema import schema
 from .sync import sync
@@ -25,7 +25,7 @@ from .sync import sync
 @register_cli("postgres")
 @click.group()
 def cli() -> None:
-    """Postgres operations"""
+    """Work inside the connected database — schema, health, shell."""
 
 
 cli.add_command(converge)
@@ -126,13 +126,27 @@ def drop_unknown_tables(yes: bool) -> None:
         if not click.confirm(f"Drop {tables_label} (CASCADE)? This cannot be undone."):
             return
 
-    with conn.cursor() as cursor:
-        for table in unknown_tables:
-            click.echo(f"  Dropping {table}...", nl=False)
-            cursor.execute(f"DROP TABLE IF EXISTS {quote_name(table)} CASCADE")
-            click.echo(" OK")
-
-    click.secho(f"✓ Dropped {tables_label}.", fg="green")
+    with cli_schema_lock():
+        # Re-check under the lock — while we sat at the prompt or waited for
+        # the lock, another process may have claimed one of these names for a
+        # real table (e.g. a migration creating a model table). Only drop
+        # what was unknown at confirm time AND is still unknown now.
+        still_unknown = set(get_unknown_tables(conn))
+        dropped_count = 0
+        with conn.cursor() as cursor:
+            for table in unknown_tables:
+                if table not in still_unknown:
+                    click.secho(f"  Skipping {table} — no longer unknown.", fg="yellow")
+                    continue
+                click.echo(f"  Dropping {table}...", nl=False)
+                cursor.execute(f"DROP TABLE IF EXISTS {quote_name(table)} CASCADE")
+                click.echo(" OK")
+                dropped_count += 1
+
+    click.secho(
+        f"✓ Dropped {dropped_count} table{'s' if dropped_count != 1 else ''}.",
+        fg="green",
+    )
 
 
 @cli.command()

{plain_postgres-0.111.2 → plain_postgres-0.113.0}/plain/postgres/cli/decorators.py

@@ -1,10 +1,26 @@
 from __future__ import annotations
 
 import functools
-from collections.abc import Callable
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
 from typing import Any
 
+import click
+
 from ..db import use_management_connection
+from ..schema_lock import SchemaLockLost, SchemaLockTimeout, schema_lock
+
+
+@contextmanager
+def cli_schema_lock() -> Iterator[Callable[[], None]]:
+    """`schema_lock()` for CLI commands: a timeout or lost lock surfaces as a
+    clean one-line error instead of a traceback burying it. Yields the lock's
+    verify callable for multi-phase commands to check between phases."""
+    try:
+        with schema_lock() as verify:
+            yield verify
+    except (SchemaLockTimeout, SchemaLockLost) as e:
+        raise click.ClickException(str(e)) from e
 
 
 def database_management_command[F: Callable[..., Any]](f: F) -> F:

{plain_postgres-0.111.2 → plain_postgres-0.113.0}/plain/postgres/cli/migrations.py

@@ -27,7 +27,7 @@ from ..migrations.recorder import MigrationRecorder
 from ..migrations.state import ModelState, ProjectState
 from ..migrations.writer import MigrationWriter
 from ..registry import models_registry
-from .decorators import database_management_command
+from .decorators import cli_schema_lock, database_management_command
 
 if TYPE_CHECKING:
     from ..connection import DatabaseConnection
@@ -511,68 +511,84 @@ def apply(
             click.secho(package_label, dim=True)
             click.echo()  # Add newline after package
 
-    pre_migrate_state = executor._create_project_state(with_applied_migrations=True)
-
     if migration_plan:
-        # Determine whether to use atomic batch
-        use_atomic_batch = False
-        atomic_batch_message = None
-        if len(migration_plan) > 1:
-            # Check if all migrations support atomic
-            non_atomic_migrations = [m for m in migration_plan if not m.atomic]
-
-            if atomic_batch is True:
-                # User explicitly requested atomic batch
-                if non_atomic_migrations:
-                    names = ", ".join(
-                        f"{m.package_label}.{m.name}" for m in non_atomic_migrations[:3]
-                    )
-                    if len(non_atomic_migrations) > 3:
-                        names += f", and {len(non_atomic_migrations) - 3} more"
-                    raise click.UsageError(
-                        f"--atomic-batch requested but these migrations have atomic=False: {names}"
-                    )
-                use_atomic_batch = True
-                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 len(migration_plan) > 1:
-                    atomic_batch_message = (
-                        f"Running {len(migration_plan)} migrations separately"
+        with cli_schema_lock():
+            # Re-plan under the lock — another process may have applied some
+            # or all of these migrations while we waited for it.
+            executor = MigrationExecutor(get_connection(), migration_progress_callback)
+            migration_plan = executor.migration_plan(targets)
+            if not migration_plan:
+                if not quiet:
+                    click.echo(
+                        "No migrations to apply (another process already applied them)."
                     )
-            else:
-                # Auto-detect (atomic_batch is None)
-                # Use atomic batch by default
-                if not non_atomic_migrations:
+                return
+
+            # Determine whether to use atomic batch
+            use_atomic_batch = False
+            atomic_batch_message = None
+            if len(migration_plan) > 1:
+                # Check if all migrations support atomic
+                non_atomic_migrations = [m for m in migration_plan if not m.atomic]
+
+                if atomic_batch is True:
+                    # User explicitly requested atomic batch
+                    if non_atomic_migrations:
+                        names = ", ".join(
+                            f"{m.package_label}.{m.name}"
+                            for m in non_atomic_migrations[:3]
+                        )
+                        if len(non_atomic_migrations) > 3:
+                            names += f", and {len(non_atomic_migrations) - 3} more"
+                        raise click.UsageError(
+                            f"--atomic-batch requested but these migrations have atomic=False: {names}"
+                        )
                     use_atomic_batch = True
                     atomic_batch_message = (
                         f"Running {len(migration_plan)} migrations in atomic batch"
                     )
-                else:
+                elif atomic_batch is False:
+                    # User explicitly disabled atomic batch
                     use_atomic_batch = False
                     if len(migration_plan) > 1:
-                        atomic_batch_message = f"Running {len(migration_plan)} migrations separately (some have atomic=False)"
-
-        if not quiet:
-            click.echo()  # Add blank line before applying
+                        atomic_batch_message = (
+                            f"Running {len(migration_plan)} migrations separately"
+                        )
+                else:
+                    # Auto-detect (atomic_batch is None)
+                    # Use atomic batch by default
+                    if not non_atomic_migrations:
+                        use_atomic_batch = True
+                        atomic_batch_message = (
+                            f"Running {len(migration_plan)} migrations in atomic batch"
+                        )
+                    else:
+                        use_atomic_batch = False
+                        if len(migration_plan) > 1:
+                            atomic_batch_message = f"Running {len(migration_plan)} migrations separately (some have atomic=False)"
+
+            if not quiet:
+                click.echo()  # Add blank line before applying
+
+            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)
 
-        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,
-            state=pre_migrate_state.clone(),
-            fake=fake,
-            atomic_batch=use_atomic_batch,
-        )
+            pre_migrate_state = executor._create_project_state(
+                with_applied_migrations=True
+            )
+            post_migrate_state = executor.migrate(
+                targets,
+                plan=migration_plan,
+                state=pre_migrate_state.clone(),
+                fake=fake,
+                atomic_batch=use_atomic_batch,
+            )
         # post_migrate signals have access to all models. Ensure that all models
         # are reloaded in case any are delayed.
         post_migrate_state.clear_delayed_models_cache()

{plain_postgres-0.111.2 → plain_postgres-0.113.0}/plain/postgres/cli/schema.py

@@ -6,7 +6,7 @@ import sys
 import click
 
 from ..convergence.analysis import ModelAnalysis, analyze_model
-from ..convergence.planning import can_auto_fix
+from ..convergence.planning import can_auto_correct
 from ..db import get_connection
 from ..introspection import MANAGED_CONSTRAINT_TYPES, get_unknown_tables
 from ..registry import models_registry
@@ -21,8 +21,8 @@ def _err(msg: str) -> None:
     click.secho(f"  ✗ {msg}", fg="red")
 
 
-def _fixable(msg: str) -> None:
-    click.secho(f"  ~ {msg} (auto-fix)", fg="yellow")
+def _correctable(msg: str) -> None:
+    click.secho(f"  ~ {msg} (auto-correct)", fg="yellow")
 
 
 def _unmanaged(type_label: str) -> None:
@@ -57,8 +57,8 @@ def _render_model(analysis: ModelAnalysis) -> None:
 
         click.echo(f"  {col_display:30s}  {' '.join(type_parts)}", nl=False)
 
-        if col.issue and col.drifts and all(can_auto_fix(d) for d in col.drifts):
-            _fixable(col.issue)
+        if col.issue and col.drifts and all(can_auto_correct(d) for d in col.drifts):
+            _correctable(col.issue)
         elif col.issue:
             _err(col.issue)
         else:
@@ -75,8 +75,8 @@ def _render_model(analysis: ModelAnalysis) -> None:
 
         if idx.access_method:
             _unmanaged(idx.access_method)
-        elif idx.issue and idx.drift and can_auto_fix(idx.drift):
-            _fixable(idx.issue)
+        elif idx.issue and idx.drift and can_auto_correct(idx.drift):
+            _correctable(idx.issue)
         elif idx.issue:
             _err(idx.issue)
         else:
@@ -98,8 +98,8 @@ def _render_model(analysis: ModelAnalysis) -> None:
 
         if con.constraint_type not in MANAGED_CONSTRAINT_TYPES:
             _unmanaged(con.constraint_type.label)
-        elif con.issue and con.drift and can_auto_fix(con.drift):
-            _fixable(con.issue)
+        elif con.issue and con.drift and can_auto_correct(con.drift):
+            _correctable(con.issue)
         elif con.issue:
             _err(con.issue)
         else:

{plain_postgres-0.111.2 → plain_postgres-0.113.0}/plain/postgres/cli/sync.py

@@ -7,7 +7,8 @@ import click
 from plain.runtime import settings
 
 from ..convergence import execute_plan, plan_convergence
-from .decorators import database_management_command
+from ..db import get_connection
+from .decorators import cli_schema_lock, database_management_command
 
 
 @click.command()
@@ -33,8 +34,12 @@ def sync(check: bool) -> None:
     if settings.DEBUG:
         _create_migrations()
 
-    _migrate()
-    _converge()
+    with cli_schema_lock() as verify_lock:
+        _migrate()
+        # If the lock session died during migrations, another process may
+        # already be converging — stop instead of interleaving with it.
+        verify_lock()
+        _converge()
 
 
 def _check() -> None:
@@ -108,7 +113,6 @@ def _create_migrations() -> None:
 
 
 def _migrate() -> None:
-    from ..db import get_connection
     from ..migrations.executor import MigrationExecutor
 
     click.secho("Applying migrations...", bold=True)

{plain_postgres-0.111.2 → plain_postgres-0.113.0}/plain/postgres/convergence/__init__.py

@@ -5,8 +5,8 @@ This is not a public import API. End users drive convergence through those CLI
 commands, not by importing from here, and it is intentionally absent from the
 top-level ``plain.postgres`` surface. The names re-exported below exist for the
 rest of ``plain.postgres`` (the CLI) to use; the drift types, ``DriftKind``,
-the ``Fix`` classes, and the ``Status`` records are convergence-internal and
-live in the ``.analysis`` / ``.fixes`` / ``.planning`` submodules.
+the ``Correction`` classes, and the ``Status`` records are convergence-internal and
+live in the ``.analysis`` / ``.corrections`` / ``.planning`` submodules.
 """
 
 from .analysis import (
@@ -17,9 +17,9 @@ from .analysis import (
 from .planning import (
     ConvergencePlan,
     ConvergenceResult,
-    FixResult,
+    CorrectionResult,
     PlanItem,
-    can_auto_fix,
+    can_auto_correct,
     execute_plan,
     plan_convergence,
     plan_model_convergence,
@@ -28,12 +28,12 @@ from .planning import (
 __all__ = [
     "ConvergencePlan",
     "ConvergenceResult",
-    "FixResult",
+    "CorrectionResult",
     "ModelAnalysis",
     "PlanItem",
     "ReadOnlyConnectionError",
     "analyze_model",
-    "can_auto_fix",
+    "can_auto_correct",
     "execute_plan",
     "plan_convergence",
     "plan_model_convergence",

{plain_postgres-0.111.2 → plain_postgres-0.113.0}/plain/postgres/convergence/analysis.py

@@ -220,7 +220,7 @@ class ColumnShouldBeNotNullDrift:
 
     table: str
     column: str
-    has_null_rows: bool = False  # existing NULL rows block an auto-fix
+    has_null_rows: bool = False  # existing NULL rows block an auto-correction
 
     def describe(self) -> str:
         if self.has_null_rows:
@@ -1166,7 +1166,7 @@ def _compare_check_constraints(
             )
 
     # Build set of framework-owned temp NOT NULL check names so leftover
-    # artifacts from a partially-completed SetNotNullFix are silently
+    # artifacts from a partially-completed SetNotNullCorrection are silently
     # ignored rather than surfaced as undeclared user constraints.
     internal_checks = {
         generate_notnull_check_name(table, f.column)
@@ -1326,7 +1326,7 @@ def _compare_foreign_keys(
 def generate_notnull_check_name(table: str, column: str) -> str:
     """Generate a hashed name for the temporary NOT NULL check constraint.
 
-    Used by SetNotNullFix for the CHECK NOT VALID → VALIDATE → SET NOT NULL
+    Used by SetNotNullCorrection for the CHECK NOT VALID → VALIDATE → SET NOT NULL
     pattern, and by analysis to recognize (and ignore) leftover temp checks.
     """
     from ..utils import generate_identifier_name