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

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

Aliased Type

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

Fields

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

Implementations

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

where Table: PostgresTable<'a>,

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

Specifies a single row to insert. Shorthand for .values([row]).

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

where I: IntoIterator<Item = Table::Insert<T>>,

Specifies multiple rows to insert.

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

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

Chooses an explicit ordered target-column list for an INSERT SELECT.

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, PostgresValue<'a>, Table, R> + InsertSourceInScope<ScopeProof> + MarkerAggValidFor<Q::Grouped, AggProof>,

Inserts a checked SELECT into every insertable table column.

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

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

Inserts an unchecked raw SELECT without a target list.

This opts out of projection shape, type, nullability, source-scope, and aggregate validation.

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

where Table: PostgresTable<'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, PostgresValue<'a>, Targets> + InsertSourceInScope<ScopeProof> + MarkerAggValidFor<Q::Grouped, AggProof>,

Inserts a checked SELECT into the chosen target columns.

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

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

Inserts an unchecked raw SELECT into the chosen target columns.

This opts out of projection shape, type, nullability, source-scope, and aggregate validation.

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 specific columns.

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::postgres::prelude::*;
use drizzle::postgres::builder::QueryBuilder;

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

#[PostgresIndex(unique)]
struct UserEmailIdx(User::email);

#[derive(PostgresSchema)]
struct Schema {
    user: User,
    user_email_idx: UserEmailIdx,
}

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

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

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

// Target a unique index
builder.insert(user).values([InsertUser::new("Alice")])
    .on_conflict(schema.user_email_idx).do_nothing();
}

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

Begins a typed ON CONFLICT ON CONSTRAINT clause (PostgreSQL-only).

The target must implement NamedConstraint<T>, which is auto-generated for unique columns and named unique constraints. Standalone indexes are conflict targets, but PostgreSQL does not accept them after ON CONFLICT ON CONSTRAINT.

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

Examples

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

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

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

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

let user = schema.user;
builder.insert(user).values([InsertUser::new("Alice")])
    .on_conflict_on_constraint(user.email).do_nothing();
}

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, PostgresValue<'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, PostgresValue<'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, PostgresValue<'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, PostgresValue<'a>> + IntoSelectTarget, Columns::Marker: ResolveRow<T>,

Adds a RETURNING clause after DO UPDATE SET