ferro-orm 0.10.4__tar.gz → 0.11.0__tar.gz

{ferro_orm-0.10.4 → ferro_orm-0.11.0}/AGENTS.md

@@ -32,7 +32,7 @@ For a single model, every emitter must agree on:
    includes the canonical `db_type` vocabulary (`text`, `varchar(N)`,
    `smallint`, `int`, `bigint`, `uuid`, `timestamp`, `timestamptz`, `date`,
    `time`) — duplicated in `_db_type_to_sa_type` (Python) and
-   `apply_db_type_to_column_def` (Rust), pinned by
+   `db_type_token_to_canonical` (Rust), pinned by
    `tests/test_db_type_cross_emitter_parity.py`.
 4. **Index names** — `idx_<table>_<col>` for single-column indexes,
    `idx_<table>_<col1>_<col2>...` for composite indexes.
@@ -147,3 +147,46 @@ search this directory before starting work.
 `docs/solutions/issues/` — debugging stories and known footguns.
 
 See `docs/solutions/README.md` for the frontmatter conventions.
+
+---
+
+## I-6: No AI attribution in commits or PRs
+
+Never sign commits or pull requests with AI/agent attribution. No
+`Co-Authored-By: Claude ...` trailers, no "Generated with Claude Code"
+footers, no robot emoji bylines — in commit messages, PR titles, or PR
+bodies. This applies even when an agent's default behavior is to add them:
+this rule overrides those defaults for this repository.
+
+---
+
+## I-7: No stop-gap solutions
+
+Every feature, bug fix, and improvement must be designed as the best,
+well-thought-out solution for the project with the library's future in
+mind — as if time and money were no object. No stop-gaps, hacks,
+quick-fixes, or otherwise lesser solves.
+
+What this means in practice:
+
+- **Prefer first-class, reusable primitives over local patches.** If a fix
+  only works for the immediate symptom while leaving the underlying
+  capability gap in place, build the capability instead. (Precedent:
+  `EngineHandle::refresh_pool()` was built as an engine-level schema-epoch
+  primitive rather than a migration-local statement-cache flush.)
+- **Fail loudly over degrading silently.** "Skip with a warning and
+  continue", "best effort", and "documented residual risk" are not
+  acceptable resolutions for correctness gaps. Either the operation
+  succeeds completely or it aborts with a clear, actionable error.
+- **Treat certain phrases as redesign triggers.** If a plan, comment, or PR
+  description contains "best-effort", "partial mitigation", "documented
+  residual risk", "good enough for now", "temporary workaround", or
+  "fallback if X turns out to be hard" — that part of the design is not
+  finished. Redesign it before presenting or implementing it.
+- **Scoped-down is fine; hollowed-out is not.** Deliberately excluding
+  something from scope (with the boundary stated and a real path for the
+  excluded case, e.g. "renames are Alembic territory") is good design.
+  Shipping a half-working version of something that is *in* scope is not.
+
+This rule binds human contributors and AI agents equally, and overrides any
+agent default that biases toward minimal or expedient changes.

{ferro_orm-0.10.4 → ferro_orm-0.11.0}/CHANGELOG.md

@@ -1,6 +1,35 @@
 # CHANGELOG
 
 
+## v0.11.0 (2026-06-11)
+
+### Chores
+
+- Solution quality requirements
+  ([`c62770b`](https://github.com/syn54x/ferro-orm/commit/c62770b6d3073e8d596c30f29895bccddc2a4d7f))
+
+### Documentation
+
+- Compound SQLite hydration learnings (#56, #58)
+  ([#60](https://github.com/syn54x/ferro-orm/pull/60),
+  [`b609e72`](https://github.com/syn54x/ferro-orm/commit/b609e7274e1886cc5d8564c7adb52fc3c79ffc8d))
+
+### Features
+
+- Extend auto_migrate with column updates and destructive drops
+  ([#69](https://github.com/syn54x/ferro-orm/pull/69),
+  [`a76cb0f`](https://github.com/syn54x/ferro-orm/commit/a76cb0f2451dab79303353f2c77d74ca3e1ad4a5))
+
+
+## v0.10.5 (2026-05-25)
+
+### Bug Fixes
+
+- Coerce Annotated StrEnum fields on cold hydration
+  ([#66](https://github.com/syn54x/ferro-orm/pull/66),
+  [`c17c13b`](https://github.com/syn54x/ferro-orm/commit/c17c13b56e100028a42fa431ca59c9729a22daeb))
+
+
 ## v0.10.4 (2026-05-24)
 
 ### Bug Fixes

{ferro_orm-0.10.4 → ferro_orm-0.11.0}/Cargo.lock

@@ -43,9 +43,9 @@ checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
 [[package]]
 name = "bitflags"
-version = "2.11.1"
+version = "2.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
 dependencies = [
  "serde_core",
 ]
@@ -79,9 +79,9 @@ checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "cc"
-version = "1.2.62"
+version = "1.2.63"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a1dce859f0832a7d088c4f1119888ab94ef4b5d6795d1ce05afb7fe159d79f98"
+checksum = "556e016178bb5662a08681bbe0f00f8e17631781a4dfc8c45e466e4b185ec27f"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -230,9 +230,9 @@ dependencies = [
 
 [[package]]
 name = "displaydoc"
-version = "0.2.5"
+version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "97369cbbc041bc366949bc74d34658d6cda5621039731c6310521892a3a20ae0"
+checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -294,7 +294,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.10.4"
+version = "0.11.0"
 dependencies = [
  "dashmap",
  "once_cell",
@@ -711,13 +711,12 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "js-sys"
-version = "0.3.99"
+version = "0.3.100"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "142bc4740e452c1e57ade0cbc129f139c9093e354346f0872ef985f4f5cf5f11"
+checksum = "f2025f20d7a4fa7785846e7b63d10a76d3f1cee98ee5cb79ea59703f95e42162"
 dependencies = [
  "cfg-if",
  "futures-util",
- "once_cell",
  "wasm-bindgen",
 ]
 
@@ -750,14 +749,14 @@ checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
 
 [[package]]
 name = "libredox"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e02f3bb43d335493c96bf3fd3a321600bf6bd07ed34bc64118e9293bdffea46c"
+checksum = "f02ab6bace2054fb888a3c16f990117b579d14a3088e472d63c6011fa185c9d3"
 dependencies = [
  "bitflags",
  "libc",
  "plain",
- "redox_syscall 0.7.5",
+ "redox_syscall 0.8.1",
 ]
 
 [[package]]
@@ -788,9 +787,9 @@ dependencies = [
 
 [[package]]
 name = "log"
-version = "0.4.29"
+version = "0.4.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
+checksum = "953f07c43838f8e6f9758cab68bf5bed85465e7587ebe0b823f1bcd81978ad3a"
 
 [[package]]
 name = "md-5"
@@ -804,9 +803,9 @@ dependencies = [
 
 [[package]]
 name = "memchr"
-version = "2.8.0"
+version = "2.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+checksum = "6b947ae49db0d222b1dbc6b113ce7248a3fc3a6ca21b696717bfc000ba4484d8"
 
 [[package]]
 name = "memoffset"
@@ -819,9 +818,9 @@ dependencies = [
 
 [[package]]
 name = "mio"
-version = "1.2.0"
+version = "1.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "50b7e5b27aa02a74bac8c3f23f448f8d87ff11f92d3aac1a6ed369ee08cc56c1"
+checksum = "02bd0af71c67b473010cbbc60715ee815645a4dc942899111f494b4b737d6fda"
 dependencies = [
  "libc",
  "wasi",
@@ -1136,9 +1135,9 @@ dependencies = [
 
 [[package]]
 name = "redox_syscall"
-version = "0.7.5"
+version = "0.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4666a1a60d8412eab19d94f6d13dcc9cea0a5ef4fdf6a5db306537413c661b1b"
+checksum = "5b44b894f2a6e36457d665d1e08c3866add6ed5e70050c1b4ba8a8ddedb02ce7"
 dependencies = [
  "bitflags",
 ]
@@ -1339,9 +1338,9 @@ dependencies = [
 
 [[package]]
 name = "shlex"
-version = "1.3.0"
+version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
 [[package]]
 name = "signal-hook-registry"
@@ -1380,9 +1379,9 @@ dependencies = [
 
 [[package]]
 name = "socket2"
-version = "0.6.3"
+version = "0.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3a766e1110788c36f4fa1c2b71b387a7815aa65f88ce0229841826633d93723e"
+checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51"
 dependencies = [
  "libc",
  "windows-sys 0.61.2",
@@ -1770,9 +1769,9 @@ dependencies = [
 
 [[package]]
 name = "typenum"
-version = "1.20.0"
+version = "1.20.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "40ce102ab67701b8526c123c1bab5cbe42d7040ccfd0f64af1a385808d2f43de"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
 
 [[package]]
 name = "unicode-bidi"
@@ -1839,9 +1838,9 @@ checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
 [[package]]
 name = "uuid"
-version = "1.23.1"
+version = "1.23.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ddd74a9687298c6858e9b88ec8935ec45d22e8fd5e6394fa1bd4e99a87789c76"
+checksum = "144d6b123cef80b301b8f72a9e2ca4370ddec21950d0a103dd22c437006d2db7"
 dependencies = [
  "getrandom 0.4.2",
  "js-sys",
@@ -1892,9 +1891,9 @@ checksum = "b8dad83b4f25e74f184f64c43b150b91efe7647395b42289f38e50566d82855b"
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.122"
+version = "0.2.123"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3ed04576f974d2b2fba0f38c51dbc5518011e38c36bf1143164be765528fd409"
+checksum = "a254a4b10c19a76f09a27640e7ffbf9bc30bf67e16a3bf28aaefa4920fe81563"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -1905,9 +1904,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.122"
+version = "0.2.123"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "916151b09da36bd82f6615cbf3a419e2f0ba23a03c6160e8e92eb6bd4aa1dec6"
+checksum = "24a40fc75b0ec6f3746ceb10d36f53a93dcd68a93b11b6445983945d79eba0dc"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -1915,9 +1914,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.122"
+version = "0.2.123"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "299047362ccbfce148b67ab7e73349f77748e00c8296f9542adfad2ad82c5c5e"
+checksum = "908f34bd9b9ce3d4caf07b72dfab63d61504d156856c6bd3cd87fa350cf3985b"
 dependencies = [
  "bumpalo",
  "proc-macro2",
@@ -1928,9 +1927,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.122"
+version = "0.2.123"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a929b2c61f11ba3e9bc35b50c1f25cb38e0e892c0c231ae2b8cf78d5dad4437"
+checksum = "7acbf7616c27b194bbb550bf77ed0c2c3e5b7fd1260a93082b95fb7f47959b92"
 dependencies = [
  "unicode-ident",
 ]
@@ -2253,9 +2252,9 @@ checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
 
 [[package]]
 name = "yoke"
-version = "0.8.2"
+version = "0.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "abe8c5fda708d9ca3df187cae8bfb9ceda00dd96231bed36e445a1a48e66f9ca"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
 dependencies = [
  "stable_deref_trait",
  "yoke-derive",
@@ -2276,18 +2275,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.48"
+version = "0.8.52"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eed437bf9d6692032087e337407a86f04cd8d6a16a37199ed57949d415bd68e9"
+checksum = "ce1022995ff5ff5d841ad7d994facc23098cd40152f2c1d11cd607c6f530653f"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.48"
+version = "0.8.52"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "70e3cd084b1788766f53af483dd21f93881ff30d7320490ec3ef7526d203bad4"
+checksum = "1ae7f38b72ec2a254e2b87ef277cf2cd4fb97cbebf944faa6f33354da0867930"
 dependencies = [
  "proc-macro2",
  "quote",

{ferro_orm-0.10.4 → ferro_orm-0.11.0}/Cargo.toml

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

{ferro_orm-0.10.4 → ferro_orm-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.10.4
+Version: 0.11.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.11.0/docs/brainstorms/2026-05-25-annotated-strenum-cold-hydration-requirements.md

@@ -0,0 +1,112 @@
+---
+date: 2026-05-25
+topic: annotated-strenum-cold-hydration
+issue: https://github.com/syn54x/ferro-orm/issues/65
+---
+
+# Annotated StrEnum Cold Hydration
+
+## Summary
+
+Register enum field types once at model class definition (using the same annotation-unwrapping logic as schema registration), then coerce string values from the database into enum members on every hydration path. This fixes cold fetches for `Annotated[StrEnum, FerroField(db_type="text")]` under PEP 563/649 deferred annotations without duplicating discovery logic in `_fix_types`.
+
+---
+
+## Problem Frame
+
+Ferro hydrates rows through a zero-copy Rust path that populates instance `__dict__` with raw column values. String-valued columns therefore arrive as `str`, not as the declared Python enum. A post-hydration pass (`Model._fix_types`) is responsible for coercing those strings into enum members.
+
+That pass discovers enum fields lazily on first use. Discovery calls `get_type_hints` with the **ferro.models** module namespace, not the user model’s defining module. With `from __future__ import annotations` (common on Python 3.14+), deferred annotation strings never resolve in that namespace; the fallback reads `__annotations__`, which are still strings and do not match `isinstance(hint, type)`. Result: `_enum_fields` stays empty, coercion is skipped, and cold reads return plain `str` even though `__ferro_schema__` already records `enum_type_name` correctly.
+
+`create()` in the same process often still yields enum instances because Pydantic validates on construction. The bug surfaces on **cold** `all()` / `get()` / query results after `reset_engine()` or a fresh connection — exactly when apps rely on `.value`, `match`/`case`, or strict `isinstance` checks.
+
+Equality with the raw string (`instance.mode == "hourly"`) still works; the failure mode is **type fidelity** and enum APIs, not storage or SQL.
+
+---
+
+## Requirements
+
+**Enum registration (canonical, class-definition time)**
+
+- R1. Each concrete `Model` subclass exposes a stable `_enum_fields: dict[str, type[Enum]]` populated during metaclass setup (Phase 3), not on first `_fix_types` call.
+- R2. Registration uses the shared `_enum_subclass_from_annotation` helper already used when building `__ferro_schema__`, so `Annotated[...]`, optional unions, and plain enum annotations are handled identically for schema and hydration.
+- R3. The source of truth for which fields are enums is Pydantic’s resolved `model_fields[<name>].annotation` (with `get_type_hints(cls, include_extras=True)` as fallback only when a field annotation is missing), never `get_type_hints` with ferro-internal `globals()` / `locals()`.
+- R4. `_fix_types` performs **coercion only** against the pre-built `_enum_fields` map; it must not re-scan annotations or mutate discovery state on fetch.
+
+**Hydration behavior**
+
+- R5. After any Rust-backed fetch (`all`, `get`, `fetch_filtered`, query builder `first`/`all`, `ModelConnection.get_or_none`, etc.), every non-null enum column whose stored value is not already an instance of the registered enum class is coerced via `enum_cls(raw_value)` (preserving current tolerant failure behavior for invalid DB values).
+- R6. Cold fetch after `reset_engine()` + reconnect must return enum members, not `str`, for models using `Annotated[StrEnum, FerroField(db_type="text")]` with PEP 563/649 deferred annotations.
+- R7. Behavior for plain `StrEnum` fields (no `Annotated`), native Postgres enum columns, and `IntEnum` with integer storage remains unchanged — no regression in existing round-trip tests.
+
+**Testing**
+
+- R8. Add an integration regression test that defines a model with `from __future__ import annotations`, `Annotated[StrEnum, FerroField(db_type="text")]`, inserts via `create()`, calls `reset_engine()`, reconnects, fetches via `all()` (or `get`), and asserts `isinstance(field, EnumSubclass)` and `.value` access works.
+- R9. Optionally assert `_enum_fields` is non-empty and includes the field name after class creation (unit-level guard against rediscovering the #65 failure mode).
+
+---
+
+## Acceptance Examples
+
+- **AE1 — Cold fetch with deferred annotations**
+  Covers: R5, R6, R8
+  Given `from __future__ import annotations` and `billing_mode: Annotated[Mode, FerroField(db_type="text")]`, when a row is created with `Mode.HOURLY`, then `reset_engine()` and reconnect, then `Row.all()[0]`, then `type(row.billing_mode)` is `Mode` and `row.billing_mode.value == "hourly"`.
+
+- **AE2 — Schema parity unchanged**
+  Covers: R2, R7
+  Given the same model class, `__ferro_schema__["properties"]["billing_mode"]["enum_type_name"]` remains `"mode"` (lowercased class name) before and after the fix.
+
+- **AE3 — Invalid DB value tolerance**
+  Covers: R5
+  Given a text column containing a string that is not a valid enum member, when fetched, the instance field remains a non-enum value (or coercion fails silently as today) without raising during `_fix_types` — no change to defensive behavior unless separately specified.
+
+---
+
+## Success Criteria
+
+- Issue #65 reproduction script exits 0 on main after the fix.
+- New regression test fails on current `main` without the fix and passes with it.
+- No new phantom DDL or cross-emitter drift (hydration-only change).
+- `_enum_fields` discovery logic exists in exactly one conceptual place (metaclass + shared helper), not duplicated in `_fix_types`.
+
+---
+
+## Scope Boundaries
+
+**In scope**
+
+- Python-side enum registration and post-hydration coercion for all existing fetch entry points.
+- Regression test under PEP 563/649 + `Annotated` + `db_type="text"`.
+- Closes GitHub issue #65.
+
+**Out of scope**
+
+- Rust-side enum coercion during dict population (duplicate logic across FFI; defer unless profiling proves Python coercion is a bottleneck).
+- Changing default storage away from native Postgres enums in Alembic (separate product decision; `db_type="text"` on StrEnum remains valid).
+- Pydantic `model_validate` on hydration (violates direct-to-dict / zero-copy invariant I-2).
+- Broader refactors of `_fix_types` for non-enum types (UUID, Decimal, etc.) unless already planned elsewhere.
+
+---
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Where to register enums | Metaclass Phase 3 | Same lifecycle as `ferro_fields` and schema registration; immune to wrong `get_type_hints` namespaces. |
+| Shared helper | Reuse `_enum_subclass_from_annotation` | Schema and hydration must agree on what counts as an enum field (AGENTS.md parity spirit). |
+| `_fix_types` role | Coercion only | Eliminates lazy discovery bug class; cheaper on hot path. |
+| Minimal patch alternative | Repair `_fix_types` discovery only | **Rejected as lesser solve** — fixes #65 but leaves two discovery paths and repeats failure modes for the next annotation shape. |
+
+---
+
+## Dependencies / Assumptions
+
+- Pydantic v2 continues to resolve `model_fields[].annotation` to real enum types even when `__annotations__` on the class remain strings under PEP 563.
+- `reset_engine()` remains a valid way to simulate cold identity-map clears in tests.
+- Issue reporter environment (ferro 0.10.3, Python 3.14+, SQLite) matches current test matrix support.
+
+---
+
+## Outstanding Questions
+
+- None blocking implementation. If PEP 649-only models without `__annotate_func__` resolution in metaclass appear in the wild, confirm `_resolve_deferred_annotations` still leaves `model_fields` authoritative (spot-check in plan phase).

{ferro_orm-0.10.4 → ferro_orm-0.11.0}/docs/coming-soon.md

@@ -410,37 +410,12 @@ Document the exception hierarchy and import paths:
 
 ### Many-to-Many Join Table Creation
 
-**Status:** Partially Implemented
-
-**Documentation References:**
-- `docs/guide/relationships.md` (lines 176-289)
-
-**Description:**
-Many-to-many relationships are defined with `ManyToMany(...)`, but the join tables are not automatically created during `auto_migrate=True`.
-
-**Example (Partially Working):**
-```python
-from typing import Annotated
-
-from ferro import BackRef, Field, ManyToMany, Model, Relation
-
-class Post(Model):
-    id: int | None = Field(default=None, primary_key=True)
-    tags: Relation[list["Tag"]] = ManyToMany(related_name="posts")
-
-class Tag(Model):
-    id: int | None = Field(default=None, primary_key=True)
-    posts: Relation[list["Post"]] = BackRef()
-
-# Models created, but join table 'post_tags' is NOT auto-created
-# This causes errors when trying to use M2M methods:
-await post.tags.add(tag)  # RuntimeError: no such table: post_tags
-```
-
-**Workaround:**
-Manual join table creation may be required, or use Alembic migrations. Further investigation needed.
+**Status:** Implemented
 
-**Test Status:** 4 tests skipped in `tests/test_documentation_features.py`
+Many-to-many join tables are registered alongside their models and created by
+`auto_migrate=True` / `create_tables()` like any other table (they also
+participate in `migrate_updates` diffing). Covered by
+`tests/test_auto_migrate.py::test_m2m_join_table_created_during_auto_migrate`.
 
 ---
 

{ferro_orm-0.10.4 → ferro_orm-0.11.0}/docs/guide/database.md

@@ -133,8 +133,53 @@ During development, automatically align the database schema with your models:
 await ferro.connect("sqlite:dev.db?mode=rwc", auto_migrate=True)
 ```
 
+`auto_migrate=True` creates missing tables (including many-to-many join tables) and never touches existing ones. Two opt-in flags extend it:
+
+```python
+await ferro.connect(
+    "sqlite:dev.db?mode=rwc",
+    auto_migrate=True,
+    migrate_updates=True,      # update existing tables to match the models
+    migrate_destructive=True,  # also drop columns removed from the models
+)
+```
+
+The flags form a ladder — `migrate_destructive` implies `migrate_updates`, which implies `auto_migrate` — so passing just the strongest flag you want is enough.
+
+#### Schema updates with `migrate_updates`
+
+When a model gains fields between releases, `migrate_updates=True` reconciles the live table on connect. What it can do is capability-relative per backend:
+
+| Change | SQLite | Postgres |
+|---|---|---|
+| Add missing column | ✅ `ADD COLUMN` | ✅ `ADD COLUMN` |
+| Add missing column's index (`index=True`) | ✅ `CREATE INDEX` | ✅ `CREATE INDEX` |
+| Add unique column (`unique=True`) | ✅ via explicit `uq_` unique index + warning | ✅ inline `UNIQUE` |
+| Add foreign-key column | ✅ column only, no FK constraint + warning | ✅ column + FK constraint |
+| Change column type | ⚠️ warning, no DDL (type affinity makes drift mostly cosmetic) | ✅ `ALTER COLUMN ... TYPE ... USING` cast |
+| Change nullability | ⚠️ warning, no DDL | ✅ `SET NOT NULL` / `DROP NOT NULL` |
+| Drop removed column (`migrate_destructive`) | ✅ dependency-aware | ✅ |
+| Rename column/table, change primary key, drop table | ❌ never — [Alembic](migrations.md) territory | ❌ never |
+
+Rules to know:
+
+- **NOT NULL additions need a literal default.** Existing rows must be backfilled, so a new required field without a literal default fails the connect with a clear error. Make the field nullable, give it a default, or use Alembic. On Postgres the backfill default is dropped immediately after the add (a fresh `CREATE TABLE` carries no server default); SQLite cannot drop a column default, so it remains — harmless, and invisible to Alembic autogenerate's defaults.
+- **Added columns reuse the exact `CREATE TABLE` DDL.** A database brought forward by `migrate_updates` is byte-identical to one created fresh, so `alembic revision --autogenerate` stays clean (this is pinned by the cross-emitter parity tests).
+- **Destructive drops are dependency-aware and fail loudly.** Explicit indexes covering a dropped column are dropped first (they are orphaned anyway). Columns that are primary keys, enforced by UNIQUE/CHECK constraints, or referenced by other tables' foreign keys abort the migration with an error pointing at Alembic — nothing is skipped silently. Tables are never dropped.
+- **Postgres native enum columns are left alone.** They only exist via Alembic, which remains their owner.
+- **Postgres type changes take an exclusive lock** and fail the connect if existing data does not cast cleanly — acceptable for a development flag, but worth knowing.
+- **The pool refreshes after any schema change.** No connection can serve a statement prepared against the pre-migration schema (on SQLite stale statements panic the sqlx worker and silently return zero rows; on Postgres they raise `cached plan must not change result type`), and identity-mapped instances hydrated before the migration are evicted so loads return fresh, complete objects.
+
+The same pass can be run explicitly on a live connection instead of at connect time:
+
+```python
+await ferro.migrate()                    # create + update (default)
+await ferro.migrate(destructive=True)    # also drop removed columns
+await ferro.migrate(using="service")     # against a named connection
+```
+
 !!! danger "Production Warning"
-    `auto_migrate=True` is intended for development only. For production, use [Alembic migrations](migrations.md).
+    `auto_migrate=True` and its extension flags are intended for development and local-first apps whose schema is still moving. For production, use [Alembic migrations](migrations.md) — renames, primary-key changes, and data transforms are deliberately out of auto-migrate's scope.
 
 ## Manual Table Creation