Skip to main content

che_orm/
query.rs

1use std::collections::HashSet;
2use std::marker::PhantomData;
3
4use crate::{
5    ColumnRef, CompareOp, CreateTableQuery, DatabaseValue, Expr, ModelField, QueryValue, TableRef,
6    TableSchema,
7};
8
9#[derive(Debug, Clone, Copy)]
10pub enum OrderDirection {
11    Asc,
12    Desc,
13}
14
15#[derive(Debug, Clone, Copy)]
16pub struct OrderBy {
17    pub column: ColumnRef,
18    pub direction: OrderDirection,
19}
20
21#[derive(Debug, Clone, Copy)]
22pub struct JoinedField<T> {
23    column: ColumnRef,
24    _marker: PhantomData<T>,
25}
26
27impl<T> JoinedField<T> {
28    pub const fn new(column: ColumnRef) -> Self {
29        Self {
30            column,
31            _marker: PhantomData,
32        }
33    }
34
35    fn comparison<V>(self, op: CompareOp, value: V) -> Expr
36    where
37        V: QueryValue<T>,
38    {
39        Expr::Compare {
40            left: Box::new(Expr::Column(self.column)),
41            op,
42            right: Box::new(Expr::Value(value.into_query_value())),
43        }
44    }
45
46    pub fn eq<V>(self, value: V) -> Expr
47    where
48        V: QueryValue<T>,
49    {
50        self.comparison(CompareOp::Eq, value)
51    }
52
53    pub fn ne<V>(self, value: V) -> Expr
54    where
55        V: QueryValue<T>,
56    {
57        self.comparison(CompareOp::Ne, value)
58    }
59
60    pub fn gt<V>(self, value: V) -> Expr
61    where
62        V: QueryValue<T>,
63    {
64        self.comparison(CompareOp::Gt, value)
65    }
66
67    pub fn gte<V>(self, value: V) -> Expr
68    where
69        V: QueryValue<T>,
70    {
71        self.comparison(CompareOp::Gte, value)
72    }
73
74    pub fn lt<V>(self, value: V) -> Expr
75    where
76        V: QueryValue<T>,
77    {
78        self.comparison(CompareOp::Lt, value)
79    }
80
81    pub fn lte<V>(self, value: V) -> Expr
82    where
83        V: QueryValue<T>,
84    {
85        self.comparison(CompareOp::Lte, value)
86    }
87
88    pub fn is_null(self) -> Expr {
89        Expr::IsNull(Box::new(Expr::Column(self.column)))
90    }
91
92    pub fn is_not_null(self) -> Expr {
93        Expr::IsNotNull(Box::new(Expr::Column(self.column)))
94    }
95
96    pub const fn asc(self) -> OrderBy {
97        OrderBy {
98            column: self.column,
99            direction: OrderDirection::Asc,
100        }
101    }
102
103    pub const fn desc(self) -> OrderBy {
104        OrderBy {
105            column: self.column,
106            direction: OrderDirection::Desc,
107        }
108    }
109}
110
111#[derive(Debug, Clone)]
112pub struct SelectAst {
113    pub table: TableRef,
114    pub columns: Vec<ColumnRef>,
115    pub joins: Vec<JoinAst>,
116    pub filter: Option<Expr>,
117    pub order_by: Vec<OrderBy>,
118    pub limit: Option<u64>,
119    pub offset: Option<u64>,
120}
121
122#[derive(Debug, Clone)]
123pub struct JoinAst {
124    pub table: TableRef,
125    pub alias: &'static str,
126    pub kind: JoinType,
127    pub on: Expr,
128}
129
130#[derive(Debug, Clone, Copy)]
131pub enum JoinType {
132    Inner,
133    Left,
134}
135
136#[derive(Debug, Clone)]
137pub struct InsertValue {
138    pub column: ColumnRef,
139    pub value: DatabaseValue,
140}
141
142#[derive(Debug, Clone)]
143pub struct InsertAst {
144    pub table: TableRef,
145    pub values: Vec<InsertValue>,
146    pub returning: Vec<ColumnRef>,
147}
148
149#[derive(Debug, Clone)]
150pub struct Assignment {
151    pub column: ColumnRef,
152    pub value: DatabaseValue,
153}
154
155#[derive(Debug, Clone)]
156pub struct UpdateAst {
157    pub table: TableRef,
158    pub assignments: Vec<Assignment>,
159    pub filter: Option<Expr>,
160    pub returning: Vec<ColumnRef>,
161    pub allow_all: bool,
162}
163
164#[derive(Debug, Clone)]
165pub struct DeleteAst {
166    pub table: TableRef,
167    pub filter: Option<Expr>,
168    pub allow_all: bool,
169}
170
171#[derive(Debug, Clone)]
172pub enum QueryAst {
173    Select(SelectAst),
174    Insert(InsertAst),
175    Update(UpdateAst),
176    Delete(DeleteAst),
177    CreateTable(crate::CreateTableAst),
178}
179
180#[derive(Debug, Clone, PartialEq, Eq)]
181/// Errors detected while finalizing a query builder.
182pub enum QueryBuildError {
183    EmptyInsert,
184    EmptyUpdate,
185    PrimaryKeyUpdate,
186    MissingFilter,
187    DuplicateColumn(&'static str),
188    ForeignTableColumn {
189        column: &'static str,
190        table: &'static str,
191        expected_table: &'static str,
192    },
193    InvalidSchema(String),
194}
195
196impl QueryAst {
197    /// Validates a query before it is sent to a database.
198    pub fn validate(&self) -> Result<(), QueryBuildError> {
199        match self {
200            Self::Select(query) => {
201                validate_expr_table(query.filter.as_ref(), query.table.name)?;
202                validate_columns_table(
203                    query.table.name,
204                    query.order_by.iter().map(|order| &order.column),
205                )
206            }
207            Self::Insert(query) => {
208                if query.values.is_empty() {
209                    return Err(QueryBuildError::EmptyInsert);
210                }
211                validate_unique_columns(query.values.iter().map(|value| &value.column))?;
212                validate_columns_table(
213                    query.table.name,
214                    query.values.iter().map(|value| &value.column),
215                )
216            }
217            Self::Update(query) => {
218                if query.assignments.is_empty() {
219                    return Err(QueryBuildError::EmptyUpdate);
220                }
221                if query.filter.is_none() && !query.allow_all {
222                    return Err(QueryBuildError::MissingFilter);
223                }
224                validate_unique_columns(
225                    query
226                        .assignments
227                        .iter()
228                        .map(|assignment| &assignment.column),
229                )?;
230                validate_columns_table(
231                    query.table.name,
232                    query
233                        .assignments
234                        .iter()
235                        .map(|assignment| &assignment.column),
236                )?;
237                validate_expr_table(query.filter.as_ref(), query.table.name)
238            }
239            Self::Delete(query) => {
240                if query.filter.is_none() && !query.allow_all {
241                    return Err(QueryBuildError::MissingFilter);
242                }
243                validate_expr_table(query.filter.as_ref(), query.table.name)
244            }
245            Self::CreateTable(query) => query
246                .schema
247                .validate()
248                .map_err(|error| QueryBuildError::InvalidSchema(format!("{error:?}"))),
249        }
250    }
251}
252
253/// Trait implemented by `#[derive(Model)]` for ORM models.
254pub trait Model: Sized {
255    fn table_name() -> &'static str;
256    fn columns() -> &'static [&'static str];
257    /// Returns the model's generated integer primary-key field.
258    fn primary_key() -> ModelField<Self, i64>;
259    fn primary_key_value(&self) -> i64 {
260        panic!("Model::primary_key_value must be implemented for eager relations")
261    }
262    fn schema() -> TableSchema;
263    fn from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<Self>;
264    fn from_row_at(row: &rusqlite::Row<'_>, offset: usize) -> rusqlite::Result<Self> {
265        if offset == 0 {
266            Self::from_row(row)
267        } else {
268            Err(rusqlite::Error::InvalidColumnIndex(offset))
269        }
270    }
271    fn insert_values(&self) -> Vec<InsertValue>;
272    fn managed_update_values() -> Vec<Assignment> {
273        Vec::new()
274    }
275    fn query() -> SelectQuery<Self> {
276        SelectQuery::new()
277    }
278    fn insert() -> InsertQuery<Self> {
279        InsertQuery::new()
280    }
281    fn update() -> UpdateQuery<Self> {
282        UpdateQuery::new()
283    }
284    fn delete() -> DeleteQuery<Self> {
285        DeleteQuery::new()
286    }
287    fn create_table() -> CreateTableQuery<Self> {
288        CreateTableQuery::new(Self::schema())
289    }
290}
291
292/// Converts a materialized ORM model into an API representation.
293pub trait ModelSerializer: serde::Serialize + Sized {
294    type Model: Model;
295    type Input;
296
297    fn from_input(input: Self::Input) -> Self;
298
299    fn to_json(input: Self::Input) -> Result<serde_json::Value, serde_json::Error> {
300        serde_json::to_value(Self::from_input(input))
301    }
302
303    fn fields() -> &'static [SerializerField] {
304        &[]
305    }
306}
307
308/// Identifies the actual foreign-key column behind a serializer relation.
309pub trait RelationSource {
310    const SOURCE: &'static str;
311}
312
313#[derive(Debug, Clone, Copy, PartialEq, Eq)]
314pub struct SerializerField {
315    pub name: &'static str,
316    pub source: &'static str,
317    pub read_only: bool,
318    pub write_only: bool,
319    pub rust_type: &'static str,
320    pub related_model: Option<&'static str>,
321    pub many: bool,
322}
323
324/// A typed forward foreign-key relation from one model to another.
325#[derive(Debug, Clone, Copy)]
326pub struct BelongsTo<From, To, Relation = (), Key = i64> {
327    field: ColumnRef,
328    getter: fn(&From) -> Key,
329    alias: &'static str,
330    related_name: &'static str,
331    _marker: PhantomData<fn() -> (From, To, Relation, Key)>,
332}
333
334impl<From, To, Relation, Key> BelongsTo<From, To, Relation, Key> {
335    pub const fn new(
336        table: &'static str,
337        column: &'static str,
338        getter: fn(&From) -> Key,
339        alias: &'static str,
340        related_name: &'static str,
341    ) -> Self {
342        Self {
343            field: ColumnRef::new(table, column),
344            getter,
345            alias,
346            related_name,
347            _marker: PhantomData,
348        }
349    }
350
351    pub const fn field(&self) -> ColumnRef {
352        self.field
353    }
354
355    pub const fn alias(&self) -> &'static str {
356        self.alias
357    }
358
359    pub const fn related_field<T>(&self, field: ModelField<To, T>) -> JoinedField<T> {
360        JoinedField::new(ColumnRef::new(self.alias, field.column().name))
361    }
362
363    pub fn foreign_key(&self, model: &From) -> Key {
364        (self.getter)(model)
365    }
366
367    pub const fn reverse(&self) -> HasMany<To, From, Relation, Key> {
368        HasMany {
369            field: self.field,
370            getter: self.getter,
371            related_name: self.related_name,
372            _marker: PhantomData,
373        }
374    }
375}
376
377/// A typed reverse foreign-key relation from one model to many related models.
378#[derive(Debug, Clone, Copy)]
379pub struct HasMany<From, To, Relation = (), Key = i64> {
380    field: ColumnRef,
381    getter: fn(&To) -> Key,
382    related_name: &'static str,
383    _marker: PhantomData<fn() -> (From, To, Relation, Key)>,
384}
385
386impl<From, To, Relation, Key> HasMany<From, To, Relation, Key> {
387    pub const fn field(&self) -> ColumnRef {
388        self.field
389    }
390
391    pub fn foreign_key(&self, model: &To) -> Key {
392        (self.getter)(model)
393    }
394
395    pub const fn related_name(&self) -> &'static str {
396        self.related_name
397    }
398}
399
400pub struct SelectQuery<M> {
401    ast: SelectAst,
402    _model: PhantomData<M>,
403}
404
405impl<M: Model> SelectQuery<M> {
406    pub fn new() -> Self {
407        let table = M::table_name();
408        let columns = M::columns()
409            .iter()
410            .map(|column| ColumnRef::new(table, column))
411            .collect();
412        Self {
413            ast: SelectAst {
414                table: TableRef::new(table),
415                columns,
416                joins: Vec::new(),
417                filter: None,
418                order_by: Vec::new(),
419                limit: None,
420                offset: None,
421            },
422            _model: PhantomData,
423        }
424    }
425    pub fn filter(mut self, expr: Expr) -> Self {
426        self.ast.filter = Some(
427            self.ast
428                .filter
429                .map_or(expr.clone(), |previous| previous.and(expr)),
430        );
431        self
432    }
433    pub fn order_by(mut self, order: OrderBy) -> Self {
434        self.ast.order_by.push(order);
435        self
436    }
437    pub fn limit(mut self, limit: u64) -> Self {
438        self.ast.limit = Some(limit);
439        self
440    }
441    pub fn offset(mut self, offset: u64) -> Self {
442        self.ast.offset = Some(offset);
443        self
444    }
445    pub fn into_ast(self) -> Result<QueryAst, QueryBuildError> {
446        let mut tables = vec![self.ast.table.name];
447        for join in &self.ast.joins {
448            tables.push(join.table.name);
449            tables.push(join.alias);
450        }
451        validate_expr_tables(self.ast.filter.as_ref(), &tables)?;
452        for join in &self.ast.joins {
453            validate_expr_tables(Some(&join.on), &tables)?;
454        }
455        Ok(QueryAst::Select(self.ast))
456    }
457
458    #[cfg(feature = "sqlite")]
459    pub(crate) fn into_select_ast(self) -> Result<SelectAst, QueryBuildError> {
460        match self.into_ast()? {
461            QueryAst::Select(select) => Ok(select),
462            _ => unreachable!(),
463        }
464    }
465
466    pub fn into_joined_ast<R: Model, Relation>(
467        self,
468        relation: BelongsTo<M, R, Relation>,
469    ) -> Result<QueryAst, QueryBuildError> {
470        self.into_joined_ast_with_kind(relation, JoinType::Inner)
471    }
472
473    pub fn into_optional_joined_ast<R: Model, Relation>(
474        self,
475        relation: BelongsTo<M, R, Relation, Option<i64>>,
476    ) -> Result<QueryAst, QueryBuildError> {
477        self.into_joined_ast_with_kind(relation, JoinType::Left)
478    }
479
480    fn into_joined_ast_with_kind<R: Model, Relation, Key>(
481        mut self,
482        relation: BelongsTo<M, R, Relation, Key>,
483        kind: JoinType,
484    ) -> Result<QueryAst, QueryBuildError> {
485        self.ast.columns.extend(
486            R::columns()
487                .iter()
488                .map(|column| ColumnRef::new(relation.alias(), column)),
489        );
490        self.ast.joins.push(JoinAst {
491            table: TableRef::new(R::table_name()),
492            alias: relation.alias(),
493            kind,
494            on: Expr::Compare {
495                left: Box::new(Expr::Column(relation.field())),
496                op: CompareOp::Eq,
497                right: Box::new(Expr::Column(ColumnRef::new(
498                    relation.alias(),
499                    R::primary_key().column().name,
500                ))),
501            },
502        });
503        self.into_ast()
504    }
505}
506
507pub struct InsertQuery<M> {
508    ast: InsertAst,
509    _model: PhantomData<M>,
510}
511
512impl<M: Model> InsertQuery<M> {
513    pub fn new() -> Self {
514        Self {
515            ast: InsertAst {
516                table: TableRef::new(M::table_name()),
517                values: Vec::new(),
518                returning: Vec::new(),
519            },
520            _model: PhantomData,
521        }
522    }
523    pub fn set<T, V>(mut self, field: ModelField<M, T>, value: V) -> Self
524    where
525        V: QueryValue<T>,
526    {
527        self.ast.values.push(InsertValue {
528            column: field.column(),
529            value: value.into_query_value(),
530        });
531        self
532    }
533    pub fn returning_all(mut self) -> Self {
534        self.ast.returning = M::columns()
535            .iter()
536            .map(|column| ColumnRef::new(M::table_name(), column))
537            .collect();
538        self
539    }
540    pub fn into_ast(self) -> Result<QueryAst, QueryBuildError> {
541        if self.ast.values.is_empty() {
542            return Err(QueryBuildError::EmptyInsert);
543        }
544        validate_unique_columns(self.ast.values.iter().map(|value| &value.column))?;
545        Ok(QueryAst::Insert(self.ast))
546    }
547}
548
549pub struct UpdateQuery<M> {
550    ast: UpdateAst,
551    allow_all: bool,
552    _model: PhantomData<M>,
553}
554
555impl<M: Model> UpdateQuery<M> {
556    pub fn new() -> Self {
557        Self {
558            ast: UpdateAst {
559                table: TableRef::new(M::table_name()),
560                assignments: Vec::new(),
561                filter: None,
562                returning: Vec::new(),
563                allow_all: false,
564            },
565            allow_all: false,
566            _model: PhantomData,
567        }
568    }
569    pub fn set<T, V>(mut self, field: ModelField<M, T>, value: V) -> Self
570    where
571        V: QueryValue<T>,
572    {
573        self.ast.assignments.push(Assignment {
574            column: field.column(),
575            value: value.into_query_value(),
576        });
577        self
578    }
579    pub fn filter(mut self, expr: Expr) -> Self {
580        self.ast.filter = Some(
581            self.ast
582                .filter
583                .map_or(expr.clone(), |previous| previous.and(expr)),
584        );
585        self
586    }
587    pub fn returning_all(mut self) -> Self {
588        self.ast.returning = M::columns()
589            .iter()
590            .map(|column| ColumnRef::new(M::table_name(), column))
591            .collect();
592        self
593    }
594    pub fn allow_all(mut self) -> Self {
595        self.allow_all = true;
596        self
597    }
598    pub fn into_ast(mut self) -> Result<QueryAst, QueryBuildError> {
599        for managed in M::managed_update_values() {
600            self.ast
601                .assignments
602                .retain(|assignment| assignment.column.name != managed.column.name);
603            self.ast.assignments.push(managed);
604        }
605        if self.ast.assignments.is_empty() {
606            return Err(QueryBuildError::EmptyUpdate);
607        }
608        if self.ast.filter.is_none() && !self.allow_all {
609            return Err(QueryBuildError::MissingFilter);
610        }
611        let primary_key = M::primary_key().column();
612        if self
613            .ast
614            .assignments
615            .iter()
616            .any(|assignment| assignment.column == primary_key)
617        {
618            return Err(QueryBuildError::PrimaryKeyUpdate);
619        }
620        validate_unique_columns(
621            self.ast
622                .assignments
623                .iter()
624                .map(|assignment| &assignment.column),
625        )?;
626        validate_expr_table(self.ast.filter.as_ref(), self.ast.table.name)?;
627        self.ast.allow_all = self.allow_all;
628        Ok(QueryAst::Update(self.ast))
629    }
630}
631
632pub struct DeleteQuery<M> {
633    ast: DeleteAst,
634    allow_all: bool,
635    _model: PhantomData<M>,
636}
637
638impl<M: Model> DeleteQuery<M> {
639    pub fn new() -> Self {
640        Self {
641            ast: DeleteAst {
642                table: TableRef::new(M::table_name()),
643                filter: None,
644                allow_all: false,
645            },
646            allow_all: false,
647            _model: PhantomData,
648        }
649    }
650    pub fn filter(mut self, expr: Expr) -> Self {
651        self.ast.filter = Some(
652            self.ast
653                .filter
654                .map_or(expr.clone(), |previous| previous.and(expr)),
655        );
656        self
657    }
658    pub fn allow_all(mut self) -> Self {
659        self.allow_all = true;
660        self
661    }
662    pub fn into_ast(mut self) -> Result<QueryAst, QueryBuildError> {
663        if self.ast.filter.is_none() && !self.allow_all {
664            return Err(QueryBuildError::MissingFilter);
665        }
666        validate_expr_table(self.ast.filter.as_ref(), self.ast.table.name)?;
667        self.ast.allow_all = self.allow_all;
668        Ok(QueryAst::Delete(self.ast))
669    }
670}
671
672fn validate_unique_columns<'a>(
673    columns: impl Iterator<Item = &'a ColumnRef>,
674) -> Result<(), QueryBuildError> {
675    let mut names = HashSet::new();
676    for column in columns {
677        if !names.insert(column.name) {
678            return Err(QueryBuildError::DuplicateColumn(column.name));
679        }
680    }
681    Ok(())
682}
683
684fn validate_columns_table<'a>(
685    table: &'static str,
686    columns: impl Iterator<Item = &'a ColumnRef>,
687) -> Result<(), QueryBuildError> {
688    for column in columns {
689        validate_column_table(column, table)?;
690    }
691    Ok(())
692}
693
694fn validate_expr_table(expr: Option<&Expr>, table: &'static str) -> Result<(), QueryBuildError> {
695    let Some(expr) = expr else {
696        return Ok(());
697    };
698    match expr {
699        Expr::Column(column) => validate_column_table(column, table),
700        Expr::Value(_) => Ok(()),
701        Expr::Like { left, pattern } => {
702            validate_expr_table(Some(left), table)?;
703            validate_expr_table(Some(pattern), table)
704        }
705        Expr::Compare { left, right, .. }
706        | Expr::And { left, right }
707        | Expr::Or { left, right } => {
708            validate_expr_table(Some(left), table)?;
709            validate_expr_table(Some(right), table)
710        }
711        Expr::In { left, .. } => validate_expr_table(Some(left), table),
712        Expr::Not(expr) | Expr::IsNull(expr) | Expr::IsNotNull(expr) => {
713            validate_expr_table(Some(expr), table)
714        }
715    }
716}
717
718fn validate_column_table(column: &ColumnRef, table: &'static str) -> Result<(), QueryBuildError> {
719    if column.table == table {
720        Ok(())
721    } else {
722        Err(QueryBuildError::ForeignTableColumn {
723            column: column.name,
724            table: column.table,
725            expected_table: table,
726        })
727    }
728}
729
730fn validate_expr_tables(
731    expr: Option<&Expr>,
732    tables: &[&'static str],
733) -> Result<(), QueryBuildError> {
734    let Some(expr) = expr else {
735        return Ok(());
736    };
737    match expr {
738        Expr::Column(column) => {
739            if tables.contains(&column.table) {
740                Ok(())
741            } else {
742                Err(QueryBuildError::ForeignTableColumn {
743                    column: column.name,
744                    table: column.table,
745                    expected_table: tables[0],
746                })
747            }
748        }
749        Expr::Like { left, pattern } => {
750            validate_expr_tables(Some(left), tables)?;
751            validate_expr_tables(Some(pattern), tables)
752        }
753        Expr::Value(_) => Ok(()),
754        Expr::Compare { left, right, .. }
755        | Expr::And { left, right }
756        | Expr::Or { left, right } => {
757            validate_expr_tables(Some(left), tables)?;
758            validate_expr_tables(Some(right), tables)
759        }
760        Expr::In { left, .. } => validate_expr_tables(Some(left), tables),
761        Expr::Not(expr) | Expr::IsNull(expr) | Expr::IsNotNull(expr) => {
762            validate_expr_tables(Some(expr), tables)
763        }
764    }
765}