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                validate_unique_columns(query.values.iter().map(|value| &value.column))?;
209                validate_columns_table(
210                    query.table.name,
211                    query.values.iter().map(|value| &value.column),
212                )
213            }
214            Self::Update(query) => {
215                if query.assignments.is_empty() {
216                    return Err(QueryBuildError::EmptyUpdate);
217                }
218                if query.filter.is_none() && !query.allow_all {
219                    return Err(QueryBuildError::MissingFilter);
220                }
221                validate_unique_columns(
222                    query
223                        .assignments
224                        .iter()
225                        .map(|assignment| &assignment.column),
226                )?;
227                validate_columns_table(
228                    query.table.name,
229                    query
230                        .assignments
231                        .iter()
232                        .map(|assignment| &assignment.column),
233                )?;
234                validate_expr_table(query.filter.as_ref(), query.table.name)
235            }
236            Self::Delete(query) => {
237                if query.filter.is_none() && !query.allow_all {
238                    return Err(QueryBuildError::MissingFilter);
239                }
240                validate_expr_table(query.filter.as_ref(), query.table.name)
241            }
242            Self::CreateTable(query) => query
243                .schema
244                .validate()
245                .map_err(|error| QueryBuildError::InvalidSchema(format!("{error:?}"))),
246        }
247    }
248}
249
250/// Trait implemented by `#[derive(Model)]` for ORM models.
251pub trait Model: Sized {
252    fn table_name() -> &'static str;
253    fn columns() -> &'static [&'static str];
254    /// Returns the model's generated integer primary-key field.
255    fn primary_key() -> ModelField<Self, i64>;
256    fn primary_key_value(&self) -> i64 {
257        panic!("Model::primary_key_value must be implemented for eager relations")
258    }
259    fn schema() -> TableSchema;
260    fn from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<Self>;
261    fn from_row_at(row: &rusqlite::Row<'_>, offset: usize) -> rusqlite::Result<Self> {
262        if offset == 0 {
263            Self::from_row(row)
264        } else {
265            Err(rusqlite::Error::InvalidColumnIndex(offset))
266        }
267    }
268    fn insert_values(&self) -> Vec<InsertValue>;
269    fn managed_update_values() -> Vec<Assignment> {
270        Vec::new()
271    }
272    fn query() -> SelectQuery<Self> {
273        SelectQuery::new()
274    }
275    fn insert() -> InsertQuery<Self> {
276        InsertQuery::new()
277    }
278    fn update() -> UpdateQuery<Self> {
279        UpdateQuery::new()
280    }
281    fn delete() -> DeleteQuery<Self> {
282        DeleteQuery::new()
283    }
284    fn create_table() -> CreateTableQuery<Self> {
285        CreateTableQuery::new(Self::schema())
286    }
287}
288
289/// Converts a materialized ORM model into an API representation.
290pub trait ModelSerializer: serde::Serialize + Sized {
291    type Model: Model;
292    type Input;
293
294    fn from_input(input: Self::Input) -> Self;
295
296    fn to_json(input: Self::Input) -> Result<serde_json::Value, serde_json::Error> {
297        serde_json::to_value(Self::from_input(input))
298    }
299
300    fn fields() -> &'static [SerializerField] {
301        &[]
302    }
303}
304
305/// Identifies the actual foreign-key column behind a serializer relation.
306pub trait RelationSource {
307    const SOURCE: &'static str;
308}
309
310#[derive(Debug, Clone, Copy, PartialEq, Eq)]
311pub struct SerializerField {
312    pub name: &'static str,
313    pub source: &'static str,
314    pub read_only: bool,
315    pub write_only: bool,
316    pub rust_type: &'static str,
317    pub related_model: Option<&'static str>,
318    pub many: bool,
319}
320
321/// A typed forward foreign-key relation from one model to another.
322#[derive(Debug, Clone, Copy)]
323pub struct BelongsTo<From, To, Relation = (), Key = i64> {
324    field: ColumnRef,
325    getter: fn(&From) -> Key,
326    alias: &'static str,
327    related_name: &'static str,
328    _marker: PhantomData<fn() -> (From, To, Relation, Key)>,
329}
330
331impl<From, To, Relation, Key> BelongsTo<From, To, Relation, Key> {
332    pub const fn new(
333        table: &'static str,
334        column: &'static str,
335        getter: fn(&From) -> Key,
336        alias: &'static str,
337        related_name: &'static str,
338    ) -> Self {
339        Self {
340            field: ColumnRef::new(table, column),
341            getter,
342            alias,
343            related_name,
344            _marker: PhantomData,
345        }
346    }
347
348    pub const fn field(&self) -> ColumnRef {
349        self.field
350    }
351
352    pub const fn alias(&self) -> &'static str {
353        self.alias
354    }
355
356    pub const fn related_field<T>(&self, field: ModelField<To, T>) -> JoinedField<T> {
357        JoinedField::new(ColumnRef::new(self.alias, field.column().name))
358    }
359
360    pub fn foreign_key(&self, model: &From) -> Key {
361        (self.getter)(model)
362    }
363
364    pub const fn reverse(&self) -> HasMany<To, From, Relation, Key> {
365        HasMany {
366            field: self.field,
367            getter: self.getter,
368            related_name: self.related_name,
369            _marker: PhantomData,
370        }
371    }
372}
373
374/// A typed reverse foreign-key relation from one model to many related models.
375#[derive(Debug, Clone, Copy)]
376pub struct HasMany<From, To, Relation = (), Key = i64> {
377    field: ColumnRef,
378    getter: fn(&To) -> Key,
379    related_name: &'static str,
380    _marker: PhantomData<fn() -> (From, To, Relation, Key)>,
381}
382
383impl<From, To, Relation, Key> HasMany<From, To, Relation, Key> {
384    pub const fn field(&self) -> ColumnRef {
385        self.field
386    }
387
388    pub fn foreign_key(&self, model: &To) -> Key {
389        (self.getter)(model)
390    }
391
392    pub const fn related_name(&self) -> &'static str {
393        self.related_name
394    }
395}
396
397pub struct SelectQuery<M> {
398    ast: SelectAst,
399    _model: PhantomData<M>,
400}
401
402impl<M: Model> SelectQuery<M> {
403    pub fn new() -> Self {
404        let table = M::table_name();
405        let columns = M::columns()
406            .iter()
407            .map(|column| ColumnRef::new(table, column))
408            .collect();
409        Self {
410            ast: SelectAst {
411                table: TableRef::new(table),
412                columns,
413                joins: Vec::new(),
414                filter: None,
415                order_by: Vec::new(),
416                limit: None,
417                offset: None,
418            },
419            _model: PhantomData,
420        }
421    }
422    pub fn filter(mut self, expr: Expr) -> Self {
423        self.ast.filter = Some(
424            self.ast
425                .filter
426                .map_or(expr.clone(), |previous| previous.and(expr)),
427        );
428        self
429    }
430    pub fn order_by(mut self, order: OrderBy) -> Self {
431        self.ast.order_by.push(order);
432        self
433    }
434    pub fn limit(mut self, limit: u64) -> Self {
435        self.ast.limit = Some(limit);
436        self
437    }
438    pub fn offset(mut self, offset: u64) -> Self {
439        self.ast.offset = Some(offset);
440        self
441    }
442    pub fn into_ast(self) -> Result<QueryAst, QueryBuildError> {
443        let mut tables = vec![self.ast.table.name];
444        for join in &self.ast.joins {
445            tables.push(join.table.name);
446            tables.push(join.alias);
447        }
448        validate_expr_tables(self.ast.filter.as_ref(), &tables)?;
449        for join in &self.ast.joins {
450            validate_expr_tables(Some(&join.on), &tables)?;
451        }
452        Ok(QueryAst::Select(self.ast))
453    }
454
455    #[cfg(feature = "sqlite")]
456    pub(crate) fn into_select_ast(self) -> Result<SelectAst, QueryBuildError> {
457        match self.into_ast()? {
458            QueryAst::Select(select) => Ok(select),
459            _ => unreachable!(),
460        }
461    }
462
463    pub fn into_joined_ast<R: Model, Relation>(
464        self,
465        relation: BelongsTo<M, R, Relation>,
466    ) -> Result<QueryAst, QueryBuildError> {
467        self.into_joined_ast_with_kind(relation, JoinType::Inner)
468    }
469
470    pub fn into_optional_joined_ast<R: Model, Relation>(
471        self,
472        relation: BelongsTo<M, R, Relation, Option<i64>>,
473    ) -> Result<QueryAst, QueryBuildError> {
474        self.into_joined_ast_with_kind(relation, JoinType::Left)
475    }
476
477    fn into_joined_ast_with_kind<R: Model, Relation, Key>(
478        mut self,
479        relation: BelongsTo<M, R, Relation, Key>,
480        kind: JoinType,
481    ) -> Result<QueryAst, QueryBuildError> {
482        self.ast.columns.extend(
483            R::columns()
484                .iter()
485                .map(|column| ColumnRef::new(relation.alias(), column)),
486        );
487        self.ast.joins.push(JoinAst {
488            table: TableRef::new(R::table_name()),
489            alias: relation.alias(),
490            kind,
491            on: Expr::Compare {
492                left: Box::new(Expr::Column(relation.field())),
493                op: CompareOp::Eq,
494                right: Box::new(Expr::Column(ColumnRef::new(
495                    relation.alias(),
496                    R::primary_key().column().name,
497                ))),
498            },
499        });
500        self.into_ast()
501    }
502}
503
504pub struct InsertQuery<M> {
505    ast: InsertAst,
506    _model: PhantomData<M>,
507}
508
509impl<M: Model> InsertQuery<M> {
510    pub fn new() -> Self {
511        Self {
512            ast: InsertAst {
513                table: TableRef::new(M::table_name()),
514                values: Vec::new(),
515                returning: Vec::new(),
516            },
517            _model: PhantomData,
518        }
519    }
520    pub fn set<T, V>(mut self, field: ModelField<M, T>, value: V) -> Self
521    where
522        V: QueryValue<T>,
523    {
524        self.ast.values.push(InsertValue {
525            column: field.column(),
526            value: value.into_query_value(),
527        });
528        self
529    }
530    pub fn returning_all(mut self) -> Self {
531        self.ast.returning = M::columns()
532            .iter()
533            .map(|column| ColumnRef::new(M::table_name(), column))
534            .collect();
535        self
536    }
537    pub fn into_ast(self) -> Result<QueryAst, QueryBuildError> {
538        validate_unique_columns(self.ast.values.iter().map(|value| &value.column))?;
539        Ok(QueryAst::Insert(self.ast))
540    }
541}
542
543pub struct UpdateQuery<M> {
544    ast: UpdateAst,
545    allow_all: bool,
546    _model: PhantomData<M>,
547}
548
549impl<M: Model> UpdateQuery<M> {
550    pub fn new() -> Self {
551        Self {
552            ast: UpdateAst {
553                table: TableRef::new(M::table_name()),
554                assignments: Vec::new(),
555                filter: None,
556                returning: Vec::new(),
557                allow_all: false,
558            },
559            allow_all: false,
560            _model: PhantomData,
561        }
562    }
563    pub fn set<T, V>(mut self, field: ModelField<M, T>, value: V) -> Self
564    where
565        V: QueryValue<T>,
566    {
567        self.ast.assignments.push(Assignment {
568            column: field.column(),
569            value: value.into_query_value(),
570        });
571        self
572    }
573    pub fn filter(mut self, expr: Expr) -> Self {
574        self.ast.filter = Some(
575            self.ast
576                .filter
577                .map_or(expr.clone(), |previous| previous.and(expr)),
578        );
579        self
580    }
581    pub fn returning_all(mut self) -> Self {
582        self.ast.returning = M::columns()
583            .iter()
584            .map(|column| ColumnRef::new(M::table_name(), column))
585            .collect();
586        self
587    }
588    pub fn allow_all(mut self) -> Self {
589        self.allow_all = true;
590        self
591    }
592    pub fn into_ast(mut self) -> Result<QueryAst, QueryBuildError> {
593        for managed in M::managed_update_values() {
594            self.ast
595                .assignments
596                .retain(|assignment| assignment.column.name != managed.column.name);
597            self.ast.assignments.push(managed);
598        }
599        if self.ast.assignments.is_empty() {
600            return Err(QueryBuildError::EmptyUpdate);
601        }
602        if self.ast.filter.is_none() && !self.allow_all {
603            return Err(QueryBuildError::MissingFilter);
604        }
605        let primary_key = M::primary_key().column();
606        if self
607            .ast
608            .assignments
609            .iter()
610            .any(|assignment| assignment.column == primary_key)
611        {
612            return Err(QueryBuildError::PrimaryKeyUpdate);
613        }
614        validate_unique_columns(
615            self.ast
616                .assignments
617                .iter()
618                .map(|assignment| &assignment.column),
619        )?;
620        validate_expr_table(self.ast.filter.as_ref(), self.ast.table.name)?;
621        self.ast.allow_all = self.allow_all;
622        Ok(QueryAst::Update(self.ast))
623    }
624}
625
626pub struct DeleteQuery<M> {
627    ast: DeleteAst,
628    allow_all: bool,
629    _model: PhantomData<M>,
630}
631
632impl<M: Model> DeleteQuery<M> {
633    pub fn new() -> Self {
634        Self {
635            ast: DeleteAst {
636                table: TableRef::new(M::table_name()),
637                filter: None,
638                allow_all: false,
639            },
640            allow_all: false,
641            _model: PhantomData,
642        }
643    }
644    pub fn filter(mut self, expr: Expr) -> Self {
645        self.ast.filter = Some(
646            self.ast
647                .filter
648                .map_or(expr.clone(), |previous| previous.and(expr)),
649        );
650        self
651    }
652    pub fn allow_all(mut self) -> Self {
653        self.allow_all = true;
654        self
655    }
656    pub fn into_ast(mut self) -> Result<QueryAst, QueryBuildError> {
657        if self.ast.filter.is_none() && !self.allow_all {
658            return Err(QueryBuildError::MissingFilter);
659        }
660        validate_expr_table(self.ast.filter.as_ref(), self.ast.table.name)?;
661        self.ast.allow_all = self.allow_all;
662        Ok(QueryAst::Delete(self.ast))
663    }
664}
665
666fn validate_unique_columns<'a>(
667    columns: impl Iterator<Item = &'a ColumnRef>,
668) -> Result<(), QueryBuildError> {
669    let mut names = HashSet::new();
670    for column in columns {
671        if !names.insert(column.name) {
672            return Err(QueryBuildError::DuplicateColumn(column.name));
673        }
674    }
675    Ok(())
676}
677
678fn validate_columns_table<'a>(
679    table: &'static str,
680    columns: impl Iterator<Item = &'a ColumnRef>,
681) -> Result<(), QueryBuildError> {
682    for column in columns {
683        validate_column_table(column, table)?;
684    }
685    Ok(())
686}
687
688fn validate_expr_table(expr: Option<&Expr>, table: &'static str) -> Result<(), QueryBuildError> {
689    let Some(expr) = expr else {
690        return Ok(());
691    };
692    match expr {
693        Expr::Column(column) => validate_column_table(column, table),
694        Expr::Value(_) => Ok(()),
695        Expr::Like { left, pattern } => {
696            validate_expr_table(Some(left), table)?;
697            validate_expr_table(Some(pattern), table)
698        }
699        Expr::Compare { left, right, .. }
700        | Expr::And { left, right }
701        | Expr::Or { left, right } => {
702            validate_expr_table(Some(left), table)?;
703            validate_expr_table(Some(right), table)
704        }
705        Expr::In { left, .. } => validate_expr_table(Some(left), table),
706        Expr::Not(expr) | Expr::IsNull(expr) | Expr::IsNotNull(expr) => {
707            validate_expr_table(Some(expr), table)
708        }
709    }
710}
711
712fn validate_column_table(column: &ColumnRef, table: &'static str) -> Result<(), QueryBuildError> {
713    if column.table == table {
714        Ok(())
715    } else {
716        Err(QueryBuildError::ForeignTableColumn {
717            column: column.name,
718            table: column.table,
719            expected_table: table,
720        })
721    }
722}
723
724fn validate_expr_tables(
725    expr: Option<&Expr>,
726    tables: &[&'static str],
727) -> Result<(), QueryBuildError> {
728    let Some(expr) = expr else {
729        return Ok(());
730    };
731    match expr {
732        Expr::Column(column) => {
733            if tables.contains(&column.table) {
734                Ok(())
735            } else {
736                Err(QueryBuildError::ForeignTableColumn {
737                    column: column.name,
738                    table: column.table,
739                    expected_table: tables[0],
740                })
741            }
742        }
743        Expr::Like { left, pattern } => {
744            validate_expr_tables(Some(left), tables)?;
745            validate_expr_tables(Some(pattern), tables)
746        }
747        Expr::Value(_) => Ok(()),
748        Expr::Compare { left, right, .. }
749        | Expr::And { left, right }
750        | Expr::Or { left, right } => {
751            validate_expr_tables(Some(left), tables)?;
752            validate_expr_tables(Some(right), tables)
753        }
754        Expr::In { left, .. } => validate_expr_tables(Some(left), tables),
755        Expr::Not(expr) | Expr::IsNull(expr) | Expr::IsNotNull(expr) => {
756            validate_expr_tables(Some(expr), tables)
757        }
758    }
759}