plain.postgres 0.107.0__tar.gz → 0.108.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.107.0
+Version: 0.108.0
 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.107.0 → plain_postgres-0.108.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,27 @@
 # plain-postgres changelog
 
+## [0.108.0](https://github.com/dropseed/plain/releases/plain-postgres@0.108.0) (2026-06-09)
+
+### What's changed
+
+- A partial index of exactly `WHERE <fk> IS NOT NULL` on the FK column now counts as FK index coverage — every FK lookup and referencing-side sweep is a `WHERE fk = ?`, which implies the predicate, so Postgres can always use it. Both the `postgres.missing_fk_indexes` preflight check (an `Index`/`UniqueConstraint` with `condition=Q(fk__isnull=False)`) and the doctor's missing-FK check (matching the live index predicate) accept it; any other partial predicate still doesn't count. ([4836069767](https://github.com/dropseed/plain/commit/4836069767))
+- The missing-FK-index warning now points out when an existing composite index or constraint already contains the FK at a non-leading position, suggesting a reorder to lead with the FK instead of adding a new index (safe when every query using the composite filters all of its columns with equality). ([084b6abba5](https://github.com/dropseed/plain/commit/084b6abba5))
+- Internal: the preflight checks moved from a single `preflight.py` into a `preflight/` package (`models.py`, `database.py`, `indexes.py`). Check names and behavior are unchanged. ([edc792d358](https://github.com/dropseed/plain/commit/edc792d358))
+
+### Upgrade instructions
+
+- No changes required.
+
+## [0.107.1](https://github.com/dropseed/plain/releases/plain-postgres@0.107.1) (2026-06-08)
+
+### What's changed
+
+- Internal: typing-only cleanup for the `ty` 0.0.45 upgrade. `Query.order_by` is now annotated `tuple[Any, ...]` instead of relying on empty-tuple inference, a few field-name dict keys are narrowed via `assert` or the known-`str` loop variable, and `ty: ignore` comments on the intentionally heterogeneous `get_fields()` / `klass_info` structures were adjusted (net removal of several ignores). No runtime behavior changes. ([5c8015795d](https://github.com/dropseed/plain/commit/5c8015795d), [95f54e880d](https://github.com/dropseed/plain/commit/95f54e880d))
+
+### Upgrade instructions
+
+- No changes required.
+
 ## [0.107.0](https://github.com/dropseed/plain/releases/plain-postgres@0.107.0) (2026-06-07)
 
 ### What's changed

{plain_postgres-0.107.0 → plain_postgres-0.108.0}/plain/postgres/constraints.py

@@ -385,7 +385,7 @@ class UniqueConstraint(BaseConstraint):
                     # A composite constraint containing NULL value cannot cause
                     # a violation since NULL != NULL in SQL.
                     return
-                lookup_kwargs[field.name] = lookup_value
+                lookup_kwargs[field_name] = lookup_value
             queryset = queryset.filter(**lookup_kwargs)
         else:
             # Ignore constraints with excluded fields.

{plain_postgres-0.107.0 → plain_postgres-0.108.0}/plain/postgres/introspection/health/checks_structural.py

@@ -192,10 +192,11 @@ def check_missing_fk_indexes(
     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.
+    still sequential-scan. The one exception is a predicate of exactly
+    ``<fk> IS NOT NULL`` on the FK column itself — every FK lookup and
+    referencing-side sweep is a ``WHERE fk = ?``, which implies
+    ``fk IS NOT NULL``, so Postgres can always use that partial. Match
+    the preflight's coverage rule.
     """
     cursor.execute("""
         SELECT
@@ -216,7 +217,11 @@ 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
+                AND (
+                    i.indpred IS NULL
+                    OR pg_get_expr(i.indpred, i.indrelid) =
+                        format('(%s IS NOT NULL)', quote_ident(a.attname))
+                )
           )
         ORDER BY ct.relname, a.attname
     """)

{plain_postgres-0.107.0 → plain_postgres-0.108.0}/plain/postgres/meta.py

@@ -511,8 +511,9 @@ class Meta:
                 fields.append(field.remote_field)
 
         if forward:
-            fields += self.local_fields
-            fields += self.local_many_to_many
+            # get_fields() intentionally returns a heterogeneous list of field types.
+            fields += self.local_fields  # ty: ignore[unsupported-operator]
+            fields += self.local_many_to_many  # ty: ignore[unsupported-operator]
 
         # In order to avoid list manipulation. Always
         # return a shallow copy of the results

{plain_postgres-0.107.0 → plain_postgres-0.108.0}/plain/postgres/migrations/executor.py

@@ -47,7 +47,7 @@ class MigrationExecutor:
                 if migration not in applied:
                     plan.append(self.loader.graph.nodes[migration])
                     applied[migration] = self.loader.graph.nodes[migration]
-        return plan
+        return plan  # ty: ignore[invalid-return-type] (graph.nodes may hold dummy None, never reached here)
 
     def _create_project_state(
         self, with_applied_migrations: bool = False

{plain_postgres-0.107.0 → plain_postgres-0.108.0}/plain/postgres/migrations/state.py

@@ -550,7 +550,7 @@ class StateModelsRegistry(ModelsRegistry):
         self.ready = True
 
         # There shouldn't be any operations pending at this point.
-        from plain.postgres.preflight import _check_lazy_references
+        from plain.postgres.preflight.models import _check_lazy_references
 
         if errors := _check_lazy_references(self, packages_registry):
             raise ValueError("\n".join(error.fix for error in errors))
@@ -679,6 +679,7 @@ class ModelState:
             if getattr(field, "remote_field", None) and exclude_rels:
                 continue
             name = field.name
+            assert name is not None
             try:
                 fields.append((name, field.clone()))
             except TypeError as e:
@@ -688,6 +689,7 @@ class ModelState:
         if not exclude_rels:
             for field in model._model_meta.local_many_to_many:
                 name = field.name
+                assert name is not None
                 try:
                     fields.append((name, field.clone()))
                 except TypeError as e:
@@ -699,7 +701,7 @@ class ModelState:
             bases = []
             for base in model.__bases__:
                 bases.append(base)
-            return bases
+            return bases  # ty: ignore[invalid-return-type] (__bases__ widens to list[type])
 
         # We can't rely on __mro__ directly because we only want to flatten
         # abstract models and not the whole tree. However by recursing on

plain_postgres-0.108.0/plain/postgres/preflight/__init__.py

@@ -0,0 +1,2 @@
+# Import these to force registration of checks
+from . import database, indexes, models  # NOQA

plain_postgres-0.108.0/plain/postgres/preflight/database.py

@@ -0,0 +1,158 @@
+"""Preflight checks on the database connection and migration state."""
+
+from __future__ import annotations
+
+from plain.postgres.db import get_connection
+from plain.preflight import PreflightCheck, PreflightResult, register_check
+from plain.runtime import settings
+
+
+@register_check("postgres.middleware_installed")
+class CheckMiddlewareInstalled(PreflightCheck):
+    """Errors if `DatabaseConnectionMiddleware` isn't in `MIDDLEWARE`.
+
+    Without it, pooled connections are only released by GC at the end of
+    each request — relying on refcount timing under load is a recipe for
+    pool exhaustion under cyclic refs or delayed finalization.
+    """
+
+    REQUIRED = "plain.postgres.DatabaseConnectionMiddleware"
+
+    def run(self) -> list[PreflightResult]:
+        if self.REQUIRED in settings.MIDDLEWARE:
+            return []
+        return [
+            PreflightResult(
+                fix=(
+                    f"Add '{self.REQUIRED}' to MIDDLEWARE so pooled "
+                    "database connections are returned at the end of each "
+                    "request. Place it first so its after_response runs "
+                    "after any middleware that queries the database."
+                ),
+                id="postgres.middleware_not_installed",
+            )
+        ]
+
+
+@register_check("postgres.postgres_version")
+class CheckPostgresVersion(PreflightCheck):
+    """Checks that the PostgreSQL server meets the minimum version requirement."""
+
+    MINIMUM_VERSION = 16
+
+    def run(self) -> list[PreflightResult]:
+        conn = get_connection()
+        conn.ensure_connection()
+        assert conn.connection is not None
+        major, minor = divmod(conn.connection.info.server_version, 10000)
+        if major < self.MINIMUM_VERSION:
+            return [
+                PreflightResult(
+                    fix=f"PostgreSQL {self.MINIMUM_VERSION} or later is required (found {major}.{minor}).",
+                    id="postgres.postgres_version_too_old",
+                )
+            ]
+        return []
+
+
+@register_check("postgres.database_tables")
+class CheckDatabaseTables(PreflightCheck):
+    """Checks for unknown tables in the database when plain.postgres is available."""
+
+    def run(self) -> list[PreflightResult]:
+        from plain.postgres.introspection import get_unknown_tables
+
+        unknown_tables = get_unknown_tables()
+
+        if not unknown_tables:
+            return []
+
+        table_names = ", ".join(unknown_tables)
+        return [
+            PreflightResult(
+                fix=f"Unknown tables in default database: {table_names}. "
+                "Tables may be from packages/models that have been uninstalled. "
+                "Make sure you have a backup, then run `plain postgres drop-unknown-tables` to remove them.",
+                id="postgres.unknown_database_tables",
+                warning=True,
+            )
+        ]
+
+
+@register_check("postgres.prunable_migrations")
+class CheckPrunableMigrations(PreflightCheck):
+    """Warns about stale migration records in the database."""
+
+    def run(self) -> list[PreflightResult]:
+        # Import here to avoid circular import issues
+        from plain.postgres.migrations.loader import MigrationLoader
+        from plain.postgres.migrations.recorder import MigrationRecorder
+
+        errors = []
+
+        # Load migrations from disk and database
+        conn = get_connection()
+        loader = MigrationLoader(conn, ignore_no_migrations=True)
+        recorder = MigrationRecorder(conn)
+        recorded_migrations = recorder.applied_migrations()
+
+        # disk_migrations should not be None after MigrationLoader initialization,
+        # but check to satisfy type checker
+        if loader.disk_migrations is None:
+            return errors
+
+        # Find all prunable migrations (recorded but not on disk)
+        all_prunable = [
+            migration
+            for migration in recorded_migrations
+            if migration not in loader.disk_migrations
+        ]
+
+        if not all_prunable:
+            return errors
+
+        # Separate into existing packages vs orphaned packages
+        existing_packages = set(loader.migrated_packages)
+        prunable_existing: list[tuple[str, str]] = []
+        prunable_orphaned: list[tuple[str, str]] = []
+
+        for migration in all_prunable:
+            package, name = migration
+            if package in existing_packages:
+                prunable_existing.append(migration)
+            else:
+                prunable_orphaned.append(migration)
+
+        # Build the warning message
+        total_count = len(all_prunable)
+        message_parts = [
+            f"Found {total_count} stale migration record{'s' if total_count != 1 else ''} in the database."
+        ]
+
+        if prunable_existing:
+            existing_list = ", ".join(
+                f"{pkg}.{name}" for pkg, name in prunable_existing[:3]
+            )
+            if len(prunable_existing) > 3:
+                existing_list += f" (and {len(prunable_existing) - 3} more)"
+            message_parts.append(f"From existing packages: {existing_list}.")
+
+        if prunable_orphaned:
+            orphaned_list = ", ".join(
+                f"{pkg}.{name}" for pkg, name in prunable_orphaned[:3]
+            )
+            if len(prunable_orphaned) > 3:
+                orphaned_list += f" (and {len(prunable_orphaned) - 3} more)"
+            message_parts.append(f"From removed packages: {orphaned_list}.")
+
+        message_parts.append("Run 'plain migrations prune' to review and remove them.")
+
+        errors.append(
+            PreflightResult(
+                fix=" ".join(message_parts),
+                id="postgres.prunable_migrations",
+                warning=True,
+            )
+        )
+
+        return errors

plain_postgres-0.108.0/plain/postgres/preflight/indexes.py

@@ -0,0 +1,250 @@
+"""Preflight checks for index coverage on app models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from plain.packages import packages_registry
+from plain.postgres.constraints import UniqueConstraint
+from plain.postgres.expressions import F, OrderBy
+from plain.postgres.fields.related import ForeignKeyField
+from plain.postgres.query_utils import Q
+from plain.postgres.registry import models_registry
+from plain.preflight import PreflightCheck, PreflightResult, register_check
+
+
+def _get_app_models() -> list[Any]:
+    """Return models from the user's app packages only (not framework/third-party)."""
+    app_models = []
+    for package_config in packages_registry.get_package_configs():
+        if package_config.name.startswith("app."):
+            app_models.extend(
+                models_registry.get_models(package_label=package_config.package_label)
+            )
+    return app_models
+
+
+def _collect_model_indexes(model: Any) -> list[tuple[str, list[str], bool]]:
+    """Collect (name, fields, is_unique) for non-partial indexes/constraints.
+
+    Partials are skipped: they only apply to rows matching their predicate,
+    so they're never interchangeable with a full index for duplicate
+    detection or reorder suggestions.
+    """
+    all_indexes: list[tuple[str, list[str], bool]] = []
+
+    for index in model.model_options.indexes:
+        if index.fields and not index.is_partial:
+            fields = [f.lstrip("-") for f in index.fields]
+            all_indexes.append((index.name, fields, False))
+
+    for constraint in model.model_options.constraints:
+        if (
+            isinstance(constraint, UniqueConstraint)
+            and constraint.fields
+            and not constraint.is_partial
+        ):
+            all_indexes.append((constraint.name, list(constraint.fields), True))
+
+    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 _leading_field_name(
+    fields: tuple[str, ...] | list[str], expressions: tuple
+) -> str | None:
+    """The leading column's field name, or `None` if it's an expression."""
+    if fields:
+        return fields[0].lstrip("-")
+    if expressions:
+        return _bare_column_name(expressions[0])
+    return None
+
+
+def _condition_is_not_null_on(condition: Q, field_name: str) -> bool:
+    """True if `condition` is exactly ``Q(<field_name>__isnull=False)``."""
+    return (
+        not condition.negated
+        and len(condition.children) == 1
+        and condition.children[0] == (f"{field_name}__isnull", False)
+    )
+
+
+def _fk_covered_field_names(model: Any) -> set[str]:
+    """Field names that appear as the leading column of an index or unique
+    constraint — covering arbitrary FK lookups via the index's leading
+    column. Includes expression-based indexes/constraints whose leading
+    expression is a bare ``F(field_name)``.
+
+    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 one exception is a predicate of exactly
+    ``Q(<fk>__isnull=False)`` on the leading FK itself — every FK lookup
+    and referencing-side sweep is a ``WHERE fk = ?``, which implies
+    ``fk IS NOT NULL``, so Postgres can always use that partial. Match
+    the doctor's coverage rule in
+    ``introspection/health/checks_structural.py``.
+    """
+    covered: set[str] = set()
+
+    def _record(index_or_constraint: Any) -> None:
+        leading = _leading_field_name(
+            index_or_constraint.fields, index_or_constraint.expressions
+        )
+        if leading is None:
+            return
+        if not index_or_constraint.is_partial or _condition_is_not_null_on(
+            index_or_constraint.condition, leading
+        ):
+            covered.add(leading)
+
+    for index in model.model_options.indexes:
+        _record(index)
+
+    for constraint in model.model_options.constraints:
+        if isinstance(constraint, UniqueConstraint):
+            _record(constraint)
+
+    return covered
+
+
+def _composite_containing(model: Any, field_name: str) -> tuple[str, list[str]] | None:
+    """First non-partial index/constraint with `field_name` at a non-leading position.
+
+    A non-leading column doesn't cover the FK, but reordering the composite to
+    lead with it often can — worth suggesting in the fix message.
+    """
+    for name, fields, _is_unique in _collect_model_indexes(model):
+        if field_name in fields[1:]:
+            return name, fields
+    return None
+
+
+@register_check("postgres.missing_fk_indexes")
+class CheckMissingFKIndexes(PreflightCheck):
+    """Warns about foreign key fields without index coverage."""
+
+    def run(self) -> list[PreflightResult]:
+        results = []
+
+        for model in _get_app_models():
+            covered_fields = _fk_covered_field_names(model)
+
+            for field in model._model_meta.local_fields:
+                if (
+                    isinstance(field, ForeignKeyField)
+                    and not field.primary_key
+                    and field.name not in covered_fields
+                ):
+                    fix = (
+                        f"Foreign key '{field.name}' has no index coverage. "
+                        f"Add an Index on [\"{field.name}\"] or a constraint with '{field.name}' as the first field."
+                    )
+
+                    if composite := _composite_containing(model, field.name):
+                        composite_name, composite_fields = composite
+                        fix += (
+                            f" Alternatively, '{composite_name}' on [{', '.join(composite_fields)}] "
+                            f"already includes '{field.name}' — reordering it to put '{field.name}' first "
+                            f"covers this FK without a new index (safe when every query using it "
+                            f"filters all of its columns with equality)."
+                        )
+
+                    results.append(
+                        PreflightResult(
+                            fix=fix,
+                            obj=f"{model.model_options.label}.{field.name}",
+                            id="postgres.missing_fk_index",
+                            warning=True,
+                        )
+                    )
+
+        return results
+
+
+@register_check("postgres.duplicate_indexes")
+class CheckDuplicateIndexes(PreflightCheck):
+    """Warns about indexes redundant with other indexes or constraints.
+
+    Catches both prefix-redundancy (a 1-column index shadowed by a wider
+    composite) and exact-column duplicates (an `Index(fields=["x"])` that
+    duplicates a same-column `UniqueConstraint`).
+    """
+
+    def run(self) -> list[PreflightResult]:
+        results = []
+
+        for model in _get_app_models():
+            all_indexes = _collect_model_indexes(model)
+
+            flagged: set[str] = set()
+            for i, idx_a in enumerate(all_indexes):
+                for idx_b in all_indexes[i + 1 :]:
+                    for shorter, longer in [(idx_a, idx_b), (idx_b, idx_a)]:
+                        s_name, s_fields, s_unique = shorter
+                        l_name, l_fields, l_unique = longer
+
+                        if s_name in flagged:
+                            continue
+
+                        is_prefix_dup = (
+                            not s_unique
+                            and len(s_fields) < len(l_fields)
+                            and l_fields[: len(s_fields)] == s_fields
+                        )
+                        is_exact_dup = (
+                            s_fields == l_fields
+                            and not s_unique
+                            and (l_unique or s_name > l_name)
+                        )
+
+                        if not (is_prefix_dup or is_exact_dup):
+                            continue
+
+                        if is_prefix_dup:
+                            fix = (
+                                f"Index '{s_name}' on [{', '.join(s_fields)}] "
+                                f"is redundant with '{l_name}' on [{', '.join(l_fields)}]. "
+                                f"The longer index covers the same queries."
+                            )
+                        elif l_unique:
+                            fix = (
+                                f"Index '{s_name}' on [{', '.join(s_fields)}] "
+                                f"is redundant with '{l_name}' on the same columns. "
+                                f"The unique-backed index already covers these queries."
+                            )
+                        else:
+                            fix = (
+                                f"Index '{s_name}' on [{', '.join(s_fields)}] "
+                                f"is an exact duplicate of '{l_name}'. "
+                                f"Drop one of them."
+                            )
+
+                        results.append(
+                            PreflightResult(
+                                fix=fix,
+                                obj=model.model_options.label,
+                                id="postgres.duplicate_index",
+                                warning=True,
+                            )
+                        )
+                        flagged.add(s_name)
+
+        return results