Struct SQL 

pub struct SQL<'a, 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: SQLParam> SQL<'a, V>

pub const fn empty() -> Self

Creates an empty SQL fragment

pub fn token(t: Token) -> Self

Creates SQL with a single token

pub fn with_capacity_chunks(capacity: usize) -> Self

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

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

Creates SQL with a quoted identifier

pub fn columns(columns: &[ColumnRef]) -> Self

Creates a comma-separated list of unqualified column identifiers.

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

Creates SQL with raw text (unquoted)

pub fn number(value: usize) -> Self

Creates SQL with a single unsigned integer literal.

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

Creates SQL with a single parameter value

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

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) -> Self

Creates SQL referencing a table

pub fn column(column: ColumnRef) -> Self

Creates SQL referencing a column

pub fn func(name: &'static str, args: Self) -> Self

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

pub fn append(self, other: impl Into<Self>) -> Self

Append another SQL fragment (flat extend)

pub fn append_mut(&mut self, other: impl Into<Self>)

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

Push a single chunk

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

pub fn with_capacity(self, additional: usize) -> Self

Pre-allocates capacity for additional chunks

pub fn join<T>(sqls: T, separator: Token) -> Self

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

Joins multiple SQL fragments with a separator

pub fn parens(self) -> Self

Wrap in parentheses: (self)

pub fn parens_if_subquery(self) -> Self

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>>) -> Self

Creates an aliased version: self AS “name”

pub fn param_list<I>(values: I) -> Self

where I: IntoIterator, I::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) -> Self

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) -> Self

where I: IntoIterator<Item = (&'static str, Self)>,

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: SQLParam>(self, f: impl FnMut(V) -> U) -> SQL<'a, U>

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: SQLParam>( self, f: impl FnMut(V) -> U, ) -> SQL<'static, U>

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: SQLParam + Into<V>>( self, params: impl IntoIterator<Item: Into<ParamBind<'a, T>>>, ) -> Self

Bind named parameters

Trait Implementations

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

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

Provides reference conversion to inner SQL.

Example

fn takes_sql_ref<'a, V>(sql: &SQL<'a, V>) { ... }
let expr = eq(users.id, 42);
takes_sql_ref(expr.as_ref());

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

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

impl<'a, V: SQLParam + 'a> AsRef<SQL<'a, V>> for SQL<'a, V>

fn as_ref(&self) -> &Self

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

impl<'a, V: Clone + SQLParam> Clone for SQL<'a, V>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a, V: Debug + SQLParam> Debug for SQL<'a, V>

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

impl<V: SQLParam + Display> Display for SQL<'_, V>

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

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

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

type ValueType = ()

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

fn from(s: &'a str) -> Self

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) -> Self

Converts to this type from the input type.

impl<'a, V: SQLParam> From<SQL<'a, V>> for OwnedSQL<V>

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

Converts to this type from the input type.

impl<'a, V: SQLParam, T: DataType, N: Nullability, A: AggregateKind> From<SQLExpr<'a, V, T, N, A>> for SQL<'a, V>

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

Converts to this type from the input type.

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

fn from(value: Token) -> Self

Converts to this type from the input type.

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

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

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

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

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) -> Self::IntoIter

Creates an iterator from a value.

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

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

type Marker = SelectExpr

impl<'a, V: SQLParam + 'a> ToSQL<'a, V> for SQL<'a, V>

fn to_sql(&self) -> Self

fn into_sql(self) -> Self

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.