plain.postgres 0.108.0__tar.gz → 0.109.0__tar.gz

{plain_postgres-0.108.0 → plain_postgres-0.109.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.108.0
+Version: 0.109.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause
@@ -957,7 +957,7 @@ book.author.name   # one query — loads the rest of the row
 
 The first access to any non-key field loads the whole row in a single query. There is no separate `author_id` attribute — `book.author.id` is the foreign key value, and it is type-checked because `book.author` is an `Author`. In loops, use `select_related()` to load related rows up front and avoid a query per row.
 
-The partial-instance shortcut relies on the database guaranteeing the row exists. A foreign key declared with `db_constraint=False` has no such guarantee, so it is queried on access instead — a stale key raises `DoesNotExist` right away rather than yielding a placeholder.
+The partial-instance shortcut is safe because Plain always creates a database foreign-key constraint, so the referenced row is guaranteed to exist.
 
 ### Reverse relationships
 

{plain_postgres-0.108.0 → plain_postgres-0.109.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,32 @@
 # plain-postgres changelog
 
+## [0.109.0](https://github.com/dropseed/plain/releases/plain-postgres@0.109.0) (2026-06-17)
+
+### What's changed
+
+- **The `db_constraint` argument is removed from `ForeignKeyField` — every foreign key is now backed by a database `FOREIGN KEY` constraint, always.** Because the database guarantees the referenced row exists, accessing a foreign key always builds a partial related instance from just the stored id (no query); the old "query on access when unconstrained" path is gone. The `fields.foreign_key_unconstrained_requires_no_action` preflight check is also removed. ([9ec559db38](https://github.com/dropseed/plain/commit/9ec559db38))
+- **`limit_choices_to` is removed from `ForeignKeyField` and `ManyToManyField`.** The supporting machinery goes with it: `RelatedField.get_choices()` / `get_limit_choices_to()`, `ForeignObjectRel.get_choices()`, and `QuerySet.complex_filter()` are removed, and `BLANK_CHOICE_DASH` is no longer exported from `plain.postgres.fields`. To restrict the rows offered for a relation, filter the queryset explicitly in your form or view. ([68b6ced4f0](https://github.com/dropseed/plain/commit/68b6ced4f0))
+- **The redundant foreign-key existence pre-check is removed.** `ForeignKeyField.validate()` no longer runs a `SELECT ... EXISTS` query to confirm the target row exists — one fewer query per FK validation. The database `FOREIGN KEY` constraint already enforces this, rejecting an invalid reference at write time (as a `psycopg.IntegrityError`). ([68b6ced4f0](https://github.com/dropseed/plain/commit/68b6ced4f0))
+- Internal: convergence (schema-drift) analysis now reuses a single session-private temp "probe" table per model across all of that model's round-trip comparisons, instead of creating and dropping one per index/constraint/default comparison — fewer DDL statements during schema checks. The internal `canon*` helpers were renamed to `probe`/`normalize`. ([67167a11ee](https://github.com/dropseed/plain/commit/67167a11ee), [06650bea63](https://github.com/dropseed/plain/commit/06650bea63))
+
+### Upgrade instructions
+
+- Remove any `db_constraint=False` arguments from `ForeignKeyField`. Foreign keys are always DB-constrained now; an unconstrained FK (e.g. for soft/cross-system references) is no longer supported.
+- Remove `limit_choices_to=` from `ForeignKeyField` / `ManyToManyField` definitions. To constrain the rows offered for a relation, filter the related queryset explicitly in your form or view.
+- Replace any `QuerySet.complex_filter(...)` calls with `.filter(...)` — pass a dict of lookups or a `Q` object directly.
+- Most projects use none of these and need no changes. The `/plain-upgrade` skill handles the rewrites.
+
+## [0.108.1](https://github.com/dropseed/plain/releases/plain-postgres@0.108.1) (2026-06-09)
+
+### What's changed
+
+- `ensure_connection()` now detects a pooled connection the server has closed while it was held (Postgres restart, failover, idle timeout) and discards it before establishing a fresh one — logging a "Discarding dead database connection" warning — instead of repeatedly failing on the dead connection. Inside an atomic block the dead connection is intentionally left in place so the transaction's normal error handling runs, rather than silently continuing the rest of the block outside its transaction. ([9e82cb4454](https://github.com/dropseed/plain/commit/9e82cb4454))
+- Query span instrumentation no longer pays for expensive attributes when the span is sampled out: the per-query Python stack walk (for `code.*` attributes) and the `DEBUG`-mode stringification of query parameters now only happen when the span is actually recording. The cheap connection attributes are still passed at span creation so attribute-aware samplers can see them in `should_sample()`. ([af736043b0](https://github.com/dropseed/plain/commit/af736043b0))
+
+### Upgrade instructions
+
+- No changes required.
+
 ## [0.108.0](https://github.com/dropseed/plain/releases/plain-postgres@0.108.0) (2026-06-09)
 
 ### What's changed

{plain_postgres-0.108.0 → plain_postgres-0.109.0}/plain/postgres/README.md

@@ -944,7 +944,7 @@ book.author.name   # one query — loads the rest of the row
 
 The first access to any non-key field loads the whole row in a single query. There is no separate `author_id` attribute — `book.author.id` is the foreign key value, and it is type-checked because `book.author` is an `Author`. In loops, use `select_related()` to load related rows up front and avoid a query per row.
 
-The partial-instance shortcut relies on the database guaranteeing the row exists. A foreign key declared with `db_constraint=False` has no such guarantee, so it is queried on access instead — a stale key raises `DoesNotExist` right away rather than yielding a placeholder.
+The partial-instance shortcut is safe because Plain always creates a database foreign-key constraint, so the referenced row is guaranteed to exist.
 
 ### Reverse relationships
 

{plain_postgres-0.108.0 → plain_postgres-0.109.0}/plain/postgres/connection.py

@@ -170,7 +170,19 @@ class DatabaseConnection:
         self.set_autocommit(True)
 
     def ensure_connection(self) -> None:
-        """Guarantee that a connection to the database is established."""
+        """Guarantee that a live connection to the database is established."""
+        if (
+            self.connection is not None
+            and self.connection.closed
+            and not self.in_atomic_block
+        ):
+            # The server closed this connection while we held it (restart,
+            # failover, idle timeout) — psycopg marks it closed once an
+            # operation fails on it. Mid-atomic, swapping it would silently
+            # run the rest of the block outside its transaction — leave the
+            # dead connection for Atomic.__exit__'s error recovery instead.
+            logger.warning("Discarding dead database connection")
+            self.close()
         if self.connection is None:
             self.connect()
 
@@ -634,7 +646,7 @@ class DatabaseConnection:
             }
         # Now get indexes. Sort order, opclasses, INCLUDE, and predicates all
         # ride along inside `pg_get_indexdef` and are compared via the
-        # canonical-tail round-trip in convergence — no need to introspect
+        # normalized-tail round-trip in convergence — no need to introspect
         # them here as separate columns.
         cursor.execute(
             """

{plain_postgres-0.108.0 → plain_postgres-0.109.0}/plain/postgres/convergence/analysis.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import contextvars
 import json
 import re
 from collections.abc import Iterator
@@ -370,14 +371,15 @@ def analyze_model(
             table_issues=["table missing from database"],
         )
 
-    return ModelAnalysis(
-        label=model.model_options.label,
-        table=table_name,
-        columns=_compare_columns(model, db, table_name, cursor),
-        indexes=_compare_indexes(cursor, model, db, table_name),
-        constraints=_compare_constraints(cursor, model, db, table_name),
-        storage_parameter_drifts=_compare_storage_parameters(model, db, table_name),
-    )
+    with _probe_session(cursor, model):
+        return ModelAnalysis(
+            label=model.model_options.label,
+            table=table_name,
+            columns=_compare_columns(model, db, table_name, cursor),
+            indexes=_compare_indexes(cursor, model, db, table_name),
+            constraints=_compare_constraints(cursor, model, db, table_name),
+            storage_parameter_drifts=_compare_storage_parameters(model, db, table_name),
+        )
 
 
 def _compare_storage_parameters(
@@ -538,7 +540,7 @@ def _extract_jsonb_literal(sql: str) -> str | None:
     return m.group(1).replace("''", "'")
 
 
-def _canonicalize_default_expr(
+def _normalize_default_expr(
     cursor: CursorWrapper, model: type[Model], column: str, default_sql: str
 ) -> str:
     """Round-trip a column DEFAULT through Postgres so both sides of the
@@ -550,9 +552,9 @@ def _canonicalize_default_expr(
     comparison then sees inequality and reports drift.
     """
     try:
-        with _canon_table(cursor, model):
+        with _probe_table(cursor, model):
             cursor.execute(
-                f"ALTER TABLE {_CANON_TABLE} ALTER COLUMN {quote_name(column)} "
+                f"ALTER TABLE {_PROBE_TABLE} ALTER COLUMN {quote_name(column)} "
                 f"SET DEFAULT {default_sql}"
             )
             cursor.execute(
@@ -561,11 +563,11 @@ def _canonicalize_default_expr(
                 "WHERE a.attrelid = (SELECT oid FROM pg_class WHERE relname = %s "
                 "AND relnamespace = pg_my_temp_schema()) "
                 "AND a.attname = %s",
-                [_CANON_TABLE, column],
+                [_PROBE_TABLE, column],
             )
             row = cursor.fetchone()
             return row[0] if row else ""
-    except _CANON_FALLBACK_ERRORS:
+    except _PROBE_FALLBACK_ERRORS:
         return ""
 
 
@@ -589,14 +591,14 @@ def _compare_column_default(
                 model_default_sql=expected_sql,
             )
 
-        canonical_expected = _canonicalize_default_expr(
+        normalized_expected = _normalize_default_expr(
             cursor, field.model, field.column, expected_sql
         )
-        if canonical_expected == actual.default_sql:
+        if normalized_expected == actual.default_sql:
             return None
-        # Semantic compare for jsonb — PG canonicalizes object keys, which
+        # Semantic compare for jsonb — PG normalizes object keys, which
         # won't match Python's dict-insertion order even after a round-trip.
-        m_json = _extract_jsonb_literal(canonical_expected)
+        m_json = _extract_jsonb_literal(normalized_expected)
         d_json = _extract_jsonb_literal(actual.default_sql)
         if m_json is not None and d_json is not None:
             try:
@@ -681,7 +683,7 @@ def _compare_indexes(
 
         # Check if definition matches
         if db_idx.definition:
-            issue = _compare_canonical_index(
+            issue = _compare_normalized_index(
                 cursor=cursor,
                 model=model,
                 expressions=index.expressions,
@@ -725,9 +727,9 @@ def _compare_indexes(
         if non_unique_indexes[n].access_method in MANAGED_INDEX_ACCESS_METHODS
     ]
 
-    # Detect renames by canonical (round-tripped) index body. Build the cheap
+    # Detect renames by normalized (round-tripped) index body. Build the cheap
     # already-introspected side first so we can skip the per-missing
-    # canonicalization loop on the steady-state path.
+    # normalization loop on the steady-state path.
     renamed_missing: set[str] = set()
     renamed_extra: set[str] = set()
 
@@ -740,7 +742,7 @@ def _compare_indexes(
     missing_by_def: dict[str, list[Index]] = {}
     if extra_by_def:
         for index in missing:
-            expected_tail = _canonicalize_index_def(
+            expected_tail = _normalize_index_def(
                 cursor,
                 model,
                 expressions=index.expressions,
@@ -750,7 +752,7 @@ def _compare_indexes(
                 include=index.include,
             )
             if not expected_tail:
-                # Canonicalization failed; bucketing under "" would conflate
+                # Normalization failed; bucketing under "" would conflate
                 # multiple sentinel-failing indexes and disable rename
                 # detection for the rest.
                 continue
@@ -908,7 +910,7 @@ def _compare_unique_constraints(
                 if expected_def:
                     issue = f"definition differs: DB has {actual_def!r}, model expects {expected_def!r}"
                 else:
-                    # Round-trip canonicalization couldn't complete; canonical
+                    # Round-trip normalization couldn't complete; normalized
                     # model text is unavailable for the diagnostic.
                     issue = f"definition differs: DB has {actual_def!r}"
                 drift = ConstraintDrift(
@@ -1013,7 +1015,7 @@ def _compare_check_constraints(
                 if expected_def:
                     issue = f"definition differs: DB has {actual_def!r}, model expects {expected_def!r}"
                 else:
-                    # Round-trip canonicalization couldn't complete; canonical
+                    # Round-trip normalization couldn't complete; normalized
                     # model text is unavailable for the diagnostic.
                     issue = f"definition differs: DB has {actual_def!r}"
                 drift = ConstraintDrift(
@@ -1099,7 +1101,7 @@ def _compare_foreign_keys(
     # Value: (field_name, constraint_name, expected_on_delete_clause, expected_confdeltype)
     expected_fks: dict[tuple[str, str, str], tuple[str, str, str, str]] = {}
     for f in model._model_meta.local_fields:
-        if isinstance(f, ForeignKeyField) and f.db_constraint:
+        if isinstance(f, ForeignKeyField):
             assert f.name is not None
             to_table = f.target_field.model.model_options.db_table
             to_column = f.target_field.column
@@ -1251,7 +1253,7 @@ def _detect_unique_renames(
     """Match missing and extra unique constraints by structure.
 
     Constraint-backed (not index_only): matched by resolved column tuple.
-    Index-only (condition/expression/opclass): matched by canonical
+    Index-only (condition/expression/opclass): matched by normalized
     (round-tripped) index definition, which captures the full semantics
     including WHERE clauses, opclasses, and expressions.
     """
@@ -1290,7 +1292,7 @@ def _detect_unique_renames(
                 old_def = actual_dict[old_name].definition
                 if not old_def:
                     continue
-                expected_tail = _canonicalize_index_def(
+                expected_tail = _normalize_index_def(
                     cursor,
                     model,
                     expressions=constraint.expressions,
@@ -1322,7 +1324,7 @@ def _detect_unique_renames(
             renamed_missing.add(constraint.name)
             renamed_extra.add(old_name)
 
-    # Phase 2: Expression-based — match by canonical (round-tripped) index
+    # Phase 2: Expression-based — match by normalized (round-tripped) index
     # body. Build the cheap already-introspected extras side first so we can
     # skip the per-missing round-trip on the steady-state path.
     extra_by_def: dict[str, list[str]] = {}
@@ -1340,7 +1342,7 @@ def _detect_unique_renames(
                 continue
             # constraint.fields is empty here (filtered above), so this is
             # the expression-based path — fields_orders is unused.
-            expected_tail = _canonicalize_index_def(
+            expected_tail = _normalize_index_def(
                 cursor,
                 model,
                 expressions=constraint.expressions,
@@ -1389,12 +1391,12 @@ def _detect_check_renames(
     model: type[Model],
     table: str,
 ) -> tuple[list[ConstraintStatus], set[str], set[str]]:
-    """Match missing and extra check constraints by canonical definition."""
+    """Match missing and extra check constraints by normalized definition."""
     statuses: list[ConstraintStatus] = []
     renamed_missing: set[str] = set()
     renamed_extra: set[str] = set()
 
-    # Skip the round-trip canonicalization loop if there are no extras to
+    # Skip the round-trip normalization loop if there are no extras to
     # potentially match — the steady-state path with no drift.
     extra_by_def: dict[str, list[str]] = {}
     for name in extra_names:
@@ -1406,7 +1408,7 @@ def _detect_check_renames(
         for constraint in missing:
             expected_def = _get_expected_check_definition(cursor, model, constraint)
             if not expected_def:
-                # Canonicalization failed; bucketing under "" would conflate
+                # Normalization failed; bucketing under "" would conflate
                 # multiple sentinel-failing constraints and disable rename
                 # detection for the rest.
                 continue
@@ -1454,7 +1456,7 @@ def _compare_index_only_unique(
     if not actual_def:
         return None, None
 
-    issue = _compare_canonical_index(
+    issue = _compare_normalized_index(
         cursor=cursor,
         model=model,
         expressions=constraint.expressions,
@@ -1474,7 +1476,7 @@ def _compare_index_only_unique(
     return None, None
 
 
-def _compare_canonical_index(
+def _compare_normalized_index(
     *,
     cursor: CursorWrapper,
     model: type[Model],
@@ -1489,11 +1491,11 @@ def _compare_canonical_index(
     """Compare a model index/constraint against pg_get_indexdef text.
 
     Round-trips the model side through Postgres so both sides come from
-    pg_get_indexdef, then string-compares the canonical `USING ...` bodies.
+    pg_get_indexdef, then string-compares the normalized `USING ...` bodies.
 
     Returns an issue string if definitions differ, None if they match.
     """
-    expected_tail = _canonicalize_index_def(
+    expected_tail = _normalize_index_def(
         cursor,
         model,
         expressions=expressions,
@@ -1505,9 +1507,9 @@ def _compare_canonical_index(
     )
     actual_tail = _index_def_tail(actual_def)
     if not expected_tail:
-        # Round-trip canonicalization couldn't complete (model SQL
+        # Round-trip normalization couldn't complete (model SQL
         # incompatible with live shape). Report drift with the actual text;
-        # the canonical model text is unavailable for the diagnostic.
+        # the normalized model text is unavailable for the diagnostic.
         return f"definition differs: DB has {actual_tail!r}"
 
     if actual_tail != expected_tail:
@@ -1518,11 +1520,11 @@ def _compare_canonical_index(
     return None
 
 
-# Round-trip canonicalization: feed model-side SQL to Postgres on a
+# Round-trip normalization: feed model-side SQL to Postgres on a
 # session-private temp table, read back via pg_get_*.
-_CANON_TABLE = "_plain_canon"
-_CANON_CONSTRAINT = "_c"
-_CANON_INDEX = "_canon_ix"
+_PROBE_TABLE = "_plain_convergence_probe"
+_PROBE_CONSTRAINT = "_c"
+_PROBE_INDEX = "_probe_ix"
 
 # Errors raised by Postgres when the model SQL is incompatible with the live
 # table shape (unmigrated column types, references to dropped columns, etc.).
@@ -1534,7 +1536,7 @@ _CANON_INDEX = "_canon_ix"
 # privilege failures (InsufficientPrivilege, also a ProgrammingError) and
 # plain-side syntax bugs must propagate so users get a clear diagnostic
 # instead of silent drift noise.
-_CANON_FALLBACK_ERRORS: tuple[type[Exception], ...] = (
+_PROBE_FALLBACK_ERRORS: tuple[type[Exception], ...] = (
     psycopg.errors.UndefinedColumn,
     psycopg.errors.UndefinedFunction,
     psycopg.errors.UndefinedObject,
@@ -1553,45 +1555,120 @@ _CANON_FALLBACK_ERRORS: tuple[type[Exception], ...] = (
 class ReadOnlyConnectionError(RuntimeError):
     """Raised when convergence analysis runs on a read-only connection.
 
-    Analysis canonicalizes the model side of each comparison by round-tripping
+    Analysis normalizes the model side of each comparison by round-tripping
     SQL through a session-private temp table. That requires DDL, which is
     rejected on standby connections and inside `read_only()` blocks.
     """
 
 
+_READ_ONLY_MESSAGE = (
+    "Convergence analysis requires write access — it normalizes model SQL by "
+    "creating a session-private temp table. The current connection rejected "
+    "DDL (read-only transaction or standby). Run analysis against a "
+    "primary/writable connection."
+)
+
+
+@dataclass
+class _ProbeSession:
+    """Reuse scope for one model's probe table (see `_probe_session`)."""
+
+    model: type[Model]
+    created: bool = False
+
+
+# Set while `analyze_model` runs so the per-comparison probes share one temp
+# table instead of creating and dropping one each. A single connection is
+# single-threaded, but a ContextVar keeps the scope clean and never leaks the
+# session if analysis raises.
+_active_probe_session: contextvars.ContextVar[_ProbeSession | None] = (
+    contextvars.ContextVar("active_probe_session", default=None)
+)
+
+
 @contextmanager
-def _canon_table(cursor: CursorWrapper, model: type[Model]) -> Iterator[None]:
-    """Set up a session-private temp table mirroring the model's real table.
-
-    `cursor.connection.transaction()` issues a SAVEPOINT when nested (or BEGIN
-    when run in autocommit). Either way, a model SQL statement incompatible
-    with the live column shape (e.g. a CHECK referencing a column whose live
-    type differs from what the model now declares) rolls back to this scope
-    rather than poisoning the surrounding analyze transaction. Helpers catch
-    psycopg errors and fall back to a sentinel — drift still gets reported,
-    just without the canonical model text.
-
-    The trailing DROP is schema-qualified to `pg_temp` so a stray real table
-    sharing the name (in the user's own schema) can't be hit by mistake. A
-    single connection is always single-threaded, so reusing the name across
-    helpers is safe.
+def _probe_session(cursor: CursorWrapper, model: type[Model]) -> Iterator[None]:
+    """Reuse one probe table across every round-trip in a model's analysis.
+
+    The temp table is created lazily by the first probe inside this scope and
+    dropped once on exit, so a model with no expression/constraint round-trips
+    creates nothing while a model with many shares a single table instead of
+    churning one per comparison. The exit DROP runs only on the success path —
+    on an error it's skipped to avoid dropping against an aborted connection, so
+    the table can briefly outlive the analysis (autocommit commits the CREATE);
+    the next analysis recreates it cleanly (see `_create_probe_table`).
+    """
+    session = _ProbeSession(model=model)
+    token = _active_probe_session.set(session)
+    try:
+        yield
+    finally:
+        _active_probe_session.reset(token)
+    if session.created:
+        cursor.execute(f"DROP TABLE pg_temp.{_PROBE_TABLE}")
+
+
+def _create_probe_table(cursor: CursorWrapper, model: type[Model]) -> None:
+    """(Re)create the session-private probe table mirroring the model's real table.
+
+    Drops any stale table of the same name first so a leak can't wedge analysis:
+    the shipped CLI runs convergence in autocommit, so the CREATE commits before
+    later probes run, and a non-fallback error escaping `analyze_model` would
+    otherwise leave the table on a pooled connection to collide with the next
+    run's CREATE. The
+    DROP is schema-qualified to `pg_temp` so a real table sharing the name (in
+    the user's own schema) can't be hit by mistake. Raises ReadOnlyConnectionError
+    when the connection rejects the DDL.
     """
     table = quote_name(model.model_options.db_table)
     try:
         with cursor.connection.transaction():
-            cursor.execute(f"CREATE TEMP TABLE {_CANON_TABLE} (LIKE {table})")
-            yield
-            cursor.execute(f"DROP TABLE pg_temp.{_CANON_TABLE}")
+            cursor.execute(f"DROP TABLE IF EXISTS pg_temp.{_PROBE_TABLE}")
+            cursor.execute(f"CREATE TEMP TABLE {_PROBE_TABLE} (LIKE {table})")
     except psycopg.errors.ReadOnlySqlTransaction as exc:
-        raise ReadOnlyConnectionError(
-            "Convergence analysis requires write access — it canonicalizes "
-            "model SQL by creating a session-private temp table. The current "
-            "connection rejected DDL (read-only transaction or standby). Run "
-            "analysis against a primary/writable connection."
-        ) from exc
+        raise ReadOnlyConnectionError(_READ_ONLY_MESSAGE) from exc
+
+
+@contextmanager
+def _probe_table(cursor: CursorWrapper, model: type[Model]) -> Iterator[None]:
+    """Provide an empty temp table mirroring the model's real table for one
+    round-trip, isolating the probe's DDL so it can't leak into the analyze
+    transaction.
+
+    Inside an active `_probe_session` for the same model, the table is created
+    once and reused: each probe runs in a SAVEPOINT that is always rolled back,
+    undoing the probe's ADD/ALTER while leaving the shared table in place.
+    Outside a session, the table is created and dropped for this one probe.
+
+    `cursor.connection.transaction()` issues a SAVEPOINT when nested (or BEGIN in
+    autocommit), so model SQL incompatible with the live column shape rolls back
+    to this scope instead of poisoning the surrounding transaction; helpers catch
+    the psycopg error and fall back to a sentinel.
+    """
+    session = _active_probe_session.get()
+    if session is not None and session.model is model:
+        # Reuse the session's shared table; `_probe_session` owns its lifetime.
+        if not session.created:
+            _create_probe_table(cursor, model)
+            session.created = True
+        drop_on_exit = False
+    else:
+        # No session: this probe owns the table for its lifetime.
+        _create_probe_table(cursor, model)
+        drop_on_exit = True
+
+    try:
+        with cursor.connection.transaction() as savepoint:
+            yield
+            # Probe read its definition; undo the ADD/ALTER but keep the table.
+            # psycopg rolls the SAVEPOINT back without surfacing an error.
+            raise psycopg.Rollback(savepoint)
+    finally:
+        if drop_on_exit:
+            cursor.execute(f"DROP TABLE pg_temp.{_PROBE_TABLE}")
 
 
-def _canonicalize_constraint_def(
+def _normalize_constraint_def(
     cursor: CursorWrapper, model: type[Model], constraint_clause: str
 ) -> str:
     """Round-trip a constraint clause through Postgres so both sides of the
@@ -1601,28 +1678,28 @@ def _canonicalize_constraint_def(
 
     Returns "" if the model SQL is incompatible with the live table shape
     (e.g. unmigrated column-type drift). Drift still gets reported via the
-    inequality with the actual live definition; only the canonical model
+    inequality with the actual live definition; only the normalized model
     text is omitted from the diagnostic.
     """
     try:
-        with _canon_table(cursor, model):
+        with _probe_table(cursor, model):
             # Add as validated: the temp table is empty so the implicit scan is
             # instant. NOT VALID would leave a trailing " NOT VALID" suffix in
             # pg_get_constraintdef that the live constraint won't have.
             cursor.execute(
-                f"ALTER TABLE {_CANON_TABLE} "
-                f"ADD CONSTRAINT {_CANON_CONSTRAINT} {constraint_clause}"
+                f"ALTER TABLE {_PROBE_TABLE} "
+                f"ADD CONSTRAINT {_PROBE_CONSTRAINT} {constraint_clause}"
             )
             cursor.execute(
                 "SELECT pg_get_constraintdef(c.oid) FROM pg_constraint c "
                 "WHERE c.conname = %s "
                 "AND c.conrelid = (SELECT oid FROM pg_class WHERE relname = %s "
                 "AND relnamespace = pg_my_temp_schema())",
-                [_CANON_CONSTRAINT, _CANON_TABLE],
+                [_PROBE_CONSTRAINT, _PROBE_TABLE],
             )
             row = cursor.fetchone()
             return row[0] if row else ""
-    except _CANON_FALLBACK_ERRORS:
+    except _PROBE_FALLBACK_ERRORS:
         return ""
 
 
@@ -1630,10 +1707,10 @@ def _get_expected_check_definition(
     cursor: CursorWrapper, model: type[Model], constraint: CheckConstraint
 ) -> str:
     check_sql = compile_expression_sql(model, constraint.check)
-    return _canonicalize_constraint_def(cursor, model, f"CHECK ({check_sql})")
+    return _normalize_constraint_def(cursor, model, f"CHECK ({check_sql})")
 
 
-def _canonicalize_index_def(
+def _normalize_index_def(
     cursor: CursorWrapper,
     model: type[Model],
     *,
@@ -1644,7 +1721,7 @@ def _canonicalize_index_def(
     include: tuple[str, ...] | None = None,
     unique: bool = False,
 ) -> str:
-    """Round-trip an index through Postgres and return its canonical body.
+    """Round-trip an index through Postgres and return its normalized body.
 
     Returns the `USING ... [INCLUDE (...)] [WHERE (...)]` tail of pg_get_indexdef,
     safe to compare directly against `_index_def_tail(actual_def)` from the
@@ -1653,7 +1730,7 @@ def _canonicalize_index_def(
 
     Returns "" if the model SQL is incompatible with the live table shape;
     comparison sites then see inequality and report drift without the
-    canonical model text.
+    normalized model text.
     """
     if expressions:
         columns_sql = compile_index_expressions_sql(model, expressions)
@@ -1676,25 +1753,25 @@ def _canonicalize_index_def(
     create_kw = "CREATE UNIQUE INDEX" if unique else "CREATE INDEX"
 
     try:
-        with _canon_table(cursor, model):
+        with _probe_table(cursor, model):
             cursor.execute(
-                f"{create_kw} {_CANON_INDEX} ON {_CANON_TABLE} "
+                f"{create_kw} {_PROBE_INDEX} ON {_PROBE_TABLE} "
                 f"({columns_sql}){include_sql}{where_sql}"
             )
             cursor.execute(
                 "SELECT pg_get_indexdef(c.oid) FROM pg_class c "
                 "WHERE c.relname = %s AND c.relnamespace = pg_my_temp_schema()",
-                [_CANON_INDEX],
+                [_PROBE_INDEX],
             )
             row = cursor.fetchone()
             return _index_def_tail(row[0]) if row else ""
-    except _CANON_FALLBACK_ERRORS:
+    except _PROBE_FALLBACK_ERRORS:
         return ""
 
 
 def _index_def_tail(definition: str) -> str:
     """Strip the `CREATE [UNIQUE] INDEX <name> ON <schema>.<table>` prefix
-    from a pg_get_indexdef output, leaving the canonical body that's safe to
+    from a pg_get_indexdef output, leaving the normalized body that's safe to
     compare across different index names/tables."""
     using_pos = definition.find("USING ")
     return definition[using_pos:] if using_pos >= 0 else definition
@@ -1703,7 +1780,7 @@ def _index_def_tail(definition: str) -> str:
 def _get_expected_unique_definition(
     cursor: CursorWrapper, model: type[Model], constraint: UniqueConstraint
 ) -> str:
-    """Canonical UNIQUE definition for the model's constraint, as Postgres
+    """Normalized UNIQUE definition for the model's constraint, as Postgres
     prints it.
 
     PostgreSQL only stores field-based unique constraints (with optional
@@ -1718,4 +1795,4 @@ def _get_expected_unique_definition(
     include_sql = build_include_sql(model, constraint.include)
     defer_sql = deferrable_sql(constraint.deferrable)
     clause = f"UNIQUE ({columns_sql}){include_sql}{defer_sql}"
-    return _canonicalize_constraint_def(cursor, model, clause)
+    return _normalize_constraint_def(cursor, model, clause)

{plain_postgres-0.108.0 → plain_postgres-0.109.0}/plain/postgres/fields/__init__.py

@@ -1,12 +1,11 @@
 from __future__ import annotations
 
+from .base import DATABASE_DEFAULT as DATABASE_DEFAULT
 from .base import (
-    BLANK_CHOICE_DASH,
     NOT_PROVIDED,
     Empty,
     Field,
 )
-from .base import DATABASE_DEFAULT as DATABASE_DEFAULT
 from .base import ChoicesField as ChoicesField
 from .base import DatabaseDefault as DatabaseDefault
 from .binary import BinaryField
@@ -26,7 +25,6 @@ from .text import EmailField, RandomStringField, TextField, URLField
 from .uuid import UUIDField
 
 __all__ = [
-    "BLANK_CHOICE_DASH",
     "PrimaryKeyField",
     "BigIntegerField",
     "BinaryField",