plain.postgres 0.94.2__tar.gz → 0.95.0__tar.gz

{plain_postgres-0.94.2 → plain_postgres-0.95.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.94.2
+Version: 0.95.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause
@@ -19,7 +19,8 @@ Description-Content-Type: text/markdown
 - [Querying](#querying)
 - [Schema management](#schema-management)
     - [Syncing](#syncing)
-    - [Migrations](#migrations)
+    - [Structural migrations](#structural-migrations)
+    - [Data migrations](#data-migrations)
     - [Convergence](#convergence)
 - [Fields](#fields)
 - [Relationships](#relationships)
@@ -445,20 +446,42 @@ Read-only mode must be set outside a transaction — calling it inside `atomic()
 
 ## Schema management
 
-Your database schema is managed by two complementary systems: **migrations** and **convergence**. Migrations handle structural changes — creating tables, adding columns, renaming things. Convergence handles everything declarative — indexes, constraints, foreign keys, and NOT NULL enforcement. You declare these on your models and convergence makes the database match.
+Schema changes fall into three categories, each with a different author and apply model:
 
-```
-Migrations                      Convergence
-(imperative, ordered)           (declarative, idempotent)
-─────────────────────────────   ─────────────────────────────
-Create / drop tables            Indexes
-Add / remove / rename columns   Check constraints
-Change column types             Unique constraints
-Data migrations (RunPython)     Foreign key constraints
-Custom SQL (RunSQL)             NOT NULL enforcement
-```
+- **Convergence** — declarative properties like indexes, constraints, NOT NULL, and FK `on_delete`. Derived from model definitions and applied automatically using online-safe DDL (`CREATE INDEX CONCURRENTLY`, `NOT VALID` + `VALIDATE`, etc.). The framework owns the safe apply pattern.
+- **Structural migrations** — tables, columns, renames, column type changes. Framework-generated from the model diff, but you review them and decide when to deploy (a column type change can rewrite the table; a column drop is destructive).
+- **Data migrations** — backfills, transformations, one-time cleanup. Authored by you via `RunPython` or `RunSQL`. The framework only sequences them.
+
+| Change                                | Category             | Safe apply pattern                              |
+| ------------------------------------- | -------------------- | ----------------------------------------------- |
+| Add / drop index                      | Convergence          | `CREATE INDEX CONCURRENTLY`                     |
+| Add / drop unique or check constraint | Convergence          | `ADD CONSTRAINT NOT VALID` + `VALIDATE`         |
+| Add / remove NOT NULL                 | Convergence          | `CHECK NOT VALID` + `VALIDATE` + `SET NOT NULL` |
+| Change FK `on_delete` action          | Convergence          | drop + re-add with `NOT VALID` + `VALIDATE`     |
+| Create / drop table                   | Structural migration | framework-generated, you review                 |
+| Add / drop / rename column            | Structural migration | framework-generated, you review                 |
+| Column type change                    | Structural migration | may rewrite the table                           |
+| Data backfill or transformation       | Data migration       | you author (`RunPython` / `RunSQL`)             |
+| One-time cleanup, seeding             | Data migration       | you author                                      |
+
+**The principle: who authors the change, and can the framework guarantee safety?** If the framework can derive both the change and a universally-safe apply pattern from model definitions, it belongs to convergence. If the framework can generate the DDL but safety depends on context (table size, deploy timing, destructiveness), it's a structural migration — you review it before deploying. If only you know what to do, it's a data migration.
+
+Many convergence-managed changes produce DB-enforced behavior — cascading deletes (`ON DELETE`), validation (`CHECK`, `NOT NULL`), default generation. Whether a change is "behavioral" doesn't determine the category; whether the framework can guarantee a safe apply does.
+
+| Property         | Convergence                                                     | Migrations                              |
+| ---------------- | --------------------------------------------------------------- | --------------------------------------- |
+| Authored by      | Framework (derived from models)                                 | Framework (structural) or you (data)    |
+| When it runs     | Every `sync`, by diffing models vs database                     | Once, in recorded timestamp order       |
+| Drift correction | Yes — reverts undeclared DB changes on next sync                | No — manual DB changes persist          |
+| Reversible       | Implicit (roll back code, re-sync re-derives)                   | No — forward-only, fix-forward          |
+| Files on disk    | None — derived from models live                                 | `.py` files in `migrations/`            |
+| Safe DDL         | Framework-applied patterns (CONCURRENTLY, NOT VALID + VALIDATE) | Generated DDL; you review before deploy |
+
+**Drift correction is a convergence-only behavior.** Convergence re-runs on every `sync` and compares models against the database. An index created manually outside a model declaration will be dropped on the next run because models are the source of truth. Migrations don't behave this way — once applied, they're recorded and never re-applied.
+
+**Caveats.** The safety promise isn't absolute. Structural migrations aren't lint-checked yet: adding a column with a volatile default (`gen_random_uuid()`, `now()`) on a large table will rewrite it without warning. Review structural migrations before deploying to production.
 
-This split exists because structural changes (adding a column) must happen in a specific order and can't be retried, while declarative objects (indexes, constraints) can be compared against model definitions and fixed automatically — even if a previous attempt failed.
+**Out of scope for convergence.** Triggers, views, stored procedures, and other non-standard DDL stay outside convergence — it won't create them from models, and it won't drop them if they exist. Manage them with `RunSQL` data migrations.
 
 ### Syncing
 
@@ -492,9 +515,9 @@ In development (`DEBUG=True`), sync auto-generates migrations before applying th
 | `plain postgres schema --json` | Machine-readable schema output                                        |
 | `plain postgres converge`      | Run convergence alone (advanced)                                      |
 
-### Migrations
+### Structural migrations
 
-Migrations track structural changes to your models. They are Python files stored in your app's `migrations/` directory.
+Structural migrations are framework-generated from model changes — tables, columns, renames, column type changes. They are Python files stored in your app's `migrations/` directory. You don't author them by hand; you edit models and run `plain migrations create`.
 
 ```bash
 plain migrations create
@@ -504,12 +527,9 @@ Key flags:
 
 - `--dry-run` — Show what migrations would be created (with operations and SQL) without writing files
 - `--check` — Exit non-zero if migrations are needed (for CI)
-- `--empty <package>` — Create an empty migration for custom data migrations
 - `--name <name>` — Set the migration filename
 
-Only write migrations by hand if they are custom data migrations.
-
-Other migration commands:
+Shared commands (apply equally to structural and data migrations):
 
 | Command                                     | Purpose                                              |
 | ------------------------------------------- | ---------------------------------------------------- |
@@ -572,6 +592,53 @@ Over time a package can accumulate dozens of migrations. Once **every environmen
 - Data migrations (`RunPython`) in the deleted history are gone, which is fine since they've already run everywhere.
 - If CI runs `migrations create --check` or `migrations apply --check`, the reset PR must be merged and deployed before those checks pass in other branches.
 
+### Data migrations
+
+Data migrations are user-authored operations — backfills, transformations, seeding, cleanup. The framework has no way to derive these from models; you write the logic and it gets sequenced in timestamp order alongside structural migrations.
+
+Create an empty migration to author one:
+
+```bash
+plain migrations create --empty <package>
+```
+
+Add a `RunPython` or `RunSQL` operation inside:
+
+```python
+def forwards(models, schema_editor):
+    User = models.get_model("users", "User")
+    # Use .update() for batch SQL — a row-by-row save loop can lock a large table.
+    User.query.filter(full_name="").update(full_name="pending")
+```
+
+For large tables, chunk the work (e.g. by ID range) and commit between batches so no single transaction holds locks for too long.
+
+See [Structural migrations](#structural-migrations) for shared commands (`apply`, `list`, `squash`, `prune`).
+
+#### Cascading deletes inside data migrations
+
+`Model.delete()` and `QuerySet.delete()` rely on Postgres `ON DELETE` clauses (`CASCADE`, `SET NULL`, `RESTRICT`) — Plain does not walk relationships in Python.
+
+Foreign key constraints are added by **convergence** (step 3 of `postgres sync`), not by migrations. During a fresh `migrations apply` (before convergence has run), FK constraints don't exist yet. A `RunPython` data migration that calls `.delete()` on a model with cascading children will:
+
+- Delete only the parent row — children become orphans
+- Cause convergence's later `VALIDATE CONSTRAINT` step to fail because of the orphans
+
+This only affects fresh applies. Existing databases keep their FK constraints across syncs, so incremental data migrations are unaffected.
+
+**If your data migration needs to delete rows that have cascading children, handle the cascade explicitly:**
+
+```python
+def forwards(models, schema_editor):
+    Parent = models.get_model("myapp", "Parent")
+    Child = models.get_model("myapp", "Child")
+    # Delete children first, then parent — explicit, no constraint reliance
+    Child.query.filter(parent__name="old").delete()
+    Parent.query.filter(name="old").delete()
+```
+
+Or use `RunSQL` with explicit cascade if the relationship is large.
+
 ### Convergence
 
 Convergence compares the indexes, constraints, foreign keys, and nullability declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
@@ -939,14 +1006,14 @@ model_options = postgres.Options(
 
 #### Choose `on_delete` deliberately
 
-CASCADE for owned children, PROTECT for referenced data, SET_NULL for optional references.
+CASCADE for owned children, RESTRICT for referenced data, SET_NULL for optional references.
 
 ```python
 # Bad — blindly using CASCADE everywhere
 company: Company = types.ForeignKeyField("Company", on_delete=postgres.CASCADE)  # deleting company deletes invoices!
 
-# Good — protect referenced data
-company: Company = types.ForeignKeyField("Company", on_delete=postgres.PROTECT)
+# Good — block the delete while invoices reference the company
+company: Company = types.ForeignKeyField("Company", on_delete=postgres.RESTRICT)
 ```
 
 #### No `allow_null` on string fields

{plain_postgres-0.94.2 → plain_postgres-0.95.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,33 @@
 # plain-postgres changelog
 
+## [0.95.0](https://github.com/dropseed/plain/releases/plain-postgres@0.95.0) (2026-04-14)
+
+### What's changed
+
+- **Deletes now run as a single DELETE statement and cascade through Postgres `ON DELETE` clauses.** The Python `Collector` (which walked relationships in Python to fire per-table DELETEs) has been removed. `Model.delete()` and `QuerySet.delete()` issue one statement and let Postgres do the cascading via the FK actions installed by convergence. The old Collector path required N queries per cascade; the new path requires exactly one. ([29e10dba51d9](https://github.com/dropseed/plain/commit/29e10dba51d9))
+- **`Model.delete()` and `QuerySet.delete()` now return `int`** (the directly-deleted row count). They previously returned a `(count, {label: count})` tuple — Postgres does not report cascaded counts, and the per-label dict was Collector-only bookkeeping. ([29e10dba51d9](https://github.com/dropseed/plain/commit/29e10dba51d9))
+- **`on_delete` constants are now `OnDelete` instances, not bare functions.** `ForeignKeyField` rejects any non-`OnDelete` value at construction, and the declared action is emitted as the FK's Postgres `ON DELETE` clause. ([29e10dba51d9](https://github.com/dropseed/plain/commit/29e10dba51d9))
+- **Removed `PROTECT`, `SET()`, `SET_DEFAULT`, `ProtectedError`, and `RestrictedError`.** `PROTECT` and `SET(callable)` had no Postgres equivalent (prefer `RESTRICT`). `SET_DEFAULT` was removed because Plain does not currently persist Python model defaults as DB-level column defaults — emitting `ON DELETE SET DEFAULT` would set children to `NULL` on bypass-the-ORM deletes, contradicting the model's intent. `SET_DEFAULT` will return once DB-level defaults are supported. `RESTRICT` now surfaces as `psycopg.errors.IntegrityError` directly. ([670dab428ad2](https://github.com/dropseed/plain/commit/670dab428ad2), [29e10dba51d9](https://github.com/dropseed/plain/commit/29e10dba51d9))
+- **Renamed `DO_NOTHING` to `NO_ACTION`** to match Postgres's SQL term. No behavior change. ([5fcf8aa9ced3](https://github.com/dropseed/plain/commit/5fcf8aa9ced3))
+- **Convergence now owns FK `on_delete` drift.** `plain postgres sync` introspects `pg_constraint.confdeltype`, compares it to the declared `on_delete`, and replaces the constraint when they drift. Replacement uses `ADD CONSTRAINT … NOT VALID` + `VALIDATE` to minimize lock time. Existing databases auto-upgrade on their next sync. ([211840197e1e](https://github.com/dropseed/plain/commit/211840197e1e))
+- **Preflight rejects `db_constraint=False` with a non-`NO_ACTION` `on_delete`.** Without a constraint there is no place to attach a deletion action. ([29e10dba51d9](https://github.com/dropseed/plain/commit/29e10dba51d9))
+- **Tightened types.** `on_delete` is now typed as `OnDelete` everywhere (was `Any`). `ForeignKeyField.remote_field` narrows to `ForeignKeyRel` so `remote_field.on_delete` is non-optional. `ForeignObjectRel`, `ForeignKeyRel`, and `ManyToManyRel` `__init__` are kwarg-only. ([29e10dba51d9](https://github.com/dropseed/plain/commit/29e10dba51d9))
+- **Known limitation: data migrations + cascading deletes.** On a fresh `migrations apply`, FK constraints don't exist yet (they're added by convergence in step 3 of `postgres sync`). A `RunPython` data migration that calls `.delete()` on a parent with cascading children will orphan the children, and the subsequent convergence `VALIDATE` will fail. Existing databases are unaffected. Documented with a workaround in the Postgres README (delete children explicitly first, or use `RunSQL`). ([29e10dba51d9](https://github.com/dropseed/plain/commit/29e10dba51d9))
+- **Rewrote the Schema management docs** to distinguish convergence, structural migrations, and data migrations by who authors the change and whether the framework can guarantee a safe apply. Added a per-change-type table covering safe apply patterns (`CREATE INDEX CONCURRENTLY`, `NOT VALID` + `VALIDATE`, etc.) and split the Migrations section into “Structural migrations” and “Data migrations.” ([8ae39e2cef78](https://github.com/dropseed/plain/commit/8ae39e2cef78), [49d2b2452dea](https://github.com/dropseed/plain/commit/49d2b2452dea))
+
+### Upgrade instructions
+
+- **Adapt callers of `.delete()`.** `.delete()` now returns an `int`, not a `(count, by_label)` tuple.
+    - Before: `count, _ = qs.delete()` or `count = qs.delete()[0]`
+    - After: `count = qs.delete()`
+- **Rename `DO_NOTHING` to `NO_ACTION`** at all import and usage sites. Regenerate or hand-edit migration files that reference `DO_NOTHING`.
+- **Replace `PROTECT` with `RESTRICT`.** Catch `psycopg.errors.IntegrityError` instead of `ProtectedError` / `RestrictedError`.
+- **Replace `SET(callable)` usages.** There is no one-line equivalent — the Python-callable path doesn't exist in Postgres. Either switch to a supported action (`SET_NULL`, `RESTRICT`, `CASCADE`, `NO_ACTION`) or handle the affected rows explicitly before deletion.
+- **Replace `SET_DEFAULT` usages.** Pick a different `on_delete`, or set the default explicitly in application code before deletion. `SET_DEFAULT` will return once Plain persists column defaults.
+- **Run `plain postgres sync`** after upgrading. Convergence will install the correct `ON DELETE` clauses on existing FKs — no migration file, no manual step.
+- **If you set `db_constraint=False` on a FK with a non-`NO_ACTION` `on_delete`**, change the action to `NO_ACTION` — preflight will now fail otherwise.
+- **Review `RunPython` migrations that call `.delete()` on parents with cascading children.** On a fresh `migrations apply` before convergence runs, children become orphans and break the subsequent `VALIDATE`. Delete children explicitly first, or use `RunSQL`.
+
 ## [0.94.2](https://github.com/dropseed/plain/releases/plain-postgres@0.94.2) (2026-04-13)
 
 ### What's changed

{plain_postgres-0.94.2 → plain_postgres-0.95.0}/plain/postgres/README.md

@@ -7,7 +7,8 @@
 - [Querying](#querying)
 - [Schema management](#schema-management)
     - [Syncing](#syncing)
-    - [Migrations](#migrations)
+    - [Structural migrations](#structural-migrations)
+    - [Data migrations](#data-migrations)
     - [Convergence](#convergence)
 - [Fields](#fields)
 - [Relationships](#relationships)
@@ -433,20 +434,42 @@ Read-only mode must be set outside a transaction — calling it inside `atomic()
 
 ## Schema management
 
-Your database schema is managed by two complementary systems: **migrations** and **convergence**. Migrations handle structural changes — creating tables, adding columns, renaming things. Convergence handles everything declarative — indexes, constraints, foreign keys, and NOT NULL enforcement. You declare these on your models and convergence makes the database match.
+Schema changes fall into three categories, each with a different author and apply model:
 
-```
-Migrations                      Convergence
-(imperative, ordered)           (declarative, idempotent)
-─────────────────────────────   ─────────────────────────────
-Create / drop tables            Indexes
-Add / remove / rename columns   Check constraints
-Change column types             Unique constraints
-Data migrations (RunPython)     Foreign key constraints
-Custom SQL (RunSQL)             NOT NULL enforcement
-```
+- **Convergence** — declarative properties like indexes, constraints, NOT NULL, and FK `on_delete`. Derived from model definitions and applied automatically using online-safe DDL (`CREATE INDEX CONCURRENTLY`, `NOT VALID` + `VALIDATE`, etc.). The framework owns the safe apply pattern.
+- **Structural migrations** — tables, columns, renames, column type changes. Framework-generated from the model diff, but you review them and decide when to deploy (a column type change can rewrite the table; a column drop is destructive).
+- **Data migrations** — backfills, transformations, one-time cleanup. Authored by you via `RunPython` or `RunSQL`. The framework only sequences them.
+
+| Change                                | Category             | Safe apply pattern                              |
+| ------------------------------------- | -------------------- | ----------------------------------------------- |
+| Add / drop index                      | Convergence          | `CREATE INDEX CONCURRENTLY`                     |
+| Add / drop unique or check constraint | Convergence          | `ADD CONSTRAINT NOT VALID` + `VALIDATE`         |
+| Add / remove NOT NULL                 | Convergence          | `CHECK NOT VALID` + `VALIDATE` + `SET NOT NULL` |
+| Change FK `on_delete` action          | Convergence          | drop + re-add with `NOT VALID` + `VALIDATE`     |
+| Create / drop table                   | Structural migration | framework-generated, you review                 |
+| Add / drop / rename column            | Structural migration | framework-generated, you review                 |
+| Column type change                    | Structural migration | may rewrite the table                           |
+| Data backfill or transformation       | Data migration       | you author (`RunPython` / `RunSQL`)             |
+| One-time cleanup, seeding             | Data migration       | you author                                      |
+
+**The principle: who authors the change, and can the framework guarantee safety?** If the framework can derive both the change and a universally-safe apply pattern from model definitions, it belongs to convergence. If the framework can generate the DDL but safety depends on context (table size, deploy timing, destructiveness), it's a structural migration — you review it before deploying. If only you know what to do, it's a data migration.
+
+Many convergence-managed changes produce DB-enforced behavior — cascading deletes (`ON DELETE`), validation (`CHECK`, `NOT NULL`), default generation. Whether a change is "behavioral" doesn't determine the category; whether the framework can guarantee a safe apply does.
+
+| Property         | Convergence                                                     | Migrations                              |
+| ---------------- | --------------------------------------------------------------- | --------------------------------------- |
+| Authored by      | Framework (derived from models)                                 | Framework (structural) or you (data)    |
+| When it runs     | Every `sync`, by diffing models vs database                     | Once, in recorded timestamp order       |
+| Drift correction | Yes — reverts undeclared DB changes on next sync                | No — manual DB changes persist          |
+| Reversible       | Implicit (roll back code, re-sync re-derives)                   | No — forward-only, fix-forward          |
+| Files on disk    | None — derived from models live                                 | `.py` files in `migrations/`            |
+| Safe DDL         | Framework-applied patterns (CONCURRENTLY, NOT VALID + VALIDATE) | Generated DDL; you review before deploy |
+
+**Drift correction is a convergence-only behavior.** Convergence re-runs on every `sync` and compares models against the database. An index created manually outside a model declaration will be dropped on the next run because models are the source of truth. Migrations don't behave this way — once applied, they're recorded and never re-applied.
+
+**Caveats.** The safety promise isn't absolute. Structural migrations aren't lint-checked yet: adding a column with a volatile default (`gen_random_uuid()`, `now()`) on a large table will rewrite it without warning. Review structural migrations before deploying to production.
 
-This split exists because structural changes (adding a column) must happen in a specific order and can't be retried, while declarative objects (indexes, constraints) can be compared against model definitions and fixed automatically — even if a previous attempt failed.
+**Out of scope for convergence.** Triggers, views, stored procedures, and other non-standard DDL stay outside convergence — it won't create them from models, and it won't drop them if they exist. Manage them with `RunSQL` data migrations.
 
 ### Syncing
 
@@ -480,9 +503,9 @@ In development (`DEBUG=True`), sync auto-generates migrations before applying th
 | `plain postgres schema --json` | Machine-readable schema output                                        |
 | `plain postgres converge`      | Run convergence alone (advanced)                                      |
 
-### Migrations
+### Structural migrations
 
-Migrations track structural changes to your models. They are Python files stored in your app's `migrations/` directory.
+Structural migrations are framework-generated from model changes — tables, columns, renames, column type changes. They are Python files stored in your app's `migrations/` directory. You don't author them by hand; you edit models and run `plain migrations create`.
 
 ```bash
 plain migrations create
@@ -492,12 +515,9 @@ Key flags:
 
 - `--dry-run` — Show what migrations would be created (with operations and SQL) without writing files
 - `--check` — Exit non-zero if migrations are needed (for CI)
-- `--empty <package>` — Create an empty migration for custom data migrations
 - `--name <name>` — Set the migration filename
 
-Only write migrations by hand if they are custom data migrations.
-
-Other migration commands:
+Shared commands (apply equally to structural and data migrations):
 
 | Command                                     | Purpose                                              |
 | ------------------------------------------- | ---------------------------------------------------- |
@@ -560,6 +580,53 @@ Over time a package can accumulate dozens of migrations. Once **every environmen
 - Data migrations (`RunPython`) in the deleted history are gone, which is fine since they've already run everywhere.
 - If CI runs `migrations create --check` or `migrations apply --check`, the reset PR must be merged and deployed before those checks pass in other branches.
 
+### Data migrations
+
+Data migrations are user-authored operations — backfills, transformations, seeding, cleanup. The framework has no way to derive these from models; you write the logic and it gets sequenced in timestamp order alongside structural migrations.
+
+Create an empty migration to author one:
+
+```bash
+plain migrations create --empty <package>
+```
+
+Add a `RunPython` or `RunSQL` operation inside:
+
+```python
+def forwards(models, schema_editor):
+    User = models.get_model("users", "User")
+    # Use .update() for batch SQL — a row-by-row save loop can lock a large table.
+    User.query.filter(full_name="").update(full_name="pending")
+```
+
+For large tables, chunk the work (e.g. by ID range) and commit between batches so no single transaction holds locks for too long.
+
+See [Structural migrations](#structural-migrations) for shared commands (`apply`, `list`, `squash`, `prune`).
+
+#### Cascading deletes inside data migrations
+
+`Model.delete()` and `QuerySet.delete()` rely on Postgres `ON DELETE` clauses (`CASCADE`, `SET NULL`, `RESTRICT`) — Plain does not walk relationships in Python.
+
+Foreign key constraints are added by **convergence** (step 3 of `postgres sync`), not by migrations. During a fresh `migrations apply` (before convergence has run), FK constraints don't exist yet. A `RunPython` data migration that calls `.delete()` on a model with cascading children will:
+
+- Delete only the parent row — children become orphans
+- Cause convergence's later `VALIDATE CONSTRAINT` step to fail because of the orphans
+
+This only affects fresh applies. Existing databases keep their FK constraints across syncs, so incremental data migrations are unaffected.
+
+**If your data migration needs to delete rows that have cascading children, handle the cascade explicitly:**
+
+```python
+def forwards(models, schema_editor):
+    Parent = models.get_model("myapp", "Parent")
+    Child = models.get_model("myapp", "Child")
+    # Delete children first, then parent — explicit, no constraint reliance
+    Child.query.filter(parent__name="old").delete()
+    Parent.query.filter(name="old").delete()
+```
+
+Or use `RunSQL` with explicit cascade if the relationship is large.
+
 ### Convergence
 
 Convergence compares the indexes, constraints, foreign keys, and nullability declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
@@ -927,14 +994,14 @@ model_options = postgres.Options(
 
 #### Choose `on_delete` deliberately
 
-CASCADE for owned children, PROTECT for referenced data, SET_NULL for optional references.
+CASCADE for owned children, RESTRICT for referenced data, SET_NULL for optional references.
 
 ```python
 # Bad — blindly using CASCADE everywhere
 company: Company = types.ForeignKeyField("Company", on_delete=postgres.CASCADE)  # deleting company deletes invoices!
 
-# Good — protect referenced data
-company: Company = types.ForeignKeyField("Company", on_delete=postgres.PROTECT)
+# Good — block the delete while invoices reference the company
+company: Company = types.ForeignKeyField("Company", on_delete=postgres.RESTRICT)
 ```
 
 #### No `allow_null` on string fields

{plain_postgres-0.94.2 → plain_postgres-0.95.0}/plain/postgres/__init__.py

@@ -7,7 +7,7 @@ from . import (
 from .base import Model
 from .constraints import CheckConstraint, UniqueConstraint
 from .db import get_connection
-from .deletion import CASCADE, DO_NOTHING, PROTECT, RESTRICT, SET, SET_DEFAULT, SET_NULL
+from .deletion import CASCADE, NO_ACTION, RESTRICT, SET_NULL
 from .expressions import F
 from .enums import IntegerChoices, TextChoices
 from .fields import (
@@ -82,11 +82,8 @@ __all__ = [
     "Index",
     # From deletion
     "CASCADE",
-    "DO_NOTHING",
-    "PROTECT",
+    "NO_ACTION",
     "RESTRICT",
-    "SET",
-    "SET_DEFAULT",
     "SET_NULL",
     # From options
     "Options",

{plain_postgres-0.94.2 → plain_postgres-0.95.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -65,7 +65,7 @@ Run `uv run plain docs postgres --section querying` for full patterns with code
 - Index fields used in `.filter()` and `.order_by()`
 - Indexes: `{table}_{column(s)}_idx`
 - Constraints: `{table}_{column(s)}_{type}` (e.g., `_unique`, `_check`)
-- Choose `on_delete` deliberately: CASCADE for children, PROTECT for referenced data
+- 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.

{plain_postgres-0.94.2 → plain_postgres-0.95.0}/plain/postgres/base.py

@@ -18,7 +18,6 @@ from plain.postgres import models_registry, transaction, types
 from plain.postgres.constants import LOOKUP_SEP
 from plain.postgres.constraints import CheckConstraint, UniqueConstraint
 from plain.postgres.db import PLAIN_VERSION_PICKLE_KEY
-from plain.postgres.deletion import Collector
 from plain.postgres.dialect import MAX_NAME_LENGTH
 from plain.postgres.exceptions import (
     DoesNotExistDescriptor,
@@ -592,15 +591,29 @@ class Model(metaclass=ModelBase):
                 ):
                     field.delete_cached_value(self)
 
-    def delete(self) -> tuple[int, dict[str, int]]:
+    def delete(self) -> int:
+        """Delete this row. Returns the number of rows deleted (1 or 0).
+
+        Cascades are handled entirely by Postgres via the `on_delete`
+        clauses declared on related foreign keys.
+        """
         if self.id is None:
             raise ValueError(
                 f"{self.model_options.object_name} object can't be deleted because its id attribute is set "
                 "to None."
             )
-        collector = Collector(origin=self)
-        collector.collect([self])
-        return collector.delete()
+        # Use base_queryset to bypass any user-defined filters on the public
+        # query (e.g. soft-delete scopes). An instance we have a reference to
+        # should always be deletable — custom querysets shape reads, not
+        # internal row lifecycle operations.
+        #
+        # mark_for_rollback_on_error: FK errors (RESTRICT / NO_ACTION) leave
+        # the DB transaction aborted. Mark the connection so outer atomic()
+        # blocks see the abort state even if the caller catches IntegrityError.
+        with transaction.mark_for_rollback_on_error():
+            count = self._model_meta.base_queryset.filter(id=self.id)._raw_delete()
+        setattr(self, self._model_meta.get_forward_field("id").attname, None)
+        return count
 
     def get_field_display(self, field_name: str) -> str:
         """Get the display value for a field, especially useful for fields with choices."""

{plain_postgres-0.94.2 → plain_postgres-0.95.0}/plain/postgres/connection.py

@@ -990,7 +990,8 @@ class DatabaseConnection:
                 WHERE fka.attrelid = c.confrelid AND fka.attnum = c.confkey[1]),
                 cl.reloptions,
                 c.convalidated,
-                pg_get_constraintdef(c.oid)
+                pg_get_constraintdef(c.oid),
+                c.confdeltype
             FROM pg_constraint AS c
             JOIN pg_class AS cl ON c.conrelid = cl.oid
             WHERE cl.relname = %s AND pg_catalog.pg_table_is_visible(cl.oid)
@@ -1005,6 +1006,7 @@ class DatabaseConnection:
             options,
             validated,
             constraintdef,
+            confdeltype,
         ) in cursor.fetchall():
             constraints[constraint] = {
                 "columns": columns,
@@ -1017,6 +1019,7 @@ class DatabaseConnection:
                 "definition": constraintdef,
                 "options": options,
                 "validated": validated,
+                "on_delete_action": confdeltype if kind == "f" else None,
             }
         # Now get indexes
         cursor.execute(

{plain_postgres-0.94.2 → plain_postgres-0.95.0}/plain/postgres/convergence/analysis.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, Any
 
 from ..constraints import CheckConstraint, UniqueConstraint
 from ..ddl import compile_expression_sql, compile_index_expressions_sql
+from ..deletion import sql_on_delete
 from ..dialect import quote_name
 from ..fields.related import ForeignKeyField
 from ..indexes import Index
@@ -111,6 +112,9 @@ class ForeignKeyDrift:
     column: str | None = None
     target_table: str | None = None
     target_column: str | None = None
+    on_delete_clause: str = ""  # SQL clause to emit, e.g. " ON DELETE CASCADE"
+    actual_action: str | None = None  # CHANGED only: current DB confdeltype
+    expected_action: str | None = None  # CHANGED only: expected confdeltype
 
     def describe(self) -> str:
         match self.kind:
@@ -118,6 +122,11 @@ class ForeignKeyDrift:
                 return f"{self.table}: FK {self.name} missing ({self.column} → {self.target_table}.{self.target_column})"
             case DriftKind.UNVALIDATED:
                 return f"{self.table}: FK {self.name} NOT VALID"
+            case DriftKind.CHANGED:
+                return (
+                    f"{self.table}: FK {self.name} on_delete changed "
+                    f"({self.actual_action!r} → {self.expected_action!r})"
+                )
             case _:
                 return f"{self.table}: FK {self.name} not declared"
 
@@ -823,8 +832,10 @@ def _compare_foreign_keys(
         if v.constraint_type == ConType.FOREIGN_KEY
     }
 
-    # Build expected FKs from model fields: shape → (field_name, constraint_name)
-    expected_fks: dict[tuple[str, str, str], tuple[str, str]] = {}
+    # Build expected FKs from model fields.
+    # Key: shape (column, target_table, target_column)
+    # Value: (field_name, constraint_name, expected_on_delete_clause, expected_confdeltype)
+    expected_fks: dict[tuple[str, str, str], tuple[str, str, str, str]] = {}
     for f in model._model_meta.local_fields:
         if isinstance(f, ForeignKeyField) and f.db_constraint:
             assert f.name is not None
@@ -833,7 +844,13 @@ def _compare_foreign_keys(
             constraint_name = generate_fk_constraint_name(
                 table, f.column, to_table, to_column
             )
-            expected_fks[(f.column, to_table, to_column)] = (f.name, constraint_name)
+            on_delete_clause, confdeltype = sql_on_delete(f.remote_field.on_delete)
+            expected_fks[(f.column, to_table, to_column)] = (
+                f.name,
+                constraint_name,
+                on_delete_clause,
+                confdeltype,
+            )
 
     # Build actual FKs from DB: shape → (constraint_name, ConstraintState)
     actual_fk_by_shape: dict[tuple[str, str, str], tuple[str, ConstraintState]] = {}
@@ -845,15 +862,41 @@ def _compare_foreign_keys(
             )
 
     matched_fk_names: set[str] = set()
-    for key, (field_name, constraint_name) in expected_fks.items():
+    for key, (
+        field_name,
+        constraint_name,
+        on_delete_clause,
+        expected_action,
+    ) in expected_fks.items():
         if match := actual_fk_by_shape.get(key):
             actual_name, cs = match
             matched_fk_names.add(actual_name)
 
-            # Check validation state
             issue: str | None = None
             drift: ForeignKeyDrift | None = None
-            if not cs.validated:
+
+            # on_delete action mismatch — drop + re-add with new clause
+            if (
+                cs.on_delete_action is not None
+                and cs.on_delete_action != expected_action
+            ):
+                issue = (
+                    f"on_delete action differs "
+                    f"({cs.on_delete_action!r} → {expected_action!r})"
+                )
+                col, to_table, to_column = key
+                drift = ForeignKeyDrift(
+                    kind=DriftKind.CHANGED,
+                    table=table,
+                    name=actual_name,
+                    column=col,
+                    target_table=to_table,
+                    target_column=to_column,
+                    on_delete_clause=on_delete_clause,
+                    actual_action=cs.on_delete_action,
+                    expected_action=expected_action,
+                )
+            elif not cs.validated:
                 issue = "NOT VALID — needs validation"
                 drift = ForeignKeyDrift(
                     kind=DriftKind.UNVALIDATED,
@@ -885,6 +928,7 @@ def _compare_foreign_keys(
                         column=col,
                         target_table=to_table,
                         target_column=to_column,
+                        on_delete_clause=on_delete_clause,
                     ),
                 )
             )