plain.postgres 0.99.0__tar.gz → 0.100.0__tar.gz

plain_postgres-0.99.0/plain/postgres/README.md → plain_postgres-0.100.0/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.4
+Name: plain.postgres
+Version: 0.100.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.**
@@ -1003,7 +1017,7 @@ author.books.query.published()
 
 ### Validation
 
-You can validate models before saving:
+`save()` runs `full_clean()` by default — field validators, model `clean()`, and any constraints with a `validate()` method are all checked, raising `ValidationError` on violation. Pass `clean_and_validate=False` to skip it (e.g. for trusted bulk loads).
 
 ```python
 @postgres.register_model
@@ -1020,10 +1034,6 @@ class User(postgres.Model):
     def clean(self):
         if self.age < 18:
             raise ValidationError("User must be 18 or older")
-
-    def save(self, *args, **kwargs):
-        self.full_clean()  # Runs validation
-        super().save(*args, **kwargs)
 ```
 
 Field-level validation happens automatically based on field types and constraints.
@@ -1050,6 +1060,38 @@ class User(postgres.Model):
     )
 ```
 
+Constraints are also checked during `full_clean()` (which `save()` runs by default — see [Validation](#validation)). Pass `violation_error` to customize the resulting `ValidationError`. It accepts anything `ValidationError(...)` accepts — a string, a `{field: message}` dict, or a fully-formed `ValidationError`:
+
+```python
+# Simple message — lands on NON_FIELD_ERRORS
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error="Age must be zero or greater.",
+)
+
+# Dict form — routes to a specific field
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error={"age": "Age must be zero or greater."},
+)
+
+# Full ValidationError — for code, params, multiple fields
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error=ValidationError(
+        {"age": "Age must be zero or greater."},
+        code="age_negative",
+    ),
+)
+```
+
+A `code` becomes `ValidationError.code` — useful for test assertions, error tracking buckets, and code that branches on specific error types without string-matching.
+
+`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.
+
 ### Schema design
 
 #### Index fields used in filters and ordering

{plain_postgres-0.99.0 → plain_postgres-0.100.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,31 @@
 # plain-postgres changelog
 
+## [0.100.0](https://github.com/dropseed/plain/releases/plain-postgres@0.100.0) (2026-04-28)
+
+### What's changed
+
+- **Replaced the `violation_error_message` / `violation_error_code` triad on `CheckConstraint` and `UniqueConstraint` with a single `violation_error` kwarg.** The new kwarg accepts anything `ValidationError(...)` accepts — a string, a `{field: message}` dict, a list, or a fully-formed `ValidationError` — so message text, error code, and field routing all live on one object. ([8650edc22c09](https://github.com/dropseed/plain/commit/8650edc22c09))
+- **Single-field `UniqueConstraint` now auto-routes flat errors to its field.** A `violation_error="That email is taken."` on `UniqueConstraint(fields=["email"])` lands on the `email` form field instead of `NON_FIELD_ERRORS`. A caller-built `ValidationError({"other_field": ...})` is preserved as-is. ([8650edc22c09](https://github.com/dropseed/plain/commit/8650edc22c09))
+- **Dropped the hardcoded `code == "unique"` routing in `validate_constraints()`.** Routing is now uniform across constraint types: dict-form errors land on fields, flat errors go to `NON_FIELD_ERRORS`. ([8650edc22c09](https://github.com/dropseed/plain/commit/8650edc22c09))
+- **Removed the `%(name)s` interpolation magic** on `BaseConstraint.default_violation_error_message`. The default message still includes the constraint name; users wanting runtime interpolation can pass `ValidationError(..., params={"name": ...})`. ([8650edc22c09](https://github.com/dropseed/plain/commit/8650edc22c09))
+- Documented that `save()` runs `full_clean()` by default (`clean_and_validate=True`); fixed the README's Validation example which previously implied users had to override `save()` to call `full_clean()` manually. ([8650edc22c09](https://github.com/dropseed/plain/commit/8650edc22c09))
+
+### Upgrade instructions
+
+- Replace `violation_error_message="..."` and `violation_error_code="..."` on `CheckConstraint` / `UniqueConstraint` with a single `violation_error=ValidationError("...", code="...")` (or a string if you only need the message).
+- If you relied on the implicit single-field-unique routing for a constraint with a custom `violation_error_code`, no change needed — single-field `UniqueConstraint` still auto-routes by default.
+- If you used `%(name)s` in `violation_error_message`, switch to `ValidationError("...", params={"name": "your_constraint_name"})` or hardcode the name.
+
+## [0.99.1](https://github.com/dropseed/plain/releases/plain-postgres@0.99.1) (2026-04-26)
+
+### What's changed
+
+- **Duplicate-index check now catches expression-prefix duplicates.** Previously the check excluded any index containing expressions (it compared raw `indkey`/`indclass` arrays), so a redundant `(LOWER(email))` alongside `(LOWER(email), team_id)` was missed. The query now compares per-column `pg_get_indexdef(indexrelid, k, false)` text — canonical output that includes column name/expression, opclass, collation, and sort order — and checks `pg_am.amname` separately so a hash and btree on the same column don't false-match. ([4bd8a713649f](https://github.com/dropseed/plain/commit/4bd8a713649f))
+
+### Upgrade instructions
+
+- No changes required.
+
 ## [0.99.0](https://github.com/dropseed/plain/releases/plain-postgres@0.99.0) (2026-04-23)
 
 ### What's changed

plain_postgres-0.99.0/PKG-INFO → plain_postgres-0.100.0/plain/postgres/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: plain.postgres
-Version: 0.99.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.**
@@ -1017,7 +1003,7 @@ author.books.query.published()
 
 ### Validation
 
-You can validate models before saving:
+`save()` runs `full_clean()` by default — field validators, model `clean()`, and any constraints with a `validate()` method are all checked, raising `ValidationError` on violation. Pass `clean_and_validate=False` to skip it (e.g. for trusted bulk loads).
 
 ```python
 @postgres.register_model
@@ -1034,10 +1020,6 @@ class User(postgres.Model):
     def clean(self):
         if self.age < 18:
             raise ValidationError("User must be 18 or older")
-
-    def save(self, *args, **kwargs):
-        self.full_clean()  # Runs validation
-        super().save(*args, **kwargs)
 ```
 
 Field-level validation happens automatically based on field types and constraints.
@@ -1064,6 +1046,38 @@ class User(postgres.Model):
     )
 ```
 
+Constraints are also checked during `full_clean()` (which `save()` runs by default — see [Validation](#validation)). Pass `violation_error` to customize the resulting `ValidationError`. It accepts anything `ValidationError(...)` accepts — a string, a `{field: message}` dict, or a fully-formed `ValidationError`:
+
+```python
+# Simple message — lands on NON_FIELD_ERRORS
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error="Age must be zero or greater.",
+)
+
+# Dict form — routes to a specific field
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error={"age": "Age must be zero or greater."},
+)
+
+# Full ValidationError — for code, params, multiple fields
+postgres.CheckConstraint(
+    check=postgres.Q(age__gte=0),
+    name="age_positive",
+    violation_error=ValidationError(
+        {"age": "Age must be zero or greater."},
+        code="age_negative",
+    ),
+)
+```
+
+A `code` becomes `ValidationError.code` — useful for test assertions, error tracking buckets, and code that branches on specific error types without string-matching.
+
+`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.
+
 ### Schema design
 
 #### Index fields used in filters and ordering

{plain_postgres-0.99.0 → plain_postgres-0.100.0}/plain/postgres/base.py

@@ -812,19 +812,13 @@ class Model(metaclass=ModelBase):
     def validate_constraints(self, exclude: set[str] | None = None) -> None:
         constraints = self.get_constraints()
 
-        errors = {}
+        errors: dict[str, list[ValidationError]] = {}
         for model_class, model_constraints in constraints:
             for constraint in model_constraints:
                 try:
                     constraint.validate(model_class, self, exclude=exclude)
                 except ValidationError as e:
-                    if (
-                        getattr(e, "code", None) == "unique"
-                        and len(constraint.fields) == 1
-                    ):
-                        errors.setdefault(constraint.fields[0], []).append(e)
-                    else:
-                        errors = e.update_error_dict(errors)
+                    errors = e.update_error_dict(errors)
         if errors:
             raise ValidationError(errors)
 

{plain_postgres-0.99.0 → plain_postgres-0.100.0}/plain/postgres/constraints.py

@@ -28,25 +28,20 @@ if TYPE_CHECKING:
 __all__ = ["BaseConstraint", "CheckConstraint", "Deferrable", "UniqueConstraint"]
 
 
+ViolationError = str | dict[str, Any] | list[Any] | ValidationError
+
+
 class BaseConstraint:
-    default_violation_error_message = 'Constraint "%(name)s" is violated.'
-    violation_error_code: str | None = None
-    violation_error_message: str | None = None
+    violation_error: ViolationError | None = None
 
     def __init__(
         self,
         *,
         name: str,
-        violation_error_code: str | None = None,
-        violation_error_message: str | None = None,
+        violation_error: ViolationError | None = None,
     ) -> None:
         self.name = name
-        if violation_error_code is not None:
-            self.violation_error_code = violation_error_code
-        if violation_error_message is not None:
-            self.violation_error_message = violation_error_message
-        else:
-            self.violation_error_message = self.default_violation_error_message
+        self.violation_error = violation_error
 
     @property
     def contains_expressions(self) -> bool:
@@ -64,21 +59,19 @@ class BaseConstraint:
             "subclasses of BaseConstraint must provide a validate() method"
         )
 
-    def get_violation_error_message(self) -> str:
-        assert self.violation_error_message is not None
-        return self.violation_error_message % {"name": self.name}
+    def _build_violation_error(self) -> ValidationError:
+        if self.violation_error is None:
+            return ValidationError(f'Constraint "{self.name}" is violated.')
+        if isinstance(self.violation_error, ValidationError):
+            return self.violation_error
+        return ValidationError(self.violation_error)
 
     def deconstruct(self) -> tuple[str, tuple[Any, ...], dict[str, Any]]:
         path = f"{self.__class__.__module__}.{self.__class__.__name__}"
         path = path.replace("plain.postgres.constraints", "plain.postgres")
         kwargs: dict[str, Any] = {"name": self.name}
-        if (
-            self.violation_error_message is not None
-            and self.violation_error_message != self.default_violation_error_message
-        ):
-            kwargs["violation_error_message"] = self.violation_error_message
-        if self.violation_error_code is not None:
-            kwargs["violation_error_code"] = self.violation_error_code
+        if self.violation_error is not None:
+            kwargs["violation_error"] = self.violation_error
         return (path, (), kwargs)
 
     def clone(self) -> BaseConstraint:
@@ -92,19 +85,14 @@ class CheckConstraint(BaseConstraint):
         *,
         check: Q,
         name: str,
-        violation_error_code: str | None = None,
-        violation_error_message: str | None = None,
+        violation_error: ViolationError | None = None,
     ) -> None:
         self.check = check
         if not getattr(check, "conditional", False):
             raise TypeError(
                 "CheckConstraint.check must be a Q instance or boolean expression."
             )
-        super().__init__(
-            name=name,
-            violation_error_code=violation_error_code,
-            violation_error_message=violation_error_message,
-        )
+        super().__init__(name=name, violation_error=violation_error)
 
     def to_sql(self, model: type[Model], *, not_valid: bool = False) -> str:
         """Generate ALTER TABLE ADD CONSTRAINT CHECK SQL as a plain string."""
@@ -122,27 +110,19 @@ class CheckConstraint(BaseConstraint):
         against = instance._get_field_value_map(meta=model._model_meta, exclude=exclude)
         try:
             if not Q(self.check).check(against):
-                raise ValidationError(
-                    self.get_violation_error_message(), code=self.violation_error_code
-                )
+                raise self._build_violation_error()
         except FieldError:
             pass
 
     def __repr__(self) -> str:
-        return "<{}: check={} name={}{}{}>".format(
+        return "<{}: check={} name={}{}>".format(
             self.__class__.__qualname__,
             self.check,
             repr(self.name),
             (
                 ""
-                if self.violation_error_code is None
-                else f" violation_error_code={self.violation_error_code!r}"
-            ),
-            (
-                ""
-                if self.violation_error_message is None
-                or self.violation_error_message == self.default_violation_error_message
-                else f" violation_error_message={self.violation_error_message!r}"
+                if self.violation_error is None
+                else f" violation_error={self.violation_error!r}"
             ),
         )
 
@@ -151,8 +131,7 @@ class CheckConstraint(BaseConstraint):
             return (
                 self.name == other.name
                 and self.check == other.check
-                and self.violation_error_code == other.violation_error_code
-                and self.violation_error_message == other.violation_error_message
+                and self.violation_error == other.violation_error
             )
         return super().__eq__(other)
 
@@ -183,8 +162,7 @@ class UniqueConstraint(BaseConstraint):
         deferrable: Deferrable | None = None,
         include: tuple[str, ...] | list[str] | None = None,
         opclasses: tuple[str, ...] | list[str] = (),
-        violation_error_code: str | None = None,
-        violation_error_message: str | None = None,
+        violation_error: ViolationError | None = None,
     ) -> None:
         if not name:
             raise ValueError("A unique constraint must be named.")
@@ -234,11 +212,7 @@ class UniqueConstraint(BaseConstraint):
             F(expression) if isinstance(expression, str) else expression
             for expression in expressions
         )
-        super().__init__(
-            name=name,
-            violation_error_code=violation_error_code,
-            violation_error_message=violation_error_message,
-        )
+        super().__init__(name=name, violation_error=violation_error)
 
     @property
     def contains_expressions(self) -> bool:
@@ -299,7 +273,7 @@ class UniqueConstraint(BaseConstraint):
         return sql
 
     def __repr__(self) -> str:
-        return "<{}:{}{}{}{}{}{}{}{}{}>".format(
+        return "<{}:{}{}{}{}{}{}{}{}>".format(
             self.__class__.__qualname__,
             "" if not self.fields else f" fields={repr(self.fields)}",
             "" if not self.expressions else f" expressions={repr(self.expressions)}",
@@ -310,14 +284,8 @@ class UniqueConstraint(BaseConstraint):
             "" if not self.opclasses else f" opclasses={repr(self.opclasses)}",
             (
                 ""
-                if self.violation_error_code is None
-                else f" violation_error_code={self.violation_error_code!r}"
-            ),
-            (
-                ""
-                if self.violation_error_message is None
-                or self.violation_error_message == self.default_violation_error_message
-                else f" violation_error_message={self.violation_error_message!r}"
+                if self.violation_error is None
+                else f" violation_error={self.violation_error!r}"
             ),
         )
 
@@ -331,8 +299,7 @@ class UniqueConstraint(BaseConstraint):
                 and self.include == other.include
                 and self.opclasses == other.opclasses
                 and self.expressions == other.expressions
-                and self.violation_error_code == other.violation_error_code
-                and self.violation_error_message == other.violation_error_message
+                and self.violation_error == other.violation_error
             )
         return super().__eq__(other)
 
@@ -395,22 +362,7 @@ class UniqueConstraint(BaseConstraint):
             queryset = queryset.exclude(id=model_class_id)
         if not self.condition:
             if queryset.exists():
-                if self.expressions:
-                    raise ValidationError(
-                        self.get_violation_error_message(),
-                        code=self.violation_error_code,
-                    )
-                # When fields are defined, use the unique_error_message() for
-                # backward compatibility.
-                for constraint_model, constraints in instance.get_constraints():
-                    for constraint in constraints:
-                        if constraint is self:
-                            raise ValidationError(
-                                instance.unique_error_message(
-                                    constraint_model,
-                                    self.fields,
-                                ),
-                            )
+                raise self._build_unique_violation(instance, model)
         else:
             against = instance._get_field_value_map(
                 meta=model._model_meta, exclude=exclude
@@ -419,9 +371,32 @@ class UniqueConstraint(BaseConstraint):
                 if (self.condition & Exists(queryset.filter(self.condition))).check(
                     against
                 ):
-                    raise ValidationError(
-                        self.get_violation_error_message(),
-                        code=self.violation_error_code,
-                    )
+                    raise self._build_unique_violation(instance, model)
             except FieldError:
                 pass
+
+    def _build_unique_violation(
+        self, instance: Model, model: type[Model]
+    ) -> ValidationError:
+        """Build the ValidationError for a unique violation.
+
+        Single-field unique constraints route the error to that field via the
+        dict form so it surfaces under the field rather than NON_FIELD_ERRORS.
+        """
+        single_field = self.fields[0] if len(self.fields) == 1 else None
+
+        if self.violation_error is not None:
+            err = self._build_violation_error()
+            # Only auto-route flat errors. A ValidationError that already has
+            # an error_dict (from dict-form input or a caller-built instance)
+            # already declares its own field routing — don't override it.
+            if single_field and not hasattr(err, "error_dict"):
+                return ValidationError({single_field: [err]})
+            return err
+
+        if self.fields:
+            err = instance.unique_error_message(model, self.fields)
+            if single_field:
+                return ValidationError({single_field: [err]})
+            return err
+        return ValidationError(f'Constraint "{self.name}" is violated.')

{plain_postgres-0.99.0 → plain_postgres-0.100.0}/plain/postgres/introspection/health/checks_structural.py

@@ -66,50 +66,65 @@ def check_invalid_indexes(
 def check_duplicate_indexes(
     cursor: Any, table_owners: dict[str, TableOwner]
 ) -> CheckResult:
-    """Indexes where one is a column-prefix of another on the same table."""
+    """Indexes where one is a column-prefix of another on the same table.
+
+    Each index column's canonical definition comes from
+    ``pg_get_indexdef(indexrelid, k, false)`` — that text includes the
+    column name or expression, plus any non-default operator class,
+    collation, or sort order. Comparing per-column definitions means we
+    catch expression duplicates (e.g. two ``LOWER(email)`` columns) and
+    won't false-positive across different opclasses or collations.
+    Access method (``pg_am.amname``) is checked separately because the
+    per-column text doesn't include it — a hash and btree on the same
+    column have identical column text but support different operators.
+    """
     cursor.execute("""
         SELECT
             ct.relname AS table_name,
             ci.relname AS index_name,
-            i.indkey::int[] AS column_numbers,
-            i.indclass::int[] AS opclass_numbers,
+            am.amname AS access_method,
+            array(
+                SELECT pg_get_indexdef(i.indexrelid, k, false)
+                FROM generate_series(1, i.indnatts) AS k
+            ) AS column_defs,
             i.indisunique,
-            pg_size_pretty(pg_relation_size(ci.oid)) AS index_size,
-            pg_relation_size(ci.oid) AS index_size_bytes
+            pg_size_pretty(pg_relation_size(ci.oid)) AS index_size
         FROM pg_catalog.pg_index i
         JOIN pg_catalog.pg_class ci ON ci.oid = i.indexrelid
         JOIN pg_catalog.pg_class ct ON ct.oid = i.indrelid
+        JOIN pg_catalog.pg_am am ON am.oid = ci.relam
         JOIN pg_catalog.pg_namespace n ON n.oid = ct.relnamespace
         WHERE n.nspname = 'public'
           AND i.indisvalid
-          AND i.indexprs IS NULL
           AND i.indpred IS NULL
         ORDER BY ct.relname, ci.relname
     """)
     rows = cursor.fetchall()
 
-    # Group by table
-    by_table: dict[str, list[tuple[str, list[int], list[int], bool, str, int]]] = {}
-    for table_name, index_name, cols, opclasses, is_unique, size, size_bytes in rows:
+    by_table: dict[str, list[tuple[str, str, list[str], bool, str]]] = {}
+    for table_name, index_name, am_name, defs, is_unique, size in rows:
         by_table.setdefault(table_name, []).append(
-            (index_name, cols, opclasses, is_unique, size, size_bytes)
+            (index_name, am_name, defs, is_unique, size)
         )
 
     items: list[CheckItem] = []
-    flagged: set[str] = set()  # avoid reporting the same index multiple times
+    flagged: set[str] = set()
     for table_name, indexes in by_table.items():
         for i, idx_a in enumerate(indexes):
             for idx_b in indexes[i + 1 :]:
                 # Check both directions: is either a prefix of the other?
                 for shorter, longer in [(idx_a, idx_b), (idx_b, idx_a)]:
-                    name_s, cols_s, ops_s, unique_s, size_s, _ = shorter
-                    name_l, cols_l, ops_l, _, _, _ = longer
+                    name_s, am_s, defs_s, unique_s, size_s = shorter
+                    name_l, am_l, defs_l, _, _ = longer
+                    # Different access methods serve different operators
+                    # (e.g. hash supports `=` only, btree supports ordering),
+                    # and unique indexes serve a constraint purpose.
                     if (
                         name_s not in flagged
-                        and len(cols_s) < len(cols_l)
-                        and cols_l[: len(cols_s)] == cols_s
-                        and ops_l[: len(cols_s)] == ops_s
-                        and not unique_s  # unique indexes serve a constraint purpose
+                        and am_s == am_l
+                        and not unique_s
+                        and len(defs_s) < len(defs_l)
+                        and defs_l[: len(defs_s)] == defs_s
                     ):
                         source, package, model_class, model_file = _table_info(
                             table_name, table_owners

{plain_postgres-0.99.0 → plain_postgres-0.100.0}/pyproject.toml

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