Struct UpdateStatement 

pub struct UpdateStatement<T: QuerySource, U, V = SetNotCalled, Ret = NoReturningClause> { /* private fields */ }

Represents a complete UPDATE statement.

See update for usage examples, or the update guide for a more exhaustive set of examples.

Implementations

impl<T: QuerySource, U> UpdateStatement<T, U, SetNotCalled>

pub fn set<V>(self, values: V) -> Set<Self, V>

where T: Table, V: AsChangeset<Target = T>, UpdateStatement<T, U, V::Changeset>: AsQuery,

Provides the SET clause of the UPDATE statement.

See update for usage examples, or the update guide for a more exhaustive set of examples.

impl<T: QuerySource, U, V, Ret> UpdateStatement<T, U, V, Ret>

pub fn filter<Predicate>(self, predicate: Predicate) -> Filter<Self, Predicate>

where Self: FilterDsl<Predicate>,

Adds the given predicate to the WHERE clause of the statement being constructed.

If there is already a WHERE clause, the predicate will be appended with AND. There is no difference in behavior between update(table.filter(x)) and update(table).filter(x).

Example

let updated_rows = diesel::update(users)
    .set(name.eq("Jim"))
    .filter(name.eq("Sean"))
    .execute(connection);
assert_eq!(Ok(1), updated_rows);

let expected_names = vec!["Jim".to_string(), "Tess".to_string()];
let names = users.select(name).order(id).load(connection);

assert_eq!(Ok(expected_names), names);

pub fn into_boxed<'a, DB>(self) -> IntoBoxed<'a, Self, DB>

where DB: Backend, Self: BoxedDsl<'a, DB>,

Boxes the WHERE clause of this update statement.

This is useful for cases where you want to conditionally modify a query, but need the type to remain the same. The backend must be specified as part of this. It is not possible to box a query and have it be useable on multiple backends.

A boxed query will incur a minor performance penalty, as the query builder can no longer be inlined by the compiler. For most applications this cost will be minimal.

Example

let mut query = diesel::update(users).set(name.eq("Jerk")).into_boxed();

if !params["tess_has_been_a_jerk"] {
    query = query.filter(name.ne("Tess"));
}

let updated_rows = query.execute(connection)?;
assert_eq!(1, updated_rows);

let expected_names = vec!["Jerk", "Tess"];
let names = users.select(name).order(id).load::<String>(connection)?;

assert_eq!(expected_names, names);

pub fn into_boxed_clone<'a, DB>(self) -> IntoBoxedClone<'a, Self, DB>

where DB: Backend, Self: BoxedCloneDsl<'a, DB>,

Wraps the WHERE clause of this update statement in an Arc.

This is useful for cases where you want to clone and conditionally modify a query, but need the type to remain the same. The backend must be specified as part of this. It is not possible to box a query and have it be useable on multiple backends.

A cloneable boxed query will incur a slightly greater performance penalty than a standard boxed query. In both cases, the query builder can no longer be inlined by the compiler. For most applications this cost will be minimal.

Example

let query = diesel::update(users).set(name.eq("Jerk")).into_boxed_clone();
let mut query = query.clone();

if !params["tess_has_been_a_jerk"] {
    query = query.filter(name.ne("Tess"));
}

let updated_rows = query.execute(connection)?;
assert_eq!(1, updated_rows);

let expected_names = vec!["Jerk", "Tess"];
let names = users.select(name).order(id).load::<String>(connection)?;

assert_eq!(expected_names, names);

impl<T: QuerySource, U, V> UpdateStatement<T, U, V, NoReturningClause>

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

where T: Table, UpdateStatement<T, U, V, ReturningClause<E>>: Query,

Specify what expression is returned after execution of the update.

On MariaDB, rows that match the filter but whose values do not change are left out of the result, so get_result returns NotFound where execute reports one updated row (MDEV-41113).

Examples

Updating a single record:

let updated_name = diesel::update(users.filter(id.eq(1)))
    .set(name.eq("Dean"))
    .returning(name)
    .get_result(connection);
assert_eq!(Ok("Dean".to_string()), updated_name);

Returning the pre-update value (PostgreSQL 18+):

RETURNING old.col — exposed via diesel::pg::returning::old() — returns the value of the column before the update was applied. This requires PostgreSQL 18 or newer.

let was_and_now = diesel::update(users.filter(id.eq(1)))
    .set(name.eq("Dean"))
    .returning((old(name), name))
    .get_result::<(String, String)>(connection);
assert_eq!(Ok(("Sean".to_string(), "Dean".to_string())), was_and_now);

Trait Implementations

impl<T, U, V> AsQuery for UpdateStatement<T, U, V, NoReturningClause>

where T: Table, UpdateStatement<T, U, V, ReturningClause<T::AllColumns>>: Query, T::AllColumns: SelectableExpression<ReturningQuerySource<UpdateStmt, T>> + ValidGrouping<()>, <T::AllColumns as ValidGrouping<()>>::IsAggregate: MixedAggregates<No, Output = No>,

type SqlType = <<UpdateStatement<T, U, V> as AsQuery>::Query as Query>::SqlType

The SQL type of Self::Query

type Query = UpdateStatement<T, U, V, 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<'a, T, U, V, Ret, DB> BoxedCloneDsl<'a, DB> for UpdateStatement<T, U, V, Ret>

where T: QuerySource, U: Into<BoxedCloneWhereClause<'a, DB>>,

type Output = UpdateStatement<T, BoxedCloneWhereClause<'a, DB>, V, Ret>

The return type of internal_into_boxed_clone

fn internal_into_boxed_clone(self) -> Self::Output

See the trait documentation.

impl<'a, T, U, V, Ret, DB> BoxedDsl<'a, DB> for UpdateStatement<T, U, V, Ret>

where T: QuerySource, U: Into<BoxedWhereClause<'a, DB>>,

type Output = UpdateStatement<T, BoxedWhereClause<'a, DB>, V, Ret>

The return type of internal_into_boxed

fn internal_into_boxed(self) -> Self::Output

See the trait documentation.

impl<T: Clone + QuerySource, U: Clone, V: Clone, Ret: Clone> Clone for UpdateStatement<T, U, V, Ret>

where T::FromClause: Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug + QuerySource, U: Debug, V: Debug, Ret: Debug> Debug for UpdateStatement<T, U, V, Ret>

where T::FromClause: Debug,

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

Formats the value using the given formatter.

impl<T, U, V, Ret, Predicate> FilterDsl<Predicate> for UpdateStatement<T, U, V, Ret>

where T: QuerySource, U: WhereAnd<Predicate>, Predicate: AppearsOnTable<T>,

type Output = UpdateStatement<T, <U as WhereAnd<Predicate>>::Output, V, Ret>

The type returned by .filter.

fn filter(self, predicate: Predicate) -> Self::Output

See the trait documentation.

impl<T, U, V, Ret> Query for UpdateStatement<T, U, V, ReturningClause<Ret>>

where T: Table, Ret: SelectableExpression<ReturningQuerySource<UpdateStmt, T>> + ValidGrouping<()>, Ret::IsAggregate: MixedAggregates<No, Output = No>,

type SqlType = <Ret as Expression>::SqlType

The SQL type that this query represents.

impl<T, U, V, Ret, DB> QueryFragment<DB> for UpdateStatement<T, U, V, Ret>

where DB: Backend + DieselReserveSpecialization, T: Table, T::FromClause: QueryFragment<DB>, U: QueryFragment<DB>, V: QueryFragment<DB> + AllowFilterForUpdate<U>, 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, V, Ret> QueryId for UpdateStatement<T, U, V, Ret>

where T: QuerySource,

const HAS_STATIC_QUERY_ID: bool = false

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

type 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<S, T, U, V> ReturningClauseHelper<S> for UpdateStatement<T, U, V>

where T: QuerySource,

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

type WithReturning = UpdateStatement<T, U, V, ReturningClause<S>>

Self with a RETURNING S clause attached.

impl<T: QuerySource, U, V, Ret> RunQueryDslSupport for UpdateStatement<T, U, V, Ret>