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

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

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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferrum-orm
-Version: 0.1.8
+Version: 0.1.11
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
@@ -168,6 +168,49 @@ class User(Model):
 
 No duplicate schema definitions.
 
+### Field Options
+
+`ferrum.Field()` accepts column-level constraints that are carried through to DDL:
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `db_default` | `str \| None` | DB-side `DEFAULT` expression (e.g. `"NOW()"`, `"''"`, `"GEN_RANDOM_UUID()"`). Token casing is normalised (`now()` → `NOW()`). |
+| `nullable` | `bool \| None` | Override annotation-derived nullability. Use `nullable=False` to force `NOT NULL` even on a `T \| None`-annotated field. |
+| `db_index` | `bool` | Emit a `CREATE INDEX` on this column (auto-named `idx_{table}_{field}`). |
+| `unique` | `bool` | Emit a `UNIQUE` constraint. |
+| `db_column` | `str \| None` | Override the database column name. |
+| `primary_key` | `bool` | Declare this field as the primary key. |
+| `uuid_generate` | `"v4" \| "v7" \| None` | Set `GEN_RANDOM_UUID()` / `UUIDV7()` as the DB default for UUID PK columns. |
+| `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)`. |
+
+```python
+from datetime import datetime
+from typing import Annotated
+from ferrum import Model, Field
+
+class Event(Model):
+    id: int
+    # DB-side timestamp default; Python annotation allows None but column is NOT NULL
+    created_at: Annotated[datetime | None, Field(db_default="now()", nullable=False)]
+    # Indexed text column
+    kind: Annotated[str, Field(db_index=True, max_length=64)]
+```
+
+`makemigrations` honours these field attributes:
+- `db_default` / `nullable` are written into `CREATE TABLE` and `ADD COLUMN` DDL.
+- `db_index=True` emits `CREATE INDEX` after the table op.
+- For **already-existing tables**, `makemigrations` now **autodiffs** index and column
+  attribute changes against the state projected from prior migration files:
+  - Adding `db_index=True` to an existing field → `AddIndex` op.
+  - Removing `db_index=True` → `DropIndex` op.
+  - Adding or changing `db_default` → `AlterColumn … SET DEFAULT …` op.
+  - Removing `db_default` → `AlterColumn … DROP DEFAULT` op.
+  - Changing nullability → `AlterColumn … SET / DROP NOT NULL` op (SET NOT NULL is
+    classified destructive and requires `--confirm`).
+  - Column type changes, renames, and drops remain manual (out of scope for v0.1).
+
 ### Django-Inspired API
 
 Familiar query interface.
@@ -309,6 +352,8 @@ and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapp
 - [x] `call_function` for allowlisted stored-procedure calls
 - [x] Migration ops for extensions, RLS policies, and function DDL
 - [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
 - [ ] Query optimization (deferred fields, prefetch tuning)
 - [ ] Advanced relationship loading
 

{ferrum_orm-0.1.8 → ferrum_orm-0.1.11}/README.md

@@ -96,6 +96,49 @@ class User(Model):
 
 No duplicate schema definitions.
 
+### Field Options
+
+`ferrum.Field()` accepts column-level constraints that are carried through to DDL:
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `db_default` | `str \| None` | DB-side `DEFAULT` expression (e.g. `"NOW()"`, `"''"`, `"GEN_RANDOM_UUID()"`). Token casing is normalised (`now()` → `NOW()`). |
+| `nullable` | `bool \| None` | Override annotation-derived nullability. Use `nullable=False` to force `NOT NULL` even on a `T \| None`-annotated field. |
+| `db_index` | `bool` | Emit a `CREATE INDEX` on this column (auto-named `idx_{table}_{field}`). |
+| `unique` | `bool` | Emit a `UNIQUE` constraint. |
+| `db_column` | `str \| None` | Override the database column name. |
+| `primary_key` | `bool` | Declare this field as the primary key. |
+| `uuid_generate` | `"v4" \| "v7" \| None` | Set `GEN_RANDOM_UUID()` / `UUIDV7()` as the DB default for UUID PK columns. |
+| `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)`. |
+
+```python
+from datetime import datetime
+from typing import Annotated
+from ferrum import Model, Field
+
+class Event(Model):
+    id: int
+    # DB-side timestamp default; Python annotation allows None but column is NOT NULL
+    created_at: Annotated[datetime | None, Field(db_default="now()", nullable=False)]
+    # Indexed text column
+    kind: Annotated[str, Field(db_index=True, max_length=64)]
+```
+
+`makemigrations` honours these field attributes:
+- `db_default` / `nullable` are written into `CREATE TABLE` and `ADD COLUMN` DDL.
+- `db_index=True` emits `CREATE INDEX` after the table op.
+- For **already-existing tables**, `makemigrations` now **autodiffs** index and column
+  attribute changes against the state projected from prior migration files:
+  - Adding `db_index=True` to an existing field → `AddIndex` op.
+  - Removing `db_index=True` → `DropIndex` op.
+  - Adding or changing `db_default` → `AlterColumn … SET DEFAULT …` op.
+  - Removing `db_default` → `AlterColumn … DROP DEFAULT` op.
+  - Changing nullability → `AlterColumn … SET / DROP NOT NULL` op (SET NOT NULL is
+    classified destructive and requires `--confirm`).
+  - Column type changes, renames, and drops remain manual (out of scope for v0.1).
+
 ### Django-Inspired API
 
 Familiar query interface.
@@ -237,6 +280,8 @@ and [API Reference](docs/api-reference.md) for per-dialect DDL and operator mapp
 - [x] `call_function` for allowlisted stored-procedure calls
 - [x] Migration ops for extensions, RLS policies, and function DDL
 - [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
 - [ ] Query optimization (deferred fields, prefetch tuning)
 - [ ] Advanced relationship loading
 

{ferrum_orm-0.1.8 → ferrum_orm-0.1.11}/crates/ferrum-core/src/compile/mod.rs

@@ -18,7 +18,7 @@
 use crate::{
     error::CompileError,
     ir::{
-        metadata::FieldType, BindValue, ModelMetadata, Operation, Predicate, QuerySetIR,
+        metadata::FieldType, BindValue, JoinSpec, ModelMetadata, Operation, Predicate, QuerySetIR,
         SortDirection, IR_VERSION,
     },
 };
@@ -127,16 +127,18 @@ 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)?;
@@ -319,14 +321,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 +469,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 +490,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 +539,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(())
 }
@@ -604,6 +645,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 +676,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 +722,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 +767,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 +791,7 @@ mod tests {
             },
             operator: "eq".into(),
             value: BindValue::Text("test@example.com".into()),
+            join_alias: None,
         });
         ir.order_by.push(OrderBy {
             field: FieldRef {

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

@@ -67,9 +67,20 @@ pub struct QuerySetIR {
     pub joins: Vec<JoinSpec>,
 }
 
-/// JOIN metadata for ``select_related`` (`PostgreSQL` LEFT JOIN).
+/// JOIN kind for ``select_related`` (LEFT) vs relation-filter (INNER) joins.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum JoinKind {
+    /// ``LEFT JOIN`` — used by ``select_related()`` (preserve parent rows).
+    #[default]
+    Left,
+    /// ``INNER JOIN`` — used by relation-filter lookups (``team__slug=...``).
+    Inner,
+}
+
+/// JOIN metadata for ``select_related`` and relation-filter lookups.
 ///
-/// The emitter produces `LEFT JOIN <remote_table> AS <alias> ON <base_table>.<local_col> = <alias>.<remote_pk_column>`.
+/// The emitter produces `<JOIN KIND> <remote_table> AS <alias> ON <base_table>.<local_col> = <alias>.<remote_pk_column>`.
 /// All identifier fields are validated on the Python side before this struct is serialized into the IR.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct JoinSpec {
@@ -83,13 +94,25 @@ pub struct JoinSpec {
     pub remote_table: String,
     /// Remote table PK column name (from model metadata).
     pub remote_pk_column: String,
-    /// Columns to project from the remote table into `<alias>__<column>` aliases.
+    /// Columns available on the joined table (for SELECT projection and/or filter allowlisting).
     pub remote_fields: Vec<JoinFieldRef>,
+    /// ``left`` (default) or ``inner``.
+    #[serde(default)]
+    pub join_kind: JoinKind,
+    /// When ``true`` (default), project ``remote_fields`` into ``alias__col`` SELECT aliases.
+    /// Filter-only joins set this ``false`` so hydration is not polluted.
+    #[serde(default = "default_true")]
+    pub project_remote: bool,
+}
+
+fn default_true() -> bool {
+    true
 }
 
 /// A field reference into a joined (remote) model's metadata.
 ///
-/// Projected as `<alias>.<column> AS "<alias>__<column>"` in the SELECT list.
+/// When ``JoinSpec::project_remote`` is true, projected as
+/// `<alias>.<column> AS "<alias>__<column>"` in the SELECT list.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct JoinFieldRef {
     /// Index into the remote model's `ModelMetadata::fields`.
@@ -98,6 +121,9 @@ pub struct JoinFieldRef {
     pub name: String,
     /// Database column name of the remote field.
     pub column: String,
+    /// Operator allowlist copied from the remote field's ``FieldMeta`` (SQL-2).
+    #[serde(default)]
+    pub allowed_operators: Vec<String>,
 }
 
 /// The SQL operation this IR node represents.
@@ -149,10 +175,6 @@ pub enum Operation {
     },
 }
 
-fn default_true() -> bool {
-    true
-}
-
 /// One row payload for :variant:`Operation::BulkUpdate`.
 /// ``pk_values`` has one entry per PK field (single entry for single-PK models).
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -173,17 +195,26 @@ pub struct FieldRef {
 
 /// A filter predicate (one leaf of the WHERE clause).
 ///
-/// `operator` must be in `FieldMeta::allowed_operators` for `field`; the compiler
-/// rejects any string not in that allowlist before SQL is produced (SQL-1).
+/// `operator` must be in `FieldMeta::allowed_operators` for `field` (base model)
+/// or in the matching ``JoinFieldRef::allowed_operators`` when ``join_alias`` is
+/// set. The compiler rejects any string not in that allowlist before SQL is
+/// produced (SQL-1 / SQL-2).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Filter {
     /// The model field being filtered.
+    ///
+    /// When ``join_alias`` is set, ``index``/``name`` refer to the **remote**
+    /// model's field (matched against ``JoinSpec::remote_fields``).
     pub field: FieldRef,
     /// Ferrum operator string, e.g. `"eq"`, `"gt"`, `"icontains"`, `"is_null"`.
-    /// Validated against `FieldMeta::allowed_operators` before SQL emission.
+    /// Validated against the field's operator allowlist before SQL emission.
     pub operator: String,
     /// Bound value for the filter — never interpolated into SQL text.
     pub value: BindValue,
+    /// When set, the filter targets a column on the JOIN with this alias
+    /// (Django-style ``relation__field`` lookups). ``None`` = base table.
+    #[serde(default)]
+    pub join_alias: Option<String>,
 }
 
 /// Composable boolean predicate tree (``Q`` objects on the Python side).

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

@@ -91,6 +91,7 @@ fn bench_select_ir() -> QuerySetIR {
                 },
                 operator: "eq".into(),
                 value: BindValue::Bool(true),
+                join_alias: None,
             },
             Filter {
                 field: FieldRef {
@@ -99,6 +100,7 @@ fn bench_select_ir() -> QuerySetIR {
                 },
                 operator: "icontains".into(),
                 value: BindValue::Text("example.com".into()),
+                join_alias: None,
             },
         ],
         order_by: vec![