plain.postgres 0.100.0__tar.gz → 0.101.0__tar.gz

{plain_postgres-0.100.0 → plain_postgres-0.101.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.100.0
+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

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

@@ -1,5 +1,16 @@
 # 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

{plain_postgres-0.100.0 → 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.100.0 → 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.100.0 → plain_postgres-0.101.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.postgres"
-version = "0.100.0"
+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"

{plain_postgres-0.100.0 → plain_postgres-0.101.0}/tests/test_convergence_constraints.py

@@ -338,8 +338,8 @@ class TestDetectConstraintFixes:
 
 
 class TestApplyConstraintFixes:
-    def test_add_check_constraint_uses_not_valid(self, isolated_db):
-        """AddConstraintFix for check constraints creates NOT VALID."""
+    def test_add_check_constraint_validates_immediately(self, isolated_db):
+        """AddConstraintFix for check constraints adds NOT VALID and validates in one apply."""
         check = CheckConstraint(
             check=Q(id__gte=0),
             name="examples_constraintexample_id_nonneg",
@@ -356,10 +356,11 @@ class TestApplyConstraintFixes:
             sql = fix.apply()
 
             assert "NOT VALID" in sql
+            assert "VALIDATE CONSTRAINT" in sql
             assert constraint_exists(
                 "examples_constraintexample", "examples_constraintexample_id_nonneg"
             )
-            assert not constraint_is_valid(
+            assert constraint_is_valid(
                 "examples_constraintexample", "examples_constraintexample_id_nonneg"
             )
         finally:
@@ -385,7 +386,7 @@ class TestApplyConstraintFixes:
         )
 
     def test_full_check_constraint_lifecycle(self, isolated_db):
-        """Add NOT VALID -> validate -> fully valid constraint."""
+        """A single converge pass adds and validates a check constraint."""
         check = CheckConstraint(
             check=Q(id__gte=0),
             name="examples_constraintexample_id_nonneg",
@@ -394,7 +395,6 @@ class TestApplyConstraintFixes:
         ConstraintExample.model_options.constraints = [*original_constraints, check]
 
         try:
-            # First converge pass: adds NOT VALID
             conn = get_connection()
             with conn.cursor() as cursor:
                 items = plan_model_convergence(
@@ -403,25 +403,12 @@ class TestApplyConstraintFixes:
             assert len(items) == 1
             assert isinstance(items[0].fix, AddConstraintFix)
 
-            items[0].fix.apply()
-            assert not constraint_is_valid(
-                "examples_constraintexample", "examples_constraintexample_id_nonneg"
-            )
-
-            # Second converge pass: detects NOT VALID, validates
-            with conn.cursor() as cursor:
-                items = plan_model_convergence(
-                    conn, cursor, ConstraintExample
-                ).executable()
-            assert len(items) == 1
-            assert isinstance(items[0].fix, ValidateConstraintFix)
-
             items[0].fix.apply()
             assert constraint_is_valid(
                 "examples_constraintexample", "examples_constraintexample_id_nonneg"
             )
 
-            # Third pass: fully converged
+            # Second pass: fully converged
             with conn.cursor() as cursor:
                 items = plan_model_convergence(
                     conn, cursor, ConstraintExample

{plain_postgres-0.100.0 → plain_postgres-0.101.0}/tests/test_convergence_timeouts.py

@@ -173,13 +173,16 @@ def test_add_constraint_unique_mixes_autocommit_and_blocking_commit(spy: _Spy):
     assert spy.commit_calls[0][1] is True
 
 
-def test_add_constraint_check_is_blocking(spy: _Spy):
+def test_add_constraint_check_blocking_add_then_nonblocking_validate(spy: _Spy):
     cc = CheckConstraint(check=Q(id__gte=0), name="check_widget_id")
     fix = AddConstraintFix(table="examples_widget", constraint=cc, model=Widget)
     fix.apply()
     assert spy.autocommit_calls == []
-    assert len(spy.commit_calls) == 1
+    assert len(spy.commit_calls) == 2
+    # Step 1: ADD CONSTRAINT ... NOT VALID — blocking
     assert spy.commit_calls[0][1] is True
+    # Step 2: VALIDATE CONSTRAINT — non-blocking
+    assert spy.commit_calls[1][1] is False
 
 
 def test_add_foreign_key_fix_blocking_add_then_nonblocking_validate(spy: _Spy):