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