Skip to main content

Crate cratestack_sql

Crate cratestack_sql 

Source
Expand description

Dialect-agnostic SQL primitives shared by the Postgres (cratestack-sqlx) and SQLite (cratestack-rusqlite) backends.

This crate carries the type definitions every backend agrees on:

Rendering SQL strings, executing queries, and any DB-driver coupling live in the backend crates.

Structs§

CoalesceExpr
Left-hand operand of a coalesce-based filter — chain a comparator method to turn it into a FilterExpr.
CoalesceFilter
COALESCE(col_a, col_b, ...) <op> <value> — left-hand expression is the first non-null among the listed columns; right-hand side is a bound value via the usual FilterValue envelope. Lets schemas express the “ranked-fallback compare” pattern that shows up in outbox / scheduler tables, where a single row carries several time columns and the dispatcher wants the earliest non-null one.
CreateDefault
FieldRef
Filter
JsonTextPath
Left-hand operand of a json_get_text filter — chain a comparison method (.eq, .lt, .is_null, …) to produce a FilterExpr.
ModelColumn
ModelDescriptor
OrderCatalog
One model’s order-by surface: its own sortable scalar columns ((api_name, sql_column)) and its own to-one relation edges. Exactly one OrderCatalog is emitted per model, regardless of how many distinct relation paths pass through it.
OrderClause
OrderRelationEdge
One to-one relation edge out of a model. target points at the related model’s own catalog so resolve_order_target can keep walking further segments; to-many relations are never represented here (mirroring the codegen’s existing to-one-only walk), so a key that names one simply fails to resolve.
Orderable
Marker for a path whose hops are all to-one, so a scalar at the end of it can be rendered as a correlated subquery and used for ordering.
PostgresDialect
Postgres dialect — $N placeholders.
Projection
Result of a .select(...)-projected read. Holds the model with only the selected columns populated — non-selected fields carry their type’s Default::default() value ("" for String, 0 for integers, None for Option<T>, etc.).
RelationFilter
RelationHop
One traversed relation edge: the FK linkage plus how the related rows are quantified (ToOne for a plain to-one hop, Some/Every/None for a to-many hop under a quantifier).
RelationInclude
Typed handle for an .include(...) call on a query builder. Carries everything the runtime needs to issue the side-load query for a to-one relation: a function pointer that extracts the FK value from a parent row, and a static descriptor of the related model.
ResolvedOrderTarget
A dotted sort key resolved down to the relation hops to traverse plus the terminal scalar column, ready for crate::order_value_sql.
SpatialPoint
Builder returned by crate::point for assembling a spatial filter. Holds nothing but the lat/lng pair until a comparator is chained.
SqlColumnValue
SqliteDialect
SQLite dialect — ?N placeholders.
Unorderable
Marker for a path that has crossed a to-many hop. Ordering accessors are not implemented for this marker, which reproduces the old guarantee that asc()/desc() simply did not exist past a to-many relation — a compile error, not a runtime failure.
ViewDescriptor

Enums§

ConflictTarget
Conflict target for an upsert. Defaults to the model’s primary key (matching the previous PK-only behavior). Columns lets callers upsert on an arbitrary unique tuple — most commonly a natural key that’s distinct from the PK (e.g. (owner_id, provider) on a per-owner-and-provider settings row, or (pairing_id, slot) on a per-slot envelope).
CreateDefaultType
FilterExpr
FilterOp
FilterValue
JsonFilter
JSON / JSONB filter predicates. Two flavors:
NullOrder
Where NULLs sort relative to non-NULL values. PostgreSQL’s default is NULLS LAST for ASC and NULLS FIRST for DESC; SQLite’s default is NULLS FIRST for both. CrateStack pins the framework default to NULLS LAST so listings stay deterministic across backends and so soft-deleted rows (typed Option<DateTime> that surface as None for visible rows) don’t muscle their way to the top of every listing. Override per-clause via OrderClause::nulls_first when scheduler / outbox queries want fresh-as-null tasks at the head of the queue.
OrderTarget
RelationQuantifier
SortDirection
SpatialFilter
PostGIS spatial filter primitives. v1 ships two ops that cover the “is point inside this zone” / “is this point within radius of that zone” cases — the rest of the ST_* surface can land on demand.
SqlValue

Traits§

CreateModelInput
Dialect
Backend SQL dialect.
IntoColumnName
Anything that can name a single SQL column. Lets coalesce accept both bare &'static str column names and typed FieldRef handles, so callers don’t have to choose between schema-rooted typing and ad-hoc strings at the call site.
IntoSqlValue
ModelPrimaryKey
Accessor for a model’s primary key. Implemented by the macro on every generated model struct so the batch operations can pair returned rows back to the position of their input PK in the request, producing a BatchItemResult with the right index and a NotFound entry for any requested PK that didn’t come back.
ReadSource
Anything a read-path query builder needs to plan and emit SQL.
UpdateModelInput
UpsertModelInput
Input shape for the upsert primitive — INSERT … ON CONFLICT (<pk>) DO UPDATE …. sql_values() must include the primary-key column (so the backend can target the conflict), and primary_key_value() exposes the PK separately so the runtime can issue a SELECT … FOR UPDATE before the upsert to drive Created vs. Updated event / audit semantics.
WriteSource
Anything a write-path query builder needs on top of ReadSource — create defaults, update / delete policy slots, audit + retention + versioning state, upsert column list, emitted event topics.

Functions§

coalesce
Build a COALESCE(...) left-hand operand. The returned CoalesceExpr carries the column list; chain a comparator method (.lte, .eq, .is_null, …) to produce a FilterExpr the query builders can consume.
find_duplicate_sql_value
Detect the first duplicate value in a list of SqlValues, used for batch_upsert input deduplication. Linear-scan with PartialEq rather than the hashed variant in cratestack-core because SqlValue::Float and SqlValue::Decimal don’t admit a sound Hash impl.
is_orderable
Whether every hop is to-one. Ordering through a to-many hop is not expressible as a scalar correlated subquery, so generated asc()/ desc() accessors are gated on this (previously enforced by simply not emitting those methods past a to-many hop).
order_value_sql
Build the correlated-subquery expression that yields column at the end of hops, relative to the table reached by the first hop.
point
Geographic point (WGS-84 lng/lat). The naming follows the PostGIS ST_MakePoint(x, y) convention — lng is the X axis (longitude), lat is the Y axis (latitude). Don’t accidentally swap them; the engine has no way to detect it and your filter will silently match points across the world.
resolve_order_target
Walk key (dot-separated, e.g. "author.profile.nickname") through catalog, following to-one relation edges one segment at a time and resolving the final segment against the current model’s scalar columns.
wrap_filter
Fold a scalar FilterExpr outward through the traversed path, applying each hop’s quantifier. Mirrors what the macro previously emitted as nested FilterExpr::relation*(...) token trees.