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 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 a comma-separated list of column assignments from pre-built SQL fragments: “col” =

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(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 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) -> 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 + 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.

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.