plain.postgres 0.99.1__tar.gz → 0.101.0__tar.gz

plain_postgres-0.99.1/plain/postgres/README.md → plain_postgres-0.101.0/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.4
+Name: plain.postgres
+Version: 0.101.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.1 → plain_postgres-0.101.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,32 @@
 # plain-postgres changelog
 
+## [0.101.0](https://github.com/dropseed/plain/releases/plain-postgres@0.101.0) (2026-04-30)
+
+### What's changed
+
+- **Validate CHECK constraints in the same converge run that adds them.** `AddConstraintFix` now runs `ALTER TABLE ... ADD CONSTRAINT ... NOT VALID` followed by `ALTER TABLE ... VALIDATE CONSTRAINT` in a single `apply()`. The add is catalog-only (brief lock) and validate uses `SHARE UPDATE EXCLUSIVE` (doesn't block writes), so there's no benefit to deferring validation to a later run. Existing rows are checked before convergence reports success — previously, a CHECK constraint could be added in `NOT VALID` state and the validation step was its own follow-up fix. ([dc7eb8d3c2b7](https://github.com/dropseed/plain/commit/dc7eb8d3c2b7))
+- `plain-postgres` rule references updated for the simpler `plain docs` CLI (no more `--section`). ([e03c3bd8b6d3](https://github.com/dropseed/plain/commit/e03c3bd8b6d3))
+
+### Upgrade instructions
+
+- No changes required. The next `plain postgres sync` (or scheduled converge run) on a database with pending CHECK constraints will now both add and validate them in one step instead of two.
+
+## [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

plain_postgres-0.99.1/PKG-INFO → plain_postgres-0.101.0/plain/postgres/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: plain.postgres
-Version: 0.99.1
-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.1 → plain_postgres-0.101.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -42,7 +42,7 @@ This means: when you add an `Index` or `UniqueConstraint` to a model, no migrati
 
 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 full workflow details.
+Run `uv run plain docs postgres` for full workflow details.
 
 ## Querying
 
@@ -57,7 +57,7 @@ Use `Model.query` to build querysets (e.g., `User.query.filter(is_active=True)`)
 - Wrap multi-step writes in `transaction.atomic()`
 - Always paginate list queries — unbounded querysets get slower as data grows
 
-Run `uv run plain docs postgres --section querying` for full patterns with code examples.
+Run `uv run plain docs postgres` for full patterns with code examples.
 
 ## Schema Design
 
@@ -68,13 +68,13 @@ Run `uv run plain docs postgres --section querying` for full patterns with code
 - Choose `on_delete` deliberately: CASCADE for owned children, RESTRICT for referenced data, SET_NULL for optional references
 - No `allow_null` on string fields — use `default=""`
 
-Run `uv run plain docs postgres --section constraints` for full patterns with code examples.
+Run `uv run plain docs postgres` for full patterns with code examples.
 
 ## Database Doctor
 
 Use the `/plain-postgres-doctor` skill to check overall database health — migration sync, schema correctness, and operational health.
 
-Run `uv run plain docs postgres --section diagnostics` for check details, thresholds, and production usage.
+Run `uv run plain docs postgres` for check details, thresholds, and production usage.
 
 ## Differences from Django
 

{plain_postgres-0.99.1 → plain_postgres-0.101.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.1 → plain_postgres-0.101.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.1 → plain_postgres-0.101.0}/plain/postgres/convergence/fixes.py

@@ -196,7 +196,10 @@ class CreateIndexFix(Fix):
 class AddConstraintFix(Fix):
     """Add a missing constraint.
 
-    Check constraints use NOT VALID to avoid a table scan.
+    Check constraints use ADD CONSTRAINT ... NOT VALID + VALIDATE CONSTRAINT
+    in a single apply() — the add is catalog-only (brief lock) and the
+    validate uses SHARE UPDATE EXCLUSIVE which doesn't block writes, so
+    there's no benefit to deferring validation to a later run.
     Unique constraints use CREATE UNIQUE INDEX CONCURRENTLY + USING INDEX
     to avoid blocking writes.
     """
@@ -208,8 +211,6 @@ class AddConstraintFix(Fix):
     model: type[Model]
 
     def describe(self) -> str:
-        if isinstance(self.constraint, CheckConstraint):
-            return f"{self.table}: add constraint {self.constraint.name} (NOT VALID)"
         return f"{self.table}: add constraint {self.constraint.name}"
 
     def apply(self) -> str:
@@ -244,9 +245,18 @@ class AddConstraintFix(Fix):
 
     def _apply_other(self) -> str:
         if isinstance(self.constraint, CheckConstraint):
-            sql = self.constraint.to_sql(self.model, not_valid=True)
-        else:
-            sql = self.constraint.to_sql(self.model)
+            add_sql = self.constraint.to_sql(self.model, not_valid=True)
+            _execute_and_commit(add_sql)
+
+            validate_sql = (
+                f"ALTER TABLE {quote_name(self.table)}"
+                f" VALIDATE CONSTRAINT {quote_name(self.constraint.name)}"
+            )
+            _execute_and_commit(validate_sql, blocking=False)
+
+            return f"{add_sql}; {validate_sql}"
+
+        sql = self.constraint.to_sql(self.model)
         _execute_and_commit(sql)
         return sql
 

{plain_postgres-0.99.1 → plain_postgres-0.101.0}/pyproject.toml

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