ferro-orm 0.7.0__tar.gz → 0.9.0__tar.gz

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/.gitignore

@@ -242,6 +242,7 @@ __marimo__/
 ferro_test.db
 .cursorrules
 .cursor
+.context/
 playground.ipynb
 IMPLEMENTATION.md
 Cargo.lock

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/CHANGELOG.md

@@ -1,6 +1,34 @@
 # CHANGELOG
 
 
+## v0.9.0 (2026-05-09)
+
+### Chores
+
+- Gitignore .context and untrack committed artifacts
+  ([#49](https://github.com/syn54x/ferro-orm/pull/49),
+  [`cac6330`](https://github.com/syn54x/ferro-orm/commit/cac63304bbcf6bb3fad22037c33e6e60dcb8946e))
+
+### Features
+
+- Add get_or_none method
+  ([`0c81e9f`](https://github.com/syn54x/ferro-orm/commit/0c81e9f414074c9a3631eb94f3a8077d16671e41))
+
+### Testing
+
+- Add tests for explicit shadow fields
+  ([`78a3471`](https://github.com/syn54x/ferro-orm/commit/78a3471d55afec3b9b7da9f44e497ec521f7d1c0))
+
+
+## v0.8.0 (2026-05-09)
+
+### Features
+
+- **query**: Typed query predicates via col() and lambda
+  ([#48](https://github.com/syn54x/ferro-orm/pull/48),
+  [`e34e3ca`](https://github.com/syn54x/ferro-orm/commit/e34e3ca43adfc851d757d8232d5736fb453db55e))
+
+
 ## v0.7.0 (2026-05-08)
 
 ### Features

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/Cargo.lock

@@ -294,7 +294,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.7.0"
+version = "0.9.0"
 dependencies = [
  "dashmap",
  "once_cell",

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ferro"
-version = "0.7.0"
+version = "0.9.0"
 edition = "2024"
 readme = "README.md"
 

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.7.0
+Version: 0.9.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: alembic>=1.18.1 ; extra == 'alembic'
 Requires-Dist: sqlalchemy>=2.0.46 ; extra == 'alembic'

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/docs/TEST_RESULTS.md

@@ -36,7 +36,7 @@ All field types and constraints work as documented:
 All documented CRUD operations work correctly:
 
 - `Model.create()` ✅
-- `Model.get()` ✅
+- `Model.get()` / `Model.get_or_none()` ✅
 - `Model.all()` ✅
 - `instance.save()` ✅
 - `instance.delete()` ✅

ferro_orm-0.9.0/docs/api/exceptions.md

@@ -0,0 +1,15 @@
+# Exceptions
+
+Public exception types raised by Ferro’s ORM layer.
+
+::: ferro.exceptions.ModelDoesNotExist
+    options:
+      show_source: false
+      heading_level: 2
+      show_root_heading: true
+
+## See Also
+
+- [Queries](../guide/queries.md) — `Model.get` vs `Model.get_or_none`
+- [Model API](model.md)
+- [Mutations](../guide/mutations.md) — error handling patterns

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/docs/api/model.md

@@ -8,6 +8,7 @@ Complete reference for the `Model` base class and related methods.
         - create
         - bulk_create
         - get
+        - get_or_none
         - where
         - select
         - all
@@ -25,5 +26,6 @@ Complete reference for the `Model` base class and related methods.
 ## See Also
 
 - [Models & Fields Guide](../guide/models-and-fields.md)
-- [Queries Guide](../guide/queries.md)
+- [Queries Guide](../guide/queries.md) — fetch by primary key (`get` / `get_or_none`)
+- [Exceptions](exceptions.md) — `ModelDoesNotExist`
 - [Mutations Guide](../guide/mutations.md)

ferro_orm-0.9.0/docs/api/query.md

@@ -0,0 +1,97 @@
+# Query API
+
+Complete reference for the Query Builder API.
+
+## `Query`
+
+`Query.where` accepts either a `QueryNode` (the operator and `col()` paths) or a lambda predicate of shape `Callable[[QueryProxy[TModel]], QueryNode]`. See [Typed Query Predicates](../concepts/query-typing.md) for a full treatment of the three predicate styles.
+
+::: ferro.query.Query
+    options:
+      members:
+        - where
+        - order_by
+        - limit
+        - offset
+        - all
+        - first
+        - count
+        - exists
+        - update
+        - delete
+      show_source: false
+      heading_level: 3
+
+## `Relation`
+
+`Relation` is the lazy collection-relationship subclass of `Query` returned by `BackRef` and `ManyToMany` fields. It accepts the same three predicate styles on `where`.
+
+::: ferro.query.Relation
+    options:
+      members:
+        - where
+        - order_by
+        - limit
+        - offset
+        - all
+        - first
+        - add
+        - remove
+        - clear
+      show_source: false
+      heading_level: 3
+
+## `col`
+
+Runtime-identity wrapper that statically narrows a model class attribute back to `FieldProxy[T]`. Use it when a single attribute on an existing chain trips your type checker; for new code prefer the lambda predicate style.
+
+::: ferro.query.col
+    options:
+      show_source: false
+      heading_level: 3
+
+## `FieldProxy`
+
+The typed proxy installed by Ferro's metaclass on every model class field. Generic over the column's Python type; operator overloads accept `T | FieldProxy[T]` and return `QueryNode`.
+
+::: ferro.query.FieldProxy
+    options:
+      members:
+        - in_
+        - like
+      show_source: false
+      heading_level: 3
+
+## `QueryProxy`
+
+The attribute proxy passed to lambda predicates. Each attribute access returns a fresh `FieldProxy` for the accessed name.
+
+::: ferro.query.QueryProxy
+    options:
+      show_source: false
+      heading_level: 3
+
+## `QueryNode`
+
+The serializable AST node produced by every predicate style. You normally do not construct these directly.
+
+::: ferro.query.QueryNode
+    options:
+      members:
+        - to_dict
+      show_source: false
+      heading_level: 3
+
+## `Predicate`
+
+Type alias for lambda predicates accepted by `Query.where`, `Relation.where`, and `Model.where`.
+
+```python
+Predicate[TModel] = Callable[[QueryProxy[TModel]], QueryNode]
+```
+
+## See Also
+
+- [Queries Guide](../guide/queries.md)
+- [Typed Query Predicates](../concepts/query-typing.md)
+- [How-To: Pagination](../howto/pagination.md)

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/docs/api/utilities.md

@@ -57,14 +57,17 @@ from ferro import evict_instance
 # Evict user with ID=1
 evict_instance("User", 1)
 
-# Next fetch will hit database
+# Next fetch will hit database (raises ModelDoesNotExist if row was removed)
 user = await User.get(1)
 ```
 
+If the row may no longer exist, use `User.get_or_none(1)` or handle [`ModelDoesNotExist`](exceptions.md).
+
 See [Identity Map Concept](../concepts/identity-map.md) for when and why to evict instances.
 
 ## See Also
 
 - [Database Setup Guide](../guide/database.md) - Connection configuration
 - [Identity Map Concept](../concepts/identity-map.md) - Instance caching details
+- [Exceptions](exceptions.md) - `ModelDoesNotExist` and related types
 - [Schema Management](../guide/migrations.md) - Production migrations

ferro_orm-0.9.0/docs/brainstorms/2026-05-08-typed-query-predicates-requirements.md

@@ -0,0 +1,95 @@
+---
+date: 2026-05-08
+topic: typed-query-predicates
+---
+
+# Typed Query Predicates
+
+## Summary
+
+Add two opt-in query-predicate styles to Ferro — a `col()` wrapper and a lambda predicate API — so that `Model.field` comparisons type-check cleanly under Pyright and `ty` without changing user model annotations or breaking the current operator API. A concept doc covers when to reach for each.
+
+---
+
+## Problem Frame
+
+Ferro models are Pydantic models, so user fields carry plain-type annotations like `archived: bool` and `transcript_id: int`. At runtime the metaclass replaces each class attribute with a `FieldProxy` whose operator overloads return `QueryNode`, so `User.archived == False` builds a query predicate that `Query.where()` accepts.
+
+Static type checkers don't see that runtime swap. Pyright and `ty` resolve `User.archived` from the source annotation as `bool`, so `User.archived == False` is interpreted as `bool.__eq__(bool)` and returns `bool`. `Query.where()` then complains that it expected a `QueryNode`. Users hitting this on every typed predicate currently silence each line with a `# type: ignore` pragma.
+
+Other Python ORMs work around this by changing what users annotate (SQLAlchemy 2.x uses `Mapped[T]`), changing the API away from class-attribute predicates (Django and Tortoise use kwargs), or shipping a mypy plugin. None of those fit Ferro: `Mapped[T]`-style breaks the "user types directly" stance and adds Pydantic interop work, and a mypy plugin doesn't help Pyright or `ty` users — Pyright has no public plugin API.
+
+---
+
+## Requirements
+
+**`col()` wrapper**
+
+- R1. Ferro exposes a `col()` function whose static signature is `(value: T) -> FieldProxy[T]`. At runtime it is identity, with a guard that raises `TypeError` if the input is not a `FieldProxy`.
+- R2. `col(Model.field) == value` (and the other comparison operators) produces a `QueryNode` that `Query.where()` accepts in mypy, Pyright, basedpyright, and `ty` without ignore pragmas.
+- R3. `FieldProxy` becomes generic over its column type (`FieldProxy[T]`), with operator overloads typed to accept `T | FieldProxy[T]` and return `QueryNode`. Runtime behavior is unchanged; users do not write the generic parameter directly.
+
+**Lambda predicate API**
+
+- R4. `Query.where()` accepts a callable that takes a typed query proxy and returns a `QueryNode`. The proxy's static type is parameterized on the model type; attribute access on the proxy is statically typed as `FieldProxy[Any]`.
+- R5. At runtime, when `where()` receives a callable that is not a `QueryNode`, it constructs a per-call proxy whose `__getattr__` returns `FieldProxy(name)`, invokes the callable with the proxy, and appends the returned node to the query.
+- R6. Lambda predicates support compound expressions via the existing `&` and `|` operators on `QueryNode`.
+
+**Backward compatibility**
+
+- R7. The existing `Model.field == value` operator path continues to work unchanged at runtime. No existing test, query, or user model needs modification.
+- R8. Adding the lambda overload does not change the runtime semantics of any current `where()` call. Dispatch checks `isinstance(QueryNode)` first, then `callable()`.
+- R9. No changes to the model metaclass, Pydantic schema generation, JSON schema bridge, or the Rust hydration paths.
+
+**Documentation**
+
+- R10. A concept document under `docs/concepts/` covers the three predicate styles (operator, `col()`, lambda), shows them combined in one query chain, and recommends when to reach for each. Lambda is positioned as the recommended idiom for new code; `col()` is the lower-ceremony fallback for users who want to keep the operator shape.
+
+---
+
+## Acceptance Examples
+
+- AE1. **Covers R1, R2.** Given `archived: bool` declared on a model and a strict type checker run, when the user writes `.where(col(T.archived) == False)`, the line type-checks without ignore pragmas in mypy, Pyright, basedpyright, and `ty`.
+- AE2. **Covers R7, R8.** Given an existing test that uses `.where(T.field == value)`, when the new code lands, the test continues to pass with no modification.
+- AE3. **Covers R4, R5, R6.** Given the predicate `lambda t: (t.archived == False) & (t.org_id == 42)`, when passed to `.where(...)`, the runtime invokes the lambda with a model proxy, appends a single compound `QueryNode` to the query, and produces the same SQL as the equivalent operator-form predicate.
+- AE4. **Covers R1.** Given a value that is not a `FieldProxy` (e.g., a raw string), when passed to `col()` at runtime, `col()` raises `TypeError` whose message names the actual argument type.
+- AE5. **Covers R2, R7, R4.** Given a single `Query` chain that combines `.where(T.a == 1)`, `.where(col(T.b) == 2)`, and `.where(lambda t: t.c == 3)` in any order, when executed, the resulting SQL contains all three predicates and the result hydrates correctly.
+
+---
+
+## Success Criteria
+
+- Ferro users hitting the original `ty` complaint can fix it by wrapping the attribute reference with `col(...)` — a single small change per call site, with no model edits and no plugin installation.
+- New Ferro code in user projects can adopt the lambda predicate style and have those predicates type-check cleanly in every supported checker.
+- Downstream agents (planning, future API work) and human reviewers have a clear definition of which `where()` shapes are supported and which were deliberately deferred.
+- Backward-compat tests in `tests/` pass without modification, demonstrating the operator-path runtime is unchanged.
+
+---
+
+## Scope Boundaries
+
+- `Mapped[T]` / descriptor-based field annotations are deferred indefinitely; they conflict with Ferro's "user types directly" stance and would require Pydantic interop work disproportionate to the typing win.
+- A mypy plugin for Ferro is out of scope; Pyright and `ty` are the target checkers and neither has an equivalent plugin API.
+- Per-field type precision in the lambda proxy via `@dataclass_transform` is deferred; this work uses `FieldProxy[Any]` for proxy attribute types.
+- A kwargs-style filter API (e.g., `.where_kw(field=value)`) is deferred until user demand surfaces.
+- A `t""` template-string predicate API is deferred until Ferro raises its minimum Python to 3.14.
+- Per-model code generation, distributed `.pyi` stubs for user models, and `if TYPE_CHECKING` shadow declarations as a documented pattern are not adopted.
+- No changes to the metaclass, Pydantic interop, JSON schema generation, or the Rust FFI bridge.
+
+---
+
+## Key Decisions
+
+- **Single PR over staged PRs.** The three pieces (`col()`, lambda API, doc) ship together on `feat/col-and-lambda-queries`. They are small, low-risk, and meaningfully more useful as a unit than incrementally.
+- **`col()` is identity at runtime, not a constructor.** `Model.field` is already a `FieldProxy` thanks to the metaclass, so `col()` is a typed pass-through, not a wrapping layer. This keeps the runtime cost zero and avoids a parallel class hierarchy.
+- **Lambda predicate proxy is per-call, not stored on the model.** Avoids touching the metaclass and keeps the lambda path opt-in. Users who never call `where(lambda ...)` never construct the proxy.
+- **`FieldProxy[Any]` over per-field precision for the lambda proxy.** Per-field types would require `@dataclass_transform` plumbing and tighter user-facing typing semantics. Deferred to a follow-up if real demand materializes.
+- **Lambda is the recommended idiom; `col()` is the fallback.** Lambda has lower per-call ceremony for chains with several predicates; `col()` is one wrapper per reference but doesn't ask users to rewrite their query shape.
+
+---
+
+## Dependencies / Assumptions
+
+- The current metaclass behavior of replacing each `model_fields` attribute with a `FieldProxy` is a stable invariant the runtime no-op `col()` relies on.
+- `QueryNode` does not currently expose `__call__`; the runtime dispatch rule "isinstance(QueryNode) first, then callable()" depends on this remaining true.
+- Generic parameters on `FieldProxy[T]` are runtime-erased (standard Python typing semantics); existing `isinstance(x, FieldProxy)` checks remain valid.

ferro_orm-0.9.0/docs/changelog.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to Ferro ORM will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Breaking
+
+- `Model.get` and `Model.using(...).get` now return the concrete model type and raise `ModelDoesNotExist` when no row exists (previously they returned `T | None`). Use the new `get_or_none` for the old optional behavior.
+
+### Added
+
+- `Model.get_or_none` and `Model.using(...).get_or_none` for primary-key lookup without raising.
+- `ModelDoesNotExist` (`LookupError` subclass with `.model` and `.pk`), exported from `ferro`. Documented under [Exceptions](api/exceptions.md).
+- Typed query predicates: `col()` wrapper and lambda predicate API on `Query.where`, `Relation.where`, and `Model.where` for static-typing-clean predicates without model annotation changes ([#48](https://github.com/syn54x/ferro-orm/pull/48)). See [Typed Query Predicates](concepts/query-typing.md).
+- `FieldProxy` is now generic (`FieldProxy[T]`); operator overloads are typed `T | FieldProxy[T] -> QueryNode`, `.like()` is gated to `FieldProxy[str]`.
+- New public symbols re-exported from `ferro.query`: `col`, `QueryProxy`, `Predicate`.
+- Comprehensive documentation restructure
+- Tutorial for new users
+- How-to guides for common patterns
+- Concept pages explaining architecture
+
+## Release History
+
+For the complete release history, see [GitHub Releases](https://github.com/syn54x/ferro-orm/releases).
+
+### Version Format
+
+- **Major** (X.0.0): Breaking changes
+- **Minor** (0.X.0): New features, backwards compatible
+- **Patch** (0.0.X): Bug fixes
+
+### Upgrade Guide
+
+When upgrading between major versions, see the migration guide in the release notes.
+
+## Reporting Issues
+
+Found a bug? [Report it on GitHub](https://github.com/syn54x/ferro-orm/issues).
+
+## Contributing
+
+See [Contributing Guide](contributing.md) for how to contribute to Ferro.

ferro_orm-0.9.0/docs/concepts/query-typing.md

@@ -0,0 +1,105 @@
+# Typed Query Predicates
+
+Ferro's query DSL accepts three predicate styles on `Model.where`, `Query.where`, and `Relation.where`. They are interchangeable, run on the same code path, and can be mixed freely in the same chain. Pick the one that reads best for the call site you're writing.
+
+## Why this exists
+
+Ferro's metaclass replaces every model field with a `FieldProxy` at class-creation time, so `User.archived` is a `FieldProxy` at runtime — and `User.archived == False` builds a `QueryNode`, not a Python `bool`. Static type checkers (Pyright, `ty`, mypy, basedpyright) only see your Pydantic annotations, though, so they read `User.archived` as a `bool` and reject the same expression they would happily run.
+
+The two new predicate styles below give you the runtime ergonomics back without forcing a model-annotation rewrite, a type-checker plugin, or any change to the existing operator path.
+
+## The three styles
+
+### 1. Operator (the original)
+
+```python
+rows = await User.where(User.id == 1).all()
+rows = await User.where(User.email.like("%@example.com")).all()
+```
+
+Works at runtime, always has, always will. Type checkers may flag boolean-column comparisons (`User.archived == False` resolves statically to `bool`) — when that bites, reach for one of the styles below.
+
+### 2. `col()` wrapper
+
+```python
+from ferro.query import col
+
+rows = await User.where(col(User.archived) == False).all()
+```
+
+`col()` is a runtime-identity helper that statically narrows its argument back to `FieldProxy[T]`. It does no work at runtime beyond an `isinstance` guard (and raises `TypeError` if you accidentally hand it a literal). Reach for it when a single attribute trips your type checker and you don't want to restructure the call site.
+
+### 3. Lambda predicate
+
+```python
+rows = await User.where(lambda t: t.archived == False).all()
+rows = await User.where(
+    lambda t: (t.role == "admin") & (t.active == True)
+).all()
+```
+
+The lambda receives a `QueryProxy` whose attribute access yields a fresh `FieldProxy` for each name — so `t.archived == False` is a `QueryNode` from the type checker's point of view as well as at runtime. This is the recommended style for new code: it keeps the call site free of `# type: ignore` even when comparing booleans, integers, or any other value type.
+
+The proxy attribute type is currently `FieldProxy[Any]`, which is a deliberate scope decision (see [Scope boundaries](#scope-boundaries) below). Pyright still resolves the predicate's *return* type as `QueryNode` correctly.
+
+## When to use which
+
+| Style | Use when |
+|------|----------|
+| Operator | Existing code that already type-checks; quick filters where the value type isn't `bool`. |
+| `col()` | One attribute on an existing chain trips your type checker and you want minimal diff. |
+| Lambda | New code, especially boolean comparisons or compound predicates; preferred idiom. |
+
+All three are equally efficient at runtime — every one of them produces a `QueryNode` and appends it to `where_clause`.
+
+## Combining styles
+
+You can mix all three on a single chain. They compose because they all funnel through the same dispatch in `Query.where`:
+
+```python
+rows = await (
+    User.where(User.id == 1)                    # operator
+    .where(col(User.archived) == False)         # col()
+    .where(lambda t: t.role == "admin")         # lambda
+    .all()
+)
+```
+
+`Relation.where` (used on `BackRef` collections) accepts the same three shapes:
+
+```python
+published = await author.posts.where(lambda t: t.published == True).all()
+```
+
+## What this does not change
+
+- Your model annotations. `archived: bool = False` stays exactly as it is.
+- The metaclass's `FieldProxy` injection. Class attribute access is unchanged.
+- Pydantic schema generation, JSON schema output, or model validation.
+- The Rust FFI bridge or how `QueryNode`s are serialized for the engine.
+- The operator-path runtime. Existing `Model.field == value` calls take the same code path they always have.
+
+## Scope boundaries
+
+The current implementation deliberately stops short of:
+
+- **Per-field types on the lambda proxy.** `t.archived` resolves to `FieldProxy[Any]`, not `FieldProxy[bool]`. Wiring per-field types through the proxy needs `@dataclass_transform` plumbing on the metaclass; that's a future PR.
+- **A type-checker plugin.** Ferro stays plugin-free.
+- **A kwargs-style or template-string predicate API.** Both have been considered; neither shipped here.
+
+If `t.archived` resolving as `FieldProxy[Any]` ever bites you statically, drop back to `col(Model.archived) == ...` for that one comparison — that's exactly the role `col()` plays.
+
+## Reference
+
+- `ferro.query.col` — runtime-identity wrapper, raises `TypeError` for non-`FieldProxy` input.
+- `ferro.query.QueryProxy` — attribute proxy passed to lambda predicates.
+- `ferro.query.Predicate` — `Callable[[QueryProxy[TModel]], QueryNode]`, the type of any lambda predicate.
+- `ferro.query.FieldProxy` — generic over the column's Python type (`FieldProxy[T]`).
+
+See the [Query API reference](../api/query.md) for full signatures.
+
+## See Also
+
+- [Queries Guide](../guide/queries.md)
+- [Type Safety](type-safety.md)
+- [Query API](../api/query.md)

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/docs/concepts/type-safety.md

@@ -57,16 +57,19 @@ class User(Model):
     username: str
     age: int
 
-# Type checker knows return type
+# Fetch by PK: definite model instance (raises ModelDoesNotExist if missing)
 user: User = await User.get(1)
 
+# Optional PK lookup
+maybe_user: User | None = await User.get_or_none(999)
+
 # Autocomplete works
 user.username  # ✓ Known attribute
 user.invalid   # ✗ Type error
 
 # Query results are typed
 users: list[User] = await User.all()
-first: User | None = await User.first()
+first: User | None = await User.where(User.username == "alice").first()
 ```
 
 ## IDE Autocomplete
@@ -85,6 +88,27 @@ User.where(
 )
 ```
 
+## Query Predicates and the Type Checker
+
+Static checkers see your Pydantic annotations, not the `FieldProxy` instances Ferro's metaclass installs at class-creation time. That means `User.archived == False` is statically a `bool` even though it is a `QueryNode` at runtime, and Pyright or `ty` will flag it where `Query.where` expects a `QueryNode`.
+
+Ferro ships three predicate styles to address this without any model-annotation changes or type-checker plugins:
+
+```python
+from ferro.query import col
+
+# Operator (unchanged)
+await User.where(User.id == 1).all()
+
+# col() — runtime identity, statically narrows back to FieldProxy[T]
+await User.where(col(User.archived) == False).all()
+
+# Lambda — receives a QueryProxy whose attributes return FieldProxy
+await User.where(lambda t: t.archived == False).all()
+```
+
+See [Typed Query Predicates](query-typing.md) for the full discussion, including when to reach for each style and how they compose.
+
 ## Field Type Validation
 
 Ferro validates field types match database types:

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/docs/guide/mutations.md

@@ -381,6 +381,23 @@ await User.bulk_create(users)
 !!! note "Exception Types"
     The documentation references exception types like `IntegrityError` and `ValidationError`. These exceptions come from the underlying database driver or Pydantic. Import paths may vary. Catch general `Exception` or check your specific database driver's exceptions.
 
+### Primary key lookup (`Model.get`)
+
+`Model.get(pk)` and `Model.using(...).get(pk)` raise [`ModelDoesNotExist`](../api/exceptions.md) when no row exists. Import it from `ferro`. For “maybe there is a row” flows (for example verifying a delete), use `get_or_none` instead of catching the exception.
+
+```python
+from ferro import ModelDoesNotExist
+
+try:
+    user = await User.get(user_id)
+except ModelDoesNotExist:
+    # e.model, e.pk
+    ...
+
+# Or, when None is the natural result:
+user = await User.get_or_none(user_id)
+```
+
 ### Unique Constraint Violations
 
 ```python

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/docs/guide/queries.md

@@ -2,6 +2,29 @@
 
 Ferro provides a fluent, type-safe API for constructing and executing database queries. All queries are constructed in Python and executed by the high-performance Rust engine.
 
+## Fetch by primary key
+
+`Model.get(pk)` loads exactly one row by primary key and returns **your model type** (not `YourModel | None`). If no row exists, Ferro raises [`ModelDoesNotExist`](../api/exceptions.md), a subclass of `LookupError` with `.model` and `.pk` set—useful for HTTP 404s or structured logging.
+
+When a missing row is a normal outcome, use `Model.get_or_none(pk)`, which returns `YourModel | None` and never raises for “not found”. The same pair exists on [`Model.using("name")`](../howto/multiple-databases.md) for named connections.
+
+```python
+from ferro import ModelDoesNotExist
+
+user = await User.get(42)
+
+try:
+    user = await User.get(client_supplied_id)
+except ModelDoesNotExist:
+    ...  # e.g. return 404 from your HTTP layer
+
+draft = await User.get_or_none(999)  # None if no such row
+
+replica_view = await User.using("replica").get_or_none(1)
+```
+
+Lazy forward relations (e.g. `await post.author`) use optional fetch internally so a broken or missing FK still resolves to `None` instead of raising.
+
 ## Basic Filtering
 
 Use standard Python comparison operators on model fields to create filter conditions:
@@ -31,6 +54,32 @@ alice_users = await User.where(User.name.like("Alice%")).all()
 | `.like()` | `LIKE` | `User.email.like("%@example.com")` |
 | `.in_()` | `IN` | `User.status.in_(["active", "pending"])` |
 
+## Predicate Styles
+
+`where()` accepts three interchangeable predicate styles. They share one runtime path and one dispatcher, and you can mix them on a single chain.
+
+```python
+from ferro.query import col
+
+# 1. Operator (the original)
+await User.where(User.id == 1).all()
+
+# 2. col() wrapper — runtime identity, statically narrows to FieldProxy[T]
+await User.where(col(User.archived) == False).all()
+
+# 3. Lambda predicate — receives a QueryProxy with FieldProxy attributes
+await User.where(lambda t: t.archived == False).all()
+```
+
+The operator style works at runtime for every column type, but static type checkers (Pyright, `ty`) flag boolean and other value-type comparisons because they see your Pydantic annotations rather than the runtime `FieldProxy`. Reach for `col()` when one attribute trips the checker, or write new code with the lambda style to sidestep the issue entirely.
+
+!!! tip "When to use which"
+    - **Operator** — existing code that already type-checks; quick filters where the column type isn't `bool`.
+    - **`col()`** — one attribute on an existing chain trips your type checker and you want minimal diff.
+    - **Lambda** — new code, especially boolean comparisons or compound predicates. Recommended idiom going forward.
+
+See [Typed Query Predicates](../concepts/query-typing.md) for the full treatment, including combined-style chains and the deliberate scope boundaries.
+
 ## Logical Operators
 
 Combine conditions with `&` (AND) and `|` (OR). **Always use parentheses** around each condition:
@@ -51,6 +100,14 @@ query = User.where(
 inactive_users = await User.where(User.is_active != True).all()
 ```
 
+The same compound expressions work inside lambda predicates — useful when you want the whole expression to type-check without `col()`:
+
+```python
+admins = await User.where(
+    lambda t: (t.role == "admin") & (t.active == True)
+).all()
+```
+
 ## Chaining
 
 Methods can be chained to build complex queries incrementally:
@@ -201,8 +258,9 @@ author = await User.where(User.username == "alice").first()
 # Get all posts by author
 author_posts = await author.posts.all()
 
-# Filter reverse relation
+# Filter reverse relation (any of the three predicate styles works)
 published_posts = await author.posts.where(Post.published == True).all()
+published_posts = await author.posts.where(lambda t: t.published == True).all()
 
 # Count reverse relation
 post_count = await author.posts.count()

{ferro_orm-0.7.0 → ferro_orm-0.9.0}/docs/howto/multiple-databases.md

@@ -33,6 +33,10 @@ users = await User.all()
 # Specific database
 replica_users = await User.using("replica").all()
 analytics_data = await Metric.using("analytics").all()
+
+# Primary-key fetch on a named connection (same semantics as Model.get / get_or_none)
+user = await User.using("replica").get(1)  # raises ModelDoesNotExist if missing
+maybe = await User.using("replica").get_or_none(unknown_id)
 ```
 
 ## Transactions