plain.postgres 0.92.0__tar.gz → 0.93.0__tar.gz

{plain_postgres-0.92.0 → plain_postgres-0.93.0}/.gitignore

@@ -20,3 +20,4 @@ plain*/tests/.plain
 /.claude/settings.local.json
 /CLAUDE.local.md
 /.benchmarks
+.claude/worktrees

{plain_postgres-0.92.0 → plain_postgres-0.93.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.92.0
+Version: 0.93.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.92.0 → plain_postgres-0.93.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,27 @@
 # plain-postgres changelog
 
+## [0.93.0](https://github.com/dropseed/plain/releases/plain-postgres@0.93.0) (2026-04-01)
+
+### What's changed
+
+- **Added `db.client.operation.duration` OTel histogram for database query timing.** Every query executed through `db_span()` now records its duration as an OpenTelemetry histogram metric, following the [semantic conventions](https://opentelemetry.io/docs/specs/semconv/db/database-metrics/) for database client metrics. Attributes include `db.system.name`, `db.operation.name`, and `db.collection.name`. Without a configured `MeterProvider`, this is a no-op with zero overhead. ([56c2f993b88c](https://github.com/dropseed/plain/commit/56c2f993b88c))
+
+### Upgrade instructions
+
+- No changes required.
+
+## [0.92.1](https://github.com/dropseed/plain/releases/plain-postgres@0.92.1) (2026-03-30)
+
+### What's changed
+
+- **Fixed false-positive "definition differs" for UniqueConstraint with expressions and conditions.** A `UniqueConstraint` using both expressions (e.g. `Lower("username")`) and a `condition` (e.g. `~Q(username="")`) was incorrectly flagged as drifted. PostgreSQL adds type casts (`''::text`) and the ORM adds extra parentheses around expressions — the old full-SQL-string comparison couldn't reconcile these differences. ([e03f3496a49a](https://github.com/dropseed/plain/commit/e03f3496a49a))
+
+- **Replaced fragile full-SQL comparison with structured comparison for all index and constraint definitions.** Instead of normalizing entire `CREATE INDEX` statements, convergence now parses `pg_get_indexdef` output into components (expression text, columns, opclasses, WHERE clause) and compares each independently. Both regular indexes and unique constraints share a single comparison core. ([e03f3496a49a](https://github.com/dropseed/plain/commit/e03f3496a49a))
+
+### Upgrade instructions
+
+- No changes required.
+
 ## [0.92.0](https://github.com/dropseed/plain/releases/plain-postgres@0.92.0) (2026-03-30)
 
 ### What's changed

{plain_postgres-0.92.0 → plain_postgres-0.93.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -33,17 +33,10 @@ Get approval before writing any model code or generating migrations.
 
 ## Migrations
 
-- `uv run plain postgres sync` — the primary command: makes migrations (in DEBUG), applies them, and converges
-- `uv run plain migrations create` — create migrations (`--dry-run` to preview, `--check` for CI)
-- `uv run plain migrations apply` — apply migrations
-- `uv run plain migrations list` — view status
-- Before committing, consolidate multiple uncommitted migrations into one:
-  delete the intermediate files, run `migrations prune --yes` to clean stale DB records,
-  run `migrations create` fresh, then `migrations apply --fake` to mark it applied
-- Use `migrations squash` only for already-committed/deployed migrations — never for dev cleanup
-- Only write migrations by hand for custom data migrations
-
-Run `uv run plain docs postgres --section migrations` for full workflow details.
+- `uv run plain postgres sync` — creates migrations (in DEBUG), applies them, and converges
+- 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 individual migration commands and full workflow details.
 
 ## Querying
 
@@ -62,9 +55,10 @@ Run `uv run plain docs postgres --section querying` for full patterns with code
 
 ## Schema Design
 
+- Always index FK columns — Postgres doesn't auto-create these. Use an `Index`, or a constraint with the FK as the first field.
 - Index fields used in `.filter()` and `.order_by()`
-- `Index` requires a `name` argument — use `{table}_{column(s)}_idx` (e.g., `plainjobs_jobrequest_priority_idx`, `plainobserver_log_trace_id_timestamp_idx`)
-- Use `UniqueConstraint` in constraints, not `unique=True` on fields
+- Indexes: `{table}_{column(s)}_idx`
+- Constraints: `{table}_{column(s)}_{type}` (e.g., `_unique`, `_check`)
 - Choose `on_delete` deliberately: CASCADE for children, PROTECT for referenced data
 - No `allow_null` on string fields — use `default=""`
 
@@ -81,6 +75,5 @@ Run `uv run plain docs postgres --section diagnostics` for check details, thresh
 - Use `Model.query` not `Model.objects`
 - Import fields from `plain.postgres.types` not `plain.postgres.fields` — and don't import field classes directly from `plain.postgres`
 - Use `model_options = postgres.Options(...)` not `class Meta`
-- Fields don't accept `unique=True` — use `UniqueConstraint` in constraints
 - Never format raw SQL strings — always use parameterized queries
 - Migrations are forward-only — no reverse migrations. `RunPython` takes a single callable (no `reverse_code` or `noop`). The callable signature is `fn(models, schema_editor)`, not `fn(apps, schema_editor)`

{plain_postgres-0.92.0 → plain_postgres-0.93.0}/plain/postgres/convergence/analysis.py

@@ -7,6 +7,7 @@ from functools import cached_property
 from typing import TYPE_CHECKING, Any
 
 from ..constraints import CheckConstraint, UniqueConstraint
+from ..ddl import compile_expression_sql, compile_index_expressions_sql
 from ..dialect import quote_name
 from ..fields.related import ForeignKeyField
 from ..indexes import Index
@@ -18,6 +19,7 @@ from ..introspection import (
     TableState,
     introspect_table,
     normalize_check_definition,
+    normalize_expression,
     normalize_index_definition,
     normalize_unique_definition,
 )
@@ -25,6 +27,8 @@ from ..introspection import (
 if TYPE_CHECKING:
     from ..base import Model
     from ..connection import DatabaseConnection
+    from ..expressions import Expression, ReplaceableExpression
+    from ..query_utils import Q
     from ..utils import CursorWrapper
 
 
@@ -421,21 +425,8 @@ def _compare_indexes(
 
         # Check if definition matches
         if db_idx.definition:
-            expected_def = normalize_index_definition(index.to_sql(model))
-            actual_def = normalize_index_definition(db_idx.definition)
-            if expected_def != actual_def:
-                if index.fields:
-                    expected_columns = [
-                        model._model_meta.get_forward_field(field_name).column
-                        for field_name in index.fields
-                    ]
-                    issue = (
-                        f"columns differ: DB has {db_idx.columns}, model expects {expected_columns}"
-                        if expected_columns != db_idx.columns
-                        else f"definition differs: DB has {db_idx.definition!r}"
-                    )
-                else:
-                    issue = f"definition differs: DB has {db_idx.definition!r}"
+            issue = _compare_index_definition(model, index, db_idx.definition)
+            if issue:
                 statuses.append(
                     IndexStatus(
                         name=index.name,
@@ -554,6 +545,23 @@ def _compare_indexes(
     return statuses
 
 
+def _compare_index_definition(
+    model: type[Model], index: Index, actual_def: str
+) -> str | None:
+    """Compare a model index against its pg_get_indexdef output.
+
+    Returns an issue string if definitions differ, None if they match.
+    """
+    return _compare_parsed_index(
+        model=model,
+        expressions=index.expressions,
+        fields=[name for name, _ in index.fields_orders],
+        opclasses=list(index.opclasses) if index.opclasses else [],
+        condition=index.condition,
+        actual_def=actual_def,
+    )
+
+
 # Constraint comparison
 
 
@@ -1099,67 +1107,78 @@ def _compare_index_only_unique(
     Index-only variants (condition, expressions, opclasses) live as unique
     indexes in PostgreSQL, not pg_constraint rows.  Their ConstraintState
     comes from the pg_index query path with a pg_get_indexdef definition.
-
-    For expression-based constraints we compare normalized index definitions.
-    For field-based (condition/opclass) we parse pg_get_indexdef into
-    structured components and compare each, avoiding fragile cross-format
-    SQL normalization between the ORM and PostgreSQL.
     """
     actual_def = actual_state.definition
     if not actual_def:
         return None, None
 
-    changed = ConstraintDrift(
-        kind=DriftKind.CHANGED, table=table, constraint=constraint, model=model
+    issue = _compare_parsed_index(
+        model=model,
+        expressions=constraint.expressions,
+        fields=list(constraint.fields),
+        opclasses=list(constraint.opclasses) if constraint.opclasses else [],
+        condition=constraint.condition,
+        actual_def=actual_def,
     )
+    if issue:
+        changed = ConstraintDrift(
+            kind=DriftKind.CHANGED, table=table, constraint=constraint, model=model
+        )
+        return issue, changed
 
-    if constraint.expressions:
-        # Expression-based: the expression IS the core structure, so
-        # normalized-definition comparison is the right tool.
-        expected_def = constraint.to_sql(model)
-        if normalize_index_definition(actual_def) != normalize_index_definition(
-            expected_def
-        ):
-            return f"definition differs: DB has {actual_def!r}", changed
+    return None, None
+
+
+def _compare_parsed_index(
+    *,
+    model: type[Model],
+    expressions: tuple[Expression | ReplaceableExpression, ...],
+    fields: list[str],
+    opclasses: list[str],
+    condition: Q | None,
+    actual_def: str,
+) -> str | None:
+    """Structured comparison of a model index/constraint against pg_get_indexdef.
+
+    Parses the DB definition into components (expression text, columns,
+    opclasses, WHERE clause) and compares each independently, avoiding
+    fragile full-SQL normalization between the ORM and PostgreSQL.
+
+    Returns an issue string if definitions differ, None if they match.
+    """
+    db_parts = _parse_index_definition(actual_def)
+
+    if expressions:
+        expected_expr = normalize_expression(
+            compile_index_expressions_sql(model, expressions)
+        )
+        actual_expr = normalize_expression(db_parts.expression_text)
+        if actual_expr != expected_expr:
+            return f"definition differs: DB has {actual_def!r}"
     else:
-        # Field-based with condition/opclasses: compare structured components
-        # parsed from pg_get_indexdef rather than normalizing full SQL strings.
-        db_parts = _parse_index_definition(actual_def)
         expected_columns = [
-            model._model_meta.get_forward_field(f).column for f in constraint.fields
+            model._model_meta.get_forward_field(f).column for f in fields
         ]
         if db_parts.columns != expected_columns:
-            return (
-                f"columns differ: DB has {db_parts.columns}, model expects {expected_columns}",
-                changed,
-            )
-        expected_opclasses = list(constraint.opclasses) if constraint.opclasses else []
-        if db_parts.opclasses != expected_opclasses:
-            return (
-                f"opclasses differ: DB has {db_parts.opclasses}, model expects {expected_opclasses}",
-                changed,
-            )
-        has_condition = constraint.condition is not None
-        if has_condition != db_parts.has_where:
-            where_desc = "has WHERE" if db_parts.has_where else "no WHERE"
-            return (
-                f"condition differs: DB {where_desc}, model {'has' if has_condition else 'no'} condition",
-                changed,
-            )
-        if has_condition and db_parts.where_clause:
-            from ..ddl import compile_expression_sql
-
-            assert constraint.condition is not None
-            expected_where = compile_expression_sql(model, constraint.condition)
-            if normalize_check_definition(
-                db_parts.where_clause
-            ) != normalize_check_definition(expected_where):
-                return (
-                    f"condition differs: DB has WHERE ({db_parts.where_clause})",
-                    changed,
-                )
+            return f"columns differ: DB has {db_parts.columns}, model expects {expected_columns}"
 
-    return None, None
+        if db_parts.opclasses != opclasses:
+            return f"opclasses differ: DB has {db_parts.opclasses}, model expects {opclasses}"
+
+    # Compare WHERE clause
+    has_condition = condition is not None
+    if has_condition != db_parts.has_where:
+        where_desc = "has WHERE" if db_parts.has_where else "no WHERE"
+        return f"condition differs: DB {where_desc}, model {'has' if has_condition else 'no'} condition"
+    if has_condition and db_parts.where_clause:
+        assert condition is not None
+        expected_where = compile_expression_sql(model, condition)
+        if normalize_check_definition(
+            db_parts.where_clause
+        ) != normalize_check_definition(expected_where):
+            return f"condition differs: DB has WHERE ({db_parts.where_clause})"
+
+    return None
 
 
 @dataclass
@@ -1170,6 +1189,7 @@ class _IndexParts:
     opclasses: list[str]
     has_where: bool
     where_clause: str | None
+    expression_text: str  # raw text between the column-list parens
 
 
 def _parse_index_definition(definition: str) -> _IndexParts:
@@ -1202,6 +1222,7 @@ def _parse_index_definition(definition: str) -> _IndexParts:
     # Find the column list: content between parens after USING method
     columns: list[str] = []
     opclasses: list[str] = []
+    expression_text = ""
     using_match = re.search(r"\busing\s+\w+\s*\(", s)
     if using_match:
         start = using_match.end()
@@ -1212,8 +1233,8 @@ def _parse_index_definition(definition: str) -> _IndexParts:
             elif s[i] == ")":
                 depth -= 1
                 if depth == 0:
-                    col_str = s[start:i].strip()
-                    for part in col_str.split(","):
+                    expression_text = s[start:i].strip()
+                    for part in expression_text.split(","):
                         part = part.strip()
                         # "col opclass" or just "col"
                         tokens = part.split()
@@ -1231,6 +1252,7 @@ def _parse_index_definition(definition: str) -> _IndexParts:
         opclasses=opclasses,
         has_where=has_where,
         where_clause=where_clause,
+        expression_text=expression_text,
     )
 
 
@@ -1238,8 +1260,6 @@ def _get_expected_check_definition(
     model: type[Model], constraint: CheckConstraint
 ) -> str:
     """Generate the CHECK expression that the model would produce."""
-    from ..ddl import compile_expression_sql
-
     check_sql = compile_expression_sql(model, constraint.check)
     return f"CHECK ({check_sql})"
 

{plain_postgres-0.92.0 → plain_postgres-0.93.0}/plain/postgres/introspection/__init__.py

@@ -17,6 +17,7 @@ from .schema import (
     get_unknown_tables,
     introspect_table,
     normalize_check_definition,
+    normalize_expression,
     normalize_index_definition,
     normalize_unique_definition,
 )
@@ -37,6 +38,7 @@ __all__ = [
     "get_unknown_tables",
     "introspect_table",
     "normalize_check_definition",
+    "normalize_expression",
     "normalize_index_definition",
     "normalize_unique_definition",
     "run_all_checks",

{plain_postgres-0.92.0 → plain_postgres-0.93.0}/plain/postgres/introspection/schema.py

@@ -214,13 +214,25 @@ def _normalize_sql(s: str) -> str:
     return re.sub(r"\s+", " ", s).strip()
 
 
+def _strip_type_casts(s: str) -> str:
+    """Strip PostgreSQL type casts (e.g. ''::text, 0::integer).
+
+    PostgreSQL adds explicit casts to stored definitions (pg_get_indexdef,
+    pg_get_constraintdef) but the ORM compiler omits them.  Only used for
+    expression/condition comparison where the two generators diverge.
+    """
+    return re.sub(r"::\w+", "", s)
+
+
 def normalize_check_definition(s: str) -> str:
-    """Normalize a CHECK constraint definition for comparison.
+    """Normalize a CHECK/condition definition for comparison.
 
-    Strips the CHECK(...) wrapper and redundant parentheses so that
-    pg_get_constraintdef output and model-generated SQL can be compared.
+    Strips the CHECK(...) wrapper, redundant parentheses, and PG type casts
+    so that pg_get_constraintdef/pg_get_indexdef output and model-generated
+    SQL can be compared.
     """
     s = _normalize_sql(s)
+    s = _strip_type_casts(s)
     # Strip outer check(...)
     if s.startswith("check"):
         s = s[5:].strip()
@@ -243,6 +255,16 @@ def normalize_unique_definition(s: str) -> str:
     return s
 
 
+def normalize_expression(s: str) -> str:
+    """Normalize an index expression for comparison.
+
+    Lowercases, strips quotes, collapses whitespace, and strips redundant
+    outer parentheses.  Used for comparing the expression portion of index
+    definitions (e.g. 'LOWER("col")' vs 'lower(col)').
+    """
+    return _strip_balanced_parens(_normalize_sql(s))
+
+
 def normalize_index_definition(s: str) -> str:
     """Extract and normalize the expression part of a CREATE INDEX definition.
 

{plain_postgres-0.92.0 → plain_postgres-0.93.0}/plain/postgres/otel.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import re
+import time
 import traceback
 from collections.abc import Generator
 from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any
 
 from opentelemetry import context as otel_context
-from opentelemetry import trace
+from opentelemetry import metrics, trace
+from opentelemetry.semconv.metrics.db_metrics import DB_CLIENT_OPERATION_DURATION
 
 if TYPE_CHECKING:
     from opentelemetry.trace import Span
@@ -47,6 +49,12 @@ _SUPPRESS_KEY = "plain.postgres.suppress_db_tracing"
 
 tracer = trace.get_tracer("plain.postgres")
 
+meter = metrics.get_meter("plain.postgres")
+query_duration_histogram = meter.create_histogram(
+    name=DB_CLIENT_OPERATION_DURATION,
+    unit="s",
+    description="Duration of database client operations.",
+)
 
 DB_SYSTEM = DbSystemValues.POSTGRESQL.value
 
@@ -174,7 +182,18 @@ def db_span(
     with tracer.start_as_current_span(
         span_name, kind=SpanKind.CLIENT, attributes=attrs
     ) as span:
+        start = time.perf_counter()
         yield span
+        duration_s = time.perf_counter() - start
+
+        metric_attrs: dict[str, str] = {
+            DB_SYSTEM_NAME: DB_SYSTEM,
+            DB_OPERATION_NAME: operation,
+        }
+        if collection_name:
+            metric_attrs[DB_COLLECTION_NAME] = collection_name
+        query_duration_histogram.record(duration_s, metric_attrs)
+
         span.set_status(trace.StatusCode.OK)
 
 

{plain_postgres-0.92.0 → plain_postgres-0.93.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.postgres"
-version = "0.92.0"
+version = "0.93.0"
 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.92.0 → plain_postgres-0.93.0}/tests/test_convergence_constraints.py

@@ -25,7 +25,7 @@ from plain.postgres.convergence import (
     plan_convergence,
     plan_model_convergence,
 )
-from plain.postgres.functions.text import Upper
+from plain.postgres.functions.text import Lower, Upper
 from plain.postgres.introspection import ConType
 
 
@@ -816,6 +816,41 @@ class TestIndexBackedUniqueConstraints:
         finally:
             Car.model_options.constraints = original_constraints
 
+    def test_matching_expression_with_condition_no_drift(self, db):
+        """Expression unique with a WHERE clause should not report false-positive drift.
+
+        PG adds type casts (e.g. ''::text) and the ORM adds extra parens around
+        expressions.  Structured comparison handles both.
+        """
+        original_constraints = list(Car.model_options.constraints)
+        constraint = UniqueConstraint(
+            Lower("make"),
+            condition=~Q(make=""),
+            name="examples_car_make_lower_cond_uq",
+        )
+        Car.model_options.constraints = [*original_constraints, constraint]
+
+        execute(constraint.to_sql(Car))
+
+        try:
+            conn = get_connection()
+            with conn.cursor() as cursor:
+                plan = plan_model_convergence(conn, cursor, Car)
+
+            constraint_drifts = [
+                d
+                for d in plan.items
+                if isinstance(d.drift, ConstraintDrift)
+                and d.drift.constraint is not None
+                and d.drift.constraint.name == "examples_car_make_lower_cond_uq"
+            ]
+            assert constraint_drifts == [], (
+                f"Expected no drift for matching expression+condition unique, got: "
+                f"{[d.describe() for d in constraint_drifts]}"
+            )
+        finally:
+            Car.model_options.constraints = original_constraints
+
     # -- Gap 3: full lifecycle converges (create → re-check → no work) --
 
     def test_conditional_unique_lifecycle(self, isolated_db):

{plain_postgres-0.92.0 → plain_postgres-0.93.0}/tests/test_introspection.py

@@ -234,6 +234,13 @@ class TestNormalizeCheckDefinition:
     def test_handles_bare_expression(self):
         assert normalize_check_definition("id > 0") == "id > 0"
 
+    def test_strips_type_casts(self):
+        """PG adds explicit type casts to stored definitions."""
+        assert (
+            normalize_check_definition("CHECK (username <> ''::text)")
+            == "username <> ''"
+        )
+
 
 class TestNormalizeIndexDefinition:
     def test_strips_prefix_with_using(self):
@@ -267,3 +274,12 @@ class TestNormalizeIndexDefinition:
         assert normalize_index_definition(db_def) == normalize_index_definition(
             model_def
         )
+
+    def test_with_where_clause(self):
+        """normalize_index_definition preserves WHERE clause as-is (structured
+        comparison handles WHERE separately)."""
+        result = normalize_index_definition(
+            "CREATE UNIQUE INDEX foo ON public.bar USING btree (lower(username)) WHERE (NOT (username = ''::text))"
+        )
+        assert "where" in result
+        assert "lower(username)" in result