pub struct InsertStatement<T, U, Op = Insert, Ret = NoReturningClause> { /* private fields */ }
Expand description

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.

Implementations

Set the column list when inserting from a select statement

See the documentation for insert_into for usage examples.

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);
assert_eq!(Ok(vec!["Timmy".to_string(), "Jimmy".to_string()]), inserted_names);

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 inserted_row_count = diesel::insert_into(users)
    .values(&user)
    .on_conflict_do_nothing()
    .execute(&conn);
assert_eq!(Ok(1), inserted_row_count);

let inserted_row_count = diesel::insert_into(users)
    .values(&user)
    .on_conflict_do_nothing()
    .execute(&conn);
assert_eq!(Ok(0), inserted_row_count);
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);
assert_eq!(Ok(1), inserted_row_count);

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

Target can be one of:

Examples
Specifying a column as the target
conn.execute("CREATE UNIQUE INDEX users_name ON users (name)").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 inserted_row_count = diesel::insert_into(users)
    .values(&same_name_different_id)
    .on_conflict(name)
    .do_nothing()
    .execute(&conn);
assert_eq!(Ok(0), inserted_row_count);

let pk_conflict_result = diesel::insert_into(users)
    .values(&same_id_different_name)
    .on_conflict(name)
    .do_nothing()
    .execute(&conn);
assert!(pk_conflict_result.is_err());
Specifying multiple columns as the target
use diesel::pg::upsert::*;

conn.execute("CREATE UNIQUE INDEX users_name_hair_color ON users (name, hair_color)").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);

See the documentation for on_constraint and do_update for more examples.

Trait Implementations

The SQL type of Self::Query

What kind of query does this type represent?

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

The SQL type that this query represents. Read more

Walk over this QueryFragment for all passes. Read more

Converts this QueryFragment to its SQL representation. Read more

Serializes all bind parameters in this query. Read more

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

A type which uniquely represents Self in a SQL query. Read more

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

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

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

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

Runs the command, and returns the affected row. Read more

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

Attempts to load a single record. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

The SQL type of Self::Query

What kind of query does this type represent?

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

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Execute this command

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Convert self to an expression for Diesel’s query builder. Read more

Convert &self to an expression for Diesel’s query builder. Read more

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.