plain.postgres 0.113.2__tar.gz → 0.115.0__tar.gz

plain_postgres-0.113.2/plain/postgres/README.md → plain_postgres-0.115.0/PKG-INFO

@@ -1,3 +1,16 @@
+Metadata-Version: 2.5
+Name: plain.postgres
+Version: 0.115.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.157.0
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: psycopg>=3.2
+Description-Content-Type: text/markdown
+
 # plain.postgres
 
 **Model your data and store it in a database.**
@@ -166,9 +179,8 @@ user = User.query.get(email="test@example.com")
 
 # Complex queries with Q objects
 from plain.postgres import Q
-users = User.query.filter(
-    Q(is_admin=True) | Q(email__endswith="@example.com")
-)
+
+users = User.query.filter(Q(is_admin=True) | Q(email__endswith="@example.com"))
 
 # Ordering
 users = User.query.order_by("-created_at")
@@ -187,6 +199,7 @@ You can customize [`QuerySet`](./query.py#QuerySet) classes to provide specializ
 from typing import Self
 from plain.postgres import types
 
+
 class PublishedQuerySet(postgres.QuerySet["Article"]):
     def published_only(self) -> Self:
         return self.filter(status="published")
@@ -194,6 +207,7 @@ class PublishedQuerySet(postgres.QuerySet["Article"]):
     def draft_only(self) -> Self:
         return self.filter(status="draft")
 
+
 @postgres.register_model
 class Article(postgres.Model):
     title: str = types.TextField(max_length=200)
@@ -201,6 +215,7 @@ class Article(postgres.Model):
 
     query = PublishedQuerySet()
 
+
 # Usage - all methods available on Article.query
 all_articles = Article.query.all()
 published_articles = Article.query.published_only()
@@ -226,6 +241,7 @@ from __future__ import annotations
 from plain import postgres
 from plain.postgres import types
 
+
 @postgres.register_model
 class User(postgres.Model):
     email: str = types.EmailField()
@@ -243,11 +259,14 @@ For complex queries that can't be expressed with the ORM, you can use raw SQL.
 Use `Model.query.raw()` to execute raw SQL and get model instances back:
 
 ```python
-users = User.query.raw("""
+users = User.query.raw(
+    """
     SELECT * FROM users
     WHERE created_at > %s
     ORDER BY created_at DESC
-""", [some_date])
+""",
+    [some_date],
+)
 
 for user in users:
     print(user.email)  # Full model instance with all fields
@@ -320,6 +339,7 @@ for category in Category.query.all():
 
 # Good — single query with annotation
 from plain.postgres.aggregates import Count
+
 for category in Category.query.annotate(num_products=Count("products")).all():
     print(category.num_products)
 ```
@@ -333,6 +353,7 @@ Templates should only render data, never trigger queries. Prepare everything in
 def get_template_context(self):
     return {"posts": Post.query.all()}  # related lookups happen in template
 
+
 # Good — eagerly load everything
 def get_template_context(self):
     return {"posts": Post.query.select_related("author").prefetch_related("tags").all()}
@@ -356,10 +377,12 @@ emails = list(User.query.values_list("email", flat=True))
 
 ```python
 # Bad
-if User.query.filter(is_active=True).count() > 0: ...
+if User.query.filter(is_active=True).count() > 0:
+    ...
 
 # Good
-if User.query.filter(is_active=True).exists(): ...
+if User.query.filter(is_active=True).exists():
+    ...
 ```
 
 #### Use `.count()` instead of `len(queryset)`
@@ -466,8 +489,8 @@ Run a block of code in a read-only transaction using `read_only()`. Any write (I
 from plain.postgres.db import read_only
 
 with read_only():
-    users = User.query.all()       # reads work
-    User.query.create(name="x")   # raises psycopg.errors.ReadOnlySqlTransaction
+    users = User.query.all()  # reads work
+    User.query.create(name="x")  # raises psycopg.errors.ReadOnlySqlTransaction
 ```
 
 `read_only()` opens a single `BEGIN READ ONLY` transaction for the block. Nested `atomic()` blocks inside become savepoints of the outer read-only transaction and inherit read-only.
@@ -480,10 +503,10 @@ Because the whole block is one transaction, catching a database error inside `re
 with read_only():
     try:
         with atomic():
-            User.query.create(name="x")   # raises, savepoint rolls back
+            User.query.create(name="x")  # raises, savepoint rolls back
     except psycopg.errors.ReadOnlySqlTransaction:
         pass
-    User.query.count()   # still works — outer txn is healthy
+    User.query.count()  # still works — outer txn is healthy
 ```
 
 ## Schema management
@@ -705,7 +728,9 @@ class User(postgres.Model):
         ],
         constraints=[
             postgres.UniqueConstraint(fields=["email"], name="users_email_uniq"),
-            postgres.CheckConstraint(check=postgres.Q(age__gte=0), name="users_age_positive"),
+            postgres.CheckConstraint(
+                check=postgres.Q(age__gte=0), name="users_age_positive"
+            ),
         ],
     )
 ```
@@ -806,6 +831,7 @@ from datetime import datetime
 from plain import postgres
 from plain.postgres import types
 
+
 class Product(postgres.Model):
     # Text fields
     name: str = types.TextField(max_length=200)
@@ -910,6 +936,7 @@ This is **not** for passwords or tokens you issue — those should be hashed (on
 from plain import postgres
 from plain.postgres import types
 
+
 @postgres.register_model
 class Integration(postgres.Model):
     name: str = types.TextField(max_length=100)
@@ -946,6 +973,7 @@ Use [`ForeignKeyField`](./fields/related.py#ForeignKeyField) for many-to-one and
 from plain import postgres
 from plain.postgres import types
 
+
 @postgres.register_model
 class Book(postgres.Model):
     title: str = types.TextField(max_length=200)
@@ -959,15 +987,23 @@ Accessing a foreign key gives you the related object without a query — only it
 
 ```python
 book = Book.query.get(id=1)
-book.author        # no query — a partial Author instance
-book.author.id     # no query — the foreign key value
-book.author.name   # one query — loads the rest of the row
+book.author  # no query — a partial Author instance
+book.author.id  # no query — the foreign key value
+book.author.name  # one query — loads the rest of the row
 ```
 
 The first access to any non-key field loads the whole row in a single query. There is no separate `author_id` attribute — `book.author.id` is the foreign key value, and it is type-checked because `book.author` is an `Author`. In loops, use `select_related()` to load related rows up front and avoid a query per row.
 
 The partial-instance shortcut is safe because Plain always creates a database foreign-key constraint, so the referenced row is guaranteed to exist.
 
+### Constraints are checked immediately
+
+Every constraint is checked at the write that violates it, never at commit — the same as Postgres's own default. Inserting a child row that points at a parent that doesn't exist yet fails at that `INSERT`, with a traceback pointing at the offending write, and deleting a parent with `RESTRICT` children fails at that `DELETE`. Create parents before children. A cycle of foreign keys needs a nullable back-reference: create both rows, then `update()` the back-reference. Two required foreign keys pointing at each other can never be inserted.
+
+To swap two rows' values under a unique constraint (reordering by `position`, say), move one row to a temporary value first — a single `UPDATE` that swaps them fails, because Postgres checks uniqueness per row.
+
+A migration can add a column, backfill it in `RunPython`, and drop or alter columns on the same table, all in one transaction.
+
 ### Reverse relationships
 
 When you define a `ForeignKey` or `ManyToManyField`, Plain automatically creates a reverse accessor on the related model (like `author.book_set`). You can explicitly declare these reverse relationships using [`ReverseForeignKey`](./fields/reverse_descriptors.py#ReverseForeignKey) and [`ReverseManyToMany`](./fields/reverse_descriptors.py#ReverseManyToMany):
@@ -976,17 +1012,20 @@ When you define a `ForeignKey` or `ManyToManyField`, Plain automatically creates
 from plain import postgres
 from plain.postgres import types
 
+
 @postgres.register_model
 class Author(postgres.Model):
     name: str = types.TextField(max_length=200)
     # Explicit reverse accessor for all books by this author
     books = types.ReverseForeignKey(to="Book", field="author")
 
+
 @postgres.register_model
 class Book(postgres.Model):
     title: str = types.TextField(max_length=200)
     author: Author = types.ForeignKeyField(Author, on_delete=postgres.CASCADE)
 
+
 # Usage
 author = Author.query.get(name="Jane Doe")
 for book in author.books.all():
@@ -1005,11 +1044,13 @@ class Feature(postgres.Model):
     # Explicit reverse accessor for all cars with this feature
     cars = types.ReverseManyToMany(to="Car", field="features")
 
+
 @postgres.register_model
 class Car(postgres.Model):
     model: str = types.TextField(max_length=100)
     features = types.ManyToManyField(Feature)
 
+
 # Usage
 feature = Feature.query.get(name="Sunroof")
 for car in feature.cars.all():
@@ -1029,10 +1070,14 @@ To get type checking for custom QuerySet methods on reverse relations, specify t
 
 ```python
 # Basic usage
-books: types.ReverseForeignKey[Book] = types.ReverseForeignKey(to="Book", field="author")
+books: types.ReverseForeignKey[Book] = types.ReverseForeignKey(
+    to="Book", field="author"
+)
 
 # With custom QuerySet for proper method recognition
-books: types.ReverseForeignKey[Book, BookQuerySet] = types.ReverseForeignKey(to="Book", field="author")
+books: types.ReverseForeignKey[Book, BookQuerySet] = types.ReverseForeignKey(
+    to="Book", field="author"
+)
 
 # Now type checkers recognize custom methods like .published()
 author.books.query.published()
@@ -1063,7 +1108,7 @@ class User(postgres.Model):
 
 Field-level validation happens automatically based on field types and constraints.
 
-**The database is authoritative for constraints.** `create()`/`update()` don't pre-check your declared unique/check constraints — they attempt the write, and if Postgres rejects it, translate the `IntegrityError` into a `ValidationError` (routed to the field for single-column uniques, `NON_FIELD_ERRORS` otherwise). You get the same field-level error you'd expect, the write costs no per-constraint `SELECT`, and a raced concurrent insert can't slip through as a 500. (FK violations, `NOT NULL`, and a hand-set primary-key collision have no declared constraint to map to and re-raise as the original `IntegrityError`. `create()` always inserts, so passing a stray `id` that already exists is rejected by Postgres as the original `IntegrityError`.)
+**The database is authoritative for constraints.** `create()`/`update()` don't pre-check your declared unique/check constraints — they attempt the write, and if Postgres rejects it, translate the `IntegrityError` into a `ValidationError` (routed to the field for single-column uniques, `NON_FIELD_ERRORS` otherwise). You get the same field-level error you'd expect, the write costs no per-constraint `SELECT`, and a raced concurrent insert can't slip through as a 500. A foreign key pointing at a row that doesn't exist maps the same way, as an error on that field. (`NOT NULL` and a hand-set primary-key collision have no declared constraint to map to and re-raise as the original `IntegrityError`. `create()` always inserts, so passing a stray `id` that already exists is rejected by Postgres as the original `IntegrityError`.)
 
 Because the rejected write reaches the database, it aborts the surrounding transaction. If you catch the `ValidationError` and want to keep using the transaction, wrap the write in `transaction.atomic()` so it rolls back to a savepoint:
 
@@ -1077,7 +1122,7 @@ except ValidationError:
 
 Forms are the exception: a `ModelForm` pre-checks constraints explicitly (a `validate_constraints()` call in its `_post_clean`) so it can surface every violation at once, then writes via `form.create()`/`form.update()` with validation already done. A direct `create()`/`update()` reports the first violation Postgres hits.
 
-This applies to instance writes only. Set-based writes — `QuerySet.update()` and `bulk_create()` — raise the raw `psycopg.IntegrityError`, since there's no instance to attribute the error to. If you retry on a unique conflict, catch both:
+This applies to instance writes only. Set-based writes — `QuerySet.update()` and `bulk_create()` — raise the raw `psycopg.IntegrityError`, since there's no instance to attribute the error to, and so does a `delete()` blocked by `RESTRICT` children. If you retry on a unique conflict, catch both:
 
 ```python
 try:
@@ -1088,8 +1133,6 @@ except (psycopg.IntegrityError, ValidationError):
 
 For a plain insert-or-update with no per-row logic, `bulk_create(..., update_conflicts=True, unique_fields=[...])` is an atomic upsert with no race to catch.
 
-Two caveats. The mapping covers **immediate** constraints — the default. An explicitly deferred constraint (`UniqueConstraint(deferrable=Deferrable.DEFERRED)`) is checked at commit, _after_ the write returns, so its violation still surfaces as a raw `psycopg.IntegrityError`. And when a row violates several constraints at once, a form's pre-check (or an explicit `validate_constraints()`) reports them all, while a direct `create()`/`update()` gets only the first one the database hits.
-
 ### Indexes and constraints
 
 You can optimize queries and ensure data integrity with indexes and constraints. These are managed automatically by [convergence](#convergence) — just declare them on the model and run `postgres sync`.
@@ -1176,6 +1219,7 @@ class Order(postgres.Model):
     status: str = types.TextField(max_length=20)
     created_at: datetime = types.DateTimeField()
 
+
 # Good — indexed for common queries
 class Order(postgres.Model):
     status: str = types.TextField(max_length=20)
@@ -1197,6 +1241,7 @@ def create(self):
         raise ValueError("duplicate")
     return super().create()
 
+
 # Good — database-enforced
 model_options = postgres.Options(
     constraints=[postgres.UniqueConstraint(fields=["email"])],
@@ -1209,7 +1254,9 @@ CASCADE for owned children, RESTRICT for referenced data, SET_NULL for optional
 
 ```python
 # Bad — blindly using CASCADE everywhere
-company: Company = types.ForeignKeyField("Company", on_delete=postgres.CASCADE)  # deleting company deletes invoices!
+company: Company = types.ForeignKeyField(
+    "Company", on_delete=postgres.CASCADE
+)  # deleting company deletes invoices!
 
 # Good — block the delete while invoices reference the company
 company: Company = types.ForeignKeyField("Company", on_delete=postgres.RESTRICT)
@@ -1235,10 +1282,12 @@ Models integrate with [plain.forms](../../../plain-forms/plain/forms/README.md):
 from plain import forms
 from .models import User
 
+
 class UserForm(forms.ModelForm):
     class Meta:
         model = User
-        fields = ["email", "is_admin"]
+        fields = ("email", "is_admin")
+
 
 # Usage
 form = UserForm(request=request)
@@ -1499,7 +1548,9 @@ Use `UniqueConstraint` in your model's `model_options`:
 ```python
 model_options = postgres.Options(
     constraints=[
-        postgres.UniqueConstraint(fields=["email", "organization"], name="unique_email_per_org"),
+        postgres.UniqueConstraint(
+            fields=["email", "organization"], name="unique_email_per_org"
+        ),
     ],
 )
 ```

{plain_postgres-0.113.2 → plain_postgres-0.115.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,45 @@
 # plain-postgres changelog
 
+## [0.115.0](https://github.com/dropseed/plain/releases/plain-postgres@0.115.0) (2026-09-02)
+
+### What's changed
+
+- **Foreign keys are now `NOT DEFERRABLE`** (Postgres's own default) and checked at each write. Plain inherited Django's `DEFERRABLE INITIALLY DEFERRED` foreign keys, added in 2007 so fixtures could contain forward references. Plain has no fixtures, and the deferral was causing real problems: a migration that adds a column, backfills it in `RunPython`, then alters the same table failed with "cannot ALTER TABLE ... because it has pending trigger events" whenever the backfill touched a row, and FK violations only surfaced at `COMMIT` with a traceback pointing at `atomic.__exit__` instead of the offending write ([8cbfa0cb40](https://github.com/dropseed/plain/commit/8cbfa0cb40))
+- Convergence detects an existing `DEFERRABLE` foreign key as drift and fixes it with a catalog-only `ALTER CONSTRAINT ... NOT DEFERRABLE` — no revalidation scan, just a brief `ACCESS EXCLUSIVE` lock bounded by the usual `lock_timeout` — so the first `postgres sync` after upgrading rewrites every FK quickly. A legacy `DEFERRABLE` + `NOT VALID` foreign key gets both corrections in one pass ([8cbfa0cb40](https://github.com/dropseed/plain/commit/8cbfa0cb40))
+- `NO_ACTION` is removed. Its only meaning was deferred checking — use `RESTRICT` ([8cbfa0cb40](https://github.com/dropseed/plain/commit/8cbfa0cb40))
+- A foreign key violation from `create()`/`update()` now surfaces as a `ValidationError` routed to the `ForeignKeyField` — "Author with id 5 does not exist." — with code `invalid_choice` so forms can override it. It lands in the same `IntegrityError` mapping that unique and check constraints already used, so a missing related row reports like any other field error instead of a 500. The message is `ForeignKeyField.does_not_exist_error_message`. Set-based writes (`QuerySet.update()`, `bulk_create()`) and a `delete()` blocked by `RESTRICT` still raise the raw `psycopg` error, since there's no instance to attribute it to ([31df77e665](https://github.com/dropseed/plain/commit/31df77e665))
+- That mapping keys on the foreign key's generated constraint name, so convergence now treats a stale name — left behind by `RenameField`/`RenameModel`, which only rename the column or table — as drift and renames the constraint. Because the write-path mapping depends on those corrections having run, FK renames and the `NOT DEFERRABLE` flip block sync on failure. `generate_fk_constraint_name()` moved to `plain.postgres.utils` and is now the single source of that name for both convergence and the write path ([31df77e665](https://github.com/dropseed/plain/commit/31df77e665))
+- **`UniqueConstraint(deferrable=...)` and the `Deferrable` enum are removed.** With foreign keys immediate, this was the last deferred-constraint concept in Plain, nothing in Plain's own packages used it, and it forced a caveat onto every "constraints are checked at the write" statement while keeping the pending-trigger-events failure alive for one case. Rails (pre-7.1), Ecto, and Laravel never had it for uniques. Every constraint is now checked at the write that violates it, never at commit ([fd1e7f1e13](https://github.com/dropseed/plain/commit/fd1e7f1e13))
+- `DatabaseConnection.check_constraints()` is gone, and the pytest `db` fixture no longer forces deferred constraints to immediate at teardown — there is nothing left to defer ([fd1e7f1e13](https://github.com/dropseed/plain/commit/fd1e7f1e13))
+- Constraint renames now run in convergence pass 1, matching index renames, so anything else planned for the same constraint in that pass addresses it by its new name ([fd1e7f1e13](https://github.com/dropseed/plain/commit/fd1e7f1e13))
+- New README section, "Constraints are checked immediately", covering the patterns this changes: create parents before children, use a nullable back-reference for a foreign key cycle (two required FKs pointing at each other can never be inserted), and move through a temporary value when swapping two rows under a unique constraint, since Postgres checks uniqueness per row even within a single `UPDATE` ([8cbfa0cb40](https://github.com/dropseed/plain/commit/8cbfa0cb40), [fd1e7f1e13](https://github.com/dropseed/plain/commit/fd1e7f1e13))
+
+### Upgrade instructions
+
+- Replace `NO_ACTION` with `RESTRICT` in your models **and in any historical migration file that references it** — `postgres.NO_ACTION` no longer exists, so a migration importing it fails to load.
+- Remove `deferrable=` from every `UniqueConstraint(...)` and drop any `Deferrable` import. An existing deferred unique constraint in the database shows as CHANGED drift with staged-rollout guidance — nothing is rewritten silently.
+- Run `plain postgres sync` after upgrading. It flips every existing foreign key to `NOT DEFERRABLE` (catalog-only, no table scan) and renames foreign key constraints left stale by past `RenameField`/`RenameModel`.
+- Code that inserted a child row before its parent, or deleted a parent and re-pointed its children later in the same transaction, now raises `ForeignKeyViolation` at that statement rather than succeeding by commit time. Create parents before children; for a foreign key cycle, create both rows and then `update()` the nullable back-reference.
+- If you catch `psycopg.IntegrityError` around `create()`/`update()` to handle a missing related row, catch `ValidationError` instead — or both, if the same block also covers set-based writes.
+- If you called `connection.check_constraints()`, remove the call.
+
+## [0.114.0](https://github.com/dropseed/plain/releases/plain-postgres@0.114.0) (2026-08-12)
+
+### What's changed
+
+- Wrong-type arguments now raise `TypeError` instead of `ValueError` across the schema and query APIs: `UniqueConstraint`/`Index` options (`condition`, `deferrable`, `include`, `opclasses`, `fields`), `Extract`/`Trunc` field types, non-bool `isnull` lookups, `RunPython` without a callable, serializer registration, assigning a wrong-model instance (or bool) to a foreign key, and reverse descriptors on non-FK/M2M fields ([f52e18f532](https://github.com/dropseed/plain/commit/f52e18f532))
+- `Migration.operations`/`dependencies`/`replaces` are typed as `Sequence`, and `plain migrations create` now writes them as tuples in generated files. Existing list-based migration files keep working ([f52e18f532](https://github.com/dropseed/plain/commit/f52e18f532))
+- Migration filename timestamps use the app's `TIME_ZONE` (via `timezone.localtime()`) instead of the machine's local clock, so a team generates consistently named migrations ([f52e18f532](https://github.com/dropseed/plain/commit/f52e18f532))
+- Model field `default_validators` is now a tuple and `empty_values` a tuple; `ignored_tables` on the connection is a tuple ([f52e18f532](https://github.com/dropseed/plain/commit/f52e18f532))
+- `ModelsRegistry.get_models()` caching was reworked to a per-instance memo (still cleared by `clear_cache()`), replacing a `functools.cache` keyed on the registry instance ([f52e18f532](https://github.com/dropseed/plain/commit/f52e18f532))
+- `on_commit()` handler errors are logged with `logger.exception()` — same message and traceback, standard idiom ([f52e18f532](https://github.com/dropseed/plain/commit/f52e18f532))
+
+### Upgrade instructions
+
+- If you catch `ValueError` around any of the argument-validation cases above, catch `TypeError` instead
+- Newly generated migrations use tuples for `dependencies`/`operations`; existing migration files don't need to change
+- Requires `plain>=0.157.0`
+
 ## [0.113.2](https://github.com/dropseed/plain/releases/plain-postgres@0.113.2) (2026-08-10)
 
 ### What's changed
@@ -408,7 +448,11 @@
 
     ```python
     # Before
-    from plain.postgres.connections import get_connection, read_only, use_management_connection
+    from plain.postgres.connections import (
+        get_connection,
+        read_only,
+        use_management_connection,
+    )
 
     # After
     from plain.postgres.db import get_connection, read_only, use_management_connection