support conditional queries in query_as!

.github/workflows/sqlx.yml

@@ -3,8 +3,6 @@ name: SQLx
 on:
   pull_request:
   push:
-    branches:
-      - master
 
 jobs:
   format:

Cargo.toml

@@ -258,6 +258,11 @@ name = "postgres-derives"
 path = "tests/postgres/derives.rs"
 required-features = ["postgres", "macros"]
 
+[[test]]
+name = "postgres-conditonal_query"
+path = "tests/postgres/conditional_query.rs"
+required-features = ["postgres", "macros"]
+
 #
 # Microsoft SQL Server (MSSQL)
 #

sqlx-core/src/lib.rs

@@ -105,3 +105,6 @@ pub mod mssql;
 /// sqlx uses ahash for increased performance, at the cost of reduced DoS resistance.
 use ahash::AHashMap as HashMap;
 //type HashMap<K, V> = std::collections::HashMap<K, V, ahash::RandomState>;
+
+#[doc(hidden)]
+pub use futures_core;

sqlx-macros/Cargo.toml

@@ -89,6 +89,6 @@ sqlx-rt = { version = "0.5.11", default-features = false, path = "../sqlx-rt" }
 serde = { version = "1.0.132", features = ["derive"], optional = true }
 serde_json = { version = "1.0.73", optional = true }
 sha2 = { version = "0.9.8", optional = true }
-syn = { version = "1.0.84", default-features = false, features = ["full"] }
+syn = { version = "1.0.84", default-features = false, features = ["full", "extra-traits"] }
 quote = { version = "1.0.14", default-features = false }
 url = { version = "2.2.2", default-features = false }

sqlx-macros/src/lib.rs

@@ -41,6 +41,210 @@ pub fn expand_query(input: TokenStream) -> TokenStream {
     }
 }
 
+/// A variant of [query!] which takes a path to an explicitly defined struct as the output type.
+///
+/// This lets you return the struct from a function or add your own trait implementations.
+///
+/// **No trait implementations are required**; the macro maps rows using a struct literal
+/// where the names of columns in the query are expected to be the same as the fields of the struct
+/// (but the order does not need to be the same). The types of the columns are based on the
+/// query and not the corresponding fields of the struct, so this is type-safe as well.
+///
+/// This enforces a few things:
+/// * The query must output at least one column.
+/// * The column names of the query must match the field names of the struct.
+/// * The field types must be the Rust equivalent of their SQL counterparts; see the corresponding
+/// module for your database for mappings:
+///     * Postgres: [crate::postgres::types]
+///     * MySQL: [crate::mysql::types]
+///     * SQLite: [crate::sqlite::types]
+///     * MSSQL: [crate::mssql::types]
+/// * If a column may be `NULL`, the corresponding field's type must be wrapped in `Option<_>`.
+/// * Neither the query nor the struct may have unused fields.
+///
+/// In contrast to the syntax of `query!()`, the struct name is given before the SQL
+/// string. Arguments may be passed, like in `query!()`, within a comma-seperated list after the
+/// SQL string, or inline within the query string using `"{<EXPRESSION>}"`:
+/// ```rust,ignore
+/// # use sqlx::Connect;
+/// # #[cfg(all(feature = "mysql", feature = "_rt-async-std"))]
+/// # #[async_std::main]
+/// # async fn main() -> sqlx::Result<()>{
+/// # let db_url = dotenv::var("DATABASE_URL").expect("DATABASE_URL must be set");
+/// #
+/// # if !(db_url.starts_with("mysql") || db_url.starts_with("mariadb")) { return Ok(()) }
+/// # let mut conn = sqlx::MySqlConnection::connect(db_url).await?;
+/// #[derive(Debug)]
+/// struct Account {
+///     id: i32,
+///     name: String
+/// }
+///
+/// // let mut conn = <impl sqlx::Executor>;
+/// let id = 1;
+/// let account = sqlx::query_as!(
+///         Account,
+///         "select * from (select (1) as id, 'Herp Derpinson' as name) accounts where id = {id}"
+///     )
+///     .fetch_one(&mut conn)
+///     .await?;
+///
+/// println!("{:?}", account);
+/// println!("{}: {}", account.id, account.name);
+///
+/// # Ok(())
+/// # }
+/// #
+/// # #[cfg(any(not(feature = "mysql"), not(feature = "_rt-async-std")))]
+/// # fn main() {}
+/// ```
+///
+/// **The method you want to call depends on how many rows you're expecting.**
+///
+/// | Number of Rows | Method to Call*             | Returns (`T` being the given struct)   | Notes |
+/// |----------------| ----------------------------|----------------------------------------|-------|
+/// | Zero or One    | `.fetch_optional(...).await`| `sqlx::Result<Option<T>>`              | Extra rows are ignored. |
+/// | Exactly One    | `.fetch_one(...).await`     | `sqlx::Result<T>`                      | Errors if no rows were returned. Extra rows are ignored. Aggregate queries, use this. |
+/// | At Least One   | `.fetch(...)`               | `impl Stream<Item = sqlx::Result<T>>`  | Call `.try_next().await` to get each row result. |
+/// | Multiple       | `.fetch_all(...)`           | `sqlx::Result<Vec<T>>`  | |
+///
+/// \* All methods accept one of `&mut {connection type}`, `&mut Transaction` or `&Pool`.
+/// (`.execute()` is omitted as this macro requires at least one column to be returned.)
+///
+/// ### Column Type Override: Infer from Struct Field
+/// In addition to the column type overrides supported by [query!], `query_as!()` supports an
+/// additional override option:
+///
+/// If you select a column `foo as "foo: _"` (Postgres/SQLite) or `` foo as `foo: _` `` (MySQL)
+/// it causes that column to be inferred based on the type of the corresponding field in the given
+/// record struct. Runtime type-checking is still done so an error will be emitted if the types
+/// are not compatible.
+///
+/// This allows you to override the inferred type of a column to instead use a custom-defined type:
+///
+/// ```rust,ignore
+/// #[derive(sqlx::Type)]
+/// #[sqlx(transparent)]
+/// struct MyInt4(i32);
+///
+/// struct Record {
+///     id: MyInt4,
+/// }
+///
+/// let my_int = MyInt4(1);
+///
+/// // Postgres/SQLite
+/// sqlx::query_as!(Record, r#"select 1 as "id: _""#) // MySQL: use "select 1 as `id: _`" instead
+///     .fetch_one(&mut conn)
+///     .await?;
+///
+/// assert_eq!(record.id, MyInt4(1));
+/// ```
+///
+/// ### Conditional Queries
+/// This macro allows you to dynamically construct queries at runtime, while still ensuring that
+/// they are checked at compile-time.
+///
+/// Let's consider an example first. Let's say you want to query all products from your database,
+/// while the user may decide if he wants them ordered in ascending or descending order.
+/// This could be achieved by writing both queries out by hand:
+/// ```rust,ignore
+/// let products = if order_ascending {
+///     sqlx::query_as!(
+///         Product,
+///         "SELECT * FROM products ORDER BY name ASC"
+///     )
+///     .fetch_all(&mut con)
+///     .await?
+/// } else {
+///     sqlx::query_as!(
+///         Product,
+///         "SELECT * FROM products ORDER BY name DESC"
+///     )
+///     .fetch_all(&mut con)
+///     .await?
+/// };
+/// ```
+/// To avoid repetition in these cases, you may use `if`, `if let` and `match` directly within the macro
+/// invocation:
+/// ```rust,ignore
+/// let products = sqlx::query_as!(
+///     Product,
+///     "SELECT * FROM products ORDER BY NAME"
+///     if order_ascending { "ASC" } else { "DESC" }
+/// )
+/// .fetch_all(&mut con)
+/// .await?;
+/// ```
+/// The macro will expand to something similar like in the verbose example above, ensuring that
+/// every possible query which may result from the macro invocation is checked at compile-time.
+///
+/// When writing *conditional* queries, parameters may only be given inline.
+///
+/// It is recommended to avoid using a lot of `if` and `match` clauses within a single `query_as!`
+/// invocation. Do not use much more than 6 within a single query to avoid drastically increased
+/// compile times.
+///
+/// ### Troubleshooting: "error: mismatched types"
+/// If you get a "mismatched types" error from an invocation of this macro and the error
+/// isn't pointing specifically at a parameter.
+///
+/// For example, code like this (using a Postgres database):
+///
+/// ```rust,ignore
+/// struct Account {
+///     id: i32,
+///     name: Option<String>,
+/// }
+///
+/// let account = sqlx::query_as!(
+///     Account,
+///     r#"SELECT id, name from (VALUES (1, 'Herp Derpinson')) accounts(id, name)"#,
+/// )
+///     .fetch_one(&mut conn)
+///     .await?;
+/// ```
+///
+/// Might produce an error like this:
+/// ```text,ignore
+/// error[E0308]: mismatched types
+///    --> tests/postgres/macros.rs:126:19
+///     |
+/// 126 |       let account = sqlx::query_as!(
+///     |  ___________________^
+/// 127 | |         Account,
+/// 128 | |         r#"SELECT id, name from (VALUES (1, 'Herp Derpinson')) accounts(id, name)"#,
+/// 129 | |     )
+///     | |_____^ expected `i32`, found enum `std::option::Option`
+///     |
+///     = note: expected type `i32`
+///                found enum `std::option::Option<i32>`
+/// ```
+///
+/// This means that you need to check that any field of the "expected" type (here, `i32`) matches
+/// the Rust type mapping for its corresponding SQL column (see the `types` module of your database,
+/// listed above, for mappings). The "found" type is the SQL->Rust mapping that the macro chose.
+///
+/// In the above example, the returned column is inferred to be nullable because it's being
+/// returned from a `VALUES` statement in Postgres, so the macro inferred the field to be nullable
+/// and so used `Option<i32>` instead of `i32`. **In this specific case** we could use
+/// `select id as "id!"` to override the inferred nullability because we know in practice
+/// that column will never be `NULL` and it will fix the error.
+///
+/// Nullability inference and type overrides are discussed in detail in the docs for [query!].
+///
+/// It unfortunately doesn't appear to be possible right now to make the error specifically mention
+/// the field; this probably requires the `const-panic` feature (still unstable as of Rust 1.45).
+#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
+#[proc_macro]
+pub fn query_as(input: TokenStream) -> TokenStream {
+    match query::query_as(input.into()) {
+        Ok(output) => output,
+        Err(err) => err.to_compile_error(),
+    }
+    .into()
+}
+
 #[proc_macro_derive(Encode, attributes(sqlx))]
 pub fn derive_encode(tokenstream: TokenStream) -> TokenStream {
     let input = syn::parse_macro_input!(tokenstream as syn::DeriveInput);

sqlx-macros/src/query/conditional/map.rs

@@ -0,0 +1,80 @@
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+
+pub fn generate_conditional_map(n: usize) -> TokenStream {
+    let map_fns = (1..=n).map(|i| format_ident!("F{}", i)).collect::<Vec<_>>();
+    let args = (1..=n).map(|i| format_ident!("A{}", i)).collect::<Vec<_>>();
+    let variants = (1..=n).map(|i| format_ident!("_{}", i)).collect::<Vec<_>>();
+    let variant_declarations = (0..n).map(|i| {
+        let variant = &variants[i];
+        let map_fn = &map_fns[i];
+        let args = &args[i];
+        quote!(#variant(sqlx::query::Map<'q, DB, #map_fn, #args>))
+    });
+
+    quote! {
+        #[doc(hidden)]
+        pub enum ConditionalMap<'q, DB, O, #(#map_fns,)* #(#args,)*>
+        where
+            DB: sqlx::Database,
+            O: Send + Unpin,
+            #(#map_fns: FnMut(DB::Row) -> sqlx::Result<O> + Send,)*
+            #(#args: 'q + Send + sqlx::IntoArguments<'q, DB>,)*
+        {
+            #(#variant_declarations),*
+        }
+        impl<'q, DB, O, #(#map_fns,)* #(#args,)*> ConditionalMap<'q, DB, O, #(#map_fns,)* #(#args,)*>
+        where
+            DB: sqlx::Database,
+            O: Send + Unpin,
+            #(#map_fns: FnMut(DB::Row) -> sqlx::Result<O> + Send,)*
+            #(#args: 'q + Send + sqlx::IntoArguments<'q, DB>,)*
+        {
+            pub fn fetch<'e, 'c: 'e, E>(self, executor: E) -> sqlx::futures_core::stream::BoxStream<'e, sqlx::Result<O>>
+            where
+                'q: 'e,
+                E: 'e + sqlx::Executor<'c, Database = DB>,
+                DB: 'e,
+                O: 'e,
+                #(#map_fns: 'e,)*
+            {
+                match self { #(
+                    Self::#variants(x) => x.fetch(executor)
+                ),* }
+            }
+            pub async fn fetch_all<'e, 'c: 'e, E>(self, executor: E) -> sqlx::Result<Vec<O>>
+            where
+                'q: 'e,
+                DB: 'e,
+                E: 'e + sqlx::Executor<'c, Database = DB>,
+                O: 'e
+            {
+               match self { #(
+                    Self::#variants(x) => x.fetch_all(executor).await
+               ),* }
+            }
+            pub async fn fetch_one<'e, 'c: 'e, E>(self, executor: E) -> sqlx::Result<O>
+            where
+                'q: 'e,
+                E: 'e + sqlx::Executor<'c, Database = DB>,
+                DB: 'e,
+                O: 'e,
+            {
+                match self { #(
+                    Self::#variants(x) => x.fetch_one(executor).await
+                ),* }
+            }
+            pub async fn fetch_optional<'e, 'c: 'e, E>(self, executor: E) -> sqlx::Result<Option<O>>
+            where
+                'q: 'e,
+                E: 'e + sqlx::Executor<'c, Database = DB>,
+                DB: 'e,
+                O: 'e,
+            {
+                match self { #(
+                    Self::#variants(x) => x.fetch_optional(executor).await
+                ),* }
+            }
+        }
+    }
+}