ferro-orm 0.10.0__tar.gz → 0.10.2__tar.gz

{ferro_orm-0.10.0 → ferro_orm-0.10.2}/CHANGELOG.md

@@ -1,6 +1,30 @@
 # CHANGELOG
 
 
+## v0.10.2 (2026-05-19)
+
+### Bug Fixes
+
+- Hydrate SQLite INTEGER-backed Decimal columns on reconnect
+  ([#59](https://github.com/syn54x/ferro-orm/pull/59),
+  [`6f13906`](https://github.com/syn54x/ferro-orm/commit/6f13906850300bc9e85c1274763c49bc5b318b5d))
+
+
+## v0.10.1 (2026-05-19)
+
+### Bug Fixes
+
+- **sqlite**: Hydrate SQL NULL as None instead of int 0
+  ([#57](https://github.com/syn54x/ferro-orm/pull/57),
+  [`249c81f`](https://github.com/syn54x/ferro-orm/commit/249c81f4b37f117c3ca80f44a9682511154ab9ec))
+
+### Testing
+
+- **schema**: Integration coverage for db_type / db_check
+  ([#55](https://github.com/syn54x/ferro-orm/pull/55),
+  [`b97d596`](https://github.com/syn54x/ferro-orm/commit/b97d59667d520c026d8a6fbb73ad1de7f71593b4))
+
+
 ## v0.10.0 (2026-05-18)
 
 ### Features

{ferro_orm-0.10.0 → ferro_orm-0.10.2}/Cargo.lock

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

{ferro_orm-0.10.0 → ferro_orm-0.10.2}/Cargo.toml

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

{ferro_orm-0.10.0 → ferro_orm-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.10.0
+Version: 0.10.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.10.2/docs/solutions/issues/sqlite-null-hydrates-as-int-zero.md

@@ -0,0 +1,92 @@
+---
+title: SQLite NULL columns hydrate as int 0 after reconnect (Alembic DATETIME)
+type: issue
+tags: [gotcha, sqlite, hydration, bridge, rust, sqlalchemy, alembic, datetime, ffi]
+related_files:
+  - src/backend.rs
+  - src/operations.rs
+  - tests/test_sqlite_alembic_reconnect_hydration.py
+related_issues: [56]
+related_prs: [57]
+captured: 2026-05-18
+---
+
+## Problem
+
+Optional fields that are `NULL` in a SQLite database (for example
+`archived_at: datetime | None`) sometimes appear as Python `int(0)` after a
+**new connection** — `ferro.reset_engine()`, a new CLI process, or any fetch
+that does not hit the identity map. The same row shows `None` on the connection
+that just inserted it, and `sqlite3` confirms the column is `NULL`.
+
+## Takeaway
+
+`materialize_engine_row` in `src/backend.rs` must call `ValueRef::is_null()` on
+the raw column **before** typed `try_get` decoding. On SQLite, `try_get::<i64>`
+on SQL `NULL` often succeeds with `0` for INTEGER/NUMERIC-affinity columns
+(including Alembic `DateTime()` → `DATETIME`). That is not limited to datetimes:
+`INTEGER`, `REAL`, `TEXT`, and `NUMERIC` NULLs were all misread as `0` before
+the fix.
+
+## Explanation
+
+**Causal chain**
+
+1. Alembic/SQLAlchemy creates nullable `archived_at` as `DATETIME` (numeric
+   affinity on SQLite).
+2. Insert leaves the column SQL `NULL`.
+3. Fetch uses `materialize_engine_row`, which tried `try_get::<i64>` first.
+4. sqlx returns `Ok(0)` for NULL on those affinities instead of an error.
+5. `engine_value_to_rust_value` maps `EngineValue::I64` to `RustValue::BigInt`
+   (date-time `format` only applies to `EngineValue::String`).
+6. Python sees `0`, so `archived_at is None` filters fail.
+
+**Why same-session `create()` looked fine**
+
+The identity map returns the in-memory instance from insert without re-reading
+the row from SQLite.
+
+**Fix (PR #57)**
+
+```rust
+let value = match row.try_get_raw(ordinal) {
+    Ok(raw) if raw.is_null() => EngineValue::Null,
+    Ok(_) | Err(_) => decode_non_null_engine_value(row, ordinal),
+};
+```
+
+Legitimate integer `0` is unchanged: SQL `NULL` is detected via `is_null()`, not
+by treating `0` as missing.
+
+**Tests**
+
+- Rust: `engine_handle_fetches_sqlite_null_columns_as_null_not_zero`,
+  `engine_handle_fetches_sqlite_non_null_zero_integer` in `src/backend.rs`.
+- Python: `tests/test_sqlite_alembic_reconnect_hydration.py` (Alembic `create_all` + reconnect).
+  Requires `aiosqlite` and `greenlet` in `ci-test` / `dev` so CI does not skip.
+
+## How to recognize
+
+- Bug only on **SQLite**, often with **Alembic-created** schema (`auto_migrate=False`).
+- `field is None` checks fail while raw SQL shows `NULL`.
+- Same process right after `create()` is correct; new connection or `reset_engine()` is wrong.
+- Affected value is `0` (int), not a datetime string or `AttributeError`.
+- Raw `ferro.raw.fetch_all` shows the same `0` — failure is in row materialization, not Pydantic coercion alone.
+
+## Prevention
+
+- Any change to `materialize_engine_row` or `EngineValue` decoding: add a Rust
+  test that inserts `DEFAULT VALUES` into a nullable column and asserts
+  `EngineValue::Null`.
+- Do not “fix” optional datetimes in Python by treating `0` as unset — fix NULL
+  detection at the bridge.
+- Related but distinct: typed **bind** NULLs for Postgres are documented in
+  `docs/solutions/patterns/typed-null-binds.md` (`NullKind`, insert/update paths).
+  Fetch-time NULL handling is separate; both layers need correct typing.
+
+## Related
+
+- GitHub issue: https://github.com/syn54x/ferro-orm/issues/56
+- PR: https://github.com/syn54x/ferro-orm/pull/57
+- `docs/solutions/patterns/typed-null-binds.md` — NULL on the **write** path
+- `docs/solutions/issues/pydantic-slots-missing-after-ferro-hydration.md` — other hydration footguns

{ferro_orm-0.10.0 → ferro_orm-0.10.2}/docs/solutions/patterns/shadow-fk-columns.md

@@ -5,7 +5,9 @@ tags: [convention, schema, relationships, pydantic]
 related_files:
   - src/ferro/base.py
   - src/ferro/schema_metadata.py
-  - src/ferro/relations.py
+  - src/ferro/metaclass.py
+  - src/ferro/_shadow_fk_types.py
+  - src/ferro/relations/__init__.py
 related_issues: [32]
 related_prs: [36]
 captured: 2026-04-28

{ferro_orm-0.10.0 → ferro_orm-0.10.2}/docs/solutions/patterns/typed-null-binds.md

@@ -1,13 +1,14 @@
 ---
 title: Typed-null binds at the SQLx boundary
 type: pattern
-tags: [convention, invariant, bridge, ffi, rust, sea-query, sqlx, postgres]
+tags: [convention, invariant, bridge, ffi, rust, sea-query, sqlx, postgres, sqlite]
 related_files:
   - src/backend.rs
   - src/operations.rs
   - src/query.rs
   - tests/test_typed_null_binds.py
-related_issues: [38, 40]
+  - tests/test_sqlite_alembic_reconnect_hydration.py
+related_issues: [38, 40, 56]
 related_prs: []
 captured: 2026-04-29
 ---
@@ -92,6 +93,27 @@ are deferred (see plan §3 Scope Boundaries).
 \*\* Temporal types continue to use `cast_as` until issue [#40] picks a
    datetime crate (`chrono` vs `time`).
 
+## Fetch-time row materialization (read path)
+
+Typed binds fix **outbound** NULL parameters. A separate failure mode is
+**inbound** row decoding in `materialize_engine_row` (`src/backend.rs`).
+
+On SQLite, `row.try_get::<i64>` on SQL `NULL` often returns `Ok(0)` for
+INTEGER/NUMERIC-affinity columns (including Alembic `DateTime()` → `DATETIME`)
+if you decode before checking nullness. Ferro then hydrates Python `int(0)`
+instead of `None` — see issue [#56].
+
+**Rule:** call `row.try_get_raw(ordinal)` and test `raw.is_null()` before any
+typed `try_get`. Non-null integer `0` is unchanged; only SQL `NULL` is affected.
+
+| Layer            | Function / path              | NULL concern                          |
+|------------------|------------------------------|---------------------------------------|
+| Bind (write)     | `bind_engine_value`          | `NullKind` → `Option::<T>::None`      |
+| Fetch (read)     | `materialize_engine_row`     | `is_null()` before `decode_non_null_*`|
+
+Rust regression: `engine_handle_fetches_sqlite_null_columns_as_null_not_zero`.
+Integration: `tests/test_sqlite_alembic_reconnect_hydration.py` (Alembic schema + reconnect).
+
 ## Raw-SQL boundary (explicit exception)
 
 The raw-SQL bind path (`src/operations.rs::python_to_engine_bind_value`,
@@ -120,6 +142,9 @@ Ferro itself.
   to `Null(Untyped)` -- non-null data goes out as a text-typed null, and
   Postgres reports `expression is of type text` rather than the actual
   type mismatch. Always pair `Some` and `None` arms when adding a type.
+- On SQLite, optional fields are `NULL` in the DB but Python sees `int(0)`
+  after reconnect — check `materialize_engine_row`, not bind typing alone
+  ([#56]).
 
 ## Recipe: adding a new schema-driven emitter
 
@@ -164,8 +189,11 @@ Ferro itself.
 - AGENTS.md I-3: no `unwrap()` across the FFI boundary.
 - `docs/plans/2026-04-29-001-typed-null-binds-plan.md`: the implementation
   plan with the unit-by-unit breakdown.
+- `docs/solutions/issues/sqlite-null-hydrates-as-int-zero.md`: fetch-time
+  NULL → `int(0)` on SQLite (issue [#56]).
 - Issue [#38]: the original bug report.
 - Issue [#40]: temporal typed binds (deferred follow-up).
 
 [#38]: https://github.com/syn54x/ferro-orm/issues/38
 [#40]: https://github.com/syn54x/ferro-orm/issues/40
+[#56]: https://github.com/syn54x/ferro-orm/issues/56

{ferro_orm-0.10.0 → ferro_orm-0.10.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ferro-orm"
-version = "0.10.0"
+version = "0.10.2"
 description = "A high-performance, Rust-backed ORM for Python."
 readme = "README.md"
 authors = [
@@ -43,6 +43,8 @@ ci-test = [
     "pytest-cov>=7.0.0",
     "pytest-examples>=0.0.18",
     "pytest-postgresql>=8.0.0",
+    "aiosqlite>=0.22.1",
+    "greenlet>=3.3.1",
 ]
 docs = [
     "mkdocs-material>=9.5.0",
@@ -74,6 +76,8 @@ dev = [
     "psycopg[binary]>=3.3.3",
     "pytest-postgresql>=8.0.0",
     "pytest-xdist>=3.8.0",
+    "aiosqlite>=0.22.1",
+    "greenlet>=3.3.1",
 ]
 
 [tool.pytest.ini_options]

{ferro_orm-0.10.0 → ferro_orm-0.10.2}/src/backend.rs

@@ -1,6 +1,6 @@
 use sqlx::ColumnIndex;
 use sqlx::pool::PoolConnection;
-use sqlx::{Column, PgPool, Postgres, Row, Sqlite, SqlitePool};
+use sqlx::{Column, PgPool, Postgres, Row, Sqlite, SqlitePool, ValueRef};
 use std::fmt;
 use std::sync::Arc;
 
@@ -360,20 +360,13 @@ where
         .iter()
         .map(|column| {
             let name = column.name().to_string();
-            let value = if let Ok(value) = row.try_get::<i64, _>(column.ordinal()) {
-                EngineValue::I64(value)
-            } else if let Ok(value) = row.try_get::<i32, _>(column.ordinal()) {
-                EngineValue::I64(i64::from(value))
-            } else if let Ok(value) = row.try_get::<f64, _>(column.ordinal()) {
-                EngineValue::F64(value)
-            } else if let Ok(value) = row.try_get::<String, _>(column.ordinal()) {
-                EngineValue::String(value)
-            } else if let Ok(value) = row.try_get::<Vec<u8>, _>(column.ordinal()) {
-                EngineValue::Bytes(value)
-            } else if let Ok(value) = row.try_get::<bool, _>(column.ordinal()) {
-                EngineValue::Bool(value)
-            } else {
-                EngineValue::Null
+            let ordinal = column.ordinal();
+            // SQLite (and some drivers) let `try_get::<i64>` succeed with 0 on SQL
+            // NULL when the column has INTEGER/NUMERIC affinity (including Alembic
+            // `DATETIME`). Always consult the raw value before typed decode.
+            let value = match row.try_get_raw(ordinal) {
+                Ok(raw) if raw.is_null() => EngineValue::Null,
+                Ok(_) | Err(_) => decode_non_null_engine_value(row, ordinal),
             };
             (name, value)
         })
@@ -382,6 +375,34 @@ where
     EngineRow { values }
 }
 
+fn decode_non_null_engine_value<R>(row: &R, ordinal: usize) -> EngineValue
+where
+    R: Row,
+    for<'r> i32: sqlx::Decode<'r, R::Database> + sqlx::Type<R::Database>,
+    for<'r> i64: sqlx::Decode<'r, R::Database> + sqlx::Type<R::Database>,
+    for<'r> f64: sqlx::Decode<'r, R::Database> + sqlx::Type<R::Database>,
+    for<'r> Vec<u8>: sqlx::Decode<'r, R::Database> + sqlx::Type<R::Database>,
+    for<'r> String: sqlx::Decode<'r, R::Database> + sqlx::Type<R::Database>,
+    for<'r> bool: sqlx::Decode<'r, R::Database> + sqlx::Type<R::Database>,
+    usize: ColumnIndex<R>,
+{
+    if let Ok(value) = row.try_get::<i64, _>(ordinal) {
+        EngineValue::I64(value)
+    } else if let Ok(value) = row.try_get::<i32, _>(ordinal) {
+        EngineValue::I64(i64::from(value))
+    } else if let Ok(value) = row.try_get::<f64, _>(ordinal) {
+        EngineValue::F64(value)
+    } else if let Ok(value) = row.try_get::<String, _>(ordinal) {
+        EngineValue::String(value)
+    } else if let Ok(value) = row.try_get::<Vec<u8>, _>(ordinal) {
+        EngineValue::Bytes(value)
+    } else if let Ok(value) = row.try_get::<bool, _>(ordinal) {
+        EngineValue::Bool(value)
+    } else {
+        EngineValue::Null
+    }
+}
+
 fn bind_engine_value<'q, DB>(
     query: sqlx::query::Query<'q, DB, <DB as sqlx::Database>::Arguments<'q>>,
     value: &'q EngineBindValue,
@@ -568,6 +589,64 @@ mod tests {
         assert_eq!(inserted, 1);
     }
 
+    #[tokio::test]
+    async fn engine_handle_fetches_sqlite_null_columns_as_null_not_zero() {
+        let pool = SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect("sqlite::memory:")
+            .await
+            .unwrap();
+        let engine = EngineHandle::new_sqlite(pool);
+
+        for (table, ddl) in [
+            ("null_int", "CREATE TABLE null_int (v INTEGER)"),
+            ("null_real", "CREATE TABLE null_real (v REAL)"),
+            ("null_text", "CREATE TABLE null_text (v TEXT)"),
+            ("null_datetime", "CREATE TABLE null_datetime (v DATETIME)"),
+        ] {
+            engine.execute_sql(ddl).await.unwrap();
+            engine
+                .execute_sql(&format!("INSERT INTO {table} DEFAULT VALUES"))
+                .await
+                .unwrap();
+            let rows = engine
+                .fetch_all_sql_with_binds(&format!("SELECT v FROM {table}"), &[])
+                .await
+                .unwrap();
+            assert_eq!(
+                rows[0].values[0].1,
+                EngineValue::Null,
+                "SQL NULL in {table} must not decode as integer zero"
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn engine_handle_fetches_sqlite_non_null_zero_integer() {
+        let pool = SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect("sqlite::memory:")
+            .await
+            .unwrap();
+        let engine = EngineHandle::new_sqlite(pool);
+
+        engine
+            .execute_sql("CREATE TABLE zero_int (v INTEGER NOT NULL)")
+            .await
+            .unwrap();
+        engine
+            .execute_sql("INSERT INTO zero_int (v) VALUES (0)")
+            .await
+            .unwrap();
+
+        let rows = engine
+            .fetch_all_sql_with_binds("SELECT v FROM zero_int", &[])
+            .await
+            .unwrap();
+
+        assert_eq!(rows[0].values[0].1, EngineValue::I64(0));
+    }
+
     #[tokio::test]
     async fn engine_handle_fetches_sqlite_rows_with_bound_values() {
         let pool = SqlitePoolOptions::new()

{ferro_orm-0.10.0 → ferro_orm-0.10.2}/src/operations.rs

@@ -193,6 +193,7 @@ fn engine_value_to_rust_value(
 
     if is_decimal {
         return match value {
+            EngineValue::I64(v) => RustValue::Decimal(v.to_string()),
             EngineValue::F64(v) => RustValue::Decimal(v.to_string()),
             EngineValue::String(v) => RustValue::Decimal(v),
             _ => RustValue::None,
@@ -3077,3 +3078,125 @@ mod raw_sql_tests {
         });
     }
 }
+
+#[cfg(test)]
+mod engine_value_to_rust_value_tests {
+    use super::engine_value_to_rust_value;
+    use crate::backend::EngineValue;
+    use crate::state::RustValue;
+
+    fn decimal_schema() -> serde_json::Value {
+        serde_json::json!({
+            "properties": {
+                "hours": {
+                    "format": "decimal",
+                    "anyOf": [
+                        {"type": "number"},
+                        {"type": "string", "pattern": "^-?\\d+(\\.\\d+)?$"}
+                    ]
+                }
+            }
+        })
+    }
+
+    #[test]
+    fn decimal_column_maps_sqlite_integer_affinity_to_decimal() {
+        let schema = decimal_schema();
+        let out = engine_value_to_rust_value(EngineValue::I64(3), &schema, "hours");
+        assert!(matches!(out, RustValue::Decimal(ref s) if s == "3"));
+    }
+
+    #[test]
+    fn decimal_column_maps_real_and_text() {
+        let schema = decimal_schema();
+        let from_real =
+            engine_value_to_rust_value(EngineValue::F64(1.5), &schema, "hours");
+        assert!(matches!(from_real, RustValue::Decimal(ref s) if s == "1.5"));
+        let from_text =
+            engine_value_to_rust_value(EngineValue::String("2.25".into()), &schema, "hours");
+        assert!(matches!(from_text, RustValue::Decimal(ref s) if s == "2.25"));
+    }
+
+    fn datetime_schema() -> serde_json::Value {
+        serde_json::json!({
+            "properties": {
+                "happened_at": {"type": "string", "format": "date-time"}
+            }
+        })
+    }
+
+    fn binary_schema() -> serde_json::Value {
+        serde_json::json!({
+            "properties": {
+                "data": {"type": "string", "format": "binary"}
+            }
+        })
+    }
+
+    fn bool_schema() -> serde_json::Value {
+        serde_json::json!({
+            "properties": {
+                "is_active": {"type": "boolean"}
+            }
+        })
+    }
+
+    fn json_schema() -> serde_json::Value {
+        serde_json::json!({
+            "properties": {
+                "payload": {"type": "object"}
+            }
+        })
+    }
+
+    #[test]
+    fn datetime_column_only_accepts_string_engine_values() {
+        let schema = datetime_schema();
+        let ok = engine_value_to_rust_value(
+            EngineValue::String("2026-04-24T18:30:00+00:00".into()),
+            &schema,
+            "happened_at",
+        );
+        assert!(matches!(ok, RustValue::DateTime(_)));
+        let from_int = engine_value_to_rust_value(EngineValue::I64(1713984600), &schema, "happened_at");
+        assert!(matches!(from_int, RustValue::BigInt(1713984600)));
+    }
+
+    #[test]
+    fn binary_column_maps_bytes_and_text() {
+        let schema = binary_schema();
+        let from_bytes =
+            engine_value_to_rust_value(EngineValue::Bytes(vec![1, 2, 3]), &schema, "data");
+        assert!(matches!(from_bytes, RustValue::Blob(v) if v == vec![1, 2, 3]));
+        let from_text =
+            engine_value_to_rust_value(EngineValue::String("abc".into()), &schema, "data");
+        assert!(matches!(from_text, RustValue::Blob(v) if v == b"abc".to_vec()));
+        let from_int = engine_value_to_rust_value(EngineValue::I64(1), &schema, "data");
+        assert!(matches!(from_int, RustValue::None));
+    }
+
+    #[test]
+    fn bool_column_maps_integer_and_bool() {
+        let schema = bool_schema();
+        assert!(matches!(
+            engine_value_to_rust_value(EngineValue::I64(1), &schema, "is_active"),
+            RustValue::Bool(true)
+        ));
+        assert!(matches!(
+            engine_value_to_rust_value(EngineValue::Bool(false), &schema, "is_active"),
+            RustValue::Bool(false)
+        ));
+    }
+
+    #[test]
+    fn json_column_parses_string_payload() {
+        let schema = json_schema();
+        let out = engine_value_to_rust_value(
+            EngineValue::String(r#"{"k":"v"}"#.into()),
+            &schema,
+            "payload",
+        );
+        assert!(matches!(out, RustValue::Json(v) if v.get("k").and_then(|x| x.as_str()) == Some("v")));
+    }
+
+}