plain.postgres 0.119.0__tar.gz → 0.120.0__tar.gz

{plain_postgres-0.119.0 → plain_postgres-0.120.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plain.postgres
-Version: 0.119.0
+Version: 0.120.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause
@@ -61,12 +61,24 @@ class User(postgres.Model):
 
 Annotate each field with `Field[T]` (the value type) — that's what gives the
 model a type-checked constructor: `User(email="a@b.com")` flags wrong value
-types, unknown field names, and missing required fields. A field is optional in
-that constructor only when its definition passes `default=` (this is general,
-not nullable-specific — a `required=False` field with no `default=` is still a
-required constructor arg), so nullable fields use `Field[T | None]` with
-`default=None`. DB-owned fields (`id`, `create_now`, generated values) are
-auto-excluded from the constructor.
+types, unknown field names, and missing required fields.
+
+Annotating is not per-model opt-in. `postgres.Model` carries the transform, so
+the checker synthesizes every subclass's constructor from its annotated
+attributes and nothing else. Drop the annotation from `email` above and it stops
+being a constructor argument at all — `User(email="a@b.com")` is then rejected as
+an unknown argument. The runtime doesn't care either way, but if you run a type
+checker, every model has to be annotated.
+
+A field is optional in that constructor only when its definition passes
+`default=` (this is general, not nullable-specific — a `required=False` field
+with no `default=` is still a required constructor arg), so nullable fields use
+`Field[T | None]` with `default=None`. The runtime already treats a nullable
+field as optional — constructing without it yields `None` — so `default=None`
+exists for the checker; it persists nothing and changes no schema.
+`plain preflight` lists the nullable fields still missing one
+(`postgres.nullable_field_without_default`). DB-owned fields (`id`,
+`create_now`, generated values) are auto-excluded from the constructor.
 
 Field types declared outside `plain.postgres.types` — `PasswordField`, or one of
 your own — are the exception: their stub still types the value, but they are
@@ -217,6 +229,8 @@ For more advanced querying options, see the [`QuerySet`](./query.py#QuerySet) cl
 `where()` is a typed alternative to `filter()`. Instead of string keyword lookups, you build each condition from a field, so a type checker catches a misspelled field or a wrong value type at the call site:
 
 ```python
+from datetime import datetime
+
 from plain import postgres
 from plain.postgres import Field, types
 
@@ -226,6 +240,8 @@ class User(postgres.Model):
     email: Field[str] = types.EmailField()
     role: Field[str] = types.TextField(max_length=20)
     age: Field[int | None] = types.IntegerField(allow_null=True, default=None)
+    created_at: Field[datetime] = types.DateTimeField(create_now=True)
+    updated_at: Field[datetime] = types.DateTimeField(update_now=True)
 
 
 # Each argument is a condition; multiple arguments are ANDed together.
@@ -235,7 +251,7 @@ admins = User.query.where(
 )
 ```
 
-Every field exposes `equals`, `not_equal`, `gt`, `gte`, `lt`, `lte`, `is_null`, and `is_in`. Text fields add `contains`, `icontains`, `startswith`, and `endswith`. Each returns a `Q`, so you can combine them with `|` and `&` or negate with `~`:
+Every field exposes `equals`, `not_equal`, `gt`, `gte`, `lt`, `lte`, `is_null`, and `is_in`. Text fields add `contains`, `startswith`, and `endswith`, plus their case-insensitive forms `icontains`, `istartswith`, `iendswith`, and `iequals` (the typed spelling of `filter(field__iexact=...)`). Each returns a `Q`, so you can combine them with `|` and `&` or negate with `~`:
 
 ```python
 # Membership, negation, and OR
@@ -244,6 +260,47 @@ User.query.where(~User.role.equals("guest"))
 User.query.where(User.email.endswith("@example.com") | User.role.equals("admin"))
 ```
 
+`~` negates whatever it wraps, which is what you want for a composite condition but not for a null check. `is_null()` takes a flag, and the two compile differently:
+
+```python
+User.query.where(~User.age.is_null())  # WHERE NOT ("age" IS NULL)
+User.query.where(User.age.is_null(False))  # WHERE "age" IS NOT NULL
+```
+
+Both match the same rows. `is_null(False)` is the conversion for `filter(age__isnull=False)` and emits the SQL you would write by hand, so reach for it and keep `~` for negating a condition that isn't a null check.
+
+A comparison can also take another column of the same value type, instead of a value:
+
+```python
+# Q(updated_at__gt=F("created_at"))
+User.query.where(User.updated_at.gt(User.created_at))
+```
+
+`equals`, `not_equal`, `gt`, `gte`, `lt`, and `lte` all accept one. The column has to belong to the same model, which `where()` checks on both sides, and it has to be the same value type — comparing an `int` column against a `str` one is a type error.
+
+A **nullable column is a different value type** to the checker — `Field[int | None]` is not a `Field[int]` — so the two directions aren't the same. A non-null column accepts a nullable one on the right; a nullable one on the left won't accept a non-null column, because there's no way to name its value type without the `None`. Compare the other way round, or drop to `filter(age__lt=F("other"))`.
+
+An `F()` expression works too, but that arm is untyped: an expression's output type isn't tracked, so nothing checks it against the column. `F()` is the same escape hatch here that it is in `filter()`.
+
+**A condition _is_ a `Q`**, so these replace `Q` everywhere, not just in `filter()`. Anything that takes a `Q` takes one unchanged — `When()`, including the ones inside a `Case()`, and an aggregate's `filter=`:
+
+```python
+from plain.postgres.aggregates import Count
+from plain.postgres.expressions import Case, Value, When
+
+User.query.annotate(
+    tier=Case(When(User.age.gte(18), then=Value("adult")), default=Value("minor"))
+)
+User.query.values("role").annotate(adults=Count("id", filter=User.age.gte(18)))
+```
+
+```sql
+-- the Case annotation
+CASE WHEN "age" >= %s THEN %s ELSE %s END AS "tier"
+-- the Count annotation
+COUNT("id") FILTER (WHERE "age" >= %s) AS "adults"
+```
+
 Conditions traverse foreign keys — accessing a field through a relation builds the joined lookup:
 
 ```python
@@ -267,9 +324,24 @@ A class-level many-to-many (`Widget.tags`) is _not_ an entry point: it has no tr
 
 A traversed field _is_ the related field, carrying the relation path as its name — so it offers exactly the conditions that field offers, including an encrypted field's refusals.
 
+**`where()` preserves the order you wrote; `filter()` sorted its kwargs alphabetically.** Converting a multi-condition `filter()` can change the WHERE clause text and the parameter order, though not which rows it matches:
+
+```sql
+-- filter(role="admin", email="a@example.com")
+WHERE ("email" = %s AND "role" = %s)  -- params: ('a@example.com', 'admin')
+-- where(User.role.equals("admin"), User.email.equals("a@example.com"))
+WHERE ("role" = %s AND "email" = %s)  -- params: ('admin', 'a@example.com')
+```
+
+Kwargs you already wrote alphabetically convert unchanged. Where the source order wasn't alphabetical, preserving it changes the predicate structure — a test asserting on generated SQL notices, and so can `pg_stat_statements`, which groups by structure rather than literal text and files the reordered statement as a new entry.
+
+**Conditions are strict where `filter()` was lenient — to the type checker.** `equals` takes the field's value type, so `User.age.equals("18")` and a `Field[UUID]`'s `.equals("3f2504e0-4f89-11d3-9a0c-0305e82c3301")` are type errors where `filter(age="18")` and `filter(uuid="3f2504e0-4f89-11d3-9a0c-0305e82c3301")` were not. Runtime coercion is unchanged: `User.age.equals("18")` still coerces the string and runs, exactly as the kwarg did.
+
+So the strictness lands on the caller. Code holding a string from a CLI argument, URL segment, or session parses it first — `int(raw)`, `uuid.UUID(raw)` — and an invalid value raises `ValueError` there, before the ORM is involved, next to the input that was wrong.
+
 **A condition belongs to the model whose field built it.** `Order.query.where(User.email.equals("x"))` raises `TypeError` naming both models. A type checker can't catch this — `Field[str]` is `Field[str]` whichever model declared it — and without the check the lookup name `"email"` just resolves against `Order`, which is silently the wrong column when both models have one. A traversed condition belongs to the model the traversal _started_ from, so `Order.query.where(Order.user.email.equals("x"))` is `Order`'s, not `User`'s. A hand-written `Q(email="x")` names no model and isn't checked — it's `filter()`'s untyped spelling and behaves like it.
 
-[Encrypted fields](#encrypted-fields) reject value comparisons because their ciphertext is non-deterministic — only `is_null()` is available, and any other condition method (`equals`, `is_in`, …) raises `TypeError`.
+[Encrypted fields](#encrypted-fields) reject value comparisons because their ciphertext is non-deterministic — only `is_null()` is available, and any other condition method (`equals`, `is_in`, …) raises `TypeError`. That holds on either side of a comparison: an encrypted column can't be the column another column is compared _against_ either, since that would match plaintext against ciphertext.
 
 ### Selecting columns with select()
 
@@ -1479,10 +1551,63 @@ from plain.postgres import Field, types
 @postgres.register_model
 class Book(postgres.Model):
     title: Field[str] = types.TextField(max_length=200)
-    author: Author = types.ForeignKeyField("Author", on_delete=postgres.CASCADE)
+    author: Field[Author] = types.ForeignKeyField(Author, on_delete=postgres.CASCADE)
     tags = types.ManyToManyField("Tag")
 ```
 
+### Referring to a model by name
+
+`ForeignKeyField` also takes a `"package.Model"` string (or `"self"`) instead of
+the class. That is a **runtime** device, for the cases where the class isn't
+importable at the point of declaration: a circular reference between two models,
+a self-reference, or a framework package pointing at the app's own `User`.
+
+The annotation is unaffected — a string-referenced foreign key is annotated
+`Field[Related]` exactly like a class-referenced one, and gets the same typed
+surface: `Model.user.email.equals(...)` traversal, `Model.user.id.equals(...)`
+conditions, and a typed `Model(user=...)` constructor. The string says nothing
+to the checker, so the annotation is where `Related` comes from; import it under
+`TYPE_CHECKING` when importing it for real would be the cycle you were avoiding:
+
+```python
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from plain import postgres
+from plain.postgres import Field, types
+
+if TYPE_CHECKING:
+    from app.users.models import User
+
+
+@postgres.register_model
+class PinnedNavItem(postgres.Model):
+    # Cross-package: plain.admin can't import the app's User at runtime.
+    user: Field[User] = types.ForeignKeyField("users.User", on_delete=postgres.CASCADE)
+
+
+@postgres.register_model
+class TreeNode(postgres.Model):
+    name: Field[str] = types.TextField(max_length=100)
+    # Self-reference, nullable: `Field[T | None]` plus `default=None`.
+    parent: Field[TreeNode | None] = types.ForeignKeyField(
+        "self", on_delete=postgres.CASCADE, allow_null=True, default=None
+    )
+```
+
+What does _not_ work is annotating the field with the related model itself
+(`user: User = types.ForeignKeyField("users.User", ...)`). That names a model
+instance rather than a field, so the checker never sees a descriptor: class
+access is a `User` rather than `type[User]`, `Model.user.id` is an `int`, and
+the condition methods are gone. `plain preflight`'s
+`postgres.foreign_key_annotated_as_value` finds these: it reports a foreign key
+whose annotation — on the model or on any of its base classes — names the
+related model. It asks for positive evidence, so it stays quiet when it can't
+establish that: an unannotated foreign key (no constructor argument at all), a
+`ClassVar[...]` one, and any spelling whose meaning it can't read. Treat a clean
+run as "nothing found", not "nothing to find".
+
 ### Foreign key access
 
 Accessing a foreign key gives you the related object without a query — only its primary key is loaded up front:
@@ -1765,12 +1890,12 @@ CASCADE for owned children, RESTRICT for referenced data, SET_NULL for optional
 
 ```python
 # Bad — blindly using CASCADE everywhere
-company: Company = types.ForeignKeyField(
-    "Company", on_delete=postgres.CASCADE
+company: Field[Company] = types.ForeignKeyField(
+    Company, on_delete=postgres.CASCADE
 )  # deleting company deletes invoices!
 
 # Good — block the delete while invoices reference the company
-company: Company = types.ForeignKeyField("Company", on_delete=postgres.RESTRICT)
+company: Field[Company] = types.ForeignKeyField(Company, on_delete=postgres.RESTRICT)
 ```
 
 #### No `allow_null` on string fields

{plain_postgres-0.119.0 → plain_postgres-0.120.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,23 @@
 # plain-postgres changelog
 
+## [0.120.0](https://github.com/dropseed/plain/releases/plain-postgres@0.120.0) (2026-09-21)
+
+### What's changed
+
+- String-referenced foreign keys get the typed condition surface. `ForeignKeyField("users.User", ...)` now returns the same typed descriptor as the class-referenced form, so the model annotates it `user: Field[User]` (with a `TYPE_CHECKING` import where the runtime import would cycle) and `Model.user.email.equals(...)`, `Model.user.id.is_in(...)` and typed construction all work through it. The rule is now one rule for every foreign key: annotate `Field[Related]` (`Field[Related | None]` plus `default=None` when nullable, `Field[Foo | None]` for `"self"`); the string form is a runtime device for import cycles and cross-package references only. New preflight warning `postgres.foreign_key_annotated_as_value` reports a foreign key whose annotation names the related model instead of `Field[...]`, with the exact rewrite. It exists because the type checker is silent on the old non-nullable spelling: PEP 681 only compares a field's declared type against the annotation when `default=` is passed ([b072153088](https://github.com/dropseed/plain/commit/b072153088))
+- `iequals`, `istartswith` and `iendswith` on `Field[str]`, the case-insensitive counterparts of `equals`/`startswith`/`endswith` (the `iexact`/`istartswith`/`iendswith` lookups). Blocked on encrypted fields like the other string conditions ([26c35167d8](https://github.com/dropseed/plain/commit/26c35167d8))
+- Comparisons against another column: `equals`, `not_equal`, `gt`, `gte`, `lt` and `lte` accept a field of the same value type, so `Post.query.where(Post.updated_at.gt(Post.created_at))` replaces `filter(updated_at__gt=F("created_at"))` and type-checks. A non-null column accepts a nullable one on the right; the reverse can't be expressed. Traversed fields carry their relation prefix; a column from another model trips the cross-model guard; an encrypted column is refused on either side. `F()` and other expressions are still accepted as the untyped escape hatch ([26c35167d8](https://github.com/dropseed/plain/commit/26c35167d8))
+- New preflight warning `postgres.nullable_field_without_default`: an `allow_null=True` field with no declared default is optional in the constructor at runtime but required to a type checker; adding `default=None` makes them agree and changes no schema. `Field.has_declared_default()` reports a declared `default=None` on the fields that accept only that default ([55d2a71790](https://github.com/dropseed/plain/commit/55d2a71790))
+- Docs corrected and filled from the internal conversion pass: typed construction is opt-in at runtime but not for a type-checked app (an unannotated model's constructor calls are unknown-argument errors, so every model must be annotated); `is_null(False)` is the conversion for `__isnull=False` (`~x.is_null()` compiles to `NOT (x IS NULL)`); typed conditions are a `Q` replacement, accepted by `When()` and an aggregate's `filter=` unchanged; `where()` preserves written condition order where `filter()` sorted kwargs alphabetically, so a converted multi-condition filter can change the emitted clause order; value-type strictness is a type-checker guard and runtime coercion is unchanged ([55d2a71790](https://github.com/dropseed/plain/commit/55d2a71790)) ([10236185ea](https://github.com/dropseed/plain/commit/10236185ea))
+
+### Upgrade instructions
+
+- Rewrite every string-referenced foreign key annotation from `X: Related = types.ForeignKeyField("...")` to `X: Field[Related] = types.ForeignKeyField("...")`, nullable ones to `Field[Related | None]` with `default=None`. Import `Related` under `if TYPE_CHECKING:` where the runtime import would cycle. This corrects the 0.119.0 instruction to annotate a string forward reference with the bare model type. `plain preflight` lists the fields to change.
+- If the project runs a type checker, annotate every model; 0.119.0 called annotation optional, which is true only at runtime.
+- Add `default=None` to nullable fields that lack a declared default; `plain preflight` lists them. No behavior or schema change.
+- When converting a multi-kwarg `filter()` to `where()`, list the conditions in the order `filter()` sorted them (alphabetical by field name) if anything pins the generated SQL.
+- `filter()`, `exclude()`, `values()`, `values_list()`, `only()`, `defer()` and string `annotate()` are unchanged.
+
 ## [0.119.0](https://github.com/dropseed/plain/releases/plain-postgres@0.119.0) (2026-09-20)
 
 ### What's changed

{plain_postgres-0.119.0 → plain_postgres-0.120.0}/plain/postgres/README.md

@@ -48,12 +48,24 @@ class User(postgres.Model):
 
 Annotate each field with `Field[T]` (the value type) — that's what gives the
 model a type-checked constructor: `User(email="a@b.com")` flags wrong value
-types, unknown field names, and missing required fields. A field is optional in
-that constructor only when its definition passes `default=` (this is general,
-not nullable-specific — a `required=False` field with no `default=` is still a
-required constructor arg), so nullable fields use `Field[T | None]` with
-`default=None`. DB-owned fields (`id`, `create_now`, generated values) are
-auto-excluded from the constructor.
+types, unknown field names, and missing required fields.
+
+Annotating is not per-model opt-in. `postgres.Model` carries the transform, so
+the checker synthesizes every subclass's constructor from its annotated
+attributes and nothing else. Drop the annotation from `email` above and it stops
+being a constructor argument at all — `User(email="a@b.com")` is then rejected as
+an unknown argument. The runtime doesn't care either way, but if you run a type
+checker, every model has to be annotated.
+
+A field is optional in that constructor only when its definition passes
+`default=` (this is general, not nullable-specific — a `required=False` field
+with no `default=` is still a required constructor arg), so nullable fields use
+`Field[T | None]` with `default=None`. The runtime already treats a nullable
+field as optional — constructing without it yields `None` — so `default=None`
+exists for the checker; it persists nothing and changes no schema.
+`plain preflight` lists the nullable fields still missing one
+(`postgres.nullable_field_without_default`). DB-owned fields (`id`,
+`create_now`, generated values) are auto-excluded from the constructor.
 
 Field types declared outside `plain.postgres.types` — `PasswordField`, or one of
 your own — are the exception: their stub still types the value, but they are
@@ -204,6 +216,8 @@ For more advanced querying options, see the [`QuerySet`](./query.py#QuerySet) cl
 `where()` is a typed alternative to `filter()`. Instead of string keyword lookups, you build each condition from a field, so a type checker catches a misspelled field or a wrong value type at the call site:
 
 ```python
+from datetime import datetime
+
 from plain import postgres
 from plain.postgres import Field, types
 
@@ -213,6 +227,8 @@ class User(postgres.Model):
     email: Field[str] = types.EmailField()
     role: Field[str] = types.TextField(max_length=20)
     age: Field[int | None] = types.IntegerField(allow_null=True, default=None)
+    created_at: Field[datetime] = types.DateTimeField(create_now=True)
+    updated_at: Field[datetime] = types.DateTimeField(update_now=True)
 
 
 # Each argument is a condition; multiple arguments are ANDed together.
@@ -222,7 +238,7 @@ admins = User.query.where(
 )
 ```
 
-Every field exposes `equals`, `not_equal`, `gt`, `gte`, `lt`, `lte`, `is_null`, and `is_in`. Text fields add `contains`, `icontains`, `startswith`, and `endswith`. Each returns a `Q`, so you can combine them with `|` and `&` or negate with `~`:
+Every field exposes `equals`, `not_equal`, `gt`, `gte`, `lt`, `lte`, `is_null`, and `is_in`. Text fields add `contains`, `startswith`, and `endswith`, plus their case-insensitive forms `icontains`, `istartswith`, `iendswith`, and `iequals` (the typed spelling of `filter(field__iexact=...)`). Each returns a `Q`, so you can combine them with `|` and `&` or negate with `~`:
 
 ```python
 # Membership, negation, and OR
@@ -231,6 +247,47 @@ User.query.where(~User.role.equals("guest"))
 User.query.where(User.email.endswith("@example.com") | User.role.equals("admin"))
 ```
 
+`~` negates whatever it wraps, which is what you want for a composite condition but not for a null check. `is_null()` takes a flag, and the two compile differently:
+
+```python
+User.query.where(~User.age.is_null())  # WHERE NOT ("age" IS NULL)
+User.query.where(User.age.is_null(False))  # WHERE "age" IS NOT NULL
+```
+
+Both match the same rows. `is_null(False)` is the conversion for `filter(age__isnull=False)` and emits the SQL you would write by hand, so reach for it and keep `~` for negating a condition that isn't a null check.
+
+A comparison can also take another column of the same value type, instead of a value:
+
+```python
+# Q(updated_at__gt=F("created_at"))
+User.query.where(User.updated_at.gt(User.created_at))
+```
+
+`equals`, `not_equal`, `gt`, `gte`, `lt`, and `lte` all accept one. The column has to belong to the same model, which `where()` checks on both sides, and it has to be the same value type — comparing an `int` column against a `str` one is a type error.
+
+A **nullable column is a different value type** to the checker — `Field[int | None]` is not a `Field[int]` — so the two directions aren't the same. A non-null column accepts a nullable one on the right; a nullable one on the left won't accept a non-null column, because there's no way to name its value type without the `None`. Compare the other way round, or drop to `filter(age__lt=F("other"))`.
+
+An `F()` expression works too, but that arm is untyped: an expression's output type isn't tracked, so nothing checks it against the column. `F()` is the same escape hatch here that it is in `filter()`.
+
+**A condition _is_ a `Q`**, so these replace `Q` everywhere, not just in `filter()`. Anything that takes a `Q` takes one unchanged — `When()`, including the ones inside a `Case()`, and an aggregate's `filter=`:
+
+```python
+from plain.postgres.aggregates import Count
+from plain.postgres.expressions import Case, Value, When
+
+User.query.annotate(
+    tier=Case(When(User.age.gte(18), then=Value("adult")), default=Value("minor"))
+)
+User.query.values("role").annotate(adults=Count("id", filter=User.age.gte(18)))
+```
+
+```sql
+-- the Case annotation
+CASE WHEN "age" >= %s THEN %s ELSE %s END AS "tier"
+-- the Count annotation
+COUNT("id") FILTER (WHERE "age" >= %s) AS "adults"
+```
+
 Conditions traverse foreign keys — accessing a field through a relation builds the joined lookup:
 
 ```python
@@ -254,9 +311,24 @@ A class-level many-to-many (`Widget.tags`) is _not_ an entry point: it has no tr
 
 A traversed field _is_ the related field, carrying the relation path as its name — so it offers exactly the conditions that field offers, including an encrypted field's refusals.
 
+**`where()` preserves the order you wrote; `filter()` sorted its kwargs alphabetically.** Converting a multi-condition `filter()` can change the WHERE clause text and the parameter order, though not which rows it matches:
+
+```sql
+-- filter(role="admin", email="a@example.com")
+WHERE ("email" = %s AND "role" = %s)  -- params: ('a@example.com', 'admin')
+-- where(User.role.equals("admin"), User.email.equals("a@example.com"))
+WHERE ("role" = %s AND "email" = %s)  -- params: ('admin', 'a@example.com')
+```
+
+Kwargs you already wrote alphabetically convert unchanged. Where the source order wasn't alphabetical, preserving it changes the predicate structure — a test asserting on generated SQL notices, and so can `pg_stat_statements`, which groups by structure rather than literal text and files the reordered statement as a new entry.
+
+**Conditions are strict where `filter()` was lenient — to the type checker.** `equals` takes the field's value type, so `User.age.equals("18")` and a `Field[UUID]`'s `.equals("3f2504e0-4f89-11d3-9a0c-0305e82c3301")` are type errors where `filter(age="18")` and `filter(uuid="3f2504e0-4f89-11d3-9a0c-0305e82c3301")` were not. Runtime coercion is unchanged: `User.age.equals("18")` still coerces the string and runs, exactly as the kwarg did.
+
+So the strictness lands on the caller. Code holding a string from a CLI argument, URL segment, or session parses it first — `int(raw)`, `uuid.UUID(raw)` — and an invalid value raises `ValueError` there, before the ORM is involved, next to the input that was wrong.
+
 **A condition belongs to the model whose field built it.** `Order.query.where(User.email.equals("x"))` raises `TypeError` naming both models. A type checker can't catch this — `Field[str]` is `Field[str]` whichever model declared it — and without the check the lookup name `"email"` just resolves against `Order`, which is silently the wrong column when both models have one. A traversed condition belongs to the model the traversal _started_ from, so `Order.query.where(Order.user.email.equals("x"))` is `Order`'s, not `User`'s. A hand-written `Q(email="x")` names no model and isn't checked — it's `filter()`'s untyped spelling and behaves like it.
 
-[Encrypted fields](#encrypted-fields) reject value comparisons because their ciphertext is non-deterministic — only `is_null()` is available, and any other condition method (`equals`, `is_in`, …) raises `TypeError`.
+[Encrypted fields](#encrypted-fields) reject value comparisons because their ciphertext is non-deterministic — only `is_null()` is available, and any other condition method (`equals`, `is_in`, …) raises `TypeError`. That holds on either side of a comparison: an encrypted column can't be the column another column is compared _against_ either, since that would match plaintext against ciphertext.
 
 ### Selecting columns with select()
 
@@ -1466,10 +1538,63 @@ from plain.postgres import Field, types
 @postgres.register_model
 class Book(postgres.Model):
     title: Field[str] = types.TextField(max_length=200)
-    author: Author = types.ForeignKeyField("Author", on_delete=postgres.CASCADE)
+    author: Field[Author] = types.ForeignKeyField(Author, on_delete=postgres.CASCADE)
     tags = types.ManyToManyField("Tag")
 ```
 
+### Referring to a model by name
+
+`ForeignKeyField` also takes a `"package.Model"` string (or `"self"`) instead of
+the class. That is a **runtime** device, for the cases where the class isn't
+importable at the point of declaration: a circular reference between two models,
+a self-reference, or a framework package pointing at the app's own `User`.
+
+The annotation is unaffected — a string-referenced foreign key is annotated
+`Field[Related]` exactly like a class-referenced one, and gets the same typed
+surface: `Model.user.email.equals(...)` traversal, `Model.user.id.equals(...)`
+conditions, and a typed `Model(user=...)` constructor. The string says nothing
+to the checker, so the annotation is where `Related` comes from; import it under
+`TYPE_CHECKING` when importing it for real would be the cycle you were avoiding:
+
+```python
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from plain import postgres
+from plain.postgres import Field, types
+
+if TYPE_CHECKING:
+    from app.users.models import User
+
+
+@postgres.register_model
+class PinnedNavItem(postgres.Model):
+    # Cross-package: plain.admin can't import the app's User at runtime.
+    user: Field[User] = types.ForeignKeyField("users.User", on_delete=postgres.CASCADE)
+
+
+@postgres.register_model
+class TreeNode(postgres.Model):
+    name: Field[str] = types.TextField(max_length=100)
+    # Self-reference, nullable: `Field[T | None]` plus `default=None`.
+    parent: Field[TreeNode | None] = types.ForeignKeyField(
+        "self", on_delete=postgres.CASCADE, allow_null=True, default=None
+    )
+```
+
+What does _not_ work is annotating the field with the related model itself
+(`user: User = types.ForeignKeyField("users.User", ...)`). That names a model
+instance rather than a field, so the checker never sees a descriptor: class
+access is a `User` rather than `type[User]`, `Model.user.id` is an `int`, and
+the condition methods are gone. `plain preflight`'s
+`postgres.foreign_key_annotated_as_value` finds these: it reports a foreign key
+whose annotation — on the model or on any of its base classes — names the
+related model. It asks for positive evidence, so it stays quiet when it can't
+establish that: an unannotated foreign key (no constructor argument at all), a
+`ClassVar[...]` one, and any spelling whose meaning it can't read. Treat a clean
+run as "nothing found", not "nothing to find".
+
 ### Foreign key access
 
 Accessing a foreign key gives you the related object without a query — only its primary key is loaded up front:
@@ -1752,12 +1877,12 @@ CASCADE for owned children, RESTRICT for referenced data, SET_NULL for optional
 
 ```python
 # Bad — blindly using CASCADE everywhere
-company: Company = types.ForeignKeyField(
-    "Company", on_delete=postgres.CASCADE
+company: Field[Company] = types.ForeignKeyField(
+    Company, on_delete=postgres.CASCADE
 )  # deleting company deletes invoices!
 
 # Good — block the delete while invoices reference the company
-company: Company = types.ForeignKeyField("Company", on_delete=postgres.RESTRICT)
+company: Field[Company] = types.ForeignKeyField(Company, on_delete=postgres.RESTRICT)
 ```
 
 #### No `allow_null` on string fields

{plain_postgres-0.119.0 → plain_postgres-0.120.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -30,6 +30,11 @@ class Article(postgres.Model):
     created_at: Field[datetime] = types.DateTimeField(create_now=True)
 ```
 
+- **Every model, not just some.** `postgres.Model` carries the transform, so the
+  checker builds each subclass's constructor out of its annotated attributes and
+  nothing else. An unannotated `name = types.TextField()` isn't a constructor
+  argument at all, and `Model(name="x")` is rejected as an unknown argument. The
+  runtime is unaffected — but a type-checked app has to annotate every model.
 - **Value type**: `Field[str]`, `Field[int]`, `Field[datetime]`; for an FK to a
   model class, `Field[RelatedModel]`.
 - **Optional in the constructor = a call-site `default=`.** A stock type checker
@@ -38,17 +43,38 @@ class Article(postgres.Model):
   `required=False` field with no `default=` is still a _required_ constructor arg.
   Add `default=` to any field you intend to omit when constructing.
 - **Nullable** (`allow_null=True`) → `Field[T | None]`, and add `default=None` so
-  it's optional in the constructor (per the rule above). Applies to class-ref and
-  string forward-ref FKs alike.
+  it's optional in the constructor (per the rule above). The runtime already
+  treats it as optional — constructing without it yields `None` — so
+  `default=None` is purely for the checker: it persists nothing and changes no
+  schema. `plain preflight` lists the ones still missing it
+  (`postgres.nullable_field_without_default`). Applies to class-ref and
+  string-ref FKs alike.
 - **DB-owned** fields are still annotated but auto-excluded from the
   constructor: the `id`, `create_now`/`update_now` datetimes, `generate=True`,
   and `RandomStringField`.
-- **String forward-ref FKs** (`"self"`, `"OtherModel"`) keep a _value-type_
-  annotation — the checker can't resolve the string to a model:
-  `parent: Foo | None = types.ForeignKeyField("self", on_delete=postgres.CASCADE, allow_null=True, default=None)`.
-  That annotation is a model instance, not a field, so `where()` traversal
-  (`Child.parent.name.equals(...)`) doesn't type-check through it — declare the
-  target above and pass the class when you want traversal typed.
+- **String model references** (`"users.User"`, `"OtherModel"`, `"self"`) annotate
+  `Field[Related]` like any other FK — the string is a runtime device for import
+  cycles, self-references, and cross-package references (a framework package
+  pointing at the app's `User`), not a typing compromise. `Related` comes from
+  the annotation, so import it under `TYPE_CHECKING` when importing it for real
+  would be the cycle you were avoiding:
+    ```python
+    if TYPE_CHECKING:
+        from app.users.models import User
+
+    user: Field[User] = types.ForeignKeyField("users.User", on_delete=postgres.CASCADE)
+    parent: Field[Foo | None] = types.ForeignKeyField(
+        "self", on_delete=postgres.CASCADE, allow_null=True, default=None
+    )
+    ```
+    Annotating the field with the related model itself (`user: User = ...`) names a
+    model instance rather than a field: class access becomes a `User`,
+    `Model.user.id` is an `int`, and the condition methods disappear.
+    `plain preflight`'s `postgres.foreign_key_annotated_as_value` reports a
+    foreign key whose annotation — on the model or any base class — names the
+    related model. It wants positive evidence, so an unannotated field, a
+    `ClassVar[...]` one, or a spelling it can't read stays quiet: a clean run
+    means "nothing found", not "nothing to find".
 - **Encrypted fields** are annotated `EncryptedField[T]` (imported from
   `plain.postgres` alongside `Field`), not `Field[T]`. It's a `Field[T]`
   subclass, so the constructor is typed identically, but it also carries the
@@ -103,6 +129,10 @@ Run `uv run plain docs postgres` for full workflow details.
 Use `Model.query` to build querysets (e.g., `User.query.filter(is_active=True)`).
 
 - `where()` takes typed conditions built off fields (`User.query.where(User.role.equals("admin"))`) instead of `filter()`'s string kwargs, so a typo or wrong value type is caught at the call site.
+- `__isnull=False` converts to `is_null(False)` (`"x" IS NOT NULL`), not `~...is_null()` (`NOT ("x" IS NULL)`) — same rows, different SQL.
+- A condition **is** a `Q`, so it goes anywhere a `Q` goes — `When(...)` (including the ones inside a `Case(...)`), `Count("id", filter=...)` — not just `where()`. `Case(...)` itself takes only `When` objects, never a bare condition.
+- `where()` keeps conditions in the order written; `filter()` sorted its kwargs alphabetically. A converted multi-condition `filter()` can emit different WHERE text and parameter order (same rows; already-alphabetical kwargs convert unchanged) — matters for tests pinning SQL and for `pg_stat_statements`, which groups by predicate structure, not literal text.
+- Conditions take the field's value type where string kwargs coerced: `Field[UUID].equals("...")` and `Field[int].equals("1")` are type errors. That is a type-checker guard only — runtime still coerces. Parse a CLI/URL/session string first (`uuid.UUID(raw)`, `int(raw)`); an invalid value raises `ValueError` there, before the ORM is involved.
 - **Conditions on a relation go through its key**: `Post.query.where(Post.author.id.equals(author.id))`, `.id.is_in([...])`, `.id.is_null()` — the typed spelling of `filter(author=author)`, same SQL. `Post.author.equals(author)` raises `AttributeError`: `Post.author` is `type[Author]` to the checker (which is what makes `Post.author.email.equals(...)` work), so it offers the related model's fields, not conditions. Traversal only _starts_ from a forward FK; a many-to-many is traversable as a later hop (`WidgetTag.widget.tags.name`), but `Widget.tags` and reverse accessors are not entry points — use `filter(tags__name=...)` there.
 - Encrypted fields can't be looked up at all: `get_or_create(secret=...)` raises — put the value in `defaults=`.
 - Use `select_related()` for FK access in loops, `prefetch_related()` for reverse/M2N