Struct SQL 

pub struct SQL<'a, V>
where
    V: SQLParam,
{
    pub chunks: SmallVec<[SQLChunk<'a, V>; 8]>,
}

A SQL fragment: tokens, identifiers, raw text, and bound parameters.

Every query builder and expression renders to a SQL. V is the driver’s value type (SQLiteValue, PostgresValue, …), which also fixes the dialect used to render placeholders: ? for SQLite and MySQL, $1, $2, ... for PostgreSQL.

Chunks are stored inline for short fragments (up to 8) without a heap allocation.

Examples

use drizzle_core::{SQL, Token};

let sql: SQL<'_, Value> = SQL::raw("SELECT")
    .append(SQL::ident("name"))
    .push(Token::FROM)
    .append(SQL::ident("users"))
    .push(Token::WHERE)
    .append(SQL::ident("id"))
    .push(Token::EQ)
    .append(SQL::param(Value(7)));

assert_eq!(sql.sql(), r#"SELECT "name" FROM "users" WHERE "id" = ?"#);
assert_eq!(sql.params().collect::<Vec<_>>(), [&Value(7)]);

Fields

chunks: SmallVec<[SQLChunk<'a, V>; 8]>

The fragment’s chunks, in order.

Implementations

impl<'a, V> SQL<'a, V>

where V: SQLParam,

pub const fn empty() -> SQL<'a, V>

Creates an empty fragment.

pub fn token(t: Token) -> SQL<'a, V>

Creates a fragment holding one keyword or punctuation Token.

pub fn with_capacity_chunks(capacity: usize) -> SQL<'a, V>

Creates an empty fragment with room for capacity chunks.

pub fn ident(name: impl Into<Cow<'a, str>>) -> SQL<'a, V>

Creates a quoted identifier, such as a table or column name.

The quote character follows the dialect: "name" for SQLite and PostgreSQL, `name` for MySQL.

Examples

use drizzle_core::SQL;

assert_eq!(SQL::<Value>::ident("user name").sql(), r#""user name""#);

pub fn columns(columns: &[ColumnRef]) -> SQL<'a, V>

Creates a comma-separated list of quoted column names, without table qualifiers: "id", "name".

pub fn raw(text: impl Into<Cow<'a, str>>) -> SQL<'a, V>

Creates a fragment of raw SQL text, written as-is.

The text is not quoted or escaped. Never pass user input here; bind it with SQL::param instead.

Examples

use drizzle_core::SQL;

assert_eq!(SQL::<Value>::raw("CURRENT_TIMESTAMP").sql(), "CURRENT_TIMESTAMP");

pub fn number(value: usize) -> SQL<'a, V>

Creates an unsigned integer literal, written into the SQL text rather than bound.

pub fn param(value: impl Into<Cow<'a, V>>) -> SQL<'a, V>

Creates a bound parameter holding value.

The SQL text gets a placeholder (? or $n); the value travels separately and is returned by SQL::params.

Examples

use drizzle_core::SQL;

let sql = SQL::param(Value(1)).append(SQL::raw("+")).append(SQL::param(Value(2)));
assert_eq!(sql.sql(), "? + ?");
assert_eq!(sql.params().count(), 2);

pub fn bytes(bytes: impl Into<Cow<'a, [u8]>>) -> SQL<'a, V>

where V: From<&'a [u8]> + From<Vec<u8>> + Into<Cow<'a, V>>,

Creates a bound binary parameter (BLOB / bytea).

Prefer this over SQL::param(Vec<u8>), which some value types treat as a list rather than one binary value.

pub fn table(table: TableRef) -> SQL<'a, V>

Creates a reference to a table, rendered as its quoted name.

Right after SELECT ... FROM, a table reference also lets the renderer expand an empty projection into the table’s columns.

pub fn column(column: ColumnRef) -> SQL<'a, V>

Creates a reference to a column, rendered as "table"."column".

pub fn func(name: &'static str, args: SQL<'a, V>) -> SQL<'a, V>

Creates a function call: NAME(args).

A subquery argument gets its own parentheses: NAME((SELECT ...)).

Examples

use drizzle_core::SQL;

let sql = SQL::<Value>::func("LOWER", SQL::ident("email"));
// SQLite and PostgreSQL put a space before `(`; MySQL does not.
assert_eq!(sql.sql(), r#"LOWER ("email")"#);

pub fn append(self, other: impl Into<SQL<'a, V>>) -> SQL<'a, V>

Appends another fragment and returns the result.

pub fn append_mut(&mut self, other: impl Into<SQL<'a, V>>)

Appends another fragment in place.

pub fn push(self, chunk: impl Into<SQLChunk<'a, V>>) -> SQL<'a, V>

Appends one chunk (a Token, parameter, …) and returns the result.

pub fn push_mut(&mut self, chunk: impl Into<SQLChunk<'a, V>>)

Appends one chunk in place.

pub fn with_capacity(self, additional: usize) -> SQL<'a, V>

Reserves room for additional more chunks.

pub fn join<T>(sqls: T, separator: Token) -> SQL<'a, V>

where T: IntoIterator, <T as IntoIterator>::Item: ToSQL<'a, V>,

Joins fragments with a separator token. Returns an empty fragment for an empty iterator.

Examples

use drizzle_core::{SQL, Token};

let cols = [SQL::<Value>::ident("id"), SQL::ident("name")];
assert_eq!(SQL::join(cols, Token::COMMA).sql(), r#""id", "name""#);

pub fn parens(self) -> SQL<'a, V>

Wraps the fragment in parentheses: (self).

pub fn parens_if_subquery(self) -> SQL<'a, V>

Wraps the fragment in parentheses only when it is a subquery (see SQL::is_subquery).

pub fn is_subquery(&self) -> bool

Returns true if the fragment starts with a SELECT or WITH token.

pub fn alias(self, name: impl Into<Cow<'a, str>>) -> SQL<'a, V>

Appends an alias: self AS "name".

pub fn param_list<I>(values: I) -> SQL<'a, V>

where I: IntoIterator, <I as IntoIterator>::Item: Into<Cow<'a, V>>,

Creates a comma-separated list of bound parameters: ?, ?, ?.

pub fn assignments<I, T>(pairs: I) -> SQL<'a, V>

where I: IntoIterator<Item = (&'static str, T)>, T: Into<Cow<'a, V>>,

Creates comma-separated assignments with bound values: "col" = ?, "other" = ?.

pub fn assignments_sql<I>(pairs: I) -> SQL<'a, V>

where I: IntoIterator<Item = (&'static str, SQL<'a, V>)>,

Creates comma-separated assignments from fragments: "col" = <expression>.

Unlike SQL::assignments, which binds each value as a parameter, this keeps each fragment as-is, so placeholders and raw expressions survive.

pub fn map_params<U>(self, f: impl FnMut(V) -> U) -> SQL<'a, U>

where U: SQLParam,

Converts every bound value with f, changing the value type to U.

Only parameter chunks change. Useful for converting between owned and borrowed value types (for example OwnedPostgresValue to PostgresValue<'a>).

pub fn into_owned_with<U>(self, f: impl FnMut(V) -> U) -> SQL<'static, U>

where U: SQLParam,

Copies every borrowed string into owned storage and converts bound values with f, giving a 'static fragment.

Generated models use this to outlive the values they were built from. Identifiers, raw text, placeholders, tables and columns are all kept.

pub fn into_owned(self) -> OwnedSQL<V>

Converts into an OwnedSQL with no borrowed data.

pub fn sql(&self) -> String

Renders the SQL text.

Placeholders follow the dialect of V: $1, $2, ... for PostgreSQL, :name (named) or ? for SQLite, and ? for MySQL. Use SQL::build to get the parameters in the same pass.

pub fn has_returning(&self) -> bool

Whether this statement has a RETURNING clause (outside any parentheses), so it returns rows although it changes data.

pub fn inline_sql(&self) -> Option<String>

Renders the SQL text with every bound value written as a literal instead of a placeholder.

For statements that cannot take parameters, such as the body of a CREATE VIEW. Returns None when a placeholder has no bound value, or a value has no literal form in this dialect (see SQLParam::write_literal).

pub fn build(&self) -> (String, SmallVec<[&V; 8]>)

Renders the SQL text and collects the bound values in one pass.

Drivers use this to execute a statement. Placeholders without a bound value are rendered but not collected. For SQLite, a named placeholder that appears more than once is collected once, since SQLite gives each distinct :name a single slot.

Examples

use drizzle_core::SQL;

let sql = SQL::raw("SELECT").append(SQL::param(Value(1)));
let (text, params) = sql.build();
assert_eq!(text, "SELECT ?");
assert_eq!(params.as_slice(), [&Value(1)]);

pub fn build_with(&self, style: ParamStyle) -> (String, SmallVec<[&V; 8]>)

Like build, but with a caller-chosen placeholder style.

For drivers that speak the dialect but bind parameters differently, such as the AWS Data API on PostgreSQL, which needs :1, :2, ... instead of $1, $2, ....

pub fn write_to(&self, buf: &mut impl Write)

Writes the SQL text to buf, like SQL::sql without allocating a new string.

pub fn write_to_with(&self, buf: &mut impl Write, style: ParamStyle)

Like write_to, but with a caller-chosen placeholder style.

pub fn write_chunk_to( &self, buf: &mut impl Write, chunk: &SQLChunk<'a, V>, index: usize, )

Writes the chunk at index to buf, expanding an empty SELECT projection that ends at this chunk.

Does not write the space that may follow the chunk.

pub fn write_qualified_columns(buf: &mut impl Write, table: &TableSqlRef)

Writes every column of table as "table"."column", separated by commas, or "table".* when the column list is unknown.

pub fn params(&self) -> impl Iterator<Item = &V> + use<'_, V>

Returns the bound values, in order. Placeholders without a value are skipped.

pub fn bind<T>( self, params: impl IntoIterator>>, ) -> SQL<'a, V>

where T: SQLParam + Into<V>, <impl IntoIterator as IntoIterator>::Item: Into<ParamBind<'a, T>>,

Fills named placeholders with values, matching by name.

Placeholders whose name is not in params keep no value. Values can come from TypedPlaceholder::bind, which also checks the value’s SQL type.

Examples

use drizzle_core::{ParamBind, Placeholder, SQL, ToSQL, Token};

let sql: SQL<'_, Value> = SQL::ident("id")
    .push(Token::EQ)
    .append(Placeholder::named("id").into_sql());
assert_eq!(sql.params().count(), 0);

let bound = sql.bind([ParamBind::new("id", Value(3))]);
assert_eq!(bound.sql(), r#""id" = :id"#);
assert_eq!(bound.params().collect::<Vec<_>>(), [&Value(3)]);

Trait Implementations

impl<'a, V> AsRef<SQL<'a, V>> for SQL<'a, V>

where V: SQLParam + 'a,

fn as_ref(&self) -> &SQL<'a, V>

Converts this type into a shared reference of the (usually inferred) input type.

impl<'a, V> Clone for SQL<'a, V>

where V: Clone + SQLParam,

fn clone(&self) -> SQL<'a, V>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, V> Debug for SQL<'a, V>

where V: Debug + SQLParam,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<V> Default for SQL<'_, V>

where V: SQLParam,

fn default() -> SQL<'_, V>

Returns the “default value” for a type.

impl<V> Display for SQL<'_, V>

where V: SQLParam + Display,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a, V> Expr<'a, V> for SQL<'a, V>

where V: SQLParam + 'a,

type SQLType = <<V as SQLParam>::DialectMarker as DialectTypes>::Any

The SQL data type this expression evaluates to.

type Nullable = Null

Whether this expression can be NULL.

type Aggregate = Scalar

Whether this is an aggregate (COUNT, SUM) or scalar expression.

fn to_expr_sql(&self) -> SQL<'a, V>

Renders this value as a scalar expression, borrowing it.

fn into_expr_sql(self) -> SQL<'a, V>

where Self: Sized,

Renders this value as a scalar expression, consuming it.

fn to_condition_sql(&self) -> Option<SQL<'a, V>>

Renders this value as one element of a ConditionList.

fn into_condition_sql(self) -> Option<SQL<'a, V>>

where Self: Sized,

Consuming counterpart of Expr::to_condition_sql.

impl<V> ExprSources for SQL<'_, V>

where V: SQLParam,

type Sources = ()

Type-level tree with one Src leaf per column read.

impl<V> ExprValueType for SQL<'_, V>

where V: SQLParam,

Raw SQL has no known type (()); the caller must name the row type.

type ValueType = ()

The decoded Rust type.

impl<'a, V> From<&'a str> for SQL<'a, V>

where V: SQLParam + 'a,

fn from(s: &'a str) -> SQL<'a, V>

Converts to this type from the input type.

impl<'a, T, V> From<&T> for SQL<'a, V>

where T: ToSQL<'a, V>, V: SQLParam,

fn from(value: &T) -> SQL<'a, V>

Converts to this type from the input type.

impl From<OwnedSQLiteValue> for SQL<'_, OwnedSQLiteValue>

fn from(value: OwnedSQLiteValue) -> Self

Converts to this type from the input type.

impl<'a, V, T, N, A, S> From<SQLExpr<'a, V, T, N, A, S>> for SQL<'a, V>

where V: SQLParam, T: DataType, N: Nullability, A: AggregateKind,

fn from(expr: SQLExpr<'a, V, T, N, A, S>) -> SQL<'a, V>

Converts to this type from the input type.

impl<'a> From<SQLiteValue<'a>> for SQL<'a, SQLiteValue<'a>>

fn from(value: SQLiteValue<'a>) -> Self

Converts to this type from the input type.

impl<V> From<Token> for SQL<'_, V>

where V: SQLParam,

fn from(value: Token) -> SQL<'_, V>

Converts to this type from the input type.

impl<'a, V, T> FromIterator<T> for SQL<'a, V>

where V: SQLParam, SQLChunk<'a, V>: From<T>,

fn from_iter<I>(iter: I) -> SQL<'a, V>

where I: IntoIterator<Item = T>,

Creates a value from an iterator.

impl<'a, V> IntoIterator for SQL<'a, V>

where V: SQLParam,

type Item = SQLChunk<'a, V>

The type of the elements being iterated over.

type IntoIter = IntoIter<[SQLChunk<'a, V>; 8]>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <SQL<'a, V> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<V> IntoSelectTarget for SQL<'_, V>

where V: SQLParam,

select(sql!(...)) → SelectExpr — user must specify row type.

type Marker = SelectExpr

The select marker.

impl<V> OrderTerm for SQL<'_, V>

where V: SQLParam,

impl<V> ScopeEntry for SQL<'_, V>

where V: SQLParam,

type Key = RawSource

How columns refer to this source: a TableKey or an AliasKey.

type Nullable = NonNull

Null when an outer join can leave this source NULL.

type Sources = ()

Sources this source reads itself, such as the tables a derived table’s subquery reads from an outer query. They resolve against the enclosing query (or, for a LATERAL join, the sources joined before it). Tables and views read nothing (()).

impl<V> SelectQuery for SQL<'_, V>

where V: SQLParam,

impl<'a, V> ToSQL<'a, V> for SQL<'a, V>

where V: SQLParam + 'a,

fn to_sql(&self) -> SQL<'a, V>

Renders self as a SQL fragment.

fn into_sql(self) -> SQL<'a, V>

Renders self as a SQL fragment, consuming it.