ferrum-orm 0.1.9__tar.gz → 0.1.13__tar.gz

{ferrum_orm-0.1.9 → ferrum_orm-0.1.13}/Cargo.lock

@@ -223,7 +223,7 @@ checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
 [[package]]
 name = "ferrum-core"
-version = "0.1.9"
+version = "0.1.13"
 dependencies = [
  "criterion",
  "proptest",
@@ -234,7 +234,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-migrate"
-version = "0.1.9"
+version = "0.1.13"
 dependencies = [
  "ferrum-core",
  "serde",
@@ -243,7 +243,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-pyo3"
-version = "0.1.9"
+version = "0.1.13"
 dependencies = [
  "ferrum-core",
  "ferrum-sql",
@@ -255,7 +255,7 @@ dependencies = [
 
 [[package]]
 name = "ferrum-sql"
-version = "0.1.9"
+version = "0.1.13"
 dependencies = [
  "criterion",
  "ferrum-core",

{ferrum_orm-0.1.9 → ferrum_orm-0.1.13}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/ferrum-core", "crates/ferrum-sql", "crates/ferrum-pyo3"]
 resolver = "2"
 
 [workspace.package]
-version = "0.1.9"
+version = "0.1.13"
 edition = "2021"
 authors = ["Ferrum Contributors"]
 license = "Apache-2.0"

{ferrum_orm-0.1.9 → ferrum_orm-0.1.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferrum-orm
-Version: 0.1.9
+Version: 0.1.13
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
@@ -184,6 +184,9 @@ No duplicate schema definitions.
 | `max_length` | `int \| None` | Emit `VARCHAR(n)` instead of `TEXT`. |
 | `max_digits` / `decimal_places` | `int \| None` | Emit `NUMERIC(p,s)`. |
 | `vector_dimensions` | `int \| None` | Required for `Vector` columns; emits `VECTOR(n)`. |
+| `jsonb_list` | `bool` | Store `list[T]` as JSONB instead of a PostgreSQL ARRAY. |
+| `generated` | `bool` | Select/hydrate the DB-generated column, but exclude it from writes. |
+| `read_only` | `bool` | Select/hydrate the column, but reject explicit write assignments. |
 
 ```python
 from datetime import datetime
@@ -224,6 +227,31 @@ users = await (
 )
 ```
 
+Typed aggregates and bounded PostgreSQL streaming use the same metadata allowlists
+and bound-parameter compiler path:
+
+```python
+from ferrum.queryset import Aggregate
+
+counts = await (
+    Ticket.objects
+    .group_by("team_id")
+    .date_trunc("created_at", "day", alias="day")
+    .having(total__gte=10)
+    .aggregate(conn, total=Aggregate.count())
+)
+
+async with Ticket.objects.filter(active=True).stream(conn, chunk_size=500) as chunks:
+    async for tickets in chunks:
+        await process(tickets)
+```
+
+`stream()` preserves projection/deferred/value-queryset materialization and
+deterministically releases its cursor on exhaustion, early break, cancellation, or
+error. It rejects `prefetch_related()` because cross-chunk relationship batching is
+not safe. Filtered `update_returning()` provides atomic compare-and-set semantics:
+encode the expected state in `filter()` and treat an empty returned list as a lost race.
+
 ### First-Class IDE Support
 
 Ferrum ships a PEP 561 `py.typed` marker, so editors and type checkers (`mypy`, `pyright`,
@@ -354,6 +382,8 @@ and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapp
 - [x] pgvector similarity score projection (`vector_search` helper)
 - [x] `Field(db_default=..., nullable=...)` — first-class DB-side defaults and nullability override
 - [x] `makemigrations` autodiff for index / default / nullability changes on existing tables
+- [x] Typed aggregates, filtered `UPDATE … RETURNING`, and bounded QuerySet streaming
+- [x] JSONB-list/generated/read-only metadata and read-only PostgreSQL schema drift reports
 - [ ] Query optimization (deferred fields, prefetch tuning)
 - [ ] Advanced relationship loading
 

{ferrum_orm-0.1.9 → ferrum_orm-0.1.13}/README.md

@@ -112,6 +112,9 @@ No duplicate schema definitions.
 | `max_length` | `int \| None` | Emit `VARCHAR(n)` instead of `TEXT`. |
 | `max_digits` / `decimal_places` | `int \| None` | Emit `NUMERIC(p,s)`. |
 | `vector_dimensions` | `int \| None` | Required for `Vector` columns; emits `VECTOR(n)`. |
+| `jsonb_list` | `bool` | Store `list[T]` as JSONB instead of a PostgreSQL ARRAY. |
+| `generated` | `bool` | Select/hydrate the DB-generated column, but exclude it from writes. |
+| `read_only` | `bool` | Select/hydrate the column, but reject explicit write assignments. |
 
 ```python
 from datetime import datetime
@@ -152,6 +155,31 @@ users = await (
 )
 ```
 
+Typed aggregates and bounded PostgreSQL streaming use the same metadata allowlists
+and bound-parameter compiler path:
+
+```python
+from ferrum.queryset import Aggregate
+
+counts = await (
+    Ticket.objects
+    .group_by("team_id")
+    .date_trunc("created_at", "day", alias="day")
+    .having(total__gte=10)
+    .aggregate(conn, total=Aggregate.count())
+)
+
+async with Ticket.objects.filter(active=True).stream(conn, chunk_size=500) as chunks:
+    async for tickets in chunks:
+        await process(tickets)
+```
+
+`stream()` preserves projection/deferred/value-queryset materialization and
+deterministically releases its cursor on exhaustion, early break, cancellation, or
+error. It rejects `prefetch_related()` because cross-chunk relationship batching is
+not safe. Filtered `update_returning()` provides atomic compare-and-set semantics:
+encode the expected state in `filter()` and treat an empty returned list as a lost race.
+
 ### First-Class IDE Support
 
 Ferrum ships a PEP 561 `py.typed` marker, so editors and type checkers (`mypy`, `pyright`,
@@ -282,6 +310,8 @@ and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapp
 - [x] pgvector similarity score projection (`vector_search` helper)
 - [x] `Field(db_default=..., nullable=...)` — first-class DB-side defaults and nullability override
 - [x] `makemigrations` autodiff for index / default / nullability changes on existing tables
+- [x] Typed aggregates, filtered `UPDATE … RETURNING`, and bounded QuerySet streaming
+- [x] JSONB-list/generated/read-only metadata and read-only PostgreSQL schema drift reports
 - [ ] Query optimization (deferred fields, prefetch tuning)
 - [ ] Advanced relationship loading
 

{ferrum_orm-0.1.9 → ferrum_orm-0.1.13}/crates/ferrum-core/src/compile/mod.rs

@@ -18,8 +18,8 @@
 use crate::{
     error::CompileError,
     ir::{
-        metadata::FieldType, BindValue, ModelMetadata, Operation, Predicate, QuerySetIR,
-        SortDirection, IR_VERSION,
+        metadata::FieldType, AggregateFunction, BindValue, GroupExpression, JoinSpec,
+        ModelMetadata, Operation, Predicate, QuerySetIR, SortDirection, IR_VERSION,
     },
 };
 
@@ -127,19 +127,22 @@ pub fn compile(metadata: &ModelMetadata, ir: &QuerySetIR) -> Result<CompiledQuer
         Operation::BulkDelete { pk_fields, ids } => validate_bulk_delete(metadata, pk_fields, ids)?,
     }
 
+    // Joins first so filter ``join_alias`` references can be checked against them.
+    validate_joins(metadata, ir)?;
+
     // Validate all field references in filters before touching SQL.
     for filter in &ir.filters {
-        validate_filter(metadata, filter)?;
+        validate_filter(metadata, filter, &ir.joins)?;
     }
 
     if let Some(predicate) = &ir.predicate {
-        validate_predicate(metadata, predicate)?;
+        validate_predicate(metadata, predicate, &ir.joins)?;
     }
 
-    validate_joins(metadata, ir)?;
     validate_order_by(metadata, ir)?;
     validate_vector_order_by(metadata, ir)?;
     validate_text_search(metadata, ir)?;
+    validate_aggregation(metadata, ir)?;
 
     // Validation passed. Return empty CompiledQuery — sql_text and bound_params
     // are populated by the SQL emitter in `ferrum-sql::emit`.
@@ -151,6 +154,144 @@ pub fn compile(metadata: &ModelMetadata, ir: &QuerySetIR) -> Result<CompiledQuer
     })
 }
 
+fn validate_field_ref<'a>(
+    metadata: &'a ModelMetadata,
+    field_ref: &crate::ir::FieldRef,
+) -> Result<&'a crate::ir::metadata::FieldMeta, CompileError> {
+    metadata
+        .fields
+        .get(field_ref.index)
+        .ok_or_else(|| CompileError::UnknownField {
+            model: metadata.model_name.clone(),
+            field: field_ref.name.clone(),
+        })
+}
+
+fn validate_aggregation(metadata: &ModelMetadata, ir: &QuerySetIR) -> Result<(), CompileError> {
+    let Some(aggregation) = &ir.aggregation else {
+        return Ok(());
+    };
+    if !matches!(ir.operation, Operation::Select { .. }) {
+        return Err(CompileError::MalformedIr {
+            reason: "aggregation is only valid for select operations".into(),
+        });
+    }
+    if aggregation.aggregates.is_empty() {
+        return Err(CompileError::MalformedIr {
+            reason: "aggregation requires at least one aggregate expression".into(),
+        });
+    }
+    if !ir.joins.is_empty()
+        || ir.vector_order_by.is_some()
+        || ir.text_rank_by.is_some()
+        || ir.distinct
+        || ir.exists
+        || !ir.order_by.is_empty()
+    {
+        return Err(CompileError::MalformedIr {
+            reason:
+                "aggregation cannot be combined with joins, ranking, distinct, exists, or order_by"
+                    .into(),
+        });
+    }
+
+    for group in &aggregation.groups {
+        let field_meta = match group {
+            GroupExpression::Field { field } => validate_field_ref(metadata, field)?,
+            GroupExpression::DateTrunc { field, .. } => {
+                let field_meta = validate_field_ref(metadata, field)?;
+                if !matches!(field_meta.field_type, FieldType::Date | FieldType::Datetime) {
+                    return Err(CompileError::UnsupportedOperator {
+                        model: metadata.model_name.clone(),
+                        field: field.name.clone(),
+                        operator: "date_trunc".into(),
+                    });
+                }
+                field_meta
+            }
+        };
+        let _ = field_meta;
+    }
+
+    for aggregate in &aggregation.aggregates {
+        validate_aggregate(metadata, aggregate, &ir.joins)?;
+    }
+    for having in &aggregation.having {
+        if having.aggregate_index >= aggregation.aggregates.len() {
+            return Err(CompileError::MalformedIr {
+                reason: "having aggregate_index is out of range".into(),
+            });
+        }
+    }
+    Ok(())
+}
+
+fn validate_aggregate(
+    metadata: &ModelMetadata,
+    aggregate: &crate::ir::AggregateExpression,
+    joins: &[JoinSpec],
+) -> Result<(), CompileError> {
+    let field_meta = aggregate
+        .field
+        .as_ref()
+        .map(|field| validate_field_ref(metadata, field))
+        .transpose()?;
+    match aggregate.function {
+        AggregateFunction::Count => {}
+        AggregateFunction::Sum | AggregateFunction::Avg => {
+            let Some(field_meta) = field_meta else {
+                return Err(CompileError::MalformedIr {
+                    reason: "sum and avg require a field".into(),
+                });
+            };
+            if !matches!(
+                field_meta.field_type,
+                FieldType::Int | FieldType::BigInt | FieldType::Float | FieldType::Decimal
+            ) {
+                return Err(CompileError::UnsupportedOperator {
+                    model: metadata.model_name.clone(),
+                    field: field_meta.name.clone(),
+                    operator: format!("{:?}", aggregate.function).to_lowercase(),
+                });
+            }
+        }
+        AggregateFunction::Min | AggregateFunction::Max => {
+            let Some(field_meta) = field_meta else {
+                return Err(CompileError::MalformedIr {
+                    reason: "min and max require a field".into(),
+                });
+            };
+            if matches!(
+                field_meta.field_type,
+                FieldType::Json
+                    | FieldType::Bytes
+                    | FieldType::Vector
+                    | FieldType::ArrayText
+                    | FieldType::ArrayUuid
+                    | FieldType::ArrayInt
+                    | FieldType::ArrayFloat
+                    | FieldType::TsVector
+            ) {
+                return Err(CompileError::UnsupportedOperator {
+                    model: metadata.model_name.clone(),
+                    field: field_meta.name.clone(),
+                    operator: format!("{:?}", aggregate.function).to_lowercase(),
+                });
+            }
+        }
+    }
+    if aggregate.function != AggregateFunction::Count && aggregate.field.is_none() {
+        return Err(CompileError::MalformedIr {
+            reason: "only count may omit a field".into(),
+        });
+    }
+    if let Some(predicate) = &aggregate.filter {
+        validate_predicate(metadata, predicate, joins)?;
+        validate_predicate_fts(metadata, predicate)?;
+    }
+    Ok(())
+}
+
 fn validate_joins(metadata: &ModelMetadata, ir: &QuerySetIR) -> Result<(), CompileError> {
     for join in &ir.joins {
         metadata
@@ -319,14 +460,15 @@ fn validate_vector_order_by(metadata: &ModelMetadata, ir: &QuerySetIR) -> Result
             operator: "nearest_to".into(),
         });
     }
-    // Accept both float_array (canonical vector type) and int_array (integer
-    // dims encoded by _encode_bind_value when the caller passes a list[int]).
+    // Prefer text (pgvector literal ``[f,f,...]`` + SQL ``::vector`` cast) so
+    // asyncpg does not bind ``list[float]`` as ``float[]`` (DataError). Still
+    // accept float_array / int_array for backwards-compatible IR producers.
     if !matches!(
         vector_order.value,
-        BindValue::FloatArray(_) | BindValue::IntArray(_)
+        BindValue::Text(_) | BindValue::FloatArray(_) | BindValue::IntArray(_)
     ) {
         return Err(CompileError::MalformedIr {
-            reason: "vector_order_by.value must be float_array or int_array".into(),
+            reason: "vector_order_by.value must be text, float_array, or int_array".into(),
         });
     }
     Ok(())
@@ -466,6 +608,11 @@ fn validate_predicate_fts(
         Predicate::Not { child } => validate_predicate_fts(metadata, child)?,
         Predicate::Filter { filter } => {
             if FTS_OPERATORS.contains(&filter.operator.as_str()) {
+                if filter.join_alias.is_some() {
+                    return Err(CompileError::MalformedIr {
+                        reason: "full-text operators are not supported on relation lookups".into(),
+                    });
+                }
                 validate_fts_filter(metadata, filter)?;
             }
         }
@@ -482,7 +629,36 @@ pub fn ir_has_where_clause(ir: &QuerySetIR) -> bool {
 fn validate_filter(
     metadata: &ModelMetadata,
     filter: &crate::ir::Filter,
+    joins: &[JoinSpec],
 ) -> Result<(), CompileError> {
+    if let Some(alias) = &filter.join_alias {
+        let join =
+            joins
+                .iter()
+                .find(|j| j.alias == *alias)
+                .ok_or_else(|| CompileError::MalformedIr {
+                    reason: format!("filter join_alias {alias:?} has no matching join"),
+                })?;
+        let remote = join
+            .remote_fields
+            .iter()
+            .find(|f| f.name == filter.field.name || f.index == filter.field.index)
+            .ok_or_else(|| CompileError::UnknownField {
+                model: metadata.model_name.clone(),
+                field: format!("{alias}__{}", filter.field.name),
+            })?;
+        if !remote.allowed_operators.is_empty()
+            && !remote.allowed_operators.contains(&filter.operator)
+        {
+            return Err(CompileError::UnsupportedOperator {
+                model: metadata.model_name.clone(),
+                field: format!("{alias}__{}", filter.field.name),
+                operator: filter.operator.clone(),
+            });
+        }
+        return Ok(());
+    }
+
     let field_meta =
         metadata
             .fields
@@ -502,15 +678,19 @@ fn validate_filter(
     Ok(())
 }
 
-fn validate_predicate(metadata: &ModelMetadata, predicate: &Predicate) -> Result<(), CompileError> {
+fn validate_predicate(
+    metadata: &ModelMetadata,
+    predicate: &Predicate,
+    joins: &[JoinSpec],
+) -> Result<(), CompileError> {
     match predicate {
         Predicate::And { children } | Predicate::Or { children } => {
             for child in children {
-                validate_predicate(metadata, child)?;
+                validate_predicate(metadata, child, joins)?;
             }
         }
-        Predicate::Not { child } => validate_predicate(metadata, child)?,
-        Predicate::Filter { filter } => validate_filter(metadata, filter)?,
+        Predicate::Not { child } => validate_predicate(metadata, child, joins)?,
+        Predicate::Filter { filter } => validate_filter(metadata, filter, joins)?,
     }
     Ok(())
 }
@@ -581,6 +761,7 @@ mod tests {
             distinct: false,
             exists: false,
             joins: vec![],
+            aggregation: None,
         }
     }
 
@@ -604,6 +785,7 @@ mod tests {
             },
             operator: "eq".into(),
             value: BindValue::Int(1),
+            join_alias: None,
         });
         let err = compile(&meta, &ir).unwrap_err();
         assert!(matches!(err, CompileError::UnknownField { .. }));
@@ -634,6 +816,7 @@ mod tests {
             },
             operator: "regex".into(), // not in allowed_operators
             value: BindValue::Int(1),
+            join_alias: None,
         });
         let err = compile(&meta, &ir).unwrap_err();
         assert!(matches!(err, CompileError::UnsupportedOperator { .. }));
@@ -679,6 +862,7 @@ mod tests {
             },
             operator: "match".into(),
             value: BindValue::Text("hello".into()),
+            join_alias: None,
         });
         let err = compile(&meta, &ir).unwrap_err();
         assert!(matches!(err, CompileError::UnsupportedOperator { .. }));
@@ -723,6 +907,7 @@ mod tests {
             },
             operator: "match_phrase".into(),
             value: BindValue::Text("hello world".into()),
+            join_alias: None,
         });
         ir.text_rank_by = Some(crate::ir::TextRankBy {
             field: FieldRef {
@@ -746,6 +931,7 @@ mod tests {
             },
             operator: "eq".into(),
             value: BindValue::Text("test@example.com".into()),
+            join_alias: None,
         });
         ir.order_by.push(OrderBy {
             field: FieldRef {
@@ -757,6 +943,53 @@ mod tests {
         assert!(compile(&meta, &ir).is_ok());
     }
 
+    #[test]
+    fn rejects_sum_on_text_field() {
+        let meta = make_metadata();
+        let mut ir = base_ir("User");
+        ir.operation = Operation::Select { fields: vec![] };
+        ir.aggregation = Some(crate::ir::Aggregation {
+            groups: vec![],
+            aggregates: vec![crate::ir::AggregateExpression {
+                function: crate::ir::AggregateFunction::Sum,
+                field: Some(FieldRef {
+                    name: "email".into(),
+                    index: 1,
+                }),
+                filter: None,
+            }],
+            having: vec![],
+        });
+
+        let error = compile(&meta, &ir).unwrap_err();
+
+        assert!(matches!(error, CompileError::UnsupportedOperator { .. }));
+    }
+
+    #[test]
+    fn rejects_having_unknown_aggregate_index() {
+        let meta = make_metadata();
+        let mut ir = base_ir("User");
+        ir.operation = Operation::Select { fields: vec![] };
+        ir.aggregation = Some(crate::ir::Aggregation {
+            groups: vec![],
+            aggregates: vec![crate::ir::AggregateExpression {
+                function: crate::ir::AggregateFunction::Count,
+                field: None,
+                filter: None,
+            }],
+            having: vec![crate::ir::Having {
+                aggregate_index: 4,
+                operator: crate::ir::HavingOperator::Gt,
+                value: BindValue::Int(0),
+            }],
+        });
+
+        let error = compile(&meta, &ir).unwrap_err();
+
+        assert!(matches!(error, CompileError::MalformedIr { .. }));
+    }
+
     #[test]
     fn query_fingerprint_contains_operation_and_model() {
         let meta = make_metadata();
@@ -790,6 +1023,7 @@ mod tests {
             distinct: false,
             exists: false,
             joins: vec![],
+            aggregation: None,
         };
         assert!(compile(&meta, &ir).is_ok());
     }
@@ -819,6 +1053,7 @@ mod tests {
             distinct: false,
             exists: false,
             joins: vec![],
+            aggregation: None,
         };
         assert!(matches!(
             compile(&meta, &ir).unwrap_err(),
@@ -843,6 +1078,7 @@ mod tests {
             distinct: false,
             exists: false,
             joins: vec![],
+            aggregation: None,
         };
         assert!(matches!(
             compile(&meta, &ir).unwrap_err(),
@@ -876,6 +1112,7 @@ mod tests {
             distinct: false,
             exists: false,
             joins: vec![],
+            aggregation: None,
         };
         assert!(matches!(
             compile(&meta, &ir).unwrap_err(),