plain.postgres 0.100.0__tar.gz → 0.102.0__tar.gz

{plain_postgres-0.100.0 → plain_postgres-0.102.0}/.gitignore

@@ -4,6 +4,8 @@
 *.py[co]
 __pycache__
 *.DS_Store
+*.swp
+*.swo
 
 /*.code-workspace
 

{plain_postgres-0.100.0 → plain_postgres-0.102.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.100.0
+Version: 0.102.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause
@@ -9,7 +9,6 @@ Requires-Python: >=3.13
 Requires-Dist: plain<1.0.0,>=0.134.0
 Requires-Dist: psycopg-pool>=3.2
 Requires-Dist: psycopg>=3.2
-Requires-Dist: sqlparse>=0.3.1
 Description-Content-Type: text/markdown
 
 # plain.postgres

{plain_postgres-0.100.0 → plain_postgres-0.102.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,30 @@
 # plain-postgres changelog
 
+## [0.102.0](https://github.com/dropseed/plain/releases/plain-postgres@0.102.0) (2026-05-05)
+
+### What's changed
+
+- **`Model.query` is now bound to `Self` (PEP 673), so subclasses specialize automatically.** `User.query` types as `QuerySet[User]` and `User.query.first()` as `User | None` without per-model annotations. Custom `QuerySet` subclasses (e.g. `TaskQuerySet`) are still preserved by the existing `Self`-returning descriptor. Now-redundant `cast(T, ...)` wrappers in the FK/M2M related managers are gone — `self.model.query.create(...)` already types as `T`. ([0f5b2f66](https://github.com/dropseed/plain/commit/0f5b2f66))
+- **Convergence diffs are now canonicalized through Postgres `pg_get_*` round-trips on a session-private temp table** instead of sqlparse-based text normalization. Both sides of every index/constraint/default comparison are deparsed by Postgres itself, eliminating false-positive drift from formatting differences. Adds `ReadOnlyConnectionError` when the round-trip can't get DDL. The `normalize_check_definition`, `normalize_default_sql`, `normalize_expression`, `normalize_index_definition`, and `normalize_unique_definition` helpers are removed from `plain.postgres.introspection`, and `sqlparse` is no longer a dependency. ([4b42b4d1](https://github.com/dropseed/plain/commit/4b42b4d1))
+- **`CheckConstraint.validate()` now exits early when a referenced field is missing from the value map**, deferring to the field-level error that excluded it. Calling `full_clean()` on a model with both `choices=` and a `CheckConstraint` referencing the same field used to crash with `AssertionError: Field lookups require a model` — the choice error excluded the field, then constraint validation tried to resolve the missing annotation. The walker is exposed as the public `CheckConstraint.referenced_fields()` method. ([d13f47d1](https://github.com/dropseed/plain/commit/d13f47d1))
+- Tightened class-level annotations on `Query.select` and friends, `Operation.atomic`, and `ChoicesField.choices` for ty 0.0.33; replaced the `ModelState` `fields_cache` descriptor with a plain `__init__`. ([4b9d1db1](https://github.com/dropseed/plain/commit/4b9d1db1))
+- Exposes `__version__` from `importlib.metadata` on `plain.postgres`. ([c6cf6edb](https://github.com/dropseed/plain/commit/c6cf6edb))
+
+### Upgrade instructions
+
+- If you imported any of `normalize_check_definition`, `normalize_default_sql`, `normalize_expression`, `normalize_index_definition`, or `normalize_unique_definition` from `plain.postgres.introspection`, those helpers are gone — use `pg_get_indexdef` / `pg_get_constraintdef` directly or rely on the new convergence round-trip path.
+
+## [0.101.0](https://github.com/dropseed/plain/releases/plain-postgres@0.101.0) (2026-04-30)
+
+### What's changed
+
+- **Validate CHECK constraints in the same converge run that adds them.** `AddConstraintFix` now runs `ALTER TABLE ... ADD CONSTRAINT ... NOT VALID` followed by `ALTER TABLE ... VALIDATE CONSTRAINT` in a single `apply()`. The add is catalog-only (brief lock) and validate uses `SHARE UPDATE EXCLUSIVE` (doesn't block writes), so there's no benefit to deferring validation to a later run. Existing rows are checked before convergence reports success — previously, a CHECK constraint could be added in `NOT VALID` state and the validation step was its own follow-up fix. ([dc7eb8d3c2b7](https://github.com/dropseed/plain/commit/dc7eb8d3c2b7))
+- `plain-postgres` rule references updated for the simpler `plain docs` CLI (no more `--section`). ([e03c3bd8b6d3](https://github.com/dropseed/plain/commit/e03c3bd8b6d3))
+
+### Upgrade instructions
+
+- No changes required. The next `plain postgres sync` (or scheduled converge run) on a database with pending CHECK constraints will now both add and validate them in one step instead of two.
+
 ## [0.100.0](https://github.com/dropseed/plain/releases/plain-postgres@0.100.0) (2026-04-28)
 
 ### What's changed

{plain_postgres-0.100.0 → plain_postgres-0.102.0}/plain/postgres/__init__.py

@@ -1,3 +1,7 @@
+from importlib.metadata import version
+
+__version__ = version("plain.postgres")
+
 from .registry import models_registry, register_model  # noqa  Create the registry first
 from . import (
     preflight,  # noqa  Imported for side effects (registers preflight checks)

{plain_postgres-0.100.0 → plain_postgres-0.102.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -42,7 +42,7 @@ This means: when you add an `Index` or `UniqueConstraint` to a model, no migrati
 
 For custom data migrations, use `uv run plain migrations create --empty --name <name>` to scaffold the file.
 
-Run `uv run plain docs postgres --section migrations` for full workflow details.
+Run `uv run plain docs postgres` for full workflow details.
 
 ## Querying
 
@@ -57,7 +57,7 @@ Use `Model.query` to build querysets (e.g., `User.query.filter(is_active=True)`)
 - Wrap multi-step writes in `transaction.atomic()`
 - Always paginate list queries — unbounded querysets get slower as data grows
 
-Run `uv run plain docs postgres --section querying` for full patterns with code examples.
+Run `uv run plain docs postgres` for full patterns with code examples.
 
 ## Schema Design
 
@@ -68,13 +68,13 @@ Run `uv run plain docs postgres --section querying` for full patterns with code
 - 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=""`
 
-Run `uv run plain docs postgres --section constraints` for full patterns with code examples.
+Run `uv run plain docs postgres` for full patterns with code examples.
 
 ## Database Doctor
 
 Use the `/plain-postgres-doctor` skill to check overall database health — migration sync, schema correctness, and operational health.
 
-Run `uv run plain docs postgres --section diagnostics` for check details, thresholds, and production usage.
+Run `uv run plain docs postgres` for check details, thresholds, and production usage.
 
 ## Differences from Django
 

{plain_postgres-0.100.0 → plain_postgres-0.102.0}/plain/postgres/base.py

@@ -4,7 +4,7 @@ import copy
 import warnings
 from collections.abc import Iterable, Iterator, Sequence
 from itertools import chain
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, Self, cast
 
 if TYPE_CHECKING:
     from plain.postgres.meta import Meta
@@ -68,16 +68,6 @@ class ModelBase(type):
         return super().__new__(cls, name, bases, attrs, **kwargs)
 
 
-class ModelStateFieldsCacheDescriptor:
-    def __get__(
-        self, instance: ModelState | None, cls: type | None = None
-    ) -> ModelStateFieldsCacheDescriptor | dict[str, Any]:
-        if instance is None:
-            return self
-        res = instance.fields_cache = {}
-        return res
-
-
 class ModelState:
     """Store model instance state."""
 
@@ -86,7 +76,9 @@ class ModelState:
     # explicit (non-auto) PKs. This impacts validation only; it has no effect
     # on the actual save.
     adding = True
-    fields_cache = ModelStateFieldsCacheDescriptor()
+
+    def __init__(self) -> None:
+        self.fields_cache: dict[str, Any] = {}
 
 
 class Model(metaclass=ModelBase):
@@ -94,7 +86,7 @@ class Model(metaclass=ModelBase):
     id: int = types.PrimaryKeyField()
 
     # Descriptors for other model behavior
-    query: QuerySet[Model] = QuerySet()
+    query: QuerySet[Self] = QuerySet()
     model_options: Options = Options()
     _model_meta: Meta = Meta()
     DoesNotExist = DoesNotExistDescriptor()

{plain_postgres-0.100.0 → plain_postgres-0.102.0}/plain/postgres/connection.py

@@ -15,7 +15,6 @@ from plain.logs import get_framework_logger
 from plain.postgres import utils
 from plain.postgres.dialect import quote_name
 from plain.postgres.fields import GenericIPAddressField, TimeField, UUIDField
-from plain.postgres.indexes import Index
 from plain.postgres.schema import DatabaseSchemaEditor
 from plain.postgres.sources import ConnectionSource
 from plain.postgres.transaction import TransactionManagementError
@@ -63,7 +62,6 @@ class DatabaseConnection:
 
     queries_limit: int = 9000
 
-    index_default_access_method = "btree"
     ignored_tables: list[str] = []
 
     def __init__(self, source: ConnectionSource):
@@ -607,7 +605,6 @@ class DatabaseConnection:
                 FROM pg_attribute AS fka
                 JOIN pg_class AS fkc ON fka.attrelid = fkc.oid
                 WHERE fka.attrelid = c.confrelid AND fka.attnum = c.confkey[1]),
-                cl.reloptions,
                 c.convalidated,
                 pg_get_constraintdef(c.oid),
                 c.confdeltype
@@ -622,54 +619,42 @@ class DatabaseConnection:
             columns,
             kind,
             used_cols,
-            options,
             validated,
             constraintdef,
             confdeltype,
         ) in cursor.fetchall():
             constraints[constraint] = {
                 "columns": columns,
-                "primary_key": kind == "p",
-                "unique": kind in ["p", "u"],
                 "foreign_key": tuple(used_cols.split(".", 1)) if kind == "f" else None,
-                "check": kind == "c",
                 "contype": kind,
                 "index": False,
                 "definition": constraintdef,
-                "options": options,
                 "validated": validated,
                 "on_delete_action": confdeltype if kind == "f" else None,
             }
-        # Now get indexes
+        # 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
+        # them here as separate columns.
         cursor.execute(
             """
             SELECT
                 indexname,
                 array_agg(attname ORDER BY arridx),
                 indisunique,
-                indisprimary,
-                array_agg(ordering ORDER BY arridx),
                 amname,
                 exprdef,
-                s2.attoptions,
-                s2.indisvalid
+                indisvalid
             FROM (
                 SELECT
                     c2.relname as indexname, idx.*, attr.attname, am.amname,
-                    pg_get_indexdef(idx.indexrelid) AS exprdef,
-                    CASE am.amname
-                        WHEN %s THEN
-                            CASE (option & 1)
-                                WHEN 1 THEN 'DESC' ELSE 'ASC'
-                            END
-                    END as ordering,
-                    c2.reloptions as attoptions
+                    pg_get_indexdef(idx.indexrelid) AS exprdef
                 FROM (
                     SELECT *
                     FROM
                         pg_index i,
-                        unnest(i.indkey, i.indoption)
-                            WITH ORDINALITY koi(key, option, arridx)
+                        unnest(i.indkey)
+                            WITH ORDINALITY koi(key, arridx)
                 ) idx
                 LEFT JOIN pg_class c ON idx.indrelid = c.oid
                 LEFT JOIN pg_class c2 ON idx.indexrelid = c2.oid
@@ -678,36 +663,26 @@ class DatabaseConnection:
                     pg_attribute attr ON attr.attrelid = c.oid AND attr.attnum = idx.key
                 WHERE c.relname = %s AND pg_catalog.pg_table_is_visible(c.oid)
             ) s2
-            GROUP BY indexname, indisunique, indisprimary, amname, exprdef, attoptions, indisvalid;
+            GROUP BY
+                indexname, indisunique, amname, exprdef, indisvalid;
         """,
-            [self.index_default_access_method, table_name],
+            [table_name],
         )
         for (
             index,
             columns,
             unique,
-            primary,
-            orders,
             type_,
             definition,
-            options,
             valid,
         ) in cursor.fetchall():
             if index not in constraints:
-                basic_index = (
-                    type_ == self.index_default_access_method and options is None
-                )
                 constraints[index] = {
                     "columns": columns if columns != [None] else [],
-                    "orders": orders if orders != [None] else [],
-                    "primary_key": primary,
                     "unique": unique,
-                    "foreign_key": None,
-                    "check": False,
                     "index": True,
-                    "type": Index.suffix if basic_index else type_,
+                    "type": type_,
                     "definition": definition,
-                    "options": options,
                     "valid": valid,
                 }
         return constraints

{plain_postgres-0.100.0 → plain_postgres-0.102.0}/plain/postgres/constraints.py

@@ -5,6 +5,7 @@ from types import NoneType
 from typing import TYPE_CHECKING, Any
 
 from plain.exceptions import ValidationError
+from plain.postgres.constants import LOOKUP_SEP
 from plain.postgres.ddl import (
     build_include_sql,
     compile_expression_sql,
@@ -104,10 +105,41 @@ class CheckConstraint(BaseConstraint):
             sql += " NOT VALID"
         return sql
 
+    def referenced_fields(self) -> set[str]:
+        """Top-level model field names referenced by `self.check`.
+
+        Walks lookup keys (`field__regex` → `field`), nested Q nodes, and
+        F-expressions in values or other source expressions.
+        """
+        fields: set[str] = set()
+
+        def visit(node: Any) -> None:
+            if isinstance(node, Q):
+                for child in node.children:
+                    visit(child)
+            elif isinstance(node, tuple) and len(node) == 2:
+                lookup, value = node
+                fields.add(lookup.split(LOOKUP_SEP, 1)[0])
+                visit(value)
+            elif isinstance(node, F):
+                fields.add(node.name.split(LOOKUP_SEP, 1)[0])
+            elif hasattr(node, "get_source_expressions"):
+                for sub in node.get_source_expressions():
+                    visit(sub)
+
+        visit(self.check)
+        return fields
+
     def validate(
         self, model: type[Model], instance: Model, exclude: set[str] | None = None
     ) -> None:
         against = instance._get_field_value_map(meta=model._model_meta, exclude=exclude)
+        # Skip the check entirely when any field referenced by `self.check` was
+        # excluded — the in-Python pipeline can't resolve a missing field's
+        # annotation, and surfacing a constraint violation here would just
+        # duplicate the field-level error that caused the exclusion.
+        if not self.referenced_fields().issubset(against):
+            return
         try:
             if not Q(self.check).check(against):
                 raise self._build_violation_error()

{plain_postgres-0.100.0 → plain_postgres-0.102.0}/plain/postgres/convergence/__init__.py

@@ -11,6 +11,7 @@ from .analysis import (
     IndexStatus,
     ModelAnalysis,
     NullabilityDrift,
+    ReadOnlyConnectionError,
     analyze_model,
 )
 from .fixes import (
@@ -65,6 +66,7 @@ __all__ = [
     "ModelAnalysis",
     "NullabilityDrift",
     "PlanItem",
+    "ReadOnlyConnectionError",
     "RebuildIndexFix",
     "RenameConstraintFix",
     "RenameIndexFix",