ferro-orm 0.16.0__tar.gz → 0.16.2__tar.gz

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/CHANGELOG.md

@@ -1,6 +1,28 @@
 # CHANGELOG
 
 
+## v0.16.2 (2026-07-15)
+
+### Bug Fixes
+
+- Self-referential FKs no longer evict their component from CREATE TABLE order
+  ([#303](https://github.com/syn54x/ferro-orm/pull/303),
+  [`d1a55f6`](https://github.com/syn54x/ferro-orm/commit/d1a55f6ae241101d98ee659e6651fa33abaf4ec5))
+
+### Refactoring
+
+- Compile QueryIR payloads at a single wire choke point
+  ([`851b3f4`](https://github.com/syn54x/ferro-orm/commit/851b3f4e1f077d70481ebca643ff0ffff81645d8))
+
+
+## v0.16.1 (2026-07-13)
+
+### Bug Fixes
+
+- Chunk bulk_create under backend bind-parameter limits
+  ([`38da62d`](https://github.com/syn54x/ferro-orm/commit/38da62d9ab9fab6b36a9eae0722c1d741b976d15))
+
+
 ## v0.16.0 (2026-07-13)
 
 ### Chores

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/CONTEXT.md

@@ -80,6 +80,14 @@ _Avoid_: Eager-loaded field, select_related, prefetched attribute, joined attrib
 A query's declaration of what its result columns become: complete root instances (every query today), a projected record of named fields, or — in the future — a populated instance graph. Every query carries exactly one plan; the plan travels with the query rather than being inferred from its column list.
 _Avoid_: Select list, projection spec, hydration mode flag
 
+**QueryIR payload**:
+The single typed wire artifact a query ships to the Rust runtime — model identity, predicates, ordering, paging, joins, and exactly one materialization plan, inside a versioned envelope. Compiled only by `compile_query`; no other code assembles query wire shape.
+_Avoid_: Query dict, query def, payload dict
+
+**Golden vector**:
+A hand-authored JSON fixture pinning one wire shape — the independent authority both the Python emitter and the Rust decoder assert against, never regenerated from either side's output. Updating one by hand is the contract-review moment for a wire change.
+_Avoid_: Snapshot, fixture dump, example payload
+
 **Aggregate projection**:
 A projection containing at least one aggregate field. Each group collapses to exactly one projected record: every non-aggregate field is a group key, so grouping is derived from the projection and never declared separately. With no non-aggregate fields, the whole result collapses to a single record. Grouping collapses rows — bucketing complete instances by a key ("partitioning") is a different, client-side operation and is not grouping.
 _Avoid_: Group-by query, summary query, rollup, partition

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/Cargo.lock

@@ -327,7 +327,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.16.0"
+version = "0.16.2"
 dependencies = [
  "chrono",
  "dashmap",
@@ -890,9 +890,9 @@ dependencies = [
 
 [[package]]
 name = "mio"
-version = "1.2.1"
+version = "1.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "02bd0af71c67b473010cbbc60715ee815645a4dc942899111f494b4b737d6fda"
+checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427"
 dependencies = [
  "libc",
  "wasi",
@@ -1249,9 +1249,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.41"
+version = "0.23.42"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6b92b125634d9b795e7beca796cc790df15a7fb38323bf3196fda83292d06b1f"
+checksum = "3c54fcab019b409d04215d3a17cb438fd7fbf192ee61461f20f4fe18704bc138"
 dependencies = [
  "once_cell",
  "ring",
@@ -1444,9 +1444,9 @@ dependencies = [
 
 [[package]]
 name = "socket2"
-version = "0.6.4"
+version = "0.6.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51"
+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
 dependencies = [
  "libc",
  "windows-sys 0.61.2",
@@ -1454,9 +1454,9 @@ dependencies = [
 
 [[package]]
 name = "spin"
-version = "0.9.8"
+version = "0.9.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6980e8d7511241f8acf4aebddbb1ff938df5eebe98691418c4468d0b72a96a67"
+checksum = "3763264f6b73151db08c50ff20d7d8a0b8796e021cdea7ceedad07b80155fa0e"
 dependencies = [
  "lock_api",
 ]
@@ -1698,9 +1698,9 @@ checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
 
 [[package]]
 name = "syn"
-version = "2.0.118"
+version = "2.0.119"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -2329,6 +2329,6 @@ dependencies = [
 
 [[package]]
 name = "zmij"
-version = "1.0.22"
+version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bd2f034a4bebf216c9e4b7083603e024cf930873fd67830cfb083c9fa33129d9"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/ferro-schema-ir", "crates/ferro-ddl-lowering", "crates/ferro-
 
 [package]
 name = "ferro"
-version = "0.16.0"
+version = "0.16.2"
 edition = "2024"
 readme = "README.md"
 

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/PKG-INFO

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

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/crates/ferro-migrate/src/emit.rs

@@ -255,47 +255,23 @@ fn post_create_artifacts(
 
 /// Order `AddTable` models so each table's FK targets are created before it.
 ///
-/// A FK dependency on a table that is *not* part of this add set (already
-/// exists in the live DB) does not constrain ordering. Cycles fall through in
-/// arbitrary order — the inline FKs are anonymous, so a cyclic create still
-/// runs (SQLite is lenient; Postgres `CREATE TABLE` with a forward inline FK
-/// reference is the pre-existing behavior preserved here).
+/// Delegates to [`crate::order_by_dependencies`] for the dependency
+/// semantics: a self-referential FK and a FK to a table outside this add set
+/// do not constrain ordering, and genuine cross-table cycles fall through in
+/// input order (SQLite tolerates the forward references; Postgres rejects
+/// them — #302 follow-up).
 pub fn order_models_for_create<'a>(models: &[&'a SchemaModel]) -> Vec<&'a SchemaModel> {
-    let mut remaining: Vec<&SchemaModel> = models.to_vec();
-    let mut ordered = Vec::new();
-    let mut created = std::collections::HashSet::new();
-
-    while !remaining.is_empty() {
-        let available: std::collections::HashSet<String> = remaining
-            .iter()
-            .map(|m| m.table_name.clone())
-            .collect();
-        let mut progress = false;
-        let mut index = 0;
-        while index < remaining.len() {
-            let deps: Vec<String> = remaining[index]
+    crate::order_by_dependencies(
+        models.to_vec(),
+        |model| model.table_name.clone(),
+        |model| {
+            model
                 .foreign_keys
                 .iter()
                 .map(|fk| fk.to_table.clone())
-                .collect();
-            if deps
-                .iter()
-                .all(|dep| created.contains(dep) || !available.contains(dep))
-            {
-                let model = remaining.remove(index);
-                created.insert(model.table_name.clone());
-                ordered.push(model);
-                progress = true;
-            } else {
-                index += 1;
-            }
-        }
-        if !progress {
-            ordered.append(&mut remaining);
-            break;
-        }
-    }
-    ordered
+                .collect()
+        },
+    )
 }
 
 fn emit_add_table_passes(

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/crates/ferro-migrate/src/lib.rs

@@ -4,12 +4,14 @@
 //! [`emit_sql_with_ir`] lowers structural ops to executable backend-specific DDL.
 
 mod emit;
+mod order;
 
 use ferro_ddl_lowering::schema_columns_storage_drift;
 use ferro_schema_ir::{IrEnvelope, SchemaIrPayload, SchemaModel};
 use std::collections::{BTreeMap, BTreeSet};
 
 pub use emit::{emit_sql_with_ir, order_models_for_create, render_create_table, CreateTableEmission};
+pub use order::order_by_dependencies;
 pub use ferro_ddl_lowering::Dialect;
 
 /// Executable SQL plus non-fatal warnings from [`emit_sql_with_ir`].

ferro_orm-0.16.2/crates/ferro-migrate/src/order.rs

@@ -0,0 +1,56 @@
+//! Dependency ordering shared by every path that emits or reconciles tables.
+
+use std::collections::HashSet;
+
+/// Order `items` so every FK dependency of an item is emitted before it.
+///
+/// This is the single dependency-order primitive: both the CREATE TABLE
+/// emitter ([`crate::order_models_for_create`]) and the runtime's migrate
+/// reconcile loop funnel through it, so the semantics live in one place:
+///
+/// - A dependency on the item's **own** table (a self-referential FK) is not
+///   an ordering constraint — the inline `REFERENCES` resolves against the
+///   table its own `CREATE TABLE` statement is creating (#302).
+/// - A dependency on a table **outside** `items` (already live in the DB)
+///   does not constrain ordering.
+/// - Genuine cross-table cycles cannot be dependency-ordered; the remaining
+///   items are appended in input order. SQLite tolerates the resulting
+///   forward references; Postgres rejects them at CREATE time (#302
+///   follow-up: defer those FKs to post-create `ALTER TABLE ADD CONSTRAINT`).
+///
+/// Ordering is deterministic: input order is preserved except where a
+/// dependency forces an item later.
+pub fn order_by_dependencies<T>(
+    items: Vec<T>,
+    table_of: impl Fn(&T) -> String,
+    deps_of: impl Fn(&T) -> Vec<String>,
+) -> Vec<T> {
+    let mut remaining = items;
+    let mut ordered = Vec::with_capacity(remaining.len());
+    let mut created: HashSet<String> = HashSet::new();
+
+    while !remaining.is_empty() {
+        let available: HashSet<String> = remaining.iter().map(&table_of).collect();
+        let mut progress = false;
+        let mut index = 0;
+        while index < remaining.len() {
+            let table = table_of(&remaining[index]);
+            let satisfied = deps_of(&remaining[index])
+                .iter()
+                .all(|dep| dep == &table || created.contains(dep) || !available.contains(dep));
+            if satisfied {
+                let item = remaining.remove(index);
+                created.insert(table);
+                ordered.push(item);
+                progress = true;
+            } else {
+                index += 1;
+            }
+        }
+        if !progress {
+            ordered.append(&mut remaining);
+            break;
+        }
+    }
+    ordered
+}

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/crates/ferro-migrate/src/tests.rs

@@ -1459,3 +1459,36 @@ fn emit_sql_with_ir_add_column_db_check_postgres_quoted_and_sqlite_warns() {
         lite.warnings
     );
 }
+
+#[test]
+fn order_models_for_create_self_fk_is_not_an_ordering_constraint() {
+    // #302: `znode` carries a self-referential FK; `areferrer` arrives first
+    // (mirroring the alphabetical incoming order) and requires `znode`. The
+    // self-loop is satisfied by the table's own CREATE, so it must not evict
+    // the component from the dependency order.
+    let znode = SchemaModel {
+        foreign_keys: vec![SchemaForeignKey {
+            column: "parent_id".to_string(),
+            to_table: "znode".to_string(),
+            to_column: "id".to_string(),
+            on_delete: None,
+            name: None,
+        }],
+        ..schema_model("znode", vec![col("id", "uuid", false)])
+    };
+    let areferrer = SchemaModel {
+        foreign_keys: vec![SchemaForeignKey {
+            column: "node_id".to_string(),
+            to_table: "znode".to_string(),
+            to_column: "id".to_string(),
+            on_delete: None,
+            name: None,
+        }],
+        ..schema_model("areferrer", vec![col("id", "uuid", false)])
+    };
+
+    let models = vec![&areferrer, &znode];
+    let ordered = order_models_for_create(&models);
+    let tables: Vec<&str> = ordered.iter().map(|m| m.table_name.as_str()).collect();
+    assert_eq!(tables, vec!["znode", "areferrer"]);
+}

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/docs/pages/concepts/performance.md

@@ -6,7 +6,7 @@ Ferro moves SQL generation, parameter binding, and row hydration out of Python a
 
 The Rust core helps most where a traditional ORM spends significant CPU time in Python:
 
-**Bulk inserts.** `bulk_create` serializes and binds an entire batch in Rust and writes it as a single statement. The per-row Python overhead — building parameter lists, driver round-trips, object bookkeeping — largely disappears:
+**Bulk inserts.** `bulk_create` serializes and binds an entire batch in Rust and writes it in as few statements as the backend's bind-parameter limit allows. The per-row Python overhead — building parameter lists, driver round-trips, object bookkeeping — largely disappears:
 
 ```python
 users = [
@@ -43,7 +43,7 @@ for i in range(1000):
 await User.bulk_create([User(username=f"user_{i}") for i in range(1000)])
 ```
 
-Batches in the low thousands (roughly 1,000–5,000 rows) are a good unit of work — large enough to amortize overhead, small enough to keep statements and memory reasonable. Note that `bulk_create` skips the [identity map](identity-map.md) by design.
+Batch size is unbounded — Ferro splits large batches under the backend's bind-parameter limit automatically and keeps the whole call all-or-nothing — so size batches by what your application can hold in memory, not by statement limits. Note that `bulk_create` skips the [identity map](identity-map.md) by design.
 
 **Use batch update/delete instead of instance loops.** Push the work into one SQL statement:
 

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/docs/pages/guide/mutations.md

@@ -14,12 +14,14 @@ Ferro's write surface is three verbs with three distinct intents — none of the
 
 ### create
 
-`Model.create(**fields)` validates, inserts, and returns the persisted instance in one call. For inserting many rows, `Model.bulk_create(instances)` batches them into a single statement and returns the inserted count:
+`Model.create(**fields)` validates, inserts, and returns the persisted instance in one call. For inserting many rows, `Model.bulk_create(instances)` writes the whole batch in bulk and returns the inserted count:
 
 ```python
 --8<-- "docs/examples/quickstart.py:create"
 ```
 
+Batch size is unbounded. Both backends cap how many parameters one statement may bind (SQLite 32,766; PostgreSQL 65,535), so Ferro splits a large batch across as many INSERT statements as the active backend requires — an implementation detail you never see. Atomicity is preserved either way: inside a [`transaction()`](transactions.md) block that transaction is the boundary, and a bare `bulk_create` call is all-or-nothing — if any row fails (say, a unique violation late in the batch), no rows from the batch are inserted.
+
 `create()` is a plain INSERT — it never updates an existing row. A duplicate primary key or unique value raises [`UniqueViolationError`](../api/exceptions.md), and the existing row is left untouched:
 
 ```python

ferro_orm-0.16.2/docs/solutions/issues/self-fk-evicts-component-from-create-order.md

@@ -0,0 +1,59 @@
+---
+title: Self-referential FK evicted its whole component from CREATE TABLE order
+type: issue
+tags: [rust, schema, migrations, gotcha, postgres]
+related_files:
+  - crates/ferro-migrate/src/order.rs
+  - crates/ferro-migrate/src/emit.rs
+  - src/schema.rs
+related_issues: [302]
+captured: 2026-07-15
+---
+
+# Self-referential FK evicted its whole component from CREATE TABLE order
+
+**Problem:** On a fresh Postgres schema, `auto_migrate` created a referrer
+table before its FK target whenever the target carried a self-referential FK —
+the inline `REFERENCES` failed with `relation "..." does not exist`.
+
+**Takeaway:** In a dependency sort, an edge to your own table is already
+satisfied by your own `CREATE TABLE`; treating it as a pending dependency makes
+the table permanently ineligible, stalls everything downstream of it, and drops
+the whole component into the cycle fallback (input/alphabetical order).
+
+## What happened
+
+Both ordering loops (`order_models_for_create` in `ferro-migrate` and
+`order_models_for_migration` in `src/schema.rs`) only scheduled a table once
+every `fk.to_table` was in the `created` set. A self-FK's target can never be
+in `created` before the table itself, so the self-FK table never became
+eligible, its dependents stalled behind it, and the no-progress fallback
+appended the remainder in incoming order. Any referrer sorting before its
+target then failed on Postgres. Existing schemas survived by alphabetical
+luck.
+
+Two things let the bug survive review:
+
+1. The ordering loop existed in **two hand-rolled copies** with the same flaw.
+   Both now delegate to one primitive:
+   `ferro_migrate::order_by_dependencies` (`crates/ferro-migrate/src/order.rs`),
+   where the self-edge rule lives exactly once.
+2. A doc comment claimed cycles were harmless because "Postgres `CREATE TABLE`
+   with a forward inline FK reference is the pre-existing behavior" — false.
+   Postgres rejects forward references at CREATE time; only SQLite tolerates
+   them. Don't trust ordering-doesn't-matter claims without a Postgres test.
+
+Genuine cross-table cycles (A→B→A) still fall through in input order and fail
+on Postgres — a real fix needs post-create `ALTER TABLE ADD CONSTRAINT`
+deferral (follow-up tracked from #302).
+
+## How to recognize
+
+- `relation "X" does not exist` during `auto_migrate` on a fresh Postgres
+  schema, where X *is* among the registered models.
+- The failure appears/disappears when a self-FK is added/removed anywhere in
+  the dependency component, or when table names are renamed across the
+  alphabetical boundary.
+- SQLite passes while Postgres fails: SQLite accepts forward FK references, so
+  ordering bugs are invisible there — regression tests for CREATE order must
+  run on the Postgres matrix.

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ferro-orm"
-version = "0.16.0"
+version = "0.16.2"
 description = "A high-performance, Rust-backed ORM for Python."
 readme = "README.md"
 authors = [

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/src/backend.rs

@@ -415,6 +415,19 @@ impl EngineHandle {
         self.backend
     }
 
+    /// Maximum bind parameters one statement may carry on this backend.
+    ///
+    /// SQLite: `SQLITE_MAX_VARIABLE_NUMBER`, 32,766 by default since 3.32.
+    /// Postgres: the wire protocol's `Bind` message carries an `int16`
+    /// parameter count, so 65,535 is a hard protocol ceiling.
+    #[must_use]
+    pub fn max_bind_params(&self) -> usize {
+        match self.backend {
+            Dialect::Sqlite => 32_766,
+            Dialect::Postgres => 65_535,
+        }
+    }
+
     /// Record one catalog-introspection round-trip (called at the single
     /// choke point that executes catalog SQL).
     pub fn record_catalog_query(&self) {
@@ -611,7 +624,6 @@ impl EngineHandle {
         }
     }
 
-    #[allow(dead_code)]
     pub async fn begin_transaction_connection(&self) -> Result<EngineConnection, sqlx::Error> {
         match &self.pool_snapshot() {
             BackendPool::Sqlite(pool) => {

{ferro_orm-0.16.0 → ferro_orm-0.16.2}/src/ferro/models.py

@@ -639,6 +639,12 @@ class Model(BaseModel, metaclass=ModelMetaclass):
     ) -> int:
         """Persist multiple instances in a single bulk operation
 
+        Batch size is unbounded: batches larger than the backend's
+        bind-parameter limit allows in one statement are split internally.
+        The call is atomic either way — inside an ambient ``transaction()``
+        that transaction is the atomicity boundary; a bare call is
+        all-or-nothing (a failure on any row inserts none).
+
         Args:
             instances: Model instances to persist.