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
OrderClause
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
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.
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.

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.
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.

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.
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.