Type Alias InsertBuilder 

pub type InsertBuilder<'a, Schema, State, Table> = QueryBuilder<'a, Schema, State, Table>;

Builds an INSERT query specifically for SQLite.

InsertBuilder provides a type-safe, fluent API for constructing INSERT statements with support for 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()
4. Optionally add a returning() clause

Basic Usage

use drizzle::sqlite::prelude::*;
use drizzle::sqlite::builder::QueryBuilder;

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

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

let builder = QueryBuilder::new::<Schema>();
let Schema { user } = Schema::new();

// Basic INSERT
let query = builder
    .insert(user)
    .values([InsertUser::new("Alice")]);
assert_eq!(query.to_sql().sql(), r#"INSERT INTO "users" ("name") VALUES (?)"#);

// Batch INSERT
let query = builder
    .insert(user)
    .values([
        InsertUser::new("Alice").with_email("alice@example.com"),
        InsertUser::new("Bob").with_email("bob@example.com"),
    ]);

Conflict Resolution

SQLite supports various conflict resolution strategies:

// Ignore conflicts (ON CONFLICT DO NOTHING)
let query = builder
    .insert(user)
    .values([InsertUser::new("Alice")])
    .on_conflict(Conflict::default());

Aliased Type

pub struct InsertBuilder<'a, Schema, State, Table> {
    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 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.

This method accepts an iterable of insert value objects generated by the SQLiteTable macro (e.g., InsertUser). You can insert single values or multiple values for batch operations.

Examples

// Single insert
let query = builder
    .insert(user)
    .values([InsertUser::new("Alice")]);
assert_eq!(query.to_sql().sql(), r#"INSERT INTO "users" ("name") VALUES (?)"#);

// Batch insert (all values must have the same fields set)
let query = builder
    .insert(user)
    .values([
        InsertUser::new("Alice").with_email("alice@example.com"),
        InsertUser::new("Bob").with_email("bob@example.com"),
    ]);
assert_eq!(
    query.to_sql().sql(),
    r#"INSERT INTO "users" ("name", "email") VALUES (?, ?), (?, ?)"#
);

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

pub fn on_conflict<TI>( self, conflict: Conflict<'a, TI>, ) -> InsertBuilder<'a, S, InsertOnConflictSet, T>

where TI: IntoIterator, TI::Item: ToSQL<'a, SQLiteValue<'a>>,

Adds conflict resolution to handle constraint violations.

SQLite supports various conflict resolution strategies when inserting data that would violate unique constraints or primary keys. This method allows you to specify how to handle such conflicts.

Examples

// Ignore conflicts (do nothing)
let query = builder
    .insert(user)
    .values([InsertUser::new("Alice")])
    .on_conflict(Conflict::default());
assert_eq!(
    query.to_sql().sql(),
    r#"INSERT INTO "users" ("name") VALUES (?) ON CONFLICT DO NOTHING"#
);

pub fn returning( self, columns: impl ToSQL<'a, SQLiteValue<'a>>, ) -> InsertBuilder<'a, S, InsertReturningSet, T>

Adds a RETURNING clause and transitions to ReturningSet state

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

pub fn returning( self, columns: impl ToSQL<'a, SQLiteValue<'a>>, ) -> InsertBuilder<'a, S, InsertReturningSet, T>

Adds a RETURNING clause after ON CONFLICT