plain.postgres 0.103.1__tar.gz → 0.103.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.103.1
+Version: 0.103.3
 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.3}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,28 @@
 # plain-postgres changelog
 
+## [0.103.3](https://github.com/dropseed/plain/releases/plain-postgres@0.103.3) (2026-05-08)
+
+### What's changed
+
+- **`QuerySet.__repr__` no longer issues SQL for unevaluated querysets.** Error reporters (Sentry, pdb, exception templates) call `repr()` on stack-frame locals to build error events, and a surprise `SELECT … LIMIT 21` inside an exception path is a known footgun — especially on production where the underlying query may itself be the cause of the failure. Unevaluated querysets now render as `<QuerySet [unevaluated]>`; once the result cache is populated, `repr()` formats from the cache as before (still truncating past 20 rows). ([d8b7c4ec30](https://github.com/dropseed/plain/commit/d8b7c4ec30))
+- **`ManyToManyField.value_from_object` no longer calls `.all()` on a manager.** The form-roundtrip path went through `getattr(obj, attname).all()`, which on the M2M manager dispatched to its descriptor and could trigger an unintended fetch/SQL path. Switched to the manager's `.query` queryset, which is the documented entry point. ([83da86b19b](https://github.com/dropseed/plain/commit/83da86b19b))
+
+### Upgrade instructions
+
+- No changes required. Note that interactive shell users who relied on `repr()` triggering evaluation (e.g., typing `qs` at the prompt to print rows) will now see `<QuerySet [unevaluated]>` — call `list(qs)` or slice it to materialize.
+
+## [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.3}/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.3}/plain/postgres/fields/related.py

@@ -1174,7 +1174,7 @@ class ManyToManyField(RelatedField):
         pass
 
     def value_from_object(self, obj: Model) -> list[Any]:
-        return [] if obj.id is None else list(getattr(obj, self.attname).all())
+        return [] if obj.id is None else list(getattr(obj, self.attname).query)
 
     def save_form_data(self, instance: Model, data: Any) -> None:
         getattr(instance, self.attname).set(data)

{plain_postgres-0.103.1 → plain_postgres-0.103.3}/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.3}/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.3}/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.3}/plain/postgres/query.py

@@ -380,7 +380,13 @@ class QuerySet[T: "Model"]:
         self.__dict__.update(state)
 
     def __repr__(self) -> str:
-        data: list[Any] = list(self[: REPR_OUTPUT_SIZE + 1])
+        # Don't run SQL from __repr__ — error reporters (Sentry, pdb,
+        # exception templates) call repr() on stack-frame locals to
+        # build error events. If the queryset hasn't been evaluated, a
+        # surprise SELECT inside an exception path is a known footgun.
+        if self._result_cache is None:
+            return f"<{self.__class__.__name__} [unevaluated]>"
+        data: list[Any] = list(self._result_cache[: REPR_OUTPUT_SIZE + 1])
         if len(data) > REPR_OUTPUT_SIZE:
             data[-1] = "...(remaining elements truncated)..."
         return f"<{self.__class__.__name__} {data!r}>"

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

@@ -1,6 +1,6 @@
 [project]
 name = "plain.postgres"
-version = "0.103.1"
+version = "0.103.3"
 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.3}/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.3/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)

{plain_postgres-0.103.1 → plain_postgres-0.103.3}/tests/public/test_m2m.py

@@ -5,10 +5,13 @@ exercise ManyToManyField accessors, the through model, and the Widget-specific
 unique constraint that produces a realistic ValidationError on duplicate create.
 """
 
+from typing import cast
+
 import pytest
 from app.examples.models.relationships import Tag, Widget, WidgetTag
 
 from plain.exceptions import ValidationError
+from plain.postgres.fields.related import ManyToManyField
 
 
 def test_create_unique_constraint(db):
@@ -94,6 +97,32 @@ def test_many_to_many_clear(db):
     assert widget.tags.query.count() == 0
 
 
+def test_value_from_object_returns_related_objects(db):
+    """ManyToManyField.value_from_object must return the currently-related
+    objects. ModelForm's `model_to_dict` calls this when given an instance
+    so the form can populate `initial` for the M2M field — a regression
+    here breaks UpdateView for any model with an M2M.
+    """
+    widget = Widget.query.create(name="Subaru", size="Outback")
+    gps = Tag.query.create(name="GPS")
+    sunroof = Tag.query.create(name="Sunroof")
+    widget.tags.add(gps, sunroof)
+
+    field = cast(ManyToManyField, Widget._model_meta.get_forward_field("tags"))
+    result = field.value_from_object(widget)
+
+    assert {t.name for t in result} == {"GPS", "Sunroof"}
+
+
+def test_value_from_object_unsaved_instance_returns_empty(db):
+    """An unsaved instance has no related rows; value_from_object should
+    return an empty list rather than crash.
+    """
+    widget = Widget(name="Mazda", size="3")
+    field = cast(ManyToManyField, Widget._model_meta.get_forward_field("tags"))
+    assert list(field.value_from_object(widget)) == []
+
+
 def test_many_to_many_through_model(db):
     """Test accessing the through model directly."""
     widget = Widget.query.create(name="Ford", size="Mustang")

plain_postgres-0.103.3/tests/public/test_queryset_repr.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from app.examples.models.iteration import IterationExample
+
+from plain.postgres.db import get_connection
+
+
+def _capture_queries(callable_):
+    conn = get_connection()
+    prev_force = conn.force_debug_cursor
+    conn.force_debug_cursor = True
+    conn.queries_log.clear()
+    try:
+        callable_()
+        return list(conn.queries_log)
+    finally:
+        conn.force_debug_cursor = prev_force
+
+
+def test_repr_does_not_execute_sql_when_unevaluated(db):
+    """repr() of an unevaluated queryset must not issue a SQL query.
+
+    Error reporters (Sentry, pdb, exception templates) call repr() on
+    stack-frame locals; a surprise SELECT inside an exception path can
+    overload the database.
+    """
+    qs = IterationExample.query.all()
+
+    queries = _capture_queries(lambda: repr(qs))
+
+    assert queries == []
+    assert repr(qs) == "<QuerySet [unevaluated]>"
+
+
+def test_repr_uses_cache_when_evaluated(db):
+    """Once a queryset is evaluated, repr() reflects its rows without re-querying."""
+    IterationExample.query.create(name="alpha", tag="a")
+    IterationExample.query.create(name="beta", tag="b")
+
+    qs = IterationExample.query.all()
+    list(qs)  # force evaluation, populates _result_cache
+
+    queries = _capture_queries(lambda: repr(qs))
+
+    assert queries == []
+    rendered = repr(qs)
+    assert "[unevaluated]" not in rendered
+    assert rendered.count("IterationExample") == 2
+
+
+def test_repr_truncates_large_evaluated_querysets(db):
+    """The truncation marker still appears past REPR_OUTPUT_SIZE."""
+    for i in range(25):
+        IterationExample.query.create(name=f"name{i:02d}", tag="t")
+
+    qs = IterationExample.query.all()
+    list(qs)
+
+    rendered = repr(qs)
+    assert "remaining elements truncated" in rendered