Type Alias Values

pub type Values<I, U> = InsertStatement<<I as InsertAutoTypeHelper>::Table, <U as Insertable<<I as InsertAutoTypeHelper>::Table>>::Values, <I as InsertAutoTypeHelper>::Op>;

Represents the return type of IncompleteInsertStatement::values()

Aliased Type

struct Values<I, U> {
    pub operator: <I as InsertAutoTypeHelper>::Op,
    pub target: <I as InsertAutoTypeHelper>::Table,
    pub records: <U as Insertable<<I as InsertAutoTypeHelper>::Table>>::Values,
    pub returning: NoReturningClause,
    /* private fields */
}

Fields

operator: <I as InsertAutoTypeHelper>::Op

The operator used by this InsertStatement

Corresponds to either Insert or Replace

target: <I as InsertAutoTypeHelper>::Table

The table we are inserting into

records: <U as Insertable<<I as InsertAutoTypeHelper>::Table>>::Values

The data which should be inserted

returning: NoReturningClause

An optional returning clause

Implementations

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: 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, 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<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<()>

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

Serializes all bind parameters in this query.

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

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

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

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