Struct InsertStatement

#[non_exhaustive]
pub struct InsertStatement<T: QuerySource, U, Op = Insert, Ret = NoReturningClause> {
    pub operator: Op,
    pub target: T,
    pub records: U,
    pub returning: Ret,
    /* private fields */
}

Available on crate feature i-implement-a-third-party-backend-and-opt-into-breaking-changes only.

A fully constructed insert statement.

The parameters of this struct represent:

• T: The table we are inserting into
• U: The data being inserted
• Op: The operation being performed. The specific types used to represent this are private, but correspond to SQL such as INSERT or REPLACE. You can safely rely on the default type representing INSERT
• Ret: The RETURNING clause of the query. The specific types used to represent this are private. You can safely rely on the default type representing a query without a RETURNING clause.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

operator: Op

The operator used by this InsertStatement

Corresponds to either Insert or Replace

target: T

The table we are inserting into

records: U

The data which should be inserted

returning: Ret

An optional returning clause

Implementations

impl<T: QuerySource, U, Op, Ret> InsertStatement<T, U, Op, Ret>

pub fn new(target: T, records: U, operator: Op, returning: Ret) -> Self

Create a new InsertStatement instance

impl<T: QuerySource, U, C, Op, Ret> InsertStatement<T, InsertFromSelect<U, C>, Op, Ret>

pub fn into_columns<C2>( self, columns: C2, ) -> InsertStatement<T, InsertFromSelect<U, C2>, Op, Ret>

where C2: ColumnList<Table = T> + Expression, U: Query<SqlType = C2::SqlType>,

Set the column list when inserting from a select statement

See the documentation for insert_into for usage examples.

impl<T: QuerySource, U, Op> InsertStatement<T, U, Op>

pub fn returning<E>( self, returns: E, ) -> InsertStatement<T, U, Op, ReturningClause<E>>

where InsertStatement<T, U, Op, ReturningClause<E>>: Query,

Specify what expression is returned after execution of the insert.

Examples

Inserting records:

let inserted_names = diesel::insert_into(users)
    .values(&vec![name.eq("Timmy"), name.eq("Jimmy")])
    .returning(name)
    .get_results(connection)
    .unwrap();
// Note that the returned order is not guaranteed to be preserved
assert_eq!(inserted_names.len(), 2);
assert!(inserted_names.contains(&"Timmy".to_string()));
assert!(inserted_names.contains(&"Jimmy".to_string()));

impl<T, U, Op, Ret> InsertStatement<T, U, Op, Ret>

where T: QuerySource, U: UndecoratedInsertRecord<T> + IntoConflictValueClause,

pub fn on_conflict_do_nothing( self, ) -> InsertStatement<T, OnConflictValues<U::ValueClause, NoConflictTarget, DoNothing<T>>, Op, Ret>

Adds ON CONFLICT DO NOTHING to the insert statement, without specifying any columns or constraints to restrict the conflict to.

Examples

Single Record

let user = User { id: 1, name: "Sean" };

let user_count = users.count().get_result::<i64>(conn)?;
assert_eq!(user_count, 0);

diesel::insert_into(users)
    .values(&user)
    .on_conflict_do_nothing()
    .execute(conn)?;
let user_count = users.count().get_result::<i64>(conn)?;
assert_eq!(user_count, 1);

diesel::insert_into(users)
    .values(&user)
    .on_conflict_do_nothing()
    .execute(conn)?;
let user_count = users.count().get_result::<i64>(conn)?;
assert_eq!(user_count, 1);

Vec of Records

let user = User { id: 1, name: "Sean" };

let inserted_row_count = diesel::insert_into(users)
    .values(&vec![user, user])
    .on_conflict_do_nothing()
    .execute(conn)?;
let user_count = users.count().get_result::<i64>(conn)?;
assert_eq!(user_count, 1);

pub fn on_conflict<Target>( self, target: Target, ) -> IncompleteOnConflict<InsertStatement<T, U::ValueClause, Op, Ret>, ConflictTarget<Target>>

where ConflictTarget<Target>: OnConflictTarget<T>,

Adds an ON CONFLICT to the insert statement, if a conflict occurs for the given unique constraint.

Target can be one of:

• A column
• A tuple of columns
• on_constraint("constraint_name")

Examples

Specifying a column as the target

This is supported by sqlite and postgres only

use diesel::upsert::*;

diesel::sql_query("CREATE UNIQUE INDEX users_name ON users (name)").execute(conn).unwrap();
let user = User { id: 1, name: "Sean" };
let same_name_different_id = User { id: 2, name: "Sean" };
let same_id_different_name = User { id: 1, name: "Pascal" };
assert_eq!(Ok(1), diesel::insert_into(users).values(&user).execute(conn));

let query = diesel::insert_into(users)
    .values(&same_id_different_name)
    .on_conflict(id)
    .do_nothing()
    .execute(conn)?;

let user_names = users.select(name).load::<String>(conn)?;
assert_eq!(user_names, vec![String::from("Sean")]);

let idx_conflict_result = diesel::insert_into(users)
    .values(&same_name_different_id)
    .on_conflict(id)
    .do_nothing()
    .execute(conn);
assert!(idx_conflict_result.is_err());
#[cfg(feature = "mysql")]
fn run_test() -> diesel::QueryResult<()> { Ok(()) }

Specifying multiple columns as the target

This is supported by sqlite and postgres only

use diesel::upsert::*;

diesel::sql_query("CREATE UNIQUE INDEX users_name_hair_color ON users (name, hair_color)").execute(conn).unwrap();
let user = User { id: 1, name: "Sean", hair_color: "black" };
let same_name_different_hair_color = User { id: 2, name: "Sean", hair_color: "brown" };
let same_name_same_hair_color = User { id: 3, name: "Sean", hair_color: "black" };

assert_eq!(Ok(1), diesel::insert_into(users).values(&user).execute(conn));

let inserted_row_count = diesel::insert_into(users)
    .values(&same_name_different_hair_color)
    .on_conflict((name, hair_color))
    .do_nothing()
    .execute(conn);
assert_eq!(Ok(1), inserted_row_count);

let inserted_row_count = diesel::insert_into(users)
    .values(&same_name_same_hair_color)
    .on_conflict((name, hair_color))
    .do_nothing()
    .execute(conn);
assert_eq!(Ok(0), inserted_row_count);

#[cfg(feature = "mysql")]
fn main() {}

ON DUPLICATE KEY

Mysql supports only catching all duplicated keys at once:

use diesel::upsert::*;

diesel::sql_query("CREATE UNIQUE INDEX users_name ON users (name)").execute(conn).unwrap();
let user = User { id: 1, name: "Sean" };
let same_name_different_id = User { id: 2, name: "Sean" };
let same_id_different_name = User { id: 1, name: "Pascal" };

assert_eq!(Ok(1), diesel::insert_into(users).values(&user).execute(conn));

let user_names = users.select(name).load::<String>(conn)?;
assert_eq!(user_names, vec![String::from("Sean")]);

let query = diesel::insert_into(users)
    .values(&same_id_different_name)
    .on_conflict(diesel::dsl::DuplicatedKeys)
    .do_nothing()
    .execute(conn)?;

let user_names = users.select(name).load::<String>(conn)?;
assert_eq!(user_names, vec![String::from("Sean")]);

let idx_conflict_result = diesel::insert_into(users)
    .values(&same_name_different_id)
    .on_conflict(diesel::dsl::DuplicatedKeys)
    .do_nothing()
    .execute(conn)?;

let user_names = users.select(name).load::<String>(conn)?;
assert_eq!(user_names, vec![String::from("Sean")]);
#[cfg(not(feature = "mysql"))]
fn run_test() -> diesel::QueryResult<()> {Ok(())}

See the documentation for on_constraint and do_update for more examples.

Trait Implementations

impl<T, U, Op> AsQuery for InsertStatement<T, U, Op, NoReturningClause>

where T: Table, InsertStatement<T, U, Op, ReturningClause<T::AllColumns>>: Query,

type SqlType = <<InsertStatement<T, U, Op> as AsQuery>::Query as Query>::SqlType

The SQL type of Self::Query

type Query = InsertStatement<T, U, Op, ReturningClause<<T as Table>::AllColumns>>

What kind of query does this type represent?

fn as_query(self) -> Self::Query

Converts a type which semantically represents a SQL query into the actual query being executed. See the trait level docs for more.

impl<T: Clone + QuerySource, U: Clone, Op: Clone, Ret: Clone> Clone for InsertStatement<T, U, Op, Ret>

where T::FromClause: Clone,

fn clone(&self) -> InsertStatement<T, U, Op, Ret>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + QuerySource, U: Debug, Op: Debug, Ret: Debug> Debug for InsertStatement<T, U, Op, Ret>

where T::FromClause: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<V, T, QId, C, Op, O, const STATIC_QUERY_ID: bool> ExecuteDsl<C, Sqlite> for InsertStatement<T, BatchInsert<Vec<ValuesClause<V, T>>, T, QId, STATIC_QUERY_ID>, Op>

where T: QuerySource, C: Connection<Backend = Sqlite>, V: ContainsDefaultableValue<Out = O>, O: Default, (O, Self): ExecuteDsl<C, Sqlite>,

Available on crate feature sqlite only.

fn execute(query: Self, conn: &mut C) -> QueryResult<usize>

Execute this command

impl<T, U, Op, Ret> Query for InsertStatement<T, U, Op, ReturningClause<Ret>>

where T: QuerySource, Ret: Expression + SelectableExpression<T> + NonAggregate,

type SqlType = <Ret as Expression>::SqlType

The SQL type that this query represents.

impl<T, U, Op, Ret, DB> QueryFragment<DB> for InsertStatement<T, U, Op, Ret>

where DB: Backend + DieselReserveSpecialization, T: Table, T::FromClause: QueryFragment<DB>, U: QueryFragment<DB> + CanInsertInSingleQuery<DB>, Op: QueryFragment<DB>, Ret: QueryFragment<DB>,

fn walk_ast<'b>(&'b self, out: AstPass<'_, 'b, DB>) -> QueryResult<()>

Walk over this QueryFragment for all passes.

fn to_sql(&self, out: &mut DB::QueryBuilder, backend: &DB) -> QueryResult<()>

Available on crate feature i-implement-a-third-party-backend-and-opt-into-breaking-changes only.

Converts this QueryFragment to its SQL representation.

fn collect_binds<'b>( &'b self, out: &mut DB::BindCollector<'b>, metadata_lookup: &mut DB::MetadataLookup, backend: &'b DB, ) -> QueryResult<()>

Available on crate feature i-implement-a-third-party-backend-and-opt-into-breaking-changes only.

Serializes all bind parameters in this query.

fn is_safe_to_cache_prepared(&self, backend: &DB) -> QueryResult<bool>

Available on crate feature i-implement-a-third-party-backend-and-opt-into-breaking-changes only.

Is this query safe to store in the prepared statement cache?

fn is_noop(&self, backend: &DB) -> QueryResult<bool>

Available on crate feature i-implement-a-third-party-backend-and-opt-into-breaking-changes only.

Does walking this AST have any effect?

impl<T, U, Op, Ret> QueryId for InsertStatement<T, U, Op, Ret>

where T: QuerySource + QueryId + 'static, U: QueryId, Op: QueryId, Ret: QueryId,

const HAS_STATIC_QUERY_ID: bool = _

Can the SQL generated by Self be uniquely identified by its type?

type QueryId = InsertStatement<T, <U as QueryId>::QueryId, <Op as QueryId>::QueryId, <Ret as QueryId>::QueryId>

A type which uniquely represents Self in a SQL query.

fn query_id() -> Option<TypeId>

Returns the type id of Self::QueryId if Self::HAS_STATIC_QUERY_ID. Returns None otherwise.

impl<T: QuerySource, U, Op, Ret, Conn> RunQueryDsl<Conn> for InsertStatement<T, U, Op, Ret>

fn execute(self, conn: &mut Conn) -> QueryResult<usize>

where Conn: Connection, Self: ExecuteDsl<Conn>,

Executes the given command, returning the number of rows affected.

fn load<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>

where Self: LoadQuery<'query, Conn, U>,

Executes the given query, returning a Vec with the returned rows.

fn load_iter<'conn, 'query: 'conn, U, B>( self, conn: &'conn mut Conn, ) -> QueryResult<Self::RowIter<'conn>>

where U: 'conn, Self: LoadQuery<'query, Conn, U, B> + 'conn,

Executes the given query, returning an Iterator with the returned rows.

fn get_result<'query, U>(self, conn: &mut Conn) -> QueryResult<U>

where Self: LoadQuery<'query, Conn, U>,

Runs the command, and returns the affected row.

fn get_results<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>

where Self: LoadQuery<'query, Conn, U>,

Runs the command, returning an Vec with the affected rows.

impl<T: Copy + QuerySource, U: Copy, Op: Copy, Ret: Copy> Copy for InsertStatement<T, U, Op, Ret>

where T::FromClause: Copy,