plain.postgres 0.104.0__tar.gz → 0.106.0__tar.gz

{plain_postgres-0.104.0 → plain_postgres-0.106.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.104.0
+Version: 0.106.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause
@@ -74,7 +74,7 @@ user = User.query.create(
 
 # Update a user
 user.email = "new@example.com"
-user.save()
+user.update()
 
 # Delete a user
 user.delete()
@@ -388,12 +388,12 @@ total = User.query.count()
 
 #### Use `bulk_create` / `bulk_update` for batch operations
 
-Avoid calling `.save()` in a loop — each call is a separate query.
+Avoid calling `.create()` in a loop — each call is a separate query.
 
 ```python
 # Bad — N INSERT statements
 for name in names:
-    Tag(name=name).save()
+    Tag(name=name).create()
 
 # Good — single INSERT
 Tag.query.bulk_create([Tag(name=name) for name in names])
@@ -405,7 +405,7 @@ Tag.query.bulk_create([Tag(name=name) for name in names])
 # Bad — N UPDATE statements
 for user in User.query.filter(is_active=False):
     user.is_archived = True
-    user.save()
+    user.update()
 
 # Good — single UPDATE statement
 User.query.filter(is_active=False).update(is_archived=True)
@@ -452,16 +452,16 @@ from plain.postgres import transaction
 
 with transaction.atomic():
     user = User(email="test@example.com")
-    user.save()
-    Profile(user=user).save()
-    # Both saves commit together, or both roll back on error
+    user.create()
+    Profile(user=user).create()
+    # Both writes commit together, or both roll back on error
 ```
 
 Nesting `atomic()` creates savepoints:
 
 ```python
 with transaction.atomic():
-    user.save()
+    user.create()
     try:
         with transaction.atomic():
             risky_operation()  # If this fails...
@@ -1033,7 +1033,7 @@ author.books.query.published()
 
 ### Validation
 
-`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).
+`create()` and `update()` run `full_clean()` by default — field validators and the model's `clean()` method — raising `ValidationError` on violation. Pass `clean_and_validate=False` to skip it (e.g. for trusted bulk loads). Constraints are _not_ pre-checked here; the database enforces them (see below).
 
 ```python
 @postgres.register_model
@@ -1054,6 +1054,33 @@ 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`.)
+
+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:
+
+```python
+try:
+    with transaction.atomic():
+        User.query.create(email=taken_email)
+except ValidationError:
+    ...  # report it — the transaction is still usable
+```
+
+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 saves 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:
+
+```python
+try:
+    obj.create()
+except (psycopg.IntegrityError, ValidationError):
+    ...  # lost a race — reload and retry, or report it
+```
+
+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`.
@@ -1076,7 +1103,7 @@ 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`:
+Constraints are checked by `validate_constraints()` — run by a `ModelForm` (and any explicit `validate_constraints()` call), but **not** by `full_clean()` (which validates shape only) or a direct `create()`/`update()`, where the database enforces them instead (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
@@ -1155,10 +1182,11 @@ class Order(postgres.Model):
 Enforce uniqueness and data integrity at the database level.
 
 ```python
-# Bad — only validated in Python
-def save(self):
+# Bad — only validated in Python (racy: two requests can both pass the check)
+def create(self):
     if MyModel.query.filter(email=self.email).exists():
         raise ValueError("duplicate")
+    return super().create()
 
 # Good — database-enforced
 model_options = postgres.Options(

{plain_postgres-0.104.0 → plain_postgres-0.106.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,37 @@
 # plain-postgres changelog
 
+## [0.106.0](https://github.com/dropseed/plain/releases/plain-postgres@0.106.0) (2026-06-03)
+
+### What's changed
+
+- **`Model.save()` is replaced by explicit `create()` (always INSERT) and `update()` (always UPDATE).** A call site now says which it does. `create()` inserts a new row and returns `self`; `update()` writes an existing row and returns `self`, raising if no row matched (there is no silent INSERT fallback). `update(fields=[...])` limits the columns written (replacing `save(update_fields=[...])`). `save()`, `save_base()`, and the `force_insert`/`force_update` arguments are removed. ([f75deb3ba2](https://github.com/dropseed/plain/commit/f75deb3ba2))
+- **Constructing a model with `id=` now raises.** A hand-set `id` at construction almost always means "load the existing row" — use `Model.query.get(id=...)`. A freshly constructed instance is unambiguously new. ([9c0acf7bac](https://github.com/dropseed/plain/commit/9c0acf7bac), [661c7806df](https://github.com/dropseed/plain/commit/661c7806df))
+- **Declared unique/check constraint violations now raise `ValidationError`, not raw `psycopg.IntegrityError`** — mapped at the write boundary, so even a violation that races past validation surfaces as the same field-level error a pre-check would raise. The database is now the authority; the pre-check `SELECT` is no longer required for correctness. Set-based writes (`bulk_create`, `QuerySet.update`) still raise raw `psycopg` errors. ([40c97521c5](https://github.com/dropseed/plain/commit/40c97521c5), [bdbdd524e5](https://github.com/dropseed/plain/commit/bdbdd524e5))
+- **`full_clean()` is now shape-only** (`clean_fields()` + `clean()`); the integrity pre-check moved to `validate_constraints()`, called explicitly. `full_clean()`'s `validate_unique`/`validate_constraints` parameters and the `Model.validate_unique()` / `_get_unique_checks` / `_perform_unique_checks` trio are removed; forms call `full_clean()` then `validate_constraints()`. ([ba4b386fb7](https://github.com/dropseed/plain/commit/ba4b386fb7), [65d56945fb](https://github.com/dropseed/plain/commit/65d56945fb))
+- `delete()` clears the instance's `id` and resets it to "new," so `create()` re-inserts it cleanly; the instance's other field values survive the delete. ([f75deb3ba2](https://github.com/dropseed/plain/commit/f75deb3ba2))
+
+### Upgrade instructions
+
+- Replace `obj.save()` with `obj.create()` for a new row or `obj.update()` for an existing one; `obj.save(update_fields=[...])` becomes `obj.update(fields=[...])`. The `/plain-upgrade` skill rewrites these for you — the create-vs-update choice is context-dependent, so it reasons per call site.
+- Remove `force_insert=`/`force_update=` — `create()` and `update()` are the explicit forms.
+- Don't pass `id=` to a model constructor; load existing rows with `Model.query.get(id=...)`.
+- Catch `ValidationError` (or `(psycopg.IntegrityError, ValidationError)` when retrying) for unique/check conflicts on instance writes. Inside an open `transaction.atomic()` a violation aborts the transaction — wrap the write in its own `atomic()` to catch and continue.
+- Direct `full_clean()` callers that relied on constraint pre-checking should call `validate_constraints()` explicitly.
+
+## [0.105.0](https://github.com/dropseed/plain/releases/plain-postgres@0.105.0) (2026-05-25)
+
+### What's changed
+
+- **Field constructors in `plain.postgres.types` are now typed as parameterized descriptors.** Stubs return `XField[T]` (e.g. `TextField[str]`, `IntegerField[int | None]` when `allow_null=True`) instead of the primitive value. Combined with `Field[T]`'s overloaded `__get__`, class-level access (`User.email`) sees the descriptor and instance access (`user.email`) sees the value — no annotation needed on model declarations. ([229ecdbbfa](https://github.com/dropseed/plain/commit/229ecdbbfa))
+- **`Field.__set__` is now typed as `value: T`** instead of `Any`, so a type checker flags `row.name = 123` on a `TextField` at the call site. Runtime conversion via `to_python()` is unchanged. ([229ecdbbfa](https://github.com/dropseed/plain/commit/229ecdbbfa))
+- **`ForeignKeyField` overloads split by `to=` argument shape.** Passing a model class (`to=Author`) returns `_ForeignKeyDescriptor[T, V]` and accepts bare-PK assignment (`book.author = 5`) via `__set__`. Passing a string forward reference (`to="Author"`) returns the bare value type and requires an LHS annotation so the type can bind. ([229ecdbbfa](https://github.com/dropseed/plain/commit/229ecdbbfa))
+- `JSONField` and `EncryptedJSONField` keep explicit annotations on model declarations — their runtime classes aren't generic, so the stubs return `Any`. ([229ecdbbfa](https://github.com/dropseed/plain/commit/229ecdbbfa))
+
+### Upgrade instructions
+
+- **Drop primitive type annotations on model field declarations.** `name: str = types.TextField()` will now fail type checking because the right-hand side is typed `TextField[str]`, not `str`. Change to `name = types.TextField()` — type checkers still infer `str` at instance access through the descriptor's `__get__`. Runtime is unchanged either way.
+- **Keep explicit annotations for `JSONField` / `EncryptedJSONField`** — these still return `Any` from the stubs, so the declared type is what flows through. Example: `parameters: dict[str, Any] | None = types.JSONField(required=False, allow_null=True)`.
+
 ## [0.104.0](https://github.com/dropseed/plain/releases/plain-postgres@0.104.0) (2026-05-22)
 
 ### What's changed

{plain_postgres-0.104.0 → plain_postgres-0.106.0}/plain/postgres/README.md

@@ -61,7 +61,7 @@ user = User.query.create(
 
 # Update a user
 user.email = "new@example.com"
-user.save()
+user.update()
 
 # Delete a user
 user.delete()
@@ -375,12 +375,12 @@ total = User.query.count()
 
 #### Use `bulk_create` / `bulk_update` for batch operations
 
-Avoid calling `.save()` in a loop — each call is a separate query.
+Avoid calling `.create()` in a loop — each call is a separate query.
 
 ```python
 # Bad — N INSERT statements
 for name in names:
-    Tag(name=name).save()
+    Tag(name=name).create()
 
 # Good — single INSERT
 Tag.query.bulk_create([Tag(name=name) for name in names])
@@ -392,7 +392,7 @@ Tag.query.bulk_create([Tag(name=name) for name in names])
 # Bad — N UPDATE statements
 for user in User.query.filter(is_active=False):
     user.is_archived = True
-    user.save()
+    user.update()
 
 # Good — single UPDATE statement
 User.query.filter(is_active=False).update(is_archived=True)
@@ -439,16 +439,16 @@ from plain.postgres import transaction
 
 with transaction.atomic():
     user = User(email="test@example.com")
-    user.save()
-    Profile(user=user).save()
-    # Both saves commit together, or both roll back on error
+    user.create()
+    Profile(user=user).create()
+    # Both writes commit together, or both roll back on error
 ```
 
 Nesting `atomic()` creates savepoints:
 
 ```python
 with transaction.atomic():
-    user.save()
+    user.create()
     try:
         with transaction.atomic():
             risky_operation()  # If this fails...
@@ -1020,7 +1020,7 @@ author.books.query.published()
 
 ### Validation
 
-`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).
+`create()` and `update()` run `full_clean()` by default — field validators and the model's `clean()` method — raising `ValidationError` on violation. Pass `clean_and_validate=False` to skip it (e.g. for trusted bulk loads). Constraints are _not_ pre-checked here; the database enforces them (see below).
 
 ```python
 @postgres.register_model
@@ -1041,6 +1041,33 @@ 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`.)
+
+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:
+
+```python
+try:
+    with transaction.atomic():
+        User.query.create(email=taken_email)
+except ValidationError:
+    ...  # report it — the transaction is still usable
+```
+
+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 saves 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:
+
+```python
+try:
+    obj.create()
+except (psycopg.IntegrityError, ValidationError):
+    ...  # lost a race — reload and retry, or report it
+```
+
+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`.
@@ -1063,7 +1090,7 @@ 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`:
+Constraints are checked by `validate_constraints()` — run by a `ModelForm` (and any explicit `validate_constraints()` call), but **not** by `full_clean()` (which validates shape only) or a direct `create()`/`update()`, where the database enforces them instead (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
@@ -1142,10 +1169,11 @@ class Order(postgres.Model):
 Enforce uniqueness and data integrity at the database level.
 
 ```python
-# Bad — only validated in Python
-def save(self):
+# Bad — only validated in Python (racy: two requests can both pass the check)
+def create(self):
     if MyModel.query.filter(email=self.email).exists():
         raise ValueError("duplicate")
+    return super().create()
 
 # Good — database-enforced
 model_options = postgres.Options(

{plain_postgres-0.104.0 → plain_postgres-0.106.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -7,13 +7,32 @@ paths:
 
 ## Field Imports
 
-Import fields via `from plain.postgres import types` and annotate with Python types:
+Import fields via `from plain.postgres import types`. Don't add primitive
+annotations — the field stubs return typed descriptors that resolve to the
+right value type on instance access:
 
 ```python
 from plain.postgres import types
 
-name: str = types.TextField(max_length=100)
-car: Car = types.ForeignKeyField("Car", on_delete=postgres.CASCADE)
+name = types.TextField(max_length=100)
+car = types.ForeignKeyField(Car, on_delete=postgres.CASCADE)
+```
+
+For string forward references (`"self"`, `"OtherModel"`), the type checker
+can't infer the target type from the string — annotate explicitly so
+instance access keeps its type:
+
+```python
+parent: TreeNode | None = types.ForeignKeyField("self", on_delete=postgres.CASCADE, allow_null=True)
+```
+
+For `JSONField` and `EncryptedJSONField`, the stub returns `Any` (the
+runtime class isn't generic over its value shape), so annotate explicitly
+to preserve typing:
+
+```python
+parameters: dict[str, Any] | None = types.JSONField(required=False, allow_null=True)
+config: dict | None = types.EncryptedJSONField(required=False, allow_null=True)
 ```
 
 Do NOT import field classes directly from `plain.postgres` or `plain.postgres.fields`.
@@ -56,6 +75,8 @@ Use `Model.query` to build querysets (e.g., `User.query.filter(is_active=True)`)
 - Use `bulk_create`/`bulk_update` for batch ops, `.update()`/`.delete()` for mass ops
 - Use `.values_list()` when you only need specific columns
 - Wrap multi-step writes in `transaction.atomic()`
+- Instance writes are `obj.create()` (always INSERT) and `obj.update()` (always UPDATE; `update(fields=[...])` limits the columns) — there is no `save()`, `force_insert`, or `force_update`. Constructing an instance then `create()`-ing it inserts; a hand-set `id` that collides raises `IntegrityError`.
+- `create()`/`update()` raise `ValidationError` (not raw `psycopg.IntegrityError`) on a declared unique/check constraint violation, even a raced one — the DB enforces it, so inside an open `transaction.atomic()` the violation aborts the transaction (wrap the write in its own `atomic()` to catch and keep using the transaction). Set-based writes (`QuerySet.update()`/`bulk_create()`) raise raw `psycopg.IntegrityError`. Retrying on conflict? `except (psycopg.IntegrityError, ValidationError)`, or `bulk_create(..., update_conflicts=True)`
 - Always paginate list queries — unbounded querysets get slower as data grows
 
 Run `uv run plain docs postgres` for full patterns with code examples.