Crate queryweave_sql

Expand description

The queryweave runtime for the persistence layer: the traits and SQL the code generated for entities and wrappers (Columns, AppendToQuery, AppendConditions) names, on top of the core runtime (queryweave), which it re-exports so that code names only this crate.

This is where the domain’s database-agnostic filters, sorting and writes (queryweave::FilterCondition, queryweave::SortKey, queryweave::FieldValue) become SQL. They name domain fields; the Columns of the entity storing them say which column each lives in, and write the SQL against them, into the query being built: any type implementing the target traits (ConditionsTarget, OrderByTarget, PageTarget, and AssignmentsTarget with merge patches).

§Features

sqlx (default): sqlx’s QueryBuilder is a target, for any database whose driver binds the domain’s raw values (BindValues).
sea-query: sea-query’s SelectStatement (conditions, ORDER BY, page), UpdateStatement (conditions, assignments) and DeleteStatement (conditions) are targets. With sea-orm, write into a query’s statement through QueryTrait::query: Order::push_conditions(select.query(), …).
diesel: the diesel module, the typed conditions, orderings, page and assignments of an entity’s Diesel columns, for the SQL types every backend has; diesel-postgres, diesel-mysql and diesel-sqlite add each backend’s own date-time types.
merge-patch (default): merge-patch writes (push_assignments).

The SQL is portable across Postgres, MySQL/MariaDB and SQLite. What stays database-specific is semantics, not syntax: LIKE is case-sensitive on Postgres but case-insensitive on SQLite (for ASCII) and under MySQL’s default collations, and column names are written unquoted, so they must not be reserved words of the database.

Modules§

diesel: Diesel’s typed query DSL as the target of a model’s data.
sea_query: sea-query’s statements as queries the SQL is written into.

Macros§

assert_columns: Assert at compile time that every one of fields has a column on entity.

Structs§

ChangeSet: The names of the fields that changed, e.g. between a model and its merge-patched version.
FieldValue: A domain field to write and the value to write to it, e.g. one changed field of a merge patch.
FilterCondition: One set filter of a generated filter-options model: field operator value.
Message: A message built at compile time (see missing_column_message).
ModelData: Items (T) naming fields of the model M, e.g. the set filters of a generated filter-options model.
QueryBuilder: The sqlx query builder the clauses are appended to, and the separated builder Columns::push_assignments returns for it: re-exported so callers can name the same sqlx as this crate, whatever they call their own sqlx dependency. A builder type for constructing queries at runtime.
Separated: The sqlx query builder the clauses are appended to, and the separated builder Columns::push_assignments returns for it: re-exported so callers can name the same sqlx as this crate, whatever they call their own sqlx dependency. A wrapper around QueryBuilder for creating comma(or other token)-separated lists.
SortKey: One sort key of a generated query model: sort by field in direction.
ValueType: What a raw type is as a Value, at compile time: its variant, and whether it may be absent (NULL, an Option).

Enums§

FilterOperator: The comparison a generated filter field performs against its column.
Junction: How conditions are joined: every one must hold (AND), or any (OR).
Patch: A field of a merge patch that may also be cleared: absent from the patch, set to null, or given a value.
SortDirectionModel: How the sorting direction is evaluated. How it is expressed in a query is up to the persistence layer.
Value: A raw value to compare against or store, in a database-agnostic form.
ValueKind: A Value variant without its value: what a raw type converts into, known at compile time (IntoValue::TYPE).

Constants§

LIKE_ESCAPE: The character escaping the LIKE metacharacters in a bound pattern (escape_like), to name in the clause: … LIKE ? ESCAPE '!'.

Traits§

AppendConditions: Append a filter-options model’s set filters to a query as conditions.
AppendToQuery: Append the filters query to the parent query.
AssignmentsTarget: A query that merge-patch writes can be written into: the assignments of an UPDATE … SET.
BindValues: A database the SQL helpers can write for.
Boolean: A raw value the bool filter applies to.
ChangedFields: Detect changes in field values.
Columns: A table (usually a sqlx entity) whose columns store a domain model’s fields, and the SQL written for that model’s data against those columns.
ConditionsTarget: A query that filter conditions can be written into: a WHERE clause.
FilterOptionsOf: A type converting into model M’s filter options model.
Filterable: The types #[derive(Filters)] generates for a root model or a mirror, so code mirroring it names them through it instead of by name.
IntoRootQuery: The query of M (a root’s query model, or a mirror’s query parameters), converting along its chain of mirrored models into the root model’s query.
IntoValue: A raw value that can be handed to the persistence layer as a Value.
MergePatchNullableFields: A merge patch model: which of its fields a client may set to null (its Patch fields), as opposed to leaving them out.
NamesField: An item naming a domain field.
NullableFields: Which fields of a merge patch struct may be set to null, under its own names.
OrderByTarget: A query that sort keys can be written into: an ORDER BY clause.
Ordered: A raw value the lt / gt filters can compare.
PageTarget: A query that a page can be written into: LIMIT and OFFSET.
PatchField: A field of a merge patch, applied to the model’s field of type F.
PatchKind: What a merge patch field can say: whether its kind of field may be set to null at all, and whether this one is.
PersistedFields: A type whose data names domain fields the persistence layer maps onto columns.
QueryOf: A type converting into model M’s query model.
RawValue: A domain field type with a raw value behind it: the value filters compare with and merge patches bind.
SortDetailsOf: A type converting into model M’s sort details.
SortFieldOf: A sortable-fields enum mirroring model M’s, variant for variant.
Text: A raw value the sw / c / ew (LIKE) filters can match.

Functions§

column_for: The column field is stored in, per a (domain field, column) table.
escape_like: Escape the LIKE metacharacters (%, _ and LIKE_ESCAPE itself) so user input matches literally instead of acting as wildcards.
first_field_without_column: The first of fields without a column in the (domain field, column) table, if any. Usable in const code, which is how assert_columns! checks coverage at compile time.
like_pattern: The LIKE pattern to bind for a LIKE operator: the escaped text wrapped in % wildcards. None for the comparison operators, which bind the value itself.
missing_column_message: The compile error assert_columns! reports for a domain field without a column on entity. Built in const code, since a const panic cannot format its message.
page_offset: The row offset of page page (0 based) of page_size rows, saturated at i64::MAX: u32 * u32 always fits a u64, and an offset past every database’s signed 64-bit row count just yields an empty page.
push_page: Write a LIMIT page_size OFFSET page * page_size clause, binding both, when both a page and a page size are requested; nothing otherwise.
sql_direction: The SQL keyword for a sort direction.
sql_junction: The SQL keyword joining conditions.
sql_operator: The SQL comparison operator for a filter operator.

Type Aliases§

Conditions: The set filters of the model M, as database-agnostic conditions.
FieldValues: Fields of the model M to write, with their values.
SortKeys: The requested sorting of the model M, in order.