umbral_core/orm/mod.rs
1//! The ORM: declarative models, typed queries, and SQL generation.
2//!
3//! At M1 the design is intentionally narrow: one hardcoded model (`Post`),
4//! a single QuerySet type backed by sea-query, and basic predicates. No
5//! `Model` trait abstraction yet (that's M2), no derive macro (that's M3),
6//! no joins / aggregates / relations (later milestones). See
7//! `docs/specs/03-orm-querysets.md` for the target shape and the
8//! M1→M2→M3 progression.
9//!
10//! Module layout:
11//!
12//! - `post` — the hardcoded `Post` struct and its sibling column module.
13//! - `column` — column types (`StrCol`, `IntCol`, `NullableDateTimeCol`,
14//! etc.) carrying inherent methods that build `Predicate`s.
15//! - `queryset` — `QuerySet<T>` and `Manager<T>`, the chainable / lazy
16//! SQL builder plus its terminal methods.
17//!
18//! The shared types — `Predicate<T>` and `OrderExpr<T>` — live here in
19//! `mod.rs` so both `column` and `queryset` can reach them without
20//! crossing each other.
21
22pub mod aggregate;
23pub mod audit;
24pub mod choices;
25pub mod cleaners;
26pub mod column;
27pub mod dynamic;
28pub mod expr;
29pub mod file_field;
30pub mod foreign_key;
31pub mod forms_runtime;
32pub mod m2m;
33pub mod masked;
34pub mod model;
35pub mod multichoice;
36pub mod one_to_one;
37pub mod post;
38pub mod queryset;
39pub mod reverse_accessor;
40pub mod reverse_set;
41pub mod search;
42pub mod secrets;
43pub mod soft_delete_cascade;
44pub mod tsvector;
45pub mod validation;
46pub mod validators;
47pub mod write;
48
49use std::marker::PhantomData;
50use std::ops::{BitAnd, BitOr};
51
52pub use aggregate::{Aggregate, AggregateKind};
53
54/// Canonical string key for a primary-key (or FK) value, for bucketing
55/// relation children by their parent's PK in a `HashMap` / `HashSet`.
56///
57/// `serde_json::Value` is not `Hash`, and the relation-hydration paths
58/// need to group children by parent PK whatever the PK type — `i64`,
59/// `String`, `uuid::Uuid`. This is the **PK-agnostic** replacement for the
60/// historical `i64` keys: the value is namespaced by shape (`n:` number,
61/// `s:` string, `o:` other) so a numeric `42` and the string `"42"` never
62/// collide in the same bucket. Pairs with
63/// [`Model::pk_as_json`](crate::orm::Model::pk_as_json) and
64/// [`HydrateRelated::fk_id_for`](crate::orm::HydrateRelated::fk_id_for),
65/// both of which return a `serde_json::Value`.
66pub fn pk_key(value: &serde_json::Value) -> String {
67 match value {
68 serde_json::Value::Number(n) => format!("n:{n}"),
69 serde_json::Value::String(s) => format!("s:{s}"),
70 other => format!("o:{other}"),
71 }
72}
73
74/// Escape SQL `LIKE` wildcards in a user-supplied **literal** substring.
75///
76/// `contains` / `startswith` / `icontains` / the REST `__contains`
77/// family treat their argument as a literal to find, then wrap it in
78/// structural `%`. Without escaping, a user typing `%`, `_` or `\` would
79/// inject wildcards into the pattern — a search for `"100%"` matches
80/// every row starting with `100`, and `"a_b"` matches `axb` (ORM-1).
81/// This backslash-escapes the three LIKE metacharacters; the caller then
82/// adds its own structural `%` and pairs the predicate with
83/// `LikeExpr::escape('\\')` so the database honours the escape. Not SQL
84/// injection (the pattern is still a bound parameter) — a match-semantics
85/// correctness fix. The user-facing `.like()` / `.ilike()` builders take
86/// a raw pattern on purpose and must NOT call this.
87pub fn escape_like_literal(s: &str) -> String {
88 let mut out = String::with_capacity(s.len());
89 for ch in s.chars() {
90 if matches!(ch, '\\' | '%' | '_') {
91 out.push('\\');
92 }
93 out.push(ch);
94 }
95 out
96}
97
98/// A typed wrapper around a `sea_query::SelectStatement` for use in
99/// `col IN (SELECT col FROM ...)` predicates (gap #26).
100///
101/// Built by [`QuerySet::into_subquery`] or
102/// [`Manager::into_subquery`]; consumed by `IntCol::in_subquery` /
103/// `ForeignKeyCol::in_subquery` to produce a `Predicate`. The inner
104/// SelectStatement only knows the projected column the caller
105/// requested.
106pub struct Subquery {
107 inner: sea_query::SelectStatement,
108}
109
110impl Subquery {
111 /// Construct from a `SelectStatement` (internal — the
112 /// QuerySet/Manager helpers are the supported entry points).
113 pub(crate) fn from_select(inner: sea_query::SelectStatement) -> Self {
114 Self { inner }
115 }
116
117 /// Consume the wrapper and hand back the inner SelectStatement
118 /// — sea-query's `in_subquery` builder takes ownership.
119 pub(crate) fn into_statement(self) -> sea_query::SelectStatement {
120 self.inner
121 }
122}
123pub use choices::ChoiceField;
124pub use dynamic::{
125 Cmp, CsvImportReport, DynError, DynQuerySet, decode_to_string, import_table_rows,
126 never_matches, typed_cmp_condition, typed_eq_condition, typed_json_value,
127};
128pub use expr::{F, FColExt, FExpr, Q};
129pub use file_field::{FileField, ImageField};
130pub use foreign_key::ForeignKey;
131pub use m2m::{M2M, load_junction_selection, set_junction_dynamic};
132pub use masked::{MaskError, MaskKeyring, Masked, set_mask_keyring};
133pub use model::{
134 ArrayElement, FieldSpec, FkAction, HydrateRelated, M2MRelationSpec, Model,
135 OneToOneRelationSpec, PrimaryKey, ReverseFkRelationSpec, SqlType,
136};
137pub use multichoice::MultiChoice;
138pub use one_to_one::OneToOne;
139pub use post::Post;
140pub use queryset::{GetError, JoinKind, Manager, QuerySet, QuerySetTx, TryForEachError};
141pub use reverse_accessor::{ReverseError, ReverseRelations};
142pub use reverse_set::ReverseSet;
143pub use search::{Search, SearchHit, SearchSources, Searchable};
144pub use tsvector::TsVector;
145pub use validators::{Email, Slug, Url, ValidatorError, validate_text_format};
146pub use write::{SaveError, slugify};
147
148/// A typed boolean condition on rows of `T`.
149///
150/// Built by inherent methods on the column types in `column` and passed
151/// to `QuerySet::filter` / `QuerySet::exclude` to constrain a query. The
152/// type parameter `T` ties the predicate to its model so a `Predicate<Post>`
153/// can't accidentally be applied to a `QuerySet<Comment>`.
154///
155/// `Clone` is implemented manually (rather than derived) so the bound does
156/// not bleed onto `T` — `sea_query::SimpleExpr` is `Clone` regardless of
157/// whether `T` is. The `get_or_create` / `update_or_create` convergence path
158/// needs to re-issue the same predicate after a `UniqueViolation` re-fetch.
159pub struct Predicate<T> {
160 /// The default condition. Renders correctly on Postgres and on
161 /// any backend whose operators match sea-query's defaults.
162 pub(crate) cond: sea_query::SimpleExpr,
163 /// Optional SQLite-specific override. Set by predicates that need
164 /// dialect-specific rendering — Phase 4.2.2 JSON operators are the
165 /// first consumer (`json_extract` instead of Postgres's `->` /
166 /// `->>`). When `None`, `cond` is used for both backends. The
167 /// QuerySet picks at terminal time based on the resolved pool
168 /// variant.
169 pub(crate) cond_sqlite: Option<sea_query::SimpleExpr>,
170 _phantom: PhantomData<T>,
171}
172
173impl<T> Predicate<T> {
174 /// Build a `col = value` predicate by column name. Use when the
175 /// column constant isn't reachable at the call site — typically
176 /// generic-over-`T` helper functions in plugin code (e.g.
177 /// `authenticate<U: UserModel>` filtering on `"username"` without
178 /// knowing `U`'s column module).
179 ///
180 /// The typed sibling-module path (`my_model::USERNAME.eq(...)`) is
181 /// preferred when you have a concrete `T`, because it catches typos
182 /// at compile time. This constructor is the escape hatch for
183 /// genuinely-generic code.
184 pub fn col_eq(col: &'static str, value: impl Into<sea_query::Value>) -> Self {
185 let expr = sea_query::Expr::col(sea_query::Alias::new(col)).eq(value);
186 Self::new(expr)
187 }
188
189 pub(crate) fn new(cond: sea_query::SimpleExpr) -> Self {
190 Self {
191 cond,
192 cond_sqlite: None,
193 _phantom: PhantomData,
194 }
195 }
196
197 /// Construct a predicate that renders differently on each backend.
198 /// Phase 4.2.2's JSON-operator path uses this to ship one
199 /// predicate that resolves to `col -> 'a' ->> 'b'` under Postgres
200 /// and `json_extract(col, '$.a.b')` under SQLite.
201 pub(crate) fn new_with_sqlite(
202 cond: sea_query::SimpleExpr,
203 cond_sqlite: sea_query::SimpleExpr,
204 ) -> Self {
205 Self {
206 cond,
207 cond_sqlite: Some(cond_sqlite),
208 _phantom: PhantomData,
209 }
210 }
211
212 /// Pick the SimpleExpr appropriate for `backend_name` (`"sqlite"`
213 /// or `"postgres"`). Falls back to the default `cond` when no
214 /// SQLite override is set or the backend isn't SQLite. Cloning
215 /// the SimpleExpr is cheap (it's a tree of small enum values).
216 pub(crate) fn cond_for(&self, backend_name: &str) -> sea_query::SimpleExpr {
217 match backend_name {
218 "sqlite" => self
219 .cond_sqlite
220 .clone()
221 .unwrap_or_else(|| self.cond.clone()),
222 _ => self.cond.clone(),
223 }
224 }
225}
226
227/// Manual `Clone` for `Predicate<T>`.
228///
229/// `sea_query::SimpleExpr` is `Clone` regardless of `T`, so we implement the
230/// trait by hand rather than deriving it. A derived impl would add an
231/// unnecessary `T: Clone` bound that would propagate to every QuerySet caller.
232impl<T> Clone for Predicate<T> {
233 fn clone(&self) -> Self {
234 Self {
235 cond: self.cond.clone(),
236 cond_sqlite: self.cond_sqlite.clone(),
237 _phantom: PhantomData,
238 }
239 }
240}
241
242/// Compose two predicates with logical AND. Both per-backend variants
243/// combine element-wise — if either side has a SQLite override, the
244/// combined predicate carries the AND of (lhs's sqlite-or-default)
245/// with (rhs's sqlite-or-default). When neither side overrides, the
246/// combined predicate keeps `cond_sqlite = None` so the default render
247/// path stays uniform.
248impl<T> BitAnd for Predicate<T> {
249 type Output = Predicate<T>;
250 fn bitand(self, rhs: Predicate<T>) -> Predicate<T> {
251 let any_sqlite_override = self.cond_sqlite.is_some() || rhs.cond_sqlite.is_some();
252 let combined_sqlite = if any_sqlite_override {
253 let lhs_sql = self
254 .cond_sqlite
255 .clone()
256 .unwrap_or_else(|| self.cond.clone());
257 let rhs_sql = rhs.cond_sqlite.clone().unwrap_or_else(|| rhs.cond.clone());
258 Some(lhs_sql.and(rhs_sql))
259 } else {
260 None
261 };
262 Predicate {
263 cond: self.cond.and(rhs.cond),
264 cond_sqlite: combined_sqlite,
265 _phantom: PhantomData,
266 }
267 }
268}
269
270/// Compose two predicates with logical OR. Same backend-variant story
271/// as [`BitAnd`].
272impl<T> BitOr for Predicate<T> {
273 type Output = Predicate<T>;
274 fn bitor(self, rhs: Predicate<T>) -> Predicate<T> {
275 let any_sqlite_override = self.cond_sqlite.is_some() || rhs.cond_sqlite.is_some();
276 let combined_sqlite = if any_sqlite_override {
277 let lhs_sql = self
278 .cond_sqlite
279 .clone()
280 .unwrap_or_else(|| self.cond.clone());
281 let rhs_sql = rhs.cond_sqlite.clone().unwrap_or_else(|| rhs.cond.clone());
282 Some(lhs_sql.or(rhs_sql))
283 } else {
284 None
285 };
286 Predicate {
287 cond: self.cond.or(rhs.cond),
288 cond_sqlite: combined_sqlite,
289 _phantom: PhantomData,
290 }
291 }
292}
293
294/// An ordering directive for one column.
295///
296/// Built by `.asc()` / `.desc()` on a column constant and passed to
297/// `QuerySet::order_by`. The type parameter `T` ties the directive to its
298/// model the same way `Predicate<T>` does.
299pub struct OrderExpr<T> {
300 pub(crate) column: &'static str,
301 pub(crate) descending: bool,
302 _phantom: PhantomData<T>,
303}
304
305impl<T> OrderExpr<T> {
306 pub(crate) fn new(column: &'static str, descending: bool) -> Self {
307 Self {
308 column,
309 descending,
310 _phantom: PhantomData,
311 }
312 }
313}