Struct diesel::query_builder::InsertStatement
source · #[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 */
}
i-implement-a-third-party-backend-and-opt-into-breaking-changes
only.Expand description
A fully constructed insert statement.
The parameters of this struct represent:
T
: The table we are inserting intoU
: The data being insertedOp
: The operation being performed. The specific types used to represent this are private, but correspond to SQL such asINSERT
orREPLACE
. You can safely rely on the default type representingINSERT
Ret
: TheRETURNING
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 aRETURNING
clause.
Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
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§
source§impl<T: QuerySource, U, Op, Ret> InsertStatement<T, U, Op, Ret>
impl<T: QuerySource, U, Op, Ret> InsertStatement<T, U, Op, Ret>
source§impl<T: QuerySource, U, C, Op, Ret> InsertStatement<T, InsertFromSelect<U, C>, Op, Ret>
impl<T: QuerySource, U, C, Op, Ret> InsertStatement<T, InsertFromSelect<U, C>, Op, Ret>
sourcepub fn into_columns<C2>(
self,
columns: C2,
) -> InsertStatement<T, InsertFromSelect<U, C2>, Op, Ret>
pub fn into_columns<C2>( self, columns: C2, ) -> InsertStatement<T, InsertFromSelect<U, C2>, Op, Ret>
Set the column list when inserting from a select statement
See the documentation for insert_into
for usage examples.
source§impl<T: QuerySource, U, Op> InsertStatement<T, U, Op>
impl<T: QuerySource, U, Op> InsertStatement<T, U, Op>
sourcepub fn returning<E>(
self,
returns: E,
) -> InsertStatement<T, U, Op, ReturningClause<E>>
pub fn returning<E>( self, returns: E, ) -> InsertStatement<T, U, Op, ReturningClause<E>>
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()));
source§impl<T, U, Op, Ret> InsertStatement<T, U, Op, Ret>where
T: QuerySource,
U: UndecoratedInsertRecord<T> + IntoConflictValueClause,
impl<T, U, Op, Ret> InsertStatement<T, U, Op, Ret>where
T: QuerySource,
U: UndecoratedInsertRecord<T> + IntoConflictValueClause,
sourcepub fn on_conflict_do_nothing(
self,
) -> InsertStatement<T, OnConflictValues<U::ValueClause, NoConflictTarget, DoNothing<T>>, Op, Ret>
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);
sourcepub fn on_conflict<Target>(
self,
target: Target,
) -> IncompleteOnConflict<InsertStatement<T, U::ValueClause, Op, Ret>, ConflictTarget<Target>>where
ConflictTarget<Target>: OnConflictTarget<T>,
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§
source§impl<T, U, Op> AsQuery for InsertStatement<T, U, Op, NoReturningClause>
impl<T, U, Op> AsQuery for InsertStatement<T, U, Op, NoReturningClause>
source§type SqlType = <<InsertStatement<T, U, Op> as AsQuery>::Query as Query>::SqlType
type SqlType = <<InsertStatement<T, U, Op> as AsQuery>::Query as Query>::SqlType
Self::Query
source§type Query = InsertStatement<T, U, Op, ReturningClause<<T as Table>::AllColumns>>
type Query = InsertStatement<T, U, Op, ReturningClause<<T as Table>::AllColumns>>
source§impl<T: Clone + QuerySource, U: Clone, Op: Clone, Ret: Clone> Clone for InsertStatement<T, U, Op, Ret>where
T::FromClause: Clone,
impl<T: Clone + QuerySource, U: Clone, Op: Clone, Ret: Clone> Clone for InsertStatement<T, U, Op, Ret>where
T::FromClause: Clone,
source§fn clone(&self) -> InsertStatement<T, U, Op, Ret>
fn clone(&self) -> InsertStatement<T, U, Op, Ret>
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl<T: Debug + QuerySource, U: Debug, Op: Debug, Ret: Debug> Debug for InsertStatement<T, U, Op, Ret>where
T::FromClause: Debug,
impl<T: Debug + QuerySource, U: Debug, Op: Debug, Ret: Debug> Debug for InsertStatement<T, U, Op, Ret>where
T::FromClause: Debug,
source§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.
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>,
sqlite
only.source§impl<T, U, Op, Ret> Query for InsertStatement<T, U, Op, ReturningClause<Ret>>
impl<T, U, Op, Ret> Query for InsertStatement<T, U, Op, ReturningClause<Ret>>
source§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>,
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>,
source§fn walk_ast<'b>(&'b self, out: AstPass<'_, 'b, DB>) -> QueryResult<()>
fn walk_ast<'b>(&'b self, out: AstPass<'_, 'b, DB>) -> QueryResult<()>
QueryFragment
for all passes. Read moresource§fn to_sql(&self, out: &mut DB::QueryBuilder, backend: &DB) -> QueryResult<()>
fn to_sql(&self, out: &mut DB::QueryBuilder, backend: &DB) -> QueryResult<()>
i-implement-a-third-party-backend-and-opt-into-breaking-changes
only.QueryFragment
to its SQL representation. Read moresource§fn collect_binds<'b>(
&'b self,
out: &mut DB::BindCollector<'b>,
metadata_lookup: &mut DB::MetadataLookup,
backend: &'b DB,
) -> QueryResult<()>
fn collect_binds<'b>( &'b self, out: &mut DB::BindCollector<'b>, metadata_lookup: &mut DB::MetadataLookup, backend: &'b DB, ) -> QueryResult<()>
i-implement-a-third-party-backend-and-opt-into-breaking-changes
only.source§fn is_safe_to_cache_prepared(&self, backend: &DB) -> QueryResult<bool>
fn is_safe_to_cache_prepared(&self, backend: &DB) -> QueryResult<bool>
i-implement-a-third-party-backend-and-opt-into-breaking-changes
only.source§impl<T, U, Op, Ret> QueryId for InsertStatement<T, U, Op, Ret>
impl<T, U, Op, Ret> QueryId for InsertStatement<T, U, Op, Ret>
source§impl<T: QuerySource, U, Op, Ret, Conn> RunQueryDsl<Conn> for InsertStatement<T, U, Op, Ret>
impl<T: QuerySource, U, Op, Ret, Conn> RunQueryDsl<Conn> for InsertStatement<T, U, Op, Ret>
source§fn load<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>where
Self: LoadQuery<'query, Conn, U>,
fn load<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>where
Self: LoadQuery<'query, Conn, U>,
source§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,
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,
source§fn get_result<'query, U>(self, conn: &mut Conn) -> QueryResult<U>where
Self: LoadQuery<'query, Conn, U>,
fn get_result<'query, U>(self, conn: &mut Conn) -> QueryResult<U>where
Self: LoadQuery<'query, Conn, U>,
source§fn get_results<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>where
Self: LoadQuery<'query, Conn, U>,
fn get_results<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>where
Self: LoadQuery<'query, Conn, U>,
Vec
with the affected rows. Read moreimpl<T: Copy + QuerySource, U: Copy, Op: Copy, Ret: Copy> Copy for InsertStatement<T, U, Op, Ret>where
T::FromClause: Copy,
Auto Trait Implementations§
impl<T, U, Op, Ret> Freeze for InsertStatement<T, U, Op, Ret>
impl<T, U, Op, Ret> RefUnwindSafe for InsertStatement<T, U, Op, Ret>where
Op: RefUnwindSafe,
T: RefUnwindSafe,
U: RefUnwindSafe,
Ret: RefUnwindSafe,
<T as QuerySource>::FromClause: RefUnwindSafe,
impl<T, U, Op, Ret> Send for InsertStatement<T, U, Op, Ret>
impl<T, U, Op, Ret> Sync for InsertStatement<T, U, Op, Ret>
impl<T, U, Op, Ret> Unpin for InsertStatement<T, U, Op, Ret>
impl<T, U, Op, Ret> UnwindSafe for InsertStatement<T, U, Op, Ret>where
Op: UnwindSafe,
T: UnwindSafe,
U: UnwindSafe,
Ret: UnwindSafe,
<T as QuerySource>::FromClause: UnwindSafe,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)