pg_named_args/

lib.rs

//! This library allows one to use named arguments in PostgreSQL queries. This
//! library is especially aimed at supporting
//! [rust-postgres](https://github.com/sfackler/rust-postgres). A macro is provided
//! to rewrite queries with named arguments, into a query and its positional
//! arguments.
//!
//! # Query Argument Syntax
//! The macro uses struct syntax for the named arguments.
//! The struct name `Args` is required to support rustfmt and rust-analyzer.
//! As can be seen from the example below, shorthand field initialization is also allowed for named arguments.
//!
//! ```
//! # use pg_named_args::query_args;
//! # struct Period {
//! #     start: u32,
//! #     end: u32,
//! # }
//! #
//! let location = "netherlands";
//! let period = Period {
//!     start: 2020,
//!     end: 2030,
//! };
//!
//! let (query, args) = query_args!(
//!     r"
//!     SELECT location, time, report
//!     FROM weather_reports
//!     WHERE location = $location
//!         AND time BETWEEN $start AND $end
//!     ORDER BY location, time DESC
//!     ",
//!     Args {
//!         location,
//!         start: period.start,
//!         end: period.end,
//!     }
//! );
//! ```
//! ```ignore
//! let rows = client.query(query, args).await?;
//! ```
//! This expands to the equivalent of
//! ```ignore
//! let (query, args) = (
//!     r"
//!     SELECT location, time, report
//!     FROM weather_reports
//!     WHERE location = $1
//!         AND time BETWEEN $2 AND $3
//!     ORDER BY location, time DESC
//!     ",
//!     &[&location, &period.start, &period.end]
//! );
//! ```
//!
//! # Insert Syntax
//! For `INSERT`'s a special syntax is supported, which helps to avoid mismatches
//! between the list of column names and the values:
//!
//! ```
//! # use pg_named_args::query_args;
//! #
//! let location = "sweden";
//! let time = "monday";
//! let report = "sunny";
//!
//! let (query, args) = query_args!(
//!     r"
//!     INSERT INTO weather_reports
//!         ( $[location, time, report] )
//!     VALUES
//!         ( $[..] )
//!     ",
//!     Args {
//!         location,
//!         time,
//!         report
//!     }
//! );
//! ```
//! ```ignore
//! client.execute(query, args).await?;
//! ```
//! The SQL would be
//! ```sql
//! INSERT INTO weather_reports
//!     ( location, time, report )
//! VALUES
//!     ( $1, $2, $3 )
//! ```
//!
//! # Optional Parameter Syntax
//! When doing updates it can be useful to dynamically build SQL.
//!
//! This is essential when for example a column must sometimes be updated, but the column is also nullable.
//! To differentiate between those cases, `pg_named_args` adds a `Update<T>` type which has the
//! `Update::Yes(val)` and `Update::No` variants. This type can be combined with the `Option` type as `Update<Option<T>>`.
//!
//! The syntax to use optional parameter is like this:
//!
//! ```rust
//! # use pg_named_args::{query_args, Update};
//! #
//! fn update_report(id: i64, report: Update<Option<&str>>) {
//!     let (query, args) = query_args!(
//!         r"
//!         UPDATE weather_reports
//!         SET $[report?] = $[..]
//!         WHERE id = $id
//!         ",
//!         Args {
//!             report,
//!             id,
//!         }
//!     );
//! }
//!
//! // Don't update the report.
//! update_report(0, Update::No);
//! // Set the report to `null`.
//! update_report(1, Update::Yes(None));
//! // Set the report to "sunny".
//! update_report(2, Update::Yes(Some("sunny")));
//! ```
//! The SQL would be
//! ```sql
//! UPDATE weather_reports
//! SET report = CASE WHEN $1 THEN $2 ELSE report END
//! WHERE id = $3
//! ```
//! The optional parameter has been desugared to two parameters, one to indicate if the value should be updated
//! and another parameter with the new value.
//!
//! Note that it is not possible to use the same argument with and without the `?` modifier in the same query.
//!
//! # Fragment Syntax
//! ```
//! # use pg_named_args::{query_args, fragment};
//! #
//! let select = fragment!("
//!     SELECT location, time, report
//!     FROM weather_reports
//! ");
//!
//! let location = "sweden";
//!
//! let (query, args) = query_args!(
//!     r"
//!     ${select}
//!     WHERE location = $location
//!     ",
//!     Args {
//!         // Temporary lifetime extension doesn't work when fragments are involved,
//!         // so we have to borrow the parameter here.
//!         location: &location,
//!     },
//!     Sql {
//!         select,
//!     }
//! );
//! ```
//! The SQL would be
//! ```sql
//! SELECT location, time, report
//! FROM weather_reports
//! WHERE location = $1
//! ```
//!
//! # IDE Support
//!
//! First, the syntax used by this macro is compatible with rustfmt.
//! Run rustfmt as you would normally and it will format the macro.
//!
//! Second, the macro is implemented in a way that is rust-analyzer "friendly".
//! This means that rust-analyzer knows which arguments are required and can complete them.
//! Use the code action "Fill struct fields" or ask rust-analyzer to complete a field name.

extern crate self as pg_named_args;

use std::borrow::Cow;

pub use pg_named_args_macros::{fragment, query_args};
#[doc(hidden)]
pub use postgres_types;

/// Helper type to safely build queries from string literals.
///
/// This type can be constructed using the [fragment] macro.
/// It can then be used in [query_args] as part of the SQL statement.
#[derive(Default, Clone)]
pub struct Fragment<'a>(
    Cow<'static, str>,
    // TODO: maybe allow `&'a [&'a dyn ..]` for const initialization?
    Vec<&'a (dyn postgres_types::ToSql + Sync)>,
);

impl<'a> Fragment<'a> {
    /// Get the SQL string for this fragment.
    pub fn get(&self) -> &str {
        self.0.as_ref()
    }

    /// Get the parameters for this fragment.
    pub fn params(&self) -> &[&'a (dyn postgres_types::ToSql + Sync)] {
        &self.1
    }

    #[doc(hidden)]
    /// This is the constructor used by the [fragment!] macro.
    /// It is not intended to be used manually.
    pub const fn new_unchecked(
        sql: Cow<'static, str>,
        vec: Vec<&'a (dyn postgres_types::ToSql + Sync)>,
    ) -> Self {
        Self(sql, vec)
    }
}

#[doc(hidden)]
/// Renumber sql parameters.
///
/// This function assumes that every '$' character is followed by a decimal number.
/// If this is not the case, then this function will panic.
pub fn renumber(sql: &str, offset: usize) -> String {
    use std::fmt::Write;
    let mut parts = sql.split('$');
    let mut output = String::new();

    // move the part before the first '$' into the output
    output.extend(parts.next());

    for part in parts {
        let num_len = part
            .find(|x: char| !x.is_ascii_digit())
            .unwrap_or(part.len());
        let num: usize = part[..num_len].parse().unwrap();
        let new_num = num + offset;
        let remainder = &part[num_len..];
        write!(&mut output, "${new_num}{remainder}").unwrap();
    }
    output
}

/// This enum is used for optional arguments.
///
/// If you want to use your own type then you can implement [Update::From<YourType>] and
/// it will be used automatically by the macros in this crate.
pub enum Update<T> {
    /// Indicates that the column should be updated.
    Yes(T),
    /// Indicates that the column should not be updated.
    /// The column name is used to set the column to the value of the same column.
    No,
}

impl<T> Update<T> {
    #[doc(hidden)]
    pub fn to_bool(&self) -> bool {
        match self {
            Update::Yes(_) => true,
            Update::No => false,
        }
    }
}

impl<'a, T> From<&'a Update<T>> for Update<&'a T> {
    fn from(value: &'a Update<T>) -> Self {
        match value {
            Update::Yes(val) => Update::Yes(val),
            Update::No => Update::No,
        }
    }
}

#[doc(hidden)]
#[derive(Debug)]
pub struct Null;

impl postgres_types::ToSql for Null {
    fn to_sql(
        &self,
        _ty: &postgres_types::Type,
        _out: &mut bytes::BytesMut,
    ) -> Result<postgres_types::IsNull, Box<dyn std::error::Error + Sync + Send>>
    where
        Self: Sized,
    {
        Ok(postgres_types::IsNull::Yes)
    }

    fn accepts(_ty: &postgres_types::Type) -> bool
    where
        Self: Sized,
    {
        true
    }

    postgres_types::to_sql_checked! {}
}

#[test]
fn ui() {
    let t = trybuild::TestCases::new();
    t.compile_fail("tests/ui/*.rs");
}