sqlx_conditional_queries/
lib.rs

1#![doc = include_str!("../README.md")]
2
3/// # Emit conditional compile-time verified `query_as!` invocations
4///
5/// The generated type exposes the same methods as `sqlx::query::Map`, with the exception of `map`
6/// and `try_map`.
7///
8///
9/// ## Bound parameters
10///
11/// This macro supports two kind of bound parameters, run-time bound and compile-time bound.
12///
13///
14/// ### Run-time bound parameters
15///
16/// Run-time bound parameers are regular bound parameters that are passed as separate parameters to
17/// the database, allowing you to use variable data without the risk of SQL injections.
18/// Additionally since the same prepared query can be reused it means that the database knows to
19/// generate a more optimized query-plan if it's used a lot.
20///
21/// Unlike in SQLx's macros you specify run-time bound parameters using a format-string-like
22/// syntax: `{foo}`.  There must be a variable with the given name in scope, and it must be a valid
23/// type to pass to `query_as!`.
24///
25/// You can pass type overrides to SQLx using a colon after the binding reference.  E.g.
26/// `{foo:_}`
27///
28/// Which kind of bound parameter references are generated depends on the activated features.
29///
30///
31/// ### Compile-time bound parameters
32///
33/// Compile-time bound parameters are expanded at compile-time.  This means that each possible
34/// option will generate a unique `query_as!` invocation.
35///
36/// They are referenced by prepending the bound name with a hash: `{#foo}`.
37///
38/// They are bound by following the query string with a series of match statements in the following
39/// format.  Compile-time binding expressions can evaluate to either a string literal or a tuple of
40/// string literals.
41///
42/// ```rust,ignore
43/// #foo = match something {
44///     true => "BAR",
45///     false => "BAZ",
46/// }
47/// ```
48///
49///
50/// ## Examples
51///
52/// ```rust,ignore
53/// enum OrderDirection {
54///     Ascending,
55///     Descending,
56/// }
57///
58/// let limit = Some(42);
59/// let order_dir = OrderDirection::Ascending;
60///
61/// conditional_query_as!(
62///     OutputType,
63///     r#"
64///         SELECT id, foo, bar
65///         FROM table
66///         {#limit}
67///         ORDER BY id {#order_dir}, foo {#order_dir_rev}
68///     "#,
69///     #limit = match limit {
70///         Some(_) => "LIMIT {limit}",
71///         None => "",
72///     },
73///     #(order_dir, order_dir_rev) = match order_dir {
74///         OrderDirection::Ascending => ("ASC", "DESC"),
75///         OrderDirection::Descending => ("DESC", "ASC"),
76///     },
77/// )
78///     .fetch_all(&mut *tx)
79///     .await?;
80/// ```
81pub use sqlx_conditional_queries_macros::conditional_query_as;
82
83/// Do not use this module.  It is only meant to be used by the generated by
84/// [`conditional_query_as!`] macro.
85#[doc(hidden)]
86pub mod exports {
87    pub use futures_core::stream::BoxStream;
88}
sqlx_conditional_queries/lib.rs

sqlx_conditional_queries/
lib.rs
