Type Alias InsertBuilder 

pub type InsertBuilder<'a, Schema, State, Table, Marker = (), Row = ()> = QueryBuilder<'a, Schema, State, Table, Marker, Row>;

Builds an INSERT query specifically for SQLite.

Provides a type-safe, fluent API for constructing INSERT statements with support for typed conflict resolution, batch inserts, and returning clauses.

Type Parameters

• Schema: The database schema type, ensuring only valid tables can be referenced
• State: The current builder state, enforcing proper query construction order
• Table: The table being inserted into

Query Building Flow

1. Start with QueryBuilder::insert(table) to specify the target table
2. Add values() to specify what data to insert
3. Optionally add conflict resolution with on_conflict(target).do_nothing() or .do_update(set)
4. Optionally add a returning() clause

Aliased Type

pub struct InsertBuilder<'a, Schema, State, Table, Marker = (), Row = ()> {
    pub sql: SQL<'a, SQLiteValue<'a>>,
    /* private fields */
}

Fields

sql: SQL<'a, SQLiteValue<'a>>

Implementations

impl<'a, Schema, Table> InsertBuilder<'a, Schema, InsertInitial, Table>

where Table: SQLiteTable<'a>,

pub fn value<T>( self, value: Table::Insert<T>, ) -> InsertBuilder<'a, Schema, InsertValuesSet, Table>

where Table::Insert<T>: SQLModel<'a, SQLiteValue<'a>>,

Specifies a single row to insert into the table.

Accepts an insert value object generated by the SQLiteTable macro (e.g., InsertUser).

pub fn values<I, T>( self, values: I, ) -> InsertBuilder<'a, Schema, InsertValuesSet, Table>

where I: IntoIterator<Item = Table::Insert<T>>, Table::Insert<T>: SQLModel<'a, SQLiteValue<'a>>,

Specifies the values to insert into the table.

Accepts an iterable of insert value objects generated by the SQLiteTable macro (e.g., InsertUser).

impl<'a, S, T> InsertBuilder<'a, S, InsertValuesSet, T>

pub fn on_conflict<C: ConflictTarget<T>>( self, target: C, ) -> OnConflictBuilder<'a, S, T>

Begins a typed ON CONFLICT clause targeting a specific constraint.

The target must implement ConflictTarget<T>, which is auto-generated for primary key columns, unique columns, and unique indexes.

Returns an OnConflictBuilder to specify do_nothing() or do_update().

Examples

fn main() {
use drizzle::sqlite::prelude::*;
use drizzle::sqlite::builder::QueryBuilder;

#[SQLiteTable(name = "users")]
struct User {
    #[column(primary)]
    id: i32,
    name: String,
    #[column(unique)]
    email: Option<String>,
}

#[derive(SQLiteSchema)]
struct Schema {
    user: User,
}

let builder = QueryBuilder::new::<Schema>();
let schema = Schema::new();
let user = schema.user;

// Target a specific column (requires PK or unique constraint)
builder.insert(user).values([InsertUser::new("Alice")])
    .on_conflict(user.id).do_nothing();

// Target with DO UPDATE
builder.insert(user).values([InsertUser::new("Alice")])
    .on_conflict(user.email).do_update(UpdateUser::default().with_name("updated"));
}

pub fn on_conflict_do_nothing( self, ) -> InsertBuilder<'a, S, InsertOnConflictSet, T>

Shorthand for ON CONFLICT DO NOTHING without specifying a target.

This matches any constraint violation.

pub fn returning<Columns>( self, columns: Columns, ) -> InsertBuilder<'a, S, InsertReturningSet, T, Scoped<<Columns as IntoSelectTarget>::Marker, Cons<T, Nil>>, <<Columns as IntoSelectTarget>::Marker as ResolveRow<T>>::Row>

where Columns: ToSQL<'a, SQLiteValue<'a>> + IntoSelectTarget, Columns::Marker: ResolveRow<T>,

Adds a RETURNING clause and transitions to ReturningSet state

impl<'a, S, T> InsertBuilder<'a, S, InsertOnConflictSet, T>

pub fn returning<Columns>( self, columns: Columns, ) -> InsertBuilder<'a, S, InsertReturningSet, T, Scoped<<Columns as IntoSelectTarget>::Marker, Cons<T, Nil>>, <<Columns as IntoSelectTarget>::Marker as ResolveRow<T>>::Row>

where Columns: ToSQL<'a, SQLiteValue<'a>> + IntoSelectTarget, Columns::Marker: ResolveRow<T>,

Adds a RETURNING clause after ON CONFLICT

impl<'a, S, T> InsertBuilder<'a, S, InsertDoUpdateSet, T>

pub fn where<E>( self, condition: E, ) -> InsertBuilder<'a, S, InsertOnConflictSet, T>

where E: Expr<'a, SQLiteValue<'a>>, E::SQLType: BooleanLike,

Adds a WHERE clause to the DO UPDATE SET clause.

Generates: ON CONFLICT (col) DO UPDATE SET ... WHERE condition

pub fn returning<Columns>( self, columns: Columns, ) -> InsertBuilder<'a, S, InsertReturningSet, T, Scoped<<Columns as IntoSelectTarget>::Marker, Cons<T, Nil>>, <<Columns as IntoSelectTarget>::Marker as ResolveRow<T>>::Row>

where Columns: ToSQL<'a, SQLiteValue<'a>> + IntoSelectTarget, Columns::Marker: ResolveRow<T>,

Adds a RETURNING clause after DO UPDATE SET