Struct SQL 

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

SQL fragment builder with flat chunk storage.

Uses SmallVec<[SQLChunk; 8]> for inline storage of typical SQL fragments without heap allocation.

Fields

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

Implementations

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

where V: SQLParam,

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

Creates an empty SQL fragment

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

Creates SQL with a single token

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

Creates an empty SQL fragment with pre-allocated chunk capacity.

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

Creates SQL with a quoted identifier

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

Creates a comma-separated list of unqualified column identifiers.

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

Creates SQL with raw text (unquoted)

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

Creates SQL with a single unsigned integer literal.

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

Creates SQL with a single parameter value

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 SQL with a binary parameter value (BLOB/bytea)

Prefer this over SQL::param(Vec<u8>) to avoid list semantics.

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

Creates SQL referencing a table

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

Creates SQL referencing a column

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

Creates SQL for a function call: NAME(args) Subqueries are automatically wrapped in parentheses: NAME((SELECT …))

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

Append another SQL fragment (flat extend)

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

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

Push a single chunk

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

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

Pre-allocates capacity for additional chunks

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

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

Joins multiple SQL fragments with a separator

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

Wrap in parentheses: (self)

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

Wrap this SQL fragment in parentheses only when it is a subquery.

pub fn is_subquery(&self) -> bool

Check if this SQL fragment is a subquery (starts with SELECT/WITH).

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

Creates an aliased version: 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 parameters. Builds chunks directly without intermediate SQL allocations.

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

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

Creates a comma-separated list of column assignments: “col” = ? Builds chunks directly without intermediate SQL allocations.

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

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

Creates comma-separated column assignments from pre-built SQL fragments, such as "col" = <expression>.

Unlike assignments() which wraps each value in SQL::param(), this variant accepts pre-built SQL fragments, preserving placeholders and raw expressions. Builds chunks directly without intermediate SQL allocations.

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

where U: SQLParam,

Maps parameter values from type V to type U using the provided function.

Only Param chunks are affected; all other chunks pass through unchanged. This is useful for converting between owned and borrowed value types (e.g. OwnedPostgresValue → PostgresValue<'a>).

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

where U: SQLParam,

Own every borrowed SQL fragment while mapping parameter values.

This is used by generated models that outlive their source values. It preserves identifiers, raw fragments, placeholders, tables, and columns instead of assuming the fragment consists of a single parameter.

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

Converts to owned version (consuming self to avoid clone)

pub fn sql(&self) -> String

Returns the SQL string with dialect-appropriate placeholders. Uses $1, $2, ... for PostgreSQL, :name or ? for SQLite, ? for MySQL.

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>

Returns the SQL string 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]>)

Generates the SQL string and collects parameter references in a single pass.

This is the preferred method for driver execution paths since it avoids iterating the chunk list twice (once for sql(), once for params()).

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

Same as build but lets the caller override the placeholder style. Drivers that speak the dialect but bind parameters differently (e.g. AWS Data API on Postgres) use this to emit :1, :2, ... instead of $1, $2, ... without any post-hoc rewriting.

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

Write SQL to a buffer with dialect-appropriate placeholders. Uses $1, $2, ... for PostgreSQL, ? or :name for SQLite, ? for MySQL.

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

Same as 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, )

Write a single chunk with pattern detection

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

Write fully qualified columns for a table

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

Returns an iterator over references to parameter values (avoids allocating a Vec - callers can collect if needed)

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>>,

Bind named parameters

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>

Render this value as a scalar expression by reference.

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

where Self: Sized,

Render this value as a scalar expression, consuming it when useful.

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

Render 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> ExprValueType for SQL<'_, V>

where V: SQLParam,

Raw SQL fallback — value type is (), user must specify the concrete type.

type ValueType = ()

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<OwnedPostgresValue> for SQL<'_, OwnedPostgresValue>

fn from(value: OwnedPostgresValue) -> Self

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

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

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

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

where V: SQLParam + 'a,

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

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

Consume self and return SQL without cloning. Default delegates to to_sql() (which clones). Types that own their SQL (like SQL and SQLExpr) override this to avoid the clone.