CHANGELOG¶

v0.14.0 (2026-07-07)¶

Bug Fixes¶

• ff-g: Make Postgres db_check ADD CONSTRAINT idempotent (G6, #176) (#181, 2c0e4cf)

Chores¶

• benchmarks: Pinned async benchmark suite over the rich-type hot path (#196, d9a656b)

Documentation¶

• Consolidate migration guides into one evergreen upgrade guide (#234, 15c83db)

• Fixes roadmap (5718d02)

• fable-fixes: Fold #176 into Epic FF-G as sub-task G6 (b966e65)

• ff-a: A5 — docs & migration guide for the mutation-surface changes (#180, ffc5476)

• ff-b: Tick FF-B sub-task and exit-gate boxes in the fable-fixes roadmap (29f9172)

Features¶

• ff-a: Create() is a real INSERT; save() distinguishes INSERT from UPDATE (A3+A4) (#179, de3ec30)

• ff-a: Reject limit/offset on mutating queries (#178, 67faf42)

• ff-a: Typed DBAPI-shaped exception hierarchy mapped from sqlx errors (#177, 9c306c5)

• ff-b: B1 canonical derived-type & naming decision table + refusal-rail scaffolding (8c879f7)

• ff-b: B2+B6 one derived-type decision table; native PG enums + timestamptz/time parity; delete bridge mirrors (bfdc1fd)

• ff-b: B3+B4 single-source artifact naming; both emitters emit named fk_/uq_ artifacts (6b771f3)

• ff-c: C1 — per-model ColumnCodec plan; delete codec.rs schema sniffing (F5) (#197, 0e8e572)

• ff-c: C2 — schema-epoch catalog cache; zero catalog queries on steady-state CRUD (#200, 8c6d6ed)

• ff-c: C3+C4 — native typed Postgres decode; plan-driven enum hydration replaces _fix_types (#198, 05a008c)

• ff-d: Session-scoped weak identity map with refresh-on-load; single-handle routing (#201, a328cfc)

• ff-e: Registry & model identity — qualified keys, configurable tables, O(N) import (#209, 6391805)

• ff-f: Query builder 1.0 shape — immutable chaining, build-time column validation, lambda-only predicates, QueryIR-only Rust (#223, eb7fece)

• ff-g-a: Hardening — hydration ABI guard, transactional PG migrate, correctness edges, decode-path caching (#232, 22617e1)

Refactoring¶

• ff-g-b: Operations.rs dedup — ModelMeta + Executor (G2) (#233, 09c2c62)

Testing¶

• ff-b: B5 I-1 sentinel on the full backend matrix with a full-type fixture, zero filters (1141eb4)

• ff-b: Force psycopg v3 driver in the Postgres sentinel regardless of URL scheme (64f9845)

v0.13.0 (2026-07-02)¶

Bug Fixes¶

• ir-p8.6: Datetime/timestamptz coarseness — stop silent Postgres column reinterpretation (#154) (#167, 7182a57)

• ir-p8.6: Stop false-positive BLOB drift warning on SQLite (#165) (#168, d554ac4)

• ir-p8.6: Surface real PEP 649 deferred-annotation error (#155) (#163, 00976e7)

Documentation¶

• Use model-named lambda predicates in examples (#132, 420ca6e)

• agents: Add I-11 — explain concepts plainly, example-first (efc7ef5)

• ir-first: Add Phase 8.6 post-8.5 cleanup backlog (epic #145) (#147, e57b74b)

• ir-first: Expand #144 scope — auto-migrate index/unique reconciliation (#150, fdbac40)

• ir-first: Lowering-consolidation audit + Phase 8.5 (#138, c6ce53c)

• ir-p8.6: Add #153 create-path IR unification spec (be4bb99)

• ir-p8.6: Add #153 create-path unification implementation plan (de3c427)

• ir-p8.6: Sync roadmap — #153 merged, file #158 (db_check check-renderer) (62c80fa)

• ir-p8.6: Sync roadmap — #154 merged (datetime/timestamptz warn-and-skip); #145 now 6/7 (31dbbb6)

• ir-p8.6: Sync roadmap — #162 merged (typed save/update bind), file #165 (5ca76a1)

• ir-p8.6: Sync roadmap — #165 merged (BLOB introspection); #145 complete 7/7, Phase 8.6 wrapped (1dbb278)

• rust: Add detailed docstrings for all public APIs (#130, 8d5a951)

Features¶

• Ir cutover (#137, 0509c2a)

• ir-p8.6: Route save/update/bulk value bind through the typed codec path (#162) (#166, 486e68c)

Refactoring¶

• Lowering consolidation & single-source-of-truth closeout (#139) (#156, f76bec9)

• Unify the CREATE TABLE path onto the Python SchemaIR (#153) (#157, c9ce7b0)

• Unify the three dialect enums into one shared Dialect (#146) (#159, 4b0dfe6)

• ir-p8.6: Single check-renderer for db_check (#158) (#161, c04df1c)

v0.12.3 (2026-06-24)¶

Bug Fixes¶

• session: Reject close while transactions are active (#128, e46f183)

• session: Serialize concurrent close teardown (#129, 7afa616)

v0.12.2 (2026-06-23)¶

Bug Fixes¶

• Cross-context session teardown (Fixes #123) (#127, 6b9ae13)

v0.12.1 (2026-06-23)¶

Bug Fixes¶

• Stop framework predicate warnings and bind unnamed sessions to default (#124, 66b92d8)

v0.12.0 (2026-06-23)¶

Documentation¶

• Rewrite site on Zensical with runnable examples (#70, da86911)

Features¶

• IR-first architecture program (Phases 0–7) (#116, 1c22857)

v0.11.0 (2026-06-11)¶

Chores¶

• Solution quality requirements (c62770b)

Documentation¶

• Compound SQLite hydration learnings (#56, #58) (#60, b609e72)

Features¶

• Extend auto_migrate with column updates and destructive drops (#69, a76cb0f)

v0.10.5 (2026-05-25)¶

Bug Fixes¶

• Coerce Annotated StrEnum fields on cold hydration (#66, c17c13b)

v0.10.4 (2026-05-24)¶

Bug Fixes¶

• query: Cast native Postgres enum RHS in .where() filters (#64, 7fea893)

v0.10.3 (2026-05-21)¶

Bug Fixes¶

• query: Typed predicates col == None / != None → IS NULL / IS NOT NULL (#62, fd4b53e)

v0.10.2 (2026-05-19)¶

Bug Fixes¶

• Hydrate SQLite INTEGER-backed Decimal columns on reconnect (#59, 6f13906)

v0.10.1 (2026-05-19)¶

Bug Fixes¶

• sqlite: Hydrate SQL NULL as None instead of int 0 (#57, 249c81f)

Testing¶

• schema: Integration coverage for db_type / db_check (#55, b97d596)

v0.10.0 (2026-05-18)¶

Features¶

• Configurable column storage types (db_type / db_check) (#53, bd5feee)

v0.9.2 (2026-05-14)¶

Bug Fixes¶

• hydration: Initialize Pydantic slots on Rust-hydrated models (#51, 7609886)

v0.9.1 (2026-05-11)¶

Bug Fixes¶

• ModelConnection annotations (337b983)

v0.9.0 (2026-05-09)¶

Chores¶

• Gitignore .context and untrack committed artifacts (#49, cac6330)

Features¶

• Add get_or_none method (0c81e9f)

Testing¶

• Add tests for explicit shadow fields (78a3471)

v0.8.0 (2026-05-09)¶

Features¶

• query: Typed query predicates via col() and lambda (#48, e34e3ca)

v0.7.0 (2026-05-08)¶

Features¶

• Per-connection identity_map on connect (#47, 0a1d629)

v0.6.1 (2026-05-07)¶

Refactoring¶

• Make ModelConnection generic to preserve model typing through .using() (#46, 50d6b68)

v0.6.0 (2026-04-30)¶

Features¶

• Support typed binds and named database routing (#45, e3fc930)

v0.5.0 (2026-04-28)¶

Bug Fixes¶

• ci: Make cargo test link against libpython by gating extension-module (e3b013e)

• fk: Address P2/P3 review findings (#32, 0ea6e02)

• raw: Make raw SQL tests pass on Postgres backend matrix (#31, 7b3c5e6)

• schema: Align Alembic single-column index names with Rust DDL (#32, 5e3211f)

Chores¶

• Refresh uv.lock and persist code-review artifacts (#32, 54e2cad)

Code Style¶

• Ruff format touched files (bbfda46)

Documentation¶

• Add AGENTS.md invariants and seed docs/solutions/ (#32, 8b0af7f)

• fk: Document ForeignKey(index=True) and add CHANGELOG entry (#32, 625a3f2)

• orm: Document ferro_composite_indexes and reverse_index (5ce3abe)

• raw: Add raw SQL API page, guide section, CHANGELOG entry (#31, 4b4699f)

Features¶

• alembic: Emit sa.Index for ferro_composite_indexes groups (a0c8176)

• fk: Accept index kwarg on ForeignKey (#32, ec39efe)

• fk: Propagate ForeignKey.index onto shadow column property (#32, 6d0f1f6)

• fk: Warn on redundant ForeignKey(unique=True, index=True) (#32, 3b311d7)

• orm: Add ferro_composite_indexes validation and schema injection (18f3b37)

• raw: Add ferro.execute/fetch_all/fetch_one with _marshal (#31, 944df61)

• raw: Add python_to_engine_bind_value helper for raw SQL binds (70bbbd3)

• raw: Transaction() yields Transaction handle for tx-bound raw SQL (#31, 226b575)

• raw: Wire raw_execute/raw_fetch_all/raw_fetch_one through PyO3 (#31, d31b580)

• relations: Add reverse_index opt-out for default M2M join tables (f1491df)

• rust: Emit non-unique CREATE INDEX for ferro_composite_indexes (e8b2d06)

Testing¶

• Add cross-emitter DDL parity sentinel (#32, e0ccc1a)

• Red test for ForeignKey(index=True) shadow column index (#32, 2bbedc5)

• fk: Regression guards for FK index default and nullable interaction (#32, 8f6a48d)

• fk: Runtime DDL parity for ForeignKey(index=True) (#32, 99d39f3)

• orm: Cover common composite-index use cases (b53643f)

• orm: Cover composite indexes on Postgres catalog (13bc21f)

• orm: Cover composite indexes with UUID/enum columns and autogen idempotence (a2ec4a5)

• orm: Cover composite-index overlap with composite-uniques (24b7481)

• raw: Cover active-tx ContextVar pickup for top-level execute (#31, 3f7a2e4)

• raw: Cover fetch_all/fetch_one shape and read-your-writes (#31, 8b4058c)

• raw: Cover invalid-SQL surface and savepoint rollback (#31, a03a398)

• raw: Cover Postgres RLS set_config/current_setting use case (#31, 4243123)

• raw: Cover UUID/datetime/Decimal/Enum/dict bind types (#31, 217d8b4)

• relations: Cover M2M reverse_index live catalog and edge cases (9aa9740)

• rust: Fix composite-index unit-test assertions for sea-query output (5c1ada1)

• rust: FK column with index flag still emits CREATE INDEX (#32, 1eca573)

v0.4.0 (2026-04-27)¶

Bug Fixes¶

• Correct BackRef type hinting for all/first (6171923)

Features¶

• Redesign relationship declarations (911e77d)

v0.3.4 (2026-04-25)¶

Bug Fixes¶

• Serialize UUID M2M query contexts (f53b3ca)

Chores¶

• Gitignore .worktrees/ for local worktrees (142cd3f)

• Update lock file (fa1c003)

Documentation¶

• Add backend guide (78f1e29)

Refactoring¶

• Replace Any backend with typed engine (71628a7)

Testing¶

• Add local Postgres test provider (f8601a5)

• Harden bridge-boundary coverage (f1a6064)

v0.3.3 (2026-04-24)¶

Bug Fixes¶

• Cast NULL and strings to ::uuid for Postgres using catalog (f5cb4f0)

• Catalog casts for date/timestamp columns on Postgres (95ef5ca)

• Clean up rebase conflicts with main (716511c)

• Enum OIDs (a9867be)

• Postgres native enums on save and StrEnum schema registration (44277e1)

• Use Postgres SQL dialect when connecting to postgres URLs (c627ac8)

• postgres: Add dual-db ORM test matrix (1fa657f)

• postgres: Bind boolean writes as booleans (346441a)

• postgres: Cast uuid columns to text in SELECT for Any decode (df957c0)

• postgres: Cast UUID filter params for sqlx Any compatibility (889cf8b)

• postgres: Decode native enum columns via text cast (1270f9d)

Refactoring¶

• Expand db matrix coverage and harden postgres paths (b82f3ac)

• Multi db architecture with true sqlite and postgres support (459a0c5)

Testing¶

• Expand schema constraints into db matrix (24a7f0a)

v0.3.2 (2026-04-24)¶

Bug Fixes¶

• Move alembic reqs to optional dependencies (87f0e81)

Build System¶

• sqlx: Enable rustls TLS for PostgreSQL connections (807fa81)

Chores¶

• Sync uv.lock with project version 0.3.1 (c3c9f91)

Continuous Integration¶

• Build preflight wheels earlier to fail faster (475c93c)

• Fix linux-aarch64 wheel builds for ring/rustls asm (5eadddc)

• Gate release on preflight wheel builds for all platforms (6ec48a2)

• Restore legacy release workflow (d3ee87c)

Documentation¶

• Add Supabase PostgreSQL connection and TLS guidance (b1d61ad)

v0.3.1 (2026-04-23)¶

Bug Fixes¶

• Alembic autogenerate named SQLAlchemy enums for PostgreSQL (25a00e8)

• migrations: Align nullable inference with field types (885f0fe)

• migrations: Propagate ForeignKey(unique=True) to Alembic metadata (#22, 9329e8f)

Continuous Integration¶

• Fix release (e2822f6)

• Fix release (e5c1adc)

• Fix release (688d01b)

Documentation¶

• Prefer Field over FerroField (3385cfa)

v0.3.0 (2026-04-23)¶

Bug Fixes¶

• Align composite unique index names and harden Alembic/Rust handling (3350481)

• Refresh Pydantic FieldInfo when reconciling shadow FK types (6cf1ac8)

Chores¶

• Remove doc (16e4028)

Continuous Integration¶

• Fix release (249e460)

• Fix release (888e15e)

• Fix release (58bb5b2)

• Reorder release steps to prevent tagging before checks are complete (ad1fd8d)

Documentation¶

• Complete documentation restructure and implementation summary (937e75e)

• Enhance shadow field documentation and clarify relationship resolution process (1d350fd)

Features¶

• Composite unique constraints and default M2M pair uniqueness (dc12880)

• Derive shadow FK types from related PK and reconcile after resolve (d3ae486)

Testing¶

• UUID FK save reparenting and bulk_create coverage (6c93cea)

v0.2.1 (2026-04-20)¶

Bug Fixes¶

• Defer annotations resolution (edd39ab)

Chores¶

• Update patch_tags in pyproject.toml to include refactor (36c29a7)

Continuous Integration¶

• Fix release & mkdocs publish workflows (630dc7c)

Documentation¶

• Restructure documentation following Diátaxis framework (b3c2cde)

• Update BackRef references and enhance field documentation (baf73ba)

• Update model field annotations to support optional back references (2044896)

Refactoring¶

• Enhance model relationship descriptors and improve field handling (6275ebb)

• Modularize metaclass new method for easier testing and maintenance (e514b95)

• Rename BackRelationship to BackRef and add back_ref to Field (d24d32d)

• Update demo_queries to use BackRef instead of BackRelationship (51799ad)

Testing¶

• Update references from BackRelationship to BackRef in test files (60a1d87)

v0.2.0 (2026-02-14)¶

Chores¶

• .gitignore: Remove src/ferro/fields.py from ignore list (1c46851)

• changelog: Fix changelog format (579bb10)

Continuous Integration¶

• docs: Publish docs site and relax strict commit checks (9b2af96)

• release: Consolidate changelog and release workflow orchestration (2724bcc)

• release: Update permissions for publish workflow (02ecf9f)

• release: Update permissions for publish workflow (d9d7243)

• release: Update workflows for PyPI Trusted Publishing (75195d5)

Features¶

• fields: Add wrapped Field helper for ferro metadata (2795ed9)

v0.1.1 (2026-02-13)¶

Chores¶

• project: Refine tooling configuration and code quality gates (d91aadd)

• query: Update demo script and dependency metadata (b737b12)

• release: Publish v0.1.0-rc.1 (a37d0d4)

• release: Publish v0.1.0-rc.2 (529801a)

• release: Publish v0.1.1 (c9ee751)

Continuous Integration¶

• Optimize caching and split PR vs main test execution (e84344c)

• docs: Add MkDocs build and deploy workflows (363ffa1)

• release: Add end-to-end CI, publish, and changelog pipelines (1589dda)

• release: Configure changelog generation and release token wiring (9b95e41)

• release: Enable prerelease publication path (eab9a18)

• release: Stabilize workflow stages and macOS/toolchain settings (dbf9a3e)

Documentation¶

• api: Reorganize docs structure and validate code examples (cd5b7b2)

• community: Add contributor and release documentation set (f9fb40e)

• readme: Clean duplicated content and streamline guidance (785573a)

• site: Add MkDocs structure and ORM usage guides (d5b4955)

Features¶

• connection: Add pool management and schema registration APIs (2fa9fd7)

• core: Add async CRUD engine and identity map bridge (64ea39f)

• logging: Route Ferro logs through Python logging (df6be66)

• migrations: Integrate Alembic-backed migration management (c244996)

• query: Add fluent query builder and predicate execution (11d0a5c)

• relations: Add relationship descriptors and query node modules (c8e72bd)

Testing¶

• core: Add integration coverage for CRUD and schema behavior (e5b3e51)

• query: Add coverage for builder operations and advanced types (6e33f40)

• relations: Cover one-to-one behavior and schema constraints (7cc8377)

v0.1.0 (2026-02-13)¶

• Initial Release