plain.postgres 0.103.1__tar.gz → 0.103.2__tar.gz

{plain_postgres-0.103.1 → plain_postgres-0.103.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.103.1
+Version: 0.103.2
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause

{plain_postgres-0.103.1 → plain_postgres-0.103.2}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,17 @@
 # plain-postgres changelog
 
+## [0.103.2](https://github.com/dropseed/plain/releases/plain-postgres@0.103.2) (2026-05-06)
+
+### What's changed
+
+- **`postgres.missing_fk_indexes` preflight now recognizes bare-column leading expressions.** A `UniqueConstraint(F("team"), Lower("email"))` declared via the `expressions=` API previously slipped past the model-level check — the preflight only inspected `fields=`, so it warned about a missing FK index even though the underlying btree's leading column was the real `team` attribute and the live diagnose check correctly recognized coverage. The preflight now extracts the leading column from `F(...)` and `OrderBy(F(...))` expressions to match Postgres' actual coverage semantics. ([ae3880098f](https://github.com/dropseed/plain/commit/ae3880098f))
+- **Both FK-coverage checks now skip partial indexes.** A partial index like `Index(fields=["team"], condition=Q(deleted_at__isnull=True))` only satisfies queries whose predicate implies the partial-index `WHERE`, so an unfiltered FK lookup or cascade delete still sequential-scans. The preflight (`_fk_covered_field_names`) and the live diagnose check (`check_missing_fk_indexes`) both used to silently treat partial indexes as covering — now they don't, so the warning fires on the real coverage gap. The narrow `WHERE fk IS NOT NULL` case is conservatively also treated as not covering; users wanting guaranteed FK coverage should add a regular non-partial `Index(fields=[...])`. ([b1d13a6b42](https://github.com/dropseed/plain/commit/b1d13a6b42))
+- New `is_partial` property on `Index` and `UniqueConstraint` returning `condition is not None`, for callers that need the distinction. ([b1d13a6b42](https://github.com/dropseed/plain/commit/b1d13a6b42))
+
+### Upgrade instructions
+
+- No changes required. After upgrading, `postgres.missing_fk_indexes` may surface previously-undetected FK coverage gaps (where the only matching index was partial) and may suppress previously-warning false positives (where the only matching index used `expressions=`). Add a non-partial `Index(fields=["fk"])` to silence the warning in the partial-index case.
+
 ## [0.103.1](https://github.com/dropseed/plain/releases/plain-postgres@0.103.1) (2026-05-06)
 
 ### What's changed

{plain_postgres-0.103.1 → plain_postgres-0.103.2}/plain/postgres/constraints.py

@@ -250,6 +250,10 @@ class UniqueConstraint(BaseConstraint):
     def contains_expressions(self) -> bool:
         return bool(self.expressions)
 
+    @property
+    def is_partial(self) -> bool:
+        return self.condition is not None
+
     @property
     def index_only(self) -> bool:
         """Whether PostgreSQL can only store this as a unique index, not a constraint.

{plain_postgres-0.103.1 → plain_postgres-0.103.2}/plain/postgres/indexes.py

@@ -83,6 +83,10 @@ class Index:
     def contains_expressions(self) -> bool:
         return bool(self.expressions)
 
+    @property
+    def is_partial(self) -> bool:
+        return self.condition is not None
+
     def to_sql(self, model: type[Model]) -> str:
         """Generate CREATE INDEX CONCURRENTLY SQL as a plain string."""
         table = model.model_options.db_table

{plain_postgres-0.103.1 → plain_postgres-0.103.2}/plain/postgres/introspection/health/checks_structural.py

@@ -187,7 +187,16 @@ def check_duplicate_indexes(
 def check_missing_fk_indexes(
     cursor: Any, table_owners: dict[str, TableOwner]
 ) -> CheckResult:
-    """Foreign key columns without a leading index — JOINs on these do sequential scans."""
+    """Foreign key columns without a leading index — JOINs on these do sequential scans.
+
+    Partial indexes (``WHERE`` clause set on ``pg_index.indpred``) don't
+    count: Postgres only uses them for queries that imply the partial
+    predicate, so FK lookups and cascade deletes outside that predicate
+    still sequential-scan. The narrow ``WHERE fk IS NOT NULL`` case —
+    which Postgres can match to ``WHERE fk = ?`` — is conservatively
+    treated as not covering; users wanting guaranteed FK coverage should
+    add a regular non-partial index. Match the preflight's coverage rule.
+    """
     cursor.execute("""
         SELECT
             ct.relname AS table_name,
@@ -207,6 +216,7 @@ def check_missing_fk_indexes(
               FROM pg_catalog.pg_index i
               WHERE i.indrelid = c.conrelid
                 AND i.indkey[0] = c.conkey[1]
+                AND i.indpred IS NULL
           )
         ORDER BY ct.relname, a.attname
     """)

{plain_postgres-0.103.1 → plain_postgres-0.103.2}/plain/postgres/preflight.py

@@ -8,6 +8,7 @@ from typing import Any
 from plain.packages import packages_registry
 from plain.postgres.constraints import UniqueConstraint
 from plain.postgres.db import get_connection
+from plain.postgres.expressions import F, OrderBy
 from plain.postgres.fields.related import ForeignKeyField
 from plain.postgres.registry import ModelsRegistry, models_registry
 from plain.preflight import PreflightCheck, PreflightResult, register_check
@@ -41,6 +42,61 @@ def _collect_model_indexes(model: Any) -> list[tuple[str, list[str], bool]]:
     return all_indexes
 
 
+def _bare_column_name(expr: Any) -> str | None:
+    """Return the column name if `expr` resolves to a bare column, else `None`.
+
+    Postgres can range-scan the leading column of an index for `WHERE col = ?`
+    only when that column is a real attribute, not an expression — so a
+    compound leading expression like `Lower("email")` returns `None` here.
+    Sort direction (`F("col").desc()` / `OrderBy(F)`) doesn't affect equality
+    lookups, so we unwrap one layer of `OrderBy` around a bare `F`.
+    """
+    if isinstance(expr, OrderBy):
+        expr = expr.expression
+    if isinstance(expr, F):
+        return expr.name
+    return None
+
+
+def _fk_covered_field_names(model: Any) -> set[str]:
+    """Field names that appear as the leading column of a non-partial index
+    or unique constraint — covering arbitrary FK lookups via the index's
+    leading column.
+
+    Partial indexes/constraints (declared with ``condition=Q(...)``) are
+    excluded: Postgres can only use them for queries whose predicate
+    implies the partial-index predicate, so an FK lookup or cascade
+    delete that doesn't filter by that condition still does a sequential
+    scan. (The narrow ``WHERE fk IS NOT NULL`` case — which Postgres can
+    match to ``WHERE fk = ?`` — is conservatively treated as not
+    covering; users wanting guaranteed FK coverage should add a regular
+    non-partial ``Index(fields=[...])``.) Includes expression-based
+    indexes/constraints whose leading expression is a bare
+    ``F(field_name)``.
+    """
+    covered: set[str] = set()
+
+    def _record_leading(
+        fields: tuple[str, ...] | list[str], expressions: tuple
+    ) -> None:
+        if fields:
+            covered.add(fields[0].lstrip("-"))
+        elif expressions:
+            name = _bare_column_name(expressions[0])
+            if name is not None:
+                covered.add(name)
+
+    for index in model.model_options.indexes:
+        if not index.is_partial:
+            _record_leading(index.fields, index.expressions)
+
+    for constraint in model.model_options.constraints:
+        if isinstance(constraint, UniqueConstraint) and not constraint.is_partial:
+            _record_leading(constraint.fields, constraint.expressions)
+
+    return covered
+
+
 @register_check("postgres.all_models")
 class CheckAllModels(PreflightCheck):
     """Validates all model definitions for common issues."""
@@ -386,10 +442,7 @@ class CheckMissingFKIndexes(PreflightCheck):
         results = []
 
         for model in _get_app_models():
-            # Leading field of each index/constraint covers FK lookups
-            covered_fields = {
-                fields[0] for _, fields, _ in _collect_model_indexes(model)
-            }
+            covered_fields = _fk_covered_field_names(model)
 
             for field in model._model_meta.local_fields:
                 if (

{plain_postgres-0.103.1 → plain_postgres-0.103.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.postgres"
-version = "0.103.1"
+version = "0.103.2"
 description = "Model your data and store it in a database."
 authors = [{ name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev" }]
 readme = "README.md"

{plain_postgres-0.103.1 → plain_postgres-0.103.2}/tests/internal/test_diagnose.py

@@ -404,6 +404,34 @@ class TestStructuralScenarios:
         flagged = [i for i in result["items"] if i["table"] == "_diag_fk_child2"]
         assert flagged == [], f"indexed FK should not be flagged; got {flagged}"
 
+    def test_missing_fk_index_detected_when_only_partial_index_covers(self) -> None:
+        """A partial index on the FK column doesn't cover arbitrary FK
+        lookups — Postgres can only use it for queries whose predicate
+        implies the partial-index `WHERE`. The check must still flag the
+        FK as missing index coverage."""
+        _execute('CREATE TABLE "_diag_fk_parent3" ("id" serial PRIMARY KEY)')
+        _execute(
+            'CREATE TABLE "_diag_fk_child3" ('
+            '"id" serial PRIMARY KEY, '
+            '"parent_id" int REFERENCES "_diag_fk_parent3"("id"), '
+            '"deleted_at" timestamptz)'
+        )
+        _execute(
+            'CREATE INDEX "_diag_fk_child3_partial_parent_idx" '
+            'ON "_diag_fk_child3" ("parent_id") '
+            "WHERE deleted_at IS NULL"
+        )
+
+        conn = get_connection()
+        with conn.cursor() as cursor:
+            result = check_missing_fk_indexes(cursor, {})
+
+        flagged = [i for i in result["items"] if i["table"] == "_diag_fk_child3"]
+        assert len(flagged) == 1, (
+            f"partial index must not satisfy FK coverage; got {flagged}"
+        )
+        assert flagged[0]["name"] == "_diag_fk_child3.parent_id"
+
     def test_sequence_exhaustion_critical_above_90pct(self) -> None:
         _execute('CREATE TABLE "_diag_seq" ("id" serial PRIMARY KEY, "n" int)')
         # int4 sequence max is 2^31-1 = 2147483647; push past 90% to trip critical.

plain_postgres-0.103.2/tests/internal/test_preflight_fk_coverage.py

@@ -0,0 +1,157 @@
+"""Unit tests for `_fk_covered_field_names` — the helper that powers
+`postgres.missing_fk_indexes`'s preflight check.
+
+The check fires on FK fields whose name doesn't appear here. The helper
+must recognize bare `F("col")` leading expressions so a constraint like
+`UniqueConstraint(F("team"), Lower("email"))` counts as covering the
+`team` FK — Postgres' underlying btree's leading column is the real
+`team` attribute, not an expression.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from plain.postgres import Q
+from plain.postgres.constraints import UniqueConstraint
+from plain.postgres.expressions import F
+from plain.postgres.functions import Lower
+from plain.postgres.indexes import Index
+from plain.postgres.preflight import _fk_covered_field_names
+
+
+def _model(*, indexes=(), constraints=()) -> SimpleNamespace:
+    """Minimal model_options stand-in for the helper."""
+    return SimpleNamespace(
+        model_options=SimpleNamespace(
+            indexes=list(indexes), constraints=list(constraints)
+        )
+    )
+
+
+def test_covers_index_with_fields():
+    model = _model(indexes=[Index(name="t_team_idx", fields=["team"])])
+    assert _fk_covered_field_names(model) == {"team"}
+
+
+def test_covers_unique_constraint_with_fields():
+    model = _model(
+        constraints=[
+            UniqueConstraint(fields=["team", "account"], name="t_team_acct_uniq")
+        ]
+    )
+    assert _fk_covered_field_names(model) == {"team"}
+
+
+def test_covers_unique_constraint_with_bare_f_leading_expression():
+    """A unique constraint declared via `expressions=` whose leading
+    expression is a bare `F("col")` covers the FK — the underlying btree's
+    leading attribute is still the real column."""
+    model = _model(
+        constraints=[
+            UniqueConstraint(
+                F("team"),
+                Lower("email"),
+                name="t_team_email_uniq",
+            )
+        ]
+    )
+    assert "team" in _fk_covered_field_names(model)
+
+
+def test_covers_unique_constraint_with_ordered_bare_f_leading_expression():
+    """`F("team").desc()` produces `OrderBy(F("team"))`. Postgres still emits
+    `team_id DESC` as a real leading column attribute, so equality FK
+    lookups are covered (sort direction doesn't matter for `WHERE = ?`)."""
+    model = _model(
+        constraints=[
+            UniqueConstraint(
+                F("team").desc(),
+                Lower("email"),
+                name="t_team_desc_email_uniq",
+            )
+        ]
+    )
+    assert "team" in _fk_covered_field_names(model)
+
+
+def test_does_not_cover_when_leading_expression_is_compound():
+    """`(LOWER(email), team)` cannot satisfy `WHERE team = ?` from the
+    leading column — the leading "column" is an expression, so Postgres
+    can't range-scan it for a value lookup on team."""
+    model = _model(
+        constraints=[
+            UniqueConstraint(
+                Lower("email"),
+                F("team"),
+                name="t_lower_email_team_uniq",
+            )
+        ]
+    )
+    assert "team" not in _fk_covered_field_names(model)
+
+
+def test_strips_descending_prefix_from_field_name():
+    """`fields=["-created_at"]` (descending) still has `created_at` as the
+    underlying column. The leading-column extraction must strip the prefix."""
+    model = _model(indexes=[Index(name="t_created_idx", fields=["-created_at"])])
+    assert _fk_covered_field_names(model) == {"created_at"}
+
+
+def test_unions_indexes_and_constraints():
+    model = _model(
+        indexes=[Index(name="t_a_idx", fields=["a"])],
+        constraints=[
+            UniqueConstraint(fields=["b"], name="t_b_uniq"),
+            UniqueConstraint(F("c"), Lower("d"), name="t_c_d_uniq"),
+        ],
+    )
+    assert _fk_covered_field_names(model) == {"a", "b", "c"}
+
+
+def test_partial_index_does_not_cover():
+    """`Index(fields=["team"], condition=Q(...))` only satisfies queries
+    whose predicate implies the partial-index `WHERE`. An unfiltered FK
+    lookup or cascade delete still sequential-scans, so the partial index
+    must not count as covering."""
+    model = _model(
+        indexes=[
+            Index(
+                name="t_team_active_idx",
+                fields=["team"],
+                condition=Q(deleted_at__isnull=True),
+            )
+        ]
+    )
+    assert "team" not in _fk_covered_field_names(model)
+
+
+def test_partial_unique_constraint_does_not_cover():
+    """Same logic as the partial index — soft-delete-style partial unique
+    constraints don't guarantee FK lookup coverage."""
+    model = _model(
+        constraints=[
+            UniqueConstraint(
+                fields=["team"],
+                name="t_team_active_uniq",
+                condition=Q(deleted_at__isnull=True),
+            )
+        ]
+    )
+    assert "team" not in _fk_covered_field_names(model)
+
+
+def test_full_index_still_covers_when_partial_sibling_exists():
+    """A non-partial index on the same column wins — partial-ness is per
+    declaration, not per column."""
+    model = _model(
+        indexes=[
+            Index(
+                name="t_team_active_idx",
+                fields=["team"],
+                condition=Q(deleted_at__isnull=True),
+            ),
+            Index(name="t_team_idx", fields=["team"]),
+        ]
+    )
+    assert "team" in _fk_covered_field_names(model)