Type Alias InsertBuilder 

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

An INSERT query being built for SQLite.

This is QueryBuilder in one of the Insert* states. Start it with QueryBuilder::insert.

Clause order

1. A row source: values or value, select, or columns followed by select.
2. Optionally a conflict clause: on_conflict followed by do_nothing() or do_update(..) (and optionally where), or on_conflict_do_nothing.
3. Optionally returning.

Nothing can follow returning.

Examples

let query = builder
    .insert(user)
    .values([InsertUser::new("Alice"), InsertUser::new("Bob")])
    .on_conflict_do_nothing()
    .returning(user.id);
assert_eq!(
    query.to_sql().sql(),
    r#"INSERT INTO "users" ("name") VALUES (?), (?) ON CONFLICT DO NOTHING RETURNING "users"."id""#
);

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

The SQL built so far.

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

Inserts one row. Same as values([value]).

value is the table’s generated insert model (for example 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>>,

Inserts one or more rows.

Each item is the table’s generated insert model (for example InsertUser). All rows must set the same columns: the insert model’s type tracks which columns are set, so rows built with different setters do not type-check together. If no column is set, this renders DEFAULT VALUES for one row (several such rows insert NULL into rowid, which a WITHOUT ROWID table rejects).

Examples

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 (?, ?), (?, ?)"#
);

pub fn columns<Columns>( self, columns: Columns, ) -> InsertBuilder<'a, Schema, InsertColumnsSet<Columns::Columns>, Table>

where Columns: InsertTargetColumns<'a, SQLiteValue<'a>, Table>,

Lists the target columns for an INSERT ... SELECT.

Pass a tuple of the table’s columns, then call select. The column list must include every required column (one without a default), and the SELECT must produce matching types in the same order; both are checked at compile time.

Panics

Panics when the same column appears more than once.

pub fn select<Q, R, ScopeProof, AggProof>( self, query: Q, ) -> InsertBuilder<'a, Schema, InsertValuesSet, Table>

where Table: InsertSelectTable, Q: IntoSelectQuery<'a, Schema, R>, Q::Marker: InsertSelectCompatible<'a, SQLiteValue<'a>, Table, R> + MarkerScopeValidFor<ScopeProof> + MarkerAggValidFor<Q::Grouped, AggProof>,

Inserts the rows of a SELECT into every insertable column of the table.

The SELECT must produce one value per insertable column, in table order, with compatible types and nullability. Its column references and aggregates are also checked. To fill only some columns, call columns first.

Examples

let query = builder
    .insert(archived_user)
    .select(builder.select((user.id, user.name)).from(user));
assert_eq!(
    query.to_sql().sql(),
    r#"INSERT INTO "archived_users" ("id", "name") SELECT "users"."id", "users"."name" FROM "users""#
);

pub fn select_raw<Q>( self, query: Q, ) -> InsertBuilder<'a, Schema, InsertValuesSet, Table>

where Q: ToSQL<'a, SQLiteValue<'a>>,

Appends any SQL as the row source, without a column list.

Nothing is checked: not the column count, types, nullability, column scope or aggregates. Prefer select.

impl<'a, Schema, Table, Targets> InsertBuilder<'a, Schema, InsertColumnsSet<Targets>, Table>

where Table: SQLiteTable<'a> + InsertSelectTable,

pub fn select<Q, R, RequiredProof, ScopeProof, AggProof>( self, query: Q, ) -> InsertBuilder<'a, Schema, InsertValuesSet, Table>

where Targets: IncludesRequired<Table::RequiredColumns, RequiredProof>, Q: IntoSelectQuery<'a, Schema, R>, Q::Marker: PartialInsertSelectCompatible<'a, SQLiteValue<'a>, Targets> + MarkerScopeValidFor<ScopeProof> + MarkerAggValidFor<Q::Grouped, AggProof>,

Inserts the rows of a SELECT into the columns chosen with columns.

The SELECT must produce one value per chosen column, in the same order, with compatible types and nullability.

Examples

let query = builder
    .insert(archived_user)
    .columns(archived_user.name)
    .select(builder.select(user.name).from(user));
assert_eq!(
    query.to_sql().sql(),
    r#"INSERT INTO "archived_users" ("name") SELECT "users"."name" FROM "users""#
);

pub fn select_raw<Q, RequiredProof>( self, query: Q, ) -> InsertBuilder<'a, Schema, InsertValuesSet, Table>

where Targets: IncludesRequired<Table::RequiredColumns, RequiredProof>, Q: ToSQL<'a, SQLiteValue<'a>>,

Appends any SQL as the row source for the chosen columns.

Only the column list is checked (it must include every required column). The SQL itself is not checked. Prefer select.

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

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

Starts an ON CONFLICT (target) clause.

The target can be a primary key or unique column, the primary key, a unique constraint, or a unique index of this table; anything else does not compile. For a partial unique index, its WHERE predicate is repeated after the target so SQLite can match the index. Finish the clause with do_nothing() or do_update(update_model). After do_update you may add a where and then returning.

When the row source is a SELECT that ends in its FROM clause, a WHERE true is added before ON CONFLICT so SQLite does not parse ON as a join condition.

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;

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

let query = builder
    .insert(user)
    .values([InsertUser::new("Alice").with_email("a@example.com")])
    .on_conflict(user.email)
    .do_update(UpdateUser::default().with_name("Alice"));
assert_eq!(
    query.to_sql().sql(),
    r#"INSERT INTO "users" ("name", "email") VALUES (?, ?) ON CONFLICT ("email") DO UPDATE SET "name" = ?"#
);
}

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

Adds ON CONFLICT DO NOTHING with no target, which skips a row that violates any unique or primary key constraint.

pub fn returning<Columns, ScopeProof>( 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: ExprSources + ToSQL<'a, SQLiteValue<'a>> + IntoSelectTarget, Columns::Sources: SourcesIn<Cons<T, Nil>, ScopeProof>, Columns::Marker: ResolveRow<T>,

Adds a RETURNING clause that reads columns of the inserted rows.

Pass one column or expression, a tuple, or () for every column (RETURNING *). Only columns of the target table may be used; other tables do not compile. The row type is inferred like a SELECT’s.

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

pub fn returning<Columns, ScopeProof>( 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: ExprSources + ToSQL<'a, SQLiteValue<'a>> + IntoSelectTarget, Columns::Sources: SourcesIn<Cons<T, Nil>, ScopeProof>, Columns::Marker: ResolveRow<T>,

Adds a RETURNING clause after the conflict clause. See returning.

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

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

where E: ExprSources + Expr<'a, SQLiteValue<'a>>, E::Sources: SourcesIn<Cons<T, Nil>, ScopeProof>, E::SQLType: BooleanLike,

Adds a WHERE to DO UPDATE SET, so the update only runs for conflicting rows that match.

Renders ON CONFLICT (..) DO UPDATE SET .. WHERE condition. The condition may only reference the target table.

pub fn returning<Columns, ScopeProof>( 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: ExprSources + ToSQL<'a, SQLiteValue<'a>> + IntoSelectTarget, Columns::Sources: SourcesIn<Cons<T, Nil>, ScopeProof>, Columns::Marker: ResolveRow<T>,

Adds a RETURNING clause after DO UPDATE SET. See returning.