plain.postgres 0.95.0__tar.gz → 0.96.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.95.0
+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
@@ -48,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
@@ -452,35 +452,42 @@ Schema changes fall into three categories, each with a different author and appl
 - **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                                      |
+| 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       | 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 |
+| 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.
 
 **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
@@ -689,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:
@@ -713,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:**
@@ -742,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:**
 
@@ -775,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
@@ -1167,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.
 
@@ -1185,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.95.0 → plain_postgres-0.96.0}/plain/postgres/CHANGELOG.md

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

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

@@ -36,7 +36,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
@@ -440,35 +440,42 @@ Schema changes fall into three categories, each with a different author and appl
 - **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                                      |
+| 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       | 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 |
+| 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.
 
 **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
@@ -677,6 +684,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:
@@ -701,8 +745,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:**
@@ -730,10 +774,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:**
 
@@ -763,8 +808,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
@@ -1155,17 +1200,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.
 
@@ -1173,7 +1222,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.95.0 → plain_postgres-0.96.0}/plain/postgres/__init__.py

@@ -9,7 +9,7 @@ from .constraints import CheckConstraint, UniqueConstraint
 from .db import get_connection
 from .deletion import CASCADE, NO_ACTION, RESTRICT, SET_NULL
 from .expressions import F
-from .enums import IntegerChoices, TextChoices
+from .enums import TextChoices
 from .fields import (
     BigIntegerField,
     BinaryField,
@@ -23,6 +23,7 @@ from .fields import (
     GenericIPAddressField,
     IntegerField,
     PrimaryKeyField,
+    RandomStringField,
     SmallIntegerField,
     TextField,
     TimeField,
@@ -54,7 +55,6 @@ __all__ = [
     "CheckConstraint",
     "UniqueConstraint",
     # From enums
-    "IntegerChoices",
     "TextChoices",
     # From fields
     "BigIntegerField",
@@ -69,6 +69,7 @@ __all__ = [
     "GenericIPAddressField",
     "IntegerField",
     "PrimaryKeyField",
+    "RandomStringField",
     "SmallIntegerField",
     "TextField",
     "TimeField",