ferro-orm 0.17.0__tar.gz → 0.17.1__tar.gz

{ferro_orm-0.17.0 → ferro_orm-0.17.1}/CHANGELOG.md

@@ -1,6 +1,15 @@
 # CHANGELOG
 
 
+## v0.17.1 (2026-07-19)
+
+### Bug Fixes
+
+- **migrate**: Auto-migrate pass ownership — column-before-index sequencing and FK on_delete
+  reconciliation ([#326](https://github.com/syn54x/ferro-orm/pull/326),
+  [`3451b1d`](https://github.com/syn54x/ferro-orm/commit/3451b1dad37d8ac39709d986aa20b1de4c12542a))
+
+
 ## v0.17.0 (2026-07-18)
 
 ### Documentation

{ferro_orm-0.17.0 → ferro_orm-0.17.1}/CONTEXT.md

@@ -123,3 +123,19 @@ _Avoid_: Import-time registration, partial registry
 **Resolved registration**:
 The registry epoch after relationship resolution completes — join tables exist, shadow FK columns are wired, and the SchemaIR modelset is authoritative for DDL and auto-migrate.
 _Avoid_: Final registration, committed registry
+
+**Create pass**:
+The auto-migrate step that brings missing tables into existence — the table, its columns, its indexes and constraints, together. A table that already exists is left completely untouched by this pass, whatever its shape.
+_Avoid_: Bootstrap, ensure-tables, table sync
+
+**Reconciliation pass**:
+The `migrate_updates` step that alters existing tables to match the registered models — the only authority for DDL against a table that already exists. Within one table, column changes land before the indexes and constraints that reference them.
+_Avoid_: Update pass, schema sync, drift repair
+
+**Ferro-owned artifact**:
+An index or constraint whose name follows ferro's canonical naming (`idx_`, `uq_`, `fk_`, `ck_`), marking it as reconcilable: auto-migrate may create, rebuild, or drop it to match the declared model. Artifacts named any other way belong to the user and are never altered or dropped.
+_Avoid_: Managed index, system constraint, internal index
+
+**Constraint rebuild**:
+Drop-and-recreate of a ferro-owned constraint whose live definition no longer matches the declared model — a foreign key's `on_delete`, its target, its columns. Metadata-only: rows are never touched. On a backend that cannot alter constraints, ferro warns loudly and skips; it never diverges silently.
+_Avoid_: Constraint alter, FK patch, in-place constraint update

{ferro_orm-0.17.0 → ferro_orm-0.17.1}/Cargo.lock

@@ -95,9 +95,9 @@ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "cc"
-version = "1.2.67"
+version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e17dd265a7d0f31ef544e1b20e03add05d3b45b491b633b10d67145d2acc1a38"
+checksum = "c89588d05638b5b4594a3348a2d6c20277e43a7f5c5202b05cc56888475a47b8"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -210,7 +210,7 @@ dependencies = [
  "ident_case",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -221,7 +221,7 @@ checksum = "fc34b93ccb385b40dc71c6fceac4b2ad23662c7eeb248cf10d529b7e055b6ead"
 dependencies = [
  "darling_core",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -269,7 +269,7 @@ checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -327,7 +327,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.17.0"
+version = "0.17.1"
 dependencies = [
  "chrono",
  "dashmap",
@@ -477,7 +477,7 @@ checksum = "2d6d3cde68c518367be28956066ddfef33813991b77a55005a69dae04bf3b10b"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -772,13 +772,13 @@ dependencies = [
 
 [[package]]
 name = "inherent"
-version = "1.0.13"
+version = "1.0.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c727f80bfa4a6c6e2508d2f05b6f4bfce242030bd88ed15ae5331c5b5d30fba7"
+checksum = "bee2c455ca60511a054699102d40ce7153621cb2429558f9eaa600e4499b5984"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 3.0.0",
 ]
 
 [[package]]
@@ -1069,9 +1069,9 @@ dependencies = [
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.106"
+version = "1.0.107"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
 dependencies = [
  "unicode-ident",
 ]
@@ -1134,7 +1134,7 @@ dependencies = [
  "proc-macro2",
  "pyo3-macros-backend",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -1147,14 +1147,14 @@ dependencies = [
  "proc-macro2",
  "pyo3-build-config",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
 name = "quote"
-version = "1.0.46"
+version = "1.0.47"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
 dependencies = [
  "proc-macro2",
 ]
@@ -1320,15 +1320,15 @@ dependencies = [
  "heck 0.4.1",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
  "thiserror",
 ]
 
 [[package]]
 name = "serde"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
 dependencies = [
  "serde_core",
  "serde_derive",
@@ -1336,22 +1336,22 @@ dependencies = [
 
 [[package]]
 name = "serde_core"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
 dependencies = [
  "serde_derive",
 ]
 
 [[package]]
 name = "serde_derive"
-version = "1.0.228"
+version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 3.0.0",
 ]
 
 [[package]]
@@ -1533,7 +1533,7 @@ dependencies = [
  "quote",
  "sqlx-core",
  "sqlx-macros-core",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -1556,7 +1556,7 @@ dependencies = [
  "sqlx-mysql",
  "sqlx-postgres",
  "sqlx-sqlite",
- "syn",
+ "syn 2.0.119",
  "tokio",
  "url",
 ]
@@ -1707,6 +1707,17 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "syn"
+version = "3.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2fac314a64dc9a36e61a9eb4261a5e9bbfbc922b27e518af97bc32b926cf967"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
 [[package]]
 name = "synstructure"
 version = "0.13.2"
@@ -1715,7 +1726,7 @@ checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -1726,22 +1737,22 @@ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
 [[package]]
 name = "thiserror"
-version = "2.0.18"
+version = "2.0.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
+checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
 dependencies = [
  "thiserror-impl",
 ]
 
 [[package]]
 name = "thiserror-impl"
-version = "2.0.18"
+version = "2.0.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
+checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 3.0.0",
 ]
 
 [[package]]
@@ -1794,7 +1805,7 @@ checksum = "6328af13490e73a9b4694030fafd93f8c8c6a9dede33e821c3fc63eddf8042ba"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -1828,7 +1839,7 @@ checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -1970,7 +1981,7 @@ dependencies = [
  "bumpalo",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
  "wasm-bindgen-shared",
 ]
 
@@ -2032,7 +2043,7 @@ checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -2043,7 +2054,7 @@ checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -2243,7 +2254,7 @@ checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
  "synstructure",
 ]
 
@@ -2264,7 +2275,7 @@ checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]
@@ -2284,7 +2295,7 @@ checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
  "synstructure",
 ]
 
@@ -2324,7 +2335,7 @@ checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.119",
 ]
 
 [[package]]

{ferro_orm-0.17.0 → ferro_orm-0.17.1}/Cargo.toml

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

{ferro_orm-0.17.0 → ferro_orm-0.17.1}/PKG-INFO

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

{ferro_orm-0.17.0 → ferro_orm-0.17.1}/crates/ferro-ddl-lowering/src/lib.rs

@@ -542,6 +542,13 @@ pub fn fk_name(table_lower: &str, col_name: &str, to_table: &str) -> String {
     raw
 }
 
+/// Whether a live constraint name follows the ferro FK convention above — the
+/// ownership test: reconciliation only ever rebuilds names ferro emits;
+/// constraints named any other way belong to the user and are never altered.
+pub fn is_ferro_fk_name(name: &str) -> bool {
+    name.starts_with("fk_")
+}
+
 /// Single-column unique name with 63-char guard.
 pub fn single_unique_index_name(table_lower: &str, col_name: &str) -> String {
     let raw = format!("uq_{table_lower}_{col_name}");

{ferro_orm-0.17.0 → ferro_orm-0.17.1}/crates/ferro-migrate/src/emit.rs

@@ -408,16 +408,7 @@ fn emit_add_column(
 
     if let Some(fk) = model.foreign_keys.iter().find(|fk| fk.column == column) {
         if dialect == Dialect::Postgres {
-            let on_delete = fk_action_from_str(fk.on_delete.as_deref());
-            result.statements.push(format!(
-                "ALTER TABLE {} ADD CONSTRAINT {} FOREIGN KEY ({}) REFERENCES {} ({}) ON DELETE {}",
-                quote_ident(table),
-                quote_ident(&fk_constraint_name(table, fk)),
-                quote_ident(column),
-                quote_ident(&fk.to_table),
-                quote_ident(&fk.to_column),
-                fk_action_sql(on_delete),
-            ));
+            result.statements.push(render_add_fk_sql(table, fk));
         } else {
             result.warnings.push(format!(
                 "Added foreign-key column '{}.{}' without its FOREIGN KEY constraint \
@@ -432,6 +423,39 @@ fn emit_add_column(
     Ok(result)
 }
 
+/// `ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY ... ON DELETE ...` for one
+/// IR foreign key. Postgres-only — SQLite cannot add table constraints to an
+/// existing table; its callers warn instead.
+fn render_add_fk_sql(table: &str, fk: &ferro_schema_ir::SchemaForeignKey) -> String {
+    format!(
+        "ALTER TABLE {} ADD CONSTRAINT {} FOREIGN KEY ({}) REFERENCES {} ({}) ON DELETE {}",
+        quote_ident(table),
+        quote_ident(&fk_constraint_name(table, fk)),
+        quote_ident(&fk.column),
+        quote_ident(&fk.to_table),
+        quote_ident(&fk.to_column),
+        fk_action_sql(fk_action_from_str(fk.on_delete.as_deref())),
+    )
+}
+
+/// Find the declared FK for `column` on `table` in the new-IR model.
+fn find_foreign_key<'a>(
+    model: &'a SchemaModel,
+    table: &str,
+    column: &str,
+) -> Result<&'a ferro_schema_ir::SchemaForeignKey, EmissionError> {
+    model
+        .foreign_keys
+        .iter()
+        .find(|fk| fk.column == column)
+        .ok_or_else(|| EmissionError {
+            message: format!(
+                "Foreign-key operation for '{}.{}' has no matching FK in the declared IR",
+                table, column
+            ),
+        })
+}
+
 fn emit_alter_column_type(
     table: &str,
     column: &str,
@@ -673,6 +697,61 @@ pub fn emit_sql_with_ir(
             MigrationOp::DropIndex { table: _, name } => {
                 result.statements.push(format!("DROP INDEX IF EXISTS \"{}\"", name));
             }
+            MigrationOp::AddForeignKey { table, column } => {
+                let model = find_model(&new_models, table)?;
+                let fk = find_foreign_key(model, table, column)?;
+                match dialect {
+                    Dialect::Postgres => result.statements.push(render_add_fk_sql(table, fk)),
+                    Dialect::Sqlite => result.warnings.push(format!(
+                        "Declared FOREIGN KEY on '{}.{}' (on_delete {}) has no live \
+                         constraint, and SQLite cannot add table constraints to an \
+                         existing table. Referential integrity for this column is not \
+                         database-enforced; use Alembic if you need the constraint.",
+                        table,
+                        column,
+                        fk_action_sql(fk_action_from_str(fk.on_delete.as_deref())),
+                    )),
+                }
+            }
+            MigrationOp::RebuildForeignKey {
+                table,
+                column,
+                old_name,
+            } => {
+                let model = find_model(&new_models, table)?;
+                let fk = find_foreign_key(model, table, column)?;
+                match dialect {
+                    Dialect::Postgres => {
+                        result.statements.push(format!(
+                            "ALTER TABLE {} DROP CONSTRAINT {}",
+                            quote_ident(table),
+                            quote_ident(old_name),
+                        ));
+                        result.statements.push(render_add_fk_sql(table, fk));
+                    }
+                    Dialect::Sqlite => {
+                        let live_action = find_model(&old_models, table)
+                            .ok()
+                            .and_then(|old| {
+                                old.foreign_keys.iter().find(|live| live.column == *column)
+                            })
+                            .map(|live| {
+                                fk_action_sql(fk_action_from_str(live.on_delete.as_deref()))
+                            })
+                            .unwrap_or("<unknown>");
+                        result.warnings.push(format!(
+                            "Foreign key on '{}.{}' declares on_delete {} but the live \
+                             constraint enforces {}; SQLite cannot alter constraints in \
+                             place, so the live behavior remains. Migrate with Alembic to \
+                             apply the declared action.",
+                            table,
+                            column,
+                            fk_action_sql(fk_action_from_str(fk.on_delete.as_deref())),
+                            live_action,
+                        ));
+                    }
+                }
+            }
         }
     }
 

{ferro_orm-0.17.0 → ferro_orm-0.17.1}/crates/ferro-migrate/src/lib.rs

@@ -6,7 +6,9 @@
 mod emit;
 mod order;
 
-use ferro_ddl_lowering::schema_columns_storage_drift;
+use ferro_ddl_lowering::{
+    fk_action_from_str, fk_action_sql, fk_name, is_ferro_fk_name, schema_columns_storage_drift,
+};
 use ferro_schema_ir::{IrEnvelope, SchemaIrPayload, SchemaModel};
 use std::collections::{BTreeMap, BTreeSet};
 
@@ -97,6 +99,25 @@ pub enum MigrationOp {
         /// Index name.
         name: String,
     },
+    /// A declared FK whose column exists live but has no FK constraint at all.
+    /// (FKs on newly added columns ride the `AddColumn` emission instead.)
+    AddForeignKey {
+        /// Owning table.
+        table: String,
+        /// Local FK column.
+        column: String,
+    },
+    /// A live ferro-owned FK whose definition (`on_delete`, target) drifted
+    /// from the declared FK on the same column — rebuilt as
+    /// `DROP CONSTRAINT` + `ADD CONSTRAINT` where the backend allows it.
+    RebuildForeignKey {
+        /// Owning table.
+        table: String,
+        /// Local FK column.
+        column: String,
+        /// Name of the live constraint to drop.
+        old_name: String,
+    },
 }
 
 /// Ordered migration operations plus non-fatal warnings collected during planning.
@@ -167,6 +188,13 @@ pub fn emit_sql(plan: &MigrationPlan, dialect: Dialect) -> Vec<String> {
             MigrationOp::DropIndex { name, .. } => {
                 sql.push(format!("-- index '{}' handled by emit_sql_with_ir", name));
             }
+            MigrationOp::AddForeignKey { table, column }
+            | MigrationOp::RebuildForeignKey { table, column, .. } => {
+                sql.push(format!(
+                    "-- foreign key for '{}.{}' handled by emit_sql_with_ir",
+                    table, column
+                ));
+            }
         }
     }
     sql
@@ -205,6 +233,7 @@ pub fn plan_from_ir(
         };
         diff_model_columns(*table, old_model, new_model, dialect, &mut plan);
         diff_model_indexes(*table, old_model, new_model, &mut plan);
+        diff_model_foreign_keys(*table, old_model, new_model, &mut plan);
     }
 
     plan
@@ -320,5 +349,78 @@ fn diff_model_indexes(
     }
 }
 
+fn diff_model_foreign_keys(
+    table: &str,
+    old_model: &SchemaModel,
+    new_model: &SchemaModel,
+    plan: &mut MigrationPlan,
+) {
+    let old_col_names: BTreeSet<&str> = old_model.columns.iter().map(|c| c.name.as_str()).collect();
+
+    for fk in &new_model.foreign_keys {
+        // An FK on a newly added column rides the AddColumn emission; the
+        // reconcile step only governs FKs whose column already exists live.
+        if !old_col_names.contains(fk.column.as_str()) {
+            continue;
+        }
+
+        let Some(live) = old_model
+            .foreign_keys
+            .iter()
+            .find(|live| live.column == fk.column)
+        else {
+            plan.operations.push(MigrationOp::AddForeignKey {
+                table: table.to_string(),
+                column: fk.column.clone(),
+            });
+            continue;
+        };
+
+        // Live `to_column` can be empty when the backend reports an
+        // implicit-PK reference (SQLite); only a stated target can drift.
+        let target_drift = live.to_table != fk.to_table
+            || (!live.to_column.is_empty() && live.to_column != fk.to_column);
+        // Compare via the canonical SQL rendering — sea-query's
+        // `ForeignKeyAction` has no equality of its own.
+        let action_drift = fk_action_sql(fk_action_from_str(live.on_delete.as_deref()))
+            != fk_action_sql(fk_action_from_str(fk.on_delete.as_deref()));
+        if !target_drift && !action_drift {
+            continue;
+        }
+
+        match live.name.as_deref() {
+            // A drifting constraint ferro does not own is never altered —
+            // but it is never silent either.
+            Some(name) if !is_ferro_fk_name(name) => {
+                plan.warnings.push(format!(
+                    "Foreign key on '{}.{}' drifts from the model (live: REFERENCES {} \
+                     ON DELETE {}; declared: REFERENCES {} ON DELETE {}), but the live \
+                     constraint '{}' is not ferro-owned, so it is left untouched. \
+                     Migrate it manually or with Alembic.",
+                    table,
+                    fk.column,
+                    live.to_table,
+                    fk_action_sql(fk_action_from_str(live.on_delete.as_deref())),
+                    fk.to_table,
+                    fk_action_sql(fk_action_from_str(fk.on_delete.as_deref())),
+                    name,
+                ));
+            }
+            _ => {
+                plan.operations.push(MigrationOp::RebuildForeignKey {
+                    table: table.to_string(),
+                    column: fk.column.clone(),
+                    // SQLite exposes no live constraint names; fall back to
+                    // the canonical name (unused there — emission warns).
+                    old_name: live
+                        .name
+                        .clone()
+                        .unwrap_or_else(|| fk_name(table, &fk.column, &live.to_table)),
+                });
+            }
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests;