ferrum-orm 0.1.11__tar.gz → 0.1.14__tar.gz

{ferrum_orm-0.1.11 → ferrum_orm-0.1.14}/Cargo.lock

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

{ferrum_orm-0.1.11 → ferrum_orm-0.1.14}/Cargo.toml

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

{ferrum_orm-0.1.11 → ferrum_orm-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferrum-orm
-Version: 0.1.11
+Version: 0.1.14
 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.11 → ferrum_orm-0.1.14}/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.11 → ferrum_orm-0.1.14}/crates/ferrum-core/src/compile/mod.rs

@@ -18,8 +18,8 @@
 use crate::{
     error::CompileError,
     ir::{
-        metadata::FieldType, BindValue, JoinSpec, ModelMetadata, Operation, Predicate, QuerySetIR,
-        SortDirection, IR_VERSION,
+        metadata::FieldType, AggregateFunction, BindValue, GroupExpression, JoinSpec,
+        ModelMetadata, Operation, Predicate, QuerySetIR, SortDirection, IR_VERSION,
     },
 };
 
@@ -142,6 +142,7 @@ pub fn compile(metadata: &ModelMetadata, ir: &QuerySetIR) -> Result<CompiledQuer
     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`.
@@ -153,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
@@ -622,6 +761,7 @@ mod tests {
             distinct: false,
             exists: false,
             joins: vec![],
+            aggregation: None,
         }
     }
 
@@ -803,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();
@@ -836,6 +1023,7 @@ mod tests {
             distinct: false,
             exists: false,
             joins: vec![],
+            aggregation: None,
         };
         assert!(compile(&meta, &ir).is_ok());
     }
@@ -865,6 +1053,7 @@ mod tests {
             distinct: false,
             exists: false,
             joins: vec![],
+            aggregation: None,
         };
         assert!(matches!(
             compile(&meta, &ir).unwrap_err(),
@@ -889,6 +1078,7 @@ mod tests {
             distinct: false,
             exists: false,
             joins: vec![],
+            aggregation: None,
         };
         assert!(matches!(
             compile(&meta, &ir).unwrap_err(),
@@ -922,6 +1112,7 @@ mod tests {
             distinct: false,
             exists: false,
             joins: vec![],
+            aggregation: None,
         };
         assert!(matches!(
             compile(&meta, &ir).unwrap_err(),

{ferrum_orm-0.1.11 → ferrum_orm-0.1.14}/crates/ferrum-core/src/ir/mod.rs

@@ -15,7 +15,7 @@ pub mod metadata;
 pub use metadata::ModelMetadata;
 
 /// Version of the IR contract this crate implements.
-pub const IR_VERSION: u32 = 3;
+pub const IR_VERSION: u32 = 4;
 
 /// The root IR node produced by `QuerySet._build_ir()` on the Python side.
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -65,6 +65,90 @@ pub struct QuerySetIR {
     /// To-one JOINs for ``select_related()`` (validated on the Python side).
     #[serde(default)]
     pub joins: Vec<JoinSpec>,
+
+    /// Optional typed aggregate projection.
+    #[serde(default)]
+    pub aggregation: Option<Aggregation>,
+}
+
+/// Aggregate projection for grouped and scalar aggregate queries.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Aggregation {
+    /// GROUP BY expressions, emitted in this order.
+    pub groups: Vec<GroupExpression>,
+    /// Aggregate expressions, emitted after grouping keys.
+    pub aggregates: Vec<AggregateExpression>,
+    /// HAVING constraints referencing aggregate positions.
+    #[serde(default)]
+    pub having: Vec<Having>,
+}
+
+/// A metadata-backed GROUP BY expression.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum GroupExpression {
+    /// Group directly by a model field.
+    Field { field: FieldRef },
+    /// Group a date/datetime field by a fixed truncation bucket.
+    DateTrunc {
+        field: FieldRef,
+        granularity: DateTruncGranularity,
+    },
+}
+
+/// Fixed `DATE_TRUNC` buckets. Unknown input is rejected during deserialization.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DateTruncGranularity {
+    Minute,
+    Hour,
+    Day,
+    Week,
+    Month,
+    Quarter,
+    Year,
+}
+
+/// One typed aggregate projection.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AggregateExpression {
+    pub function: AggregateFunction,
+    /// COUNT may omit a field to emit COUNT(*); all other functions require one.
+    pub field: Option<FieldRef>,
+    /// `PostgreSQL` FILTER predicate, validated through the normal predicate path.
+    #[serde(default)]
+    pub filter: Option<Predicate>,
+}
+
+/// Aggregate functions supported by Ferrum.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AggregateFunction {
+    Count,
+    Sum,
+    Avg,
+    Min,
+    Max,
+}
+
+/// A HAVING constraint against an aggregate by zero-based projection index.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Having {
+    pub aggregate_index: usize,
+    pub operator: HavingOperator,
+    pub value: BindValue,
+}
+
+/// Fixed HAVING comparison operators.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum HavingOperator {
+    Eq,
+    Ne,
+    Gt,
+    Gte,
+    Lt,
+    Lte,
 }
 
 /// JOIN kind for ``select_related`` (LEFT) vs relation-filter (INNER) joins.
@@ -124,6 +208,9 @@ pub struct JoinFieldRef {
     /// Operator allowlist copied from the remote field's ``FieldMeta`` (SQL-2).
     #[serde(default)]
     pub allowed_operators: Vec<String>,
+    /// Remote field type used for type-specific SQL operator emission.
+    #[serde(default)]
+    pub field_type: Option<metadata::FieldType>,
 }
 
 /// The SQL operation this IR node represents.

{ferrum_orm-0.1.11 → ferrum_orm-0.1.14}/crates/ferrum-sql/benches/compile.rs

@@ -127,6 +127,7 @@ fn bench_select_ir() -> QuerySetIR {
         distinct: false,
         exists: false,
         joins: vec![],
+        aggregation: None,
     }
 }