plain.postgres 0.94.2__tar.gz → 0.96.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.94.2
+Version: 0.96.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)
@@ -47,7 +48,7 @@ class User(postgres.Model):
     email: str = types.EmailField()
     password = PasswordField()
     is_admin: bool = types.BooleanField(default=False)
-    created_at: datetime = types.DateTimeField(auto_now_add=True)
+    created_at: datetime = types.DateTimeField(create_now=True)
 
     def __str__(self) -> str:
         return self.email
@@ -445,20 +446,49 @@ 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`         |
+| Set / change / drop column `DEFAULT`  | Convergence          | catalog-only `ALTER COLUMN SET/DROP DEFAULT`        |
+| Create / drop table                   | Structural migration | framework-generated, you review                     |
+| Add / drop / rename column            | Structural migration | framework-generated, you review                     |
+| Column type change (safe widening)    | Structural migration | framework-generated `ALTER TYPE` with implicit cast |
+| Column type change (other)            | Data migration       | you author (explicit `RunSQL` with `USING`)         |
+| 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 (intentional) | Implicit — roll back code, re-sync re-derives                         | No — forward-only, fix-forward                              |
+| Failure behavior         | Per-operation commits — partial progress on failure (re-run to retry) | Batch transaction — failure rolls back the entire migration |
+| 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.
 
-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.
+**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.
+
+**Column type changes.** The autodetector only auto-generates `AlterField` for a small allowlist of lossless widenings (`smallint → integer`, `smallint → bigint`, `integer → bigint`) and for parameter-only changes like `max_length`. Every other base-type change rejects with guidance — arbitrary `USING col::newtype` casts either fail at apply time (e.g. timestamp → uuid) or silently corrupt data (e.g. bigint FK → text stringifies PKs), and migrations are forward-only. For anything outside the allowlist, scaffold `plain migrations create --empty --name alter_<model>_<field>_type` and author an explicit `RunSQL` with a `USING` expression you've reviewed.
+
+"Safe" here means data-integrity safe, not operationally cheap. An `ALTER COLUMN ... TYPE` that changes on-disk width (any of the allowlisted widenings) takes `ACCESS EXCLUSIVE` and rewrites the table — on a large table this can block writes for minutes. Deploy these during a maintenance window, not in the middle of traffic.
+
+**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 +522,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 +534,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 +599,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`.
@@ -622,6 +696,43 @@ Some changes can't be applied automatically. For example, if you add `NOT NULL`
 
 When you remove an index or constraint from a model, convergence automatically drops the undeclared database object on the next `postgres sync`. Models are the source of truth — if it's not declared, it gets removed.
 
+### DDL timeouts
+
+Every framework-issued DDL statement — both in migrations and in convergence — is wrapped with `lock_timeout` and `statement_timeout` so a deploy can't hang indefinitely waiting for a lock, and so a backfill against an unexpectedly large table fails fast instead of holding `ACCESS EXCLUSIVE` for minutes.
+
+```python
+# app/settings.py — defaults shown
+POSTGRES_MIGRATION_LOCK_TIMEOUT = "3s"
+POSTGRES_MIGRATION_STATEMENT_TIMEOUT = "3s"
+POSTGRES_CONVERGENCE_LOCK_TIMEOUT = "3s"
+POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT = "3s"
+```
+
+`lock_timeout` applies to every DDL. `statement_timeout` applies only to statements that take `ACCESS EXCLUSIVE` — non-blocking operations (`CREATE INDEX CONCURRENTLY`, `VALIDATE CONSTRAINT`) run unbounded because they can't cascade the lock queue.
+
+If a migration issues a row-touching UPDATE (e.g. a hand-written `RunPython` or `RunSQL` backfill), the 3s `statement_timeout` will kill it on any non-tiny table. That's intentional — the right fix is a batched data migration, not a single long-running UPDATE. The common first-time failure mode is applying migrations against a pre-seeded dev or staging database: raise the ceiling for that one run, then lower it back for production deploys.
+
+Use `RunSQL(no_timeout=True)` to opt out for a specific operation:
+
+```python
+from plain.postgres.migrations.operations import RunSQL
+
+operations = [
+    RunSQL(
+        "UPDATE orders SET status = 'pending' WHERE status IS NULL",
+        no_timeout=True,
+    ),
+]
+```
+
+Non-atomic migrations (`Migration.atomic = False`, used for `CREATE INDEX CONCURRENTLY` in a migration) skip the timeout prelude automatically — `SET LOCAL` is a no-op outside a transaction block. Manage timeouts inside your own `RunSQL` if you need them.
+
+Environment overrides: every setting accepts `PLAIN_POSTGRES_*` env vars, so you can raise the ceiling for a specific deploy without a code change:
+
+```bash
+PLAIN_POSTGRES_MIGRATION_STATEMENT_TIMEOUT=30s plain migrations apply
+```
+
 ## Fields
 
 You can use many field types for different data:
@@ -646,8 +757,8 @@ class Product(postgres.Model):
     is_active: bool = types.BooleanField(default=True)
 
     # Date and time fields
-    created_at: datetime = types.DateTimeField(auto_now_add=True)
-    updated_at: datetime = types.DateTimeField(auto_now=True)
+    created_at: datetime = types.DateTimeField(create_now=True)
+    updated_at: datetime = types.DateTimeField(update_now=True)
 ```
 
 **Text fields:**
@@ -675,10 +786,11 @@ class Product(postgres.Model):
 **Other fields:**
 
 - [`BooleanField`](./fields/__init__.py#BooleanField) - True/False
-- [`UUIDField`](./fields/__init__.py#UUIDField) - UUID
+- [`UUIDField`](./fields/__init__.py#UUIDField) - UUID (pass `generate=True` for a per-row `gen_random_uuid()` default)
 - [`BinaryField`](./fields/__init__.py#BinaryField) - Raw binary data
 - [`JSONField`](./fields/json.py#JSONField) - JSON data
 - [`GenericIPAddressField`](./fields/__init__.py#GenericIPAddressField) - IPv4 or IPv6 address
+- [`RandomStringField`](./fields/text.py#RandomStringField) - Per-row random hex string generated by Postgres (`length=`) — use for tokens, slugs, short IDs instead of a Python callable default. Slices `gen_random_uuid()` directly; values are uniform hex characters
 
 **Encrypted fields:**
 
@@ -708,8 +820,8 @@ from plain.postgres import types
 
 # Regular Python class for shared fields
 class TimestampedMixin:
-    created_at: datetime = types.DateTimeField(auto_now_add=True)
-    updated_at: datetime = types.DateTimeField(auto_now=True)
+    created_at: datetime = types.DateTimeField(create_now=True)
+    updated_at: datetime = types.DateTimeField(update_now=True)
 
 
 # Models inherit from the mixin AND postgres.Model
@@ -939,14 +1051,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
@@ -1100,17 +1212,21 @@ When `DATABASE_URL` is set, it is parsed into the individual connection settings
 
 Set `DATABASE_URL=none` to explicitly disable the database (e.g. during Docker image builds).
 
-| Setting                       | Type          | Default | Env var                             |
-| ----------------------------- | ------------- | ------- | ----------------------------------- |
-| `POSTGRES_HOST`               | `str`         | —       | `PLAIN_POSTGRES_HOST`               |
-| `POSTGRES_PORT`               | `int \| None` | `None`  | `PLAIN_POSTGRES_PORT`               |
-| `POSTGRES_DATABASE`           | `str`         | —       | `PLAIN_POSTGRES_DATABASE`           |
-| `POSTGRES_USER`               | `str`         | —       | `PLAIN_POSTGRES_USER`               |
-| `POSTGRES_PASSWORD`           | `Secret[str]` | —       | `PLAIN_POSTGRES_PASSWORD`           |
-| `POSTGRES_CONN_MAX_AGE`       | `int`         | `600`   | `PLAIN_POSTGRES_CONN_MAX_AGE`       |
-| `POSTGRES_CONN_HEALTH_CHECKS` | `bool`        | `True`  | `PLAIN_POSTGRES_CONN_HEALTH_CHECKS` |
-| `POSTGRES_OPTIONS`            | `dict`        | `{}`    | —                                   |
-| `POSTGRES_TIME_ZONE`          | `str \| None` | `None`  | `PLAIN_POSTGRES_TIME_ZONE`          |
+| Setting                                  | Type          | Default | Env var                                        |
+| ---------------------------------------- | ------------- | ------- | ---------------------------------------------- |
+| `POSTGRES_HOST`                          | `str`         | —       | `PLAIN_POSTGRES_HOST`                          |
+| `POSTGRES_PORT`                          | `int \| None` | `None`  | `PLAIN_POSTGRES_PORT`                          |
+| `POSTGRES_DATABASE`                      | `str`         | —       | `PLAIN_POSTGRES_DATABASE`                      |
+| `POSTGRES_USER`                          | `str`         | —       | `PLAIN_POSTGRES_USER`                          |
+| `POSTGRES_PASSWORD`                      | `Secret[str]` | —       | `PLAIN_POSTGRES_PASSWORD`                      |
+| `POSTGRES_CONN_MAX_AGE`                  | `int`         | `600`   | `PLAIN_POSTGRES_CONN_MAX_AGE`                  |
+| `POSTGRES_CONN_HEALTH_CHECKS`            | `bool`        | `True`  | `PLAIN_POSTGRES_CONN_HEALTH_CHECKS`            |
+| `POSTGRES_OPTIONS`                       | `dict`        | `{}`    | —                                              |
+| `POSTGRES_TIME_ZONE`                     | `str \| None` | `None`  | `PLAIN_POSTGRES_TIME_ZONE`                     |
+| `POSTGRES_MIGRATION_LOCK_TIMEOUT`        | `str`         | `"3s"`  | `PLAIN_POSTGRES_MIGRATION_LOCK_TIMEOUT`        |
+| `POSTGRES_MIGRATION_STATEMENT_TIMEOUT`   | `str`         | `"3s"`  | `PLAIN_POSTGRES_MIGRATION_STATEMENT_TIMEOUT`   |
+| `POSTGRES_CONVERGENCE_LOCK_TIMEOUT`      | `str`         | `"3s"`  | `PLAIN_POSTGRES_CONVERGENCE_LOCK_TIMEOUT`      |
+| `POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT` | `str`         | `"3s"`  | `PLAIN_POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT` |
 
 See [`default_settings.py`](./default_settings.py) for more details.
 
@@ -1118,7 +1234,19 @@ See [`default_settings.py`](./default_settings.py) for more details.
 
 #### How do I add a field to an existing model?
 
-Add the field to your model class, then run `plain migrations create` to create a migration. If the field is required (no default value and not nullable), you'll be prompted to provide a default value for existing rows.
+Add the field to your model class, then run `plain migrations create` to create a migration.
+
+If the field is required (no `default=` and not `allow_null=True`), the autodetector refuses to generate the migration, since there's no value to seed existing rows with. You have two options:
+
+1. Declare a `default=` on the field so the new column has a value for existing rows.
+2. Add the field with `allow_null=True`, scaffold a data migration with `plain migrations create --empty --name backfill_<field>` to populate existing rows, then remove `allow_null=True` from the field — convergence applies `NOT NULL` on the next `postgres sync`.
+
+#### How do I make an existing column `NOT NULL`?
+
+Edit the field to remove `allow_null=True`. `plain migrations create` won't detect a schema change — nullability is managed by convergence. Run `plain postgres sync`:
+
+- If the column has no `NULL` rows, convergence applies the change with a non-blocking `CHECK NOT VALID` + `VALIDATE` + `SET NOT NULL` pattern.
+- If `NULL` rows exist, convergence blocks and prints the table and column to backfill. Scaffold a data migration with `plain migrations create --empty --name backfill_<field>`, write the backfill, and run `postgres sync` again.
 
 #### How do I create a unique constraint on multiple fields?
 

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

@@ -1,5 +1,83 @@
 # plain-postgres changelog
 
+## [0.96.0](https://github.com/dropseed/plain/releases/plain-postgres@0.96.0) (2026-04-17)
+
+### What's changed
+
+- **`DateTimeField` gained `create_now=True` / `update_now=True` kwargs; `auto_now_add` and `auto_now` are removed.** `create_now=True` installs a persistent `DEFAULT STATEMENT_TIMESTAMP()` column default — raw-SQL inserts now get a value, not just ORM-driven ones. `update_now=True` stamps the column on every `save()` via `pre_save`. Preflight requires `update_now=True` to be paired with `create_now=True` or `allow_null=True` so existing rows have a backfill path. `default=` is no longer accepted on `DateTimeField`. ([5d145e4](https://github.com/dropseed/plain/commit/5d145e4), [a44e5ec](https://github.com/dropseed/plain/commit/a44e5ec), [091bac7](https://github.com/dropseed/plain/commit/091bac7))
+- **`UUIDField` gained `generate=True`; `default=GenRandomUUID()` is no longer accepted.** `generate=True` installs `DEFAULT gen_random_uuid()` on the column, so Postgres produces a fresh UUID per row (raw-SQL inserts included). ([a44e5ec](https://github.com/dropseed/plain/commit/a44e5ec))
+- **Added `RandomStringField(length=N)`** for per-row DB-generated random hex strings. Backed by a `DEFAULT` that slices `gen_random_uuid()::text`; use in place of Python `default=secrets.token_hex` callables for tokens, slugs, and short IDs. Alphabet is always hex — an earlier draft accepted `alphabet=` but it was dropped because the generated expression grew to ~4 KB for a 40-char token. ([34858ab](https://github.com/dropseed/plain/commit/34858ab), [0918702](https://github.com/dropseed/plain/commit/0918702))
+- **Added `GenRandomUUID()` function.** Exported at `plain.postgres.functions.GenRandomUUID`. No longer valid as `default=`; use `UUIDField(generate=True)` or reference it in annotations/expressions. ([da58230](https://github.com/dropseed/plain/commit/da58230))
+- **Callable `default=` is banned on model fields.** `default=uuid.uuid4`, `default=secrets.token_hex`, `default=dict`, `default=lambda: ...`, etc. raise `TypeError` at field construction. Use DB-side generation (`UUIDField(generate=True)`, `RandomStringField`, `DateTimeField(create_now=True)`) or a static literal. Empty-collection defaults use literal `{}` / `[]` — the value is deep-copied on each `get_default()` call. ([091bac7](https://github.com/dropseed/plain/commit/091bac7))
+- **Literal `default=X` values now persist as column `DEFAULT` in the catalog and are reconciled by convergence.** Previously `default=` was Python-side only; now it is compiled to a DDL `DEFAULT <literal>` clause. Raw-SQL `INSERT`s get the default, and drift is detected if someone edits it out-of-band. ([c59473d](https://github.com/dropseed/plain/commit/c59473d), [6ed95fe](https://github.com/dropseed/plain/commit/6ed95fe), [161c7f9](https://github.com/dropseed/plain/commit/161c7f9))
+- **Column nullability and DEFAULT transitions now go through convergence, not the schema editor.** `AlterField` is a no-op when only `allow_null` or `default=` changed; `plain postgres sync` applies the change with online-safe DDL (`CHECK NOT VALID` + `VALIDATE` + `SET NOT NULL` for NOT NULL flips; catalog-only `SET`/`DROP DEFAULT` for default changes). The old 4-way NULL → NOT NULL backfill in the schema editor is gone — if a column has NULL rows, convergence now blocks with guidance instead of silently backfilling. ([3e10ab2](https://github.com/dropseed/plain/commit/3e10ab2), [c59473d](https://github.com/dropseed/plain/commit/c59473d))
+- **Every framework-issued DDL statement now emits `SET LOCAL lock_timeout` and, where relevant, `SET LOCAL statement_timeout`.** Defaults are `3s` each and apply to both migration operations and convergence fixes. Non-blocking operations (`CREATE INDEX CONCURRENTLY`, `VALIDATE CONSTRAINT`) skip `statement_timeout`. Configure via new settings `POSTGRES_MIGRATION_LOCK_TIMEOUT`, `POSTGRES_MIGRATION_STATEMENT_TIMEOUT`, `POSTGRES_CONVERGENCE_LOCK_TIMEOUT`, `POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT` (all `PLAIN_POSTGRES_*` env-var compatible). `RunSQL(no_timeout=True)` opts a single operation out — useful for batched backfills that manage their own timeouts. ([11d903b](https://github.com/dropseed/plain/commit/11d903b))
+- **The autodetector rejects unsafe column type changes.** Base-type changes outside a lossless widening allowlist (`smallint → integer`, `smallint → bigint`, `integer → bigint`) raise `MigrationSchemaError` with scaffold guidance instead of emitting an `AlterField` that would compile to a blind `ALTER COLUMN ... TYPE ... USING col::newtype`. Parameter-only changes (e.g. `max_length`) and the widening allowlist still auto-generate. ([073a9af](https://github.com/dropseed/plain/commit/073a9af))
+- **The autodetector rejects adding a NOT NULL column without a default.** Previously Plain prompted interactively for a one-shot value; now the autodetector errors out with two remediation options: declare a `default=`, or add the field as nullable, backfill, and drop `allow_null=True` via convergence. The `MigrationQuestioner.ask_not_null_*` prompts are gone. ([091bac7](https://github.com/dropseed/plain/commit/091bac7))
+- **`AddField` / `AlterField` no longer accept `preserve_default`.** The argument is removed from both operation classes and from `ProjectState.add_field` / `alter_field`. Existing migration files that pass it will fail to load — regenerate them or remove the kwarg. ([c0a117f](https://github.com/dropseed/plain/commit/c0a117f))
+- **Backslashes are banned in string `default=` values.** `default=r"C:\path"` raises `ValueError` at construction to prevent spurious DEFAULT drift on every convergence run. ([f8b6227](https://github.com/dropseed/plain/commit/f8b6227))
+- **`choices=` is now only accepted on `TextField` (and `TimeZoneField`).** Other fields (`IntegerField`, `BooleanField`, etc.) reject `choices=` at call time. ([01584dc](https://github.com/dropseed/plain/commit/01584dc))
+- **Removed `IntegerChoices` and the `Choices` base class.** Only `TextChoices` remains; it now subclasses `str, enum.Enum` directly. ([96acf13](https://github.com/dropseed/plain/commit/96acf13))
+- **`max_length=` is now only accepted on `TextField`, `BinaryField`, and `EncryptedTextField`.** Other fields reject it. ([aaa0fb6](https://github.com/dropseed/plain/commit/aaa0fb6))
+- **`default=` is no longer accepted on `ForeignKeyField`, `ManyToManyField`, `BinaryField`, `EncryptedTextField`, or `EncryptedJSONField`.** ([60299dc](https://github.com/dropseed/plain/commit/60299dc), [99ba5c2](https://github.com/dropseed/plain/commit/99ba5c2))
+- **`ManyToManyField` signature is now explicit** — it rejects `required=`, `allow_null=`, `default=`, and `validators=` with `TypeError`. ([be7fd86](https://github.com/dropseed/plain/commit/be7fd86))
+- **Removed `error_messages=` from model fields and `ModelForm.Meta`.** Form-field `error_messages` is unchanged; this only affects the model layer. ([4dee5ec](https://github.com/dropseed/plain/commit/4dee5ec))
+- **`PrimaryKeyField` takes no arguments.** It is always `bigint GENERATED BY DEFAULT AS IDENTITY NOT NULL`. Removed kwargs for `required`, `allow_null`, `default`, and `validators`; the type stub now matches the runtime signature. ([ca122c9](https://github.com/dropseed/plain/commit/ca122c9), [0ecd71e](https://github.com/dropseed/plain/commit/0ecd71e))
+- **`plain postgres sync --check` now prints pending work.** Previously `--check` only exited non-zero; it now enumerates pending migrations, convergence items, and blocked items with guidance. ([0de289d](https://github.com/dropseed/plain/commit/0de289d))
+- **Fixed index drift false positive for `DESC` / `NULLS FIRST|LAST` columns.** Indexes like `Index(fields=["-created_at"])` were rebuilt on every `postgres sync` because the introspection parser misread the sort direction as an opclass. ([07cb500](https://github.com/dropseed/plain/commit/07cb500))
+- **Fixed `Field.deconstruct()` over-shortening import paths** — `plain.postgres.fields.<submod>.X` now shortens to `plain.postgres.X` only when `X` is actually re-exported at the top level. ([34858ab](https://github.com/dropseed/plain/commit/34858ab))
+- **`ModelForm` no longer marks DB-expression-default and auto-filled fields as `required`.** Fields with `db_returning=True` (e.g. `create_now=True`, `generate=True`, `RandomStringField`) and `auto_fills_on_save=True` (`update_now=True`) produce form fields with `required=False` and preserve the `DATABASE_DEFAULT` sentinel through `construct_instance` so INSERT emits `DEFAULT` instead of NULL on empty submissions. `modelfield_to_formfield` now returns `None` for non-column-backed fields (M2M, etc.). ([6ed95fe](https://github.com/dropseed/plain/commit/6ed95fe))
+- **Internal restructuring.** `Field` is split into `ColumnField` → `DefaultableField` → `ChoicesField` with kwargs scoped to the fields that actually accept them. `plain.postgres.fields.__init__` is split into per-type modules (`base`, `text`, `numeric`, `temporal`, `boolean`, `binary`, `uuid`, `network`, `duration`, `primary_key`). `PrimaryKeyField` moved off the `BigIntegerField → IntegerField` chain onto `ColumnField[int]` directly. `non_db_attrs` renamed to `non_migration_attrs`. Removed dead Django-era internals: `SubqueryConstraint`, `MultiColSource`, multi-column FK machinery, multi-table-inheritance UPDATE machinery, `Field.description`, `Field.value_to_string()`, `Field.get_limit_choices_to()`. ([476e1ae](https://github.com/dropseed/plain/commit/476e1ae), [9ed8cc6](https://github.com/dropseed/plain/commit/9ed8cc6), [ca122c9](https://github.com/dropseed/plain/commit/ca122c9), [21cf85f](https://github.com/dropseed/plain/commit/21cf85f), [18080ca](https://github.com/dropseed/plain/commit/18080ca), [9d4ff49](https://github.com/dropseed/plain/commit/9d4ff49), [07b5f0b](https://github.com/dropseed/plain/commit/07b5f0b), [176f56e](https://github.com/dropseed/plain/commit/176f56e), [16e4fcd](https://github.com/dropseed/plain/commit/16e4fcd), [cb98bfa](https://github.com/dropseed/plain/commit/cb98bfa))
+
+### Upgrade instructions
+
+- **Replace `auto_now_add=True` with `create_now=True`** on every `DateTimeField`.
+- **Replace `auto_now=True` with `update_now=True`**. If the field was `NOT NULL`, also set `create_now=True` (or `allow_null=True`) — preflight will fail otherwise.
+- **Replace `DateTimeField(default=timezone.now)` / `default=Now()`** with `DateTimeField(create_now=True)`. `DateTimeField(default=...)` is no longer accepted.
+- **Replace `UUIDField(default=uuid.uuid4)` and `UUIDField(default=GenRandomUUID())`** with `UUIDField(generate=True)`. `UUIDField(default=...)` is no longer accepted.
+- **Replace `default=secrets.token_hex` / `default=secrets.token_urlsafe`** with `RandomStringField(length=N)` (hex output only).
+- **Replace `default=dict` / `default=list`** with `default={}` / `default=[]`. Any other callable passed as `default=` will now raise `TypeError`.
+- **Remove `choices=` from non-text fields** (`IntegerField`, `BooleanField`, etc.).
+- **Replace `IntegerChoices` usages** with `TextChoices` or a plain `enum.IntEnum`. `Choices` (the base class) is also gone.
+- **Remove `max_length=` from any field that isn't `TextField`, `BinaryField`, or `EncryptedTextField`.**
+- **Remove `default=` from `ForeignKeyField`, `BinaryField`, `EncryptedTextField`, and `EncryptedJSONField`.**
+- **Remove `required=`, `allow_null=`, `default=`, and `validators=` from `ManyToManyField`** — its signature is now explicit (`to`, `through`, `through_fields`, `related_query_name`, `limit_choices_to`, `symmetrical`).
+- **Remove kwargs from `PrimaryKeyField()`** — it no longer accepts any.
+- **Remove `error_messages=` from model-level fields and `ModelForm.Meta`.** (Form-field `error_messages` on standalone form fields is unchanged.)
+- **Escape backslashes in string `default=` values.** `default="C:\\path"` is fine; `default=r"C:\path"` now raises at construction.
+- **Edit or regenerate migration files that pass `preserve_default=...`** to `AddField` / `AlterField` — the kwarg was removed.
+- **Rename `non_db_attrs` to `non_migration_attrs`** in any custom field subclass.
+- **If your migrations hit the new 3s `statement_timeout`** against a large dev/staging DB, raise it for that run via `PLAIN_POSTGRES_MIGRATION_STATEMENT_TIMEOUT=30s`, or pass `RunSQL(sql, no_timeout=True)` on individual long-running operations.
+- **Run `plain postgres sync`** after upgrading to let convergence install persisted column DEFAULTs on existing tables.
+
+## [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