plain.postgres 0.101.0__tar.gz → 0.103.0__tar.gz

{plain_postgres-0.101.0 → plain_postgres-0.103.0}/.gitignore

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

plain_postgres-0.101.0/plain/postgres/README.md → plain_postgres-0.103.0/PKG-INFO

@@ -1,3 +1,16 @@
+Metadata-Version: 2.4
+Name: plain.postgres
+Version: 0.103.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.**
@@ -687,7 +700,7 @@ Or use `RunSQL` with explicit cascade if the relationship is large.
 
 ### Convergence
 
-Convergence compares the indexes, constraints, foreign keys, and nullability declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
+Convergence compares the indexes, constraints, foreign keys, nullability, and [storage parameters](#storage-parameters) declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
 
 ```python
 @postgres.register_model
@@ -1078,6 +1091,26 @@ A `code` becomes `ValidationError.code` — useful for test assertions, error tr
 
 `UniqueConstraint` accepts the same `violation_error`. With a single-field unique constraint, a string `violation_error="That email is taken."` auto-routes to that field; otherwise (multi-field, expressions, or a CheckConstraint) errors land on `NON_FIELD_ERRORS` unless you pass the dict form. See [BaseConstraint](./constraints.py#BaseConstraint) for the full signature.
 
+### Storage parameters
+
+Per-table Postgres [storage parameters](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS) (`pg_class.reloptions`) are declared on `model_options` and managed by [convergence](#convergence) — `postgres sync` issues the `ALTER TABLE … SET/RESET (...)` to make the live table match. They're not serialized into migrations.
+
+```python
+class CachedItem(postgres.Model):
+    ...
+
+    model_options = postgres.Options(
+        storage_parameters={
+            # Tighter autovacuum on a churn-heavy table
+            "autovacuum_vacuum_scale_factor": 0.1,
+            # TOAST has its own autovacuum schedule — prefix with `toast.`
+            "toast.autovacuum_vacuum_scale_factor": 0.05,
+        },
+    )
+```
+
+Models are the source of truth: undeclared parameters set on the live table are reset on the next sync. Use this for autovacuum tuning, `fillfactor`, TOAST options, etc. — anything you'd otherwise apply by hand with `ALTER TABLE … SET (...)`.
+
 ### Schema design
 
 #### Index fields used in filters and ordering
@@ -1277,16 +1310,17 @@ fix in their model code. (In JSON output each finding still carries
 it.) Each finding still carries the exact SQL in its suggestion for anyone
 who wants to act.
 
-| Finding             | What it reports                                                                  |
-| ------------------- | -------------------------------------------------------------------------------- |
-| **Stats freshness** | Tables whose planner statistics are missing (never analyzed) or stale            |
-| **Vacuum health**   | Tables with >10% dead tuples                                                     |
-| **Index bloat**     | btree indexes with significant estimated wasted space (≥10 MB, ioguix estimator) |
+| Finding             | What it reports                                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------ |
+| **Stats freshness** | Tables whose planner statistics are missing (never analyzed) or stale                      |
+| **Vacuum health**   | Tables with >10% dead tuples                                                               |
+| **Table bloat**     | Tables with significant estimated wasted space (≥100 MB AND ≥25% bloat, ioguix estimator)  |
+| **Index bloat**     | btree indexes with significant estimated wasted space (≥100 MB AND ≥30%, ioguix estimator) |
 
-If a future release exposes per-table autovacuum / fillfactor parameters in
-`model_options` (see the `postgres-model-storage-parameters` arc), these
-findings can graduate back to the warning tier — because the remedy will be
-expressible in code.
+Now that per-table autovacuum / fillfactor knobs are expressible in
+[storage parameters](#storage-parameters) on `model_options`, these
+findings may graduate back to the warning tier in a future release — the
+remedy is now in code.
 
 ### Informational context
 
@@ -1335,7 +1369,7 @@ heroku run -a your-app "plain postgres diagnose --json"
 
 The `--json` flag must be quoted so Heroku passes it through to the command.
 
-Cumulative-stat checks (`stats_freshness`, `vacuum_health`, `unused_indexes`, `missing_index_candidates`, `index_bloat`) need cumulative stat history after the last reset to be reliable. Check the `stats_reset` informational to see how much history you have. (Note: this list spans both the warning and operational tiers — the common thread is that all five depend on counters that `pg_stat_reset()` wipes.)
+Cumulative-stat checks (`stats_freshness`, `vacuum_health`, `unused_indexes`, `missing_index_candidates`, `table_bloat`, `index_bloat`) need cumulative stat history after the last reset to be reliable. Check the `stats_reset` informational to see how much history you have. (Note: this list spans both the warning and operational tiers — the common thread is that all five depend on counters that `pg_stat_reset()` wipes.)
 
 ### Preflight checks
 

{plain_postgres-0.101.0 → plain_postgres-0.103.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,31 @@
 # plain-postgres changelog
 
+## [0.103.0](https://github.com/dropseed/plain/releases/plain-postgres@0.103.0) (2026-05-06)
+
+### What's changed
+
+- **New `storage_parameters` on `model_options`, managed by convergence.** Declare per-table Postgres storage parameters (`pg_class.reloptions`) on the model — autovacuum tuning, `fillfactor`, TOAST options, anything you'd otherwise set with `ALTER TABLE … SET (...)` — and `plain postgres sync` reconciles them via instant catalog-only `ALTER TABLE … SET / RESET (...)` statements. Models are the source of truth: parameters set on the live table that aren't declared on the model get reset, matching how indexes and constraints work. TOAST parameters use a `toast.` prefix (`toast.autovacuum_vacuum_scale_factor`) and are stored on the toast relation. Storage parameters are not serialized into migrations. New public API: `StorageParameterDrift`, `SetStorageParameterFix`, `ResetStorageParameterFix`. ([7fe40f72](https://github.com/dropseed/plain/commit/7fe40f72))
+- **New `table_bloat` health check.** Estimates per-table page-level bloat using the ioguix estimator (same heuristic as pghero). Complements `vacuum_health`: dead-tuple counts only show what autovacuum hasn't reclaimed yet, but a table that's been vacuumed regularly can still carry gigabytes of bloat because plain `VACUUM` marks pages reusable without returning space to the OS. Surfaces tables with both >100 MB wasted bytes AND >25% bloat ratio, with `pg_repack` / `pg_squeeze` / `VACUUM FULL` suggestions. Cross-check caveats now link `vacuum_health` and `table_bloat` findings on the same table. ([ee9dc1d5](https://github.com/dropseed/plain/commit/ee9dc1d5))
+- **Tightened `index_bloat` thresholds.** Now requires both >100 MB wasted bytes AND >30% bloat ratio (was 10 MB only). The previous floor surfaced too many small, healthy indexes; the higher percentage bar reflects that `REINDEX CONCURRENTLY` is cheap so it's only worth flagging genuinely degraded indexes. Results are also capped at 100 rows per check. ([ee9dc1d5](https://github.com/dropseed/plain/commit/ee9dc1d5))
+
+### Upgrade instructions
+
+- No changes required. To opt into the new `storage_parameters` API, declare them on `model_options = postgres.Options(storage_parameters={...})` and run `plain postgres sync`. After upgrading, expect previously-noisy `index_bloat` findings to disappear (now require ≥100 MB AND ≥30%) and the new `table_bloat` check to appear in `plain postgres diagnose`.
+
+## [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

plain_postgres-0.101.0/PKG-INFO → plain_postgres-0.103.0/plain/postgres/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: plain.postgres
-Version: 0.101.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
-Requires-Dist: sqlparse>=0.3.1
-Description-Content-Type: text/markdown
-
 # plain.postgres
 
 **Model your data and store it in a database.**
@@ -701,7 +687,7 @@ Or use `RunSQL` with explicit cascade if the relationship is large.
 
 ### Convergence
 
-Convergence compares the indexes, constraints, foreign keys, and nullability declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
+Convergence compares the indexes, constraints, foreign keys, nullability, and [storage parameters](#storage-parameters) declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
 
 ```python
 @postgres.register_model
@@ -1092,6 +1078,26 @@ A `code` becomes `ValidationError.code` — useful for test assertions, error tr
 
 `UniqueConstraint` accepts the same `violation_error`. With a single-field unique constraint, a string `violation_error="That email is taken."` auto-routes to that field; otherwise (multi-field, expressions, or a CheckConstraint) errors land on `NON_FIELD_ERRORS` unless you pass the dict form. See [BaseConstraint](./constraints.py#BaseConstraint) for the full signature.
 
+### Storage parameters
+
+Per-table Postgres [storage parameters](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS) (`pg_class.reloptions`) are declared on `model_options` and managed by [convergence](#convergence) — `postgres sync` issues the `ALTER TABLE … SET/RESET (...)` to make the live table match. They're not serialized into migrations.
+
+```python
+class CachedItem(postgres.Model):
+    ...
+
+    model_options = postgres.Options(
+        storage_parameters={
+            # Tighter autovacuum on a churn-heavy table
+            "autovacuum_vacuum_scale_factor": 0.1,
+            # TOAST has its own autovacuum schedule — prefix with `toast.`
+            "toast.autovacuum_vacuum_scale_factor": 0.05,
+        },
+    )
+```
+
+Models are the source of truth: undeclared parameters set on the live table are reset on the next sync. Use this for autovacuum tuning, `fillfactor`, TOAST options, etc. — anything you'd otherwise apply by hand with `ALTER TABLE … SET (...)`.
+
 ### Schema design
 
 #### Index fields used in filters and ordering
@@ -1291,16 +1297,17 @@ fix in their model code. (In JSON output each finding still carries
 it.) Each finding still carries the exact SQL in its suggestion for anyone
 who wants to act.
 
-| Finding             | What it reports                                                                  |
-| ------------------- | -------------------------------------------------------------------------------- |
-| **Stats freshness** | Tables whose planner statistics are missing (never analyzed) or stale            |
-| **Vacuum health**   | Tables with >10% dead tuples                                                     |
-| **Index bloat**     | btree indexes with significant estimated wasted space (≥10 MB, ioguix estimator) |
+| Finding             | What it reports                                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------ |
+| **Stats freshness** | Tables whose planner statistics are missing (never analyzed) or stale                      |
+| **Vacuum health**   | Tables with >10% dead tuples                                                               |
+| **Table bloat**     | Tables with significant estimated wasted space (≥100 MB AND ≥25% bloat, ioguix estimator)  |
+| **Index bloat**     | btree indexes with significant estimated wasted space (≥100 MB AND ≥30%, ioguix estimator) |
 
-If a future release exposes per-table autovacuum / fillfactor parameters in
-`model_options` (see the `postgres-model-storage-parameters` arc), these
-findings can graduate back to the warning tier — because the remedy will be
-expressible in code.
+Now that per-table autovacuum / fillfactor knobs are expressible in
+[storage parameters](#storage-parameters) on `model_options`, these
+findings may graduate back to the warning tier in a future release — the
+remedy is now in code.
 
 ### Informational context
 
@@ -1349,7 +1356,7 @@ heroku run -a your-app "plain postgres diagnose --json"
 
 The `--json` flag must be quoted so Heroku passes it through to the command.
 
-Cumulative-stat checks (`stats_freshness`, `vacuum_health`, `unused_indexes`, `missing_index_candidates`, `index_bloat`) need cumulative stat history after the last reset to be reliable. Check the `stats_reset` informational to see how much history you have. (Note: this list spans both the warning and operational tiers — the common thread is that all five depend on counters that `pg_stat_reset()` wipes.)
+Cumulative-stat checks (`stats_freshness`, `vacuum_health`, `unused_indexes`, `missing_index_candidates`, `table_bloat`, `index_bloat`) need cumulative stat history after the last reset to be reliable. Check the `stats_reset` informational to see how much history you have. (Note: this list spans both the warning and operational tiers — the common thread is that all five depend on counters that `pg_stat_reset()` wipes.)
 
 ### Preflight checks
 

{plain_postgres-0.101.0 → plain_postgres-0.103.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.101.0 → plain_postgres-0.103.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -36,7 +36,7 @@ Get approval before writing any model code or generating migrations.
 `uv run plain postgres sync` runs three steps: create migrations → apply migrations → converge schema.
 
 - **Migrations** handle tables and columns (CreateModel, AddField, AlterField, etc.)
-- **Convergence** handles indexes, constraints, and FK constraints — declared on the model but NOT serialized into migration files. (FK _columns_ like `team_id bigint` are created by migrations; the actual `FOREIGN KEY` constraint is added by convergence.)
+- **Convergence** handles indexes, constraints, FK constraints, and storage parameters — declared on the model but NOT serialized into migration files. (FK _columns_ like `team_id bigint` are created by migrations; the actual `FOREIGN KEY` constraint is added by convergence.)
 
 This means: when you add an `Index` or `UniqueConstraint` to a model, no migration is generated. The converge step reads the live model class and syncs the database directly. Don't worry about serializing constraint expressions (like `Lower()`) for migrations — they never go there.
 

{plain_postgres-0.101.0 → plain_postgres-0.103.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.101.0 → plain_postgres-0.103.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.101.0 → plain_postgres-0.103.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.101.0 → plain_postgres-0.103.0}/plain/postgres/convergence/__init__.py

@@ -11,6 +11,8 @@ from .analysis import (
     IndexStatus,
     ModelAnalysis,
     NullabilityDrift,
+    ReadOnlyConnectionError,
+    StorageParameterDrift,
     analyze_model,
 )
 from .fixes import (
@@ -25,8 +27,10 @@ from .fixes import (
     RebuildIndexFix,
     RenameConstraintFix,
     RenameIndexFix,
+    ResetStorageParameterFix,
     SetColumnDefaultFix,
     SetNotNullFix,
+    SetStorageParameterFix,
     ValidateConstraintFix,
 )
 from .planning import (
@@ -65,11 +69,15 @@ __all__ = [
     "ModelAnalysis",
     "NullabilityDrift",
     "PlanItem",
+    "ReadOnlyConnectionError",
     "RebuildIndexFix",
     "RenameConstraintFix",
     "RenameIndexFix",
+    "ResetStorageParameterFix",
     "SetColumnDefaultFix",
     "SetNotNullFix",
+    "SetStorageParameterFix",
+    "StorageParameterDrift",
     "ValidateConstraintFix",
     "analyze_model",
     "can_auto_fix",