pub struct SetClause { /* private fields */ }Expand description
Accumulates col = :col SET fragments and their bound values for
INSERT INTO … SET … / UPDATE … SET … statements whose shape is only
known at runtime (optional fields, conditional writes).
The placeholder name IS the column name, so a fragment can never reference a param that wasn’t bound — the silently-nulling placeholder/key mismatch failure mode is unrepresentable by construction.
let clause = SetClause::new()
.set("completed_at", now)
.set_opt("score", score) // None → column omitted entirely
.set_when(rewrite, "audio_model", model);
let sql = format!("UPDATE t SET {} WHERE id = :id", clause.sql());
client.execute_with_values(&sql, clause.set("id", id).into_params()).await?;None handling is deliberately omit, don’t bind: on UPDATE paths the
stored value is preserved, on INSERT paths the schema default/null applies.
List writes: append is the
server-side append (col = col || :param). Positional element updates
have no server-native form: SET list[i] = :v is
accepted-but-silently-ignored and PUT list i :v is a syntax error —
read-modify-write (select the list, patch in Rust,
set the whole list) remains the shape for
those.
Implementations§
Source§impl SetClause
impl SetClause
pub fn new() -> Self
Sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
True when nothing was pushed (callers may want to skip the write).
Sourcepub fn set(self, col: &str, value: impl IntoGrpcValue) -> Self
pub fn set(self, col: &str, value: impl IntoGrpcValue) -> Self
Always include col = :col with the bound value. Build each column
once — re-setting emits the fragment twice (last value wins).
Sourcepub fn set_opt<T: IntoGrpcValue>(self, col: &str, value: Option<T>) -> Self
pub fn set_opt<T: IntoGrpcValue>(self, col: &str, value: Option<T>) -> Self
set only when value is Some.
Sourcepub fn set_when(self, cond: bool, col: &str, value: impl IntoGrpcValue) -> Self
pub fn set_when(self, cond: bool, col: &str, value: impl IntoGrpcValue) -> Self
set only when cond holds.
Sourcepub fn set_raw(
self,
fragment: impl Into<String>,
name: &str,
value: impl IntoGrpcValue,
) -> Self
pub fn set_raw( self, fragment: impl Into<String>, name: &str, value: impl IntoGrpcValue, ) -> Self
Escape hatch for fragments that are not a plain col = :col.
The fragment must still reference :name; name is registered
so it can never dangle.
Sourcepub fn set_expr(self, col: &str, expr: &str) -> Self
pub fn set_expr(self, col: &str, expr: &str) -> Self
Set a column to a SERVER-SIDE expression (count = count + 1,
checked_at = sysdate()) — the increment/anchor forms that have no
client-side value to bind. Both halves are caller-owned SQL: col
must be a plain schema identifier (same contract as
set, which likewise interpolates it), expr is
inserted verbatim — never data.
Sourcepub fn bind(self, name: &str, value: impl IntoGrpcValue) -> Self
pub fn bind(self, name: &str, value: impl IntoGrpcValue) -> Self
Register a param WITHOUT emitting a fragment — for values referenced
from elsewhere in the statement. Composes with
sql/into_params.
Sourcepub fn apply_if<T>(
self,
option: Option<T>,
f: impl FnOnce(Self, T) -> Self,
) -> Self
pub fn apply_if<T>( self, option: Option<T>, f: impl FnOnce(Self, T) -> Self, ) -> Self
Apply a multi-call step only when option is Some — the
conditional-composition form for write shapes that need more than
one builder call (e.g. append + bind
together). None passes the clause through untouched. Read-side
twin: FilterClause::apply_if.
let clause = SetClause::new()
.apply_if(Some("red"), |c, v| c.append("labels", v))
.apply_if(None::<String>, |c, v| c.set("note", v));
assert_eq!(clause.sql(), "labels = labels || :labels__append");Sourcepub fn append(self, col: &str, value: impl IntoGrpcValue) -> Self
pub fn append(self, col: &str, value: impl IntoGrpcValue) -> Self
Server-side list append: emits col = col || :{col}__append with the
element bound as a one-element list. One roundtrip, no
read-merge-write window, works on a NULL column
(null || [x] = [x]) and preserves element kinds.
Chained appends on the same column coalesce into ONE fragment + one
merged list param. Appending to a column also plain-set in the
same clause is unsupported (build one or the other).
The idempotent append is one statement — CONTAINS accepts the same
single-element list param as a membership test:
let clause = SetClause::new().append("labels", "red");
assert_eq!(clause.sql(), "labels = labels || :labels__append");The update’s affected_records is the “did it change” bool.
Sourcepub fn set_or_null<T: IntoGrpcValue>(self, col: &str, value: Option<T>) -> Self
pub fn set_or_null<T: IntoGrpcValue>(self, col: &str, value: Option<T>) -> Self
set when value is Some; explicitly null the
column when None.
Unlike set_opt (which omits None columns to
preserve stored values), this is the write-what-you-mean form for
refresh paths where an absent source field must CLEAR stale data.
The None arm cannot bind: the wire oneof has no null kind, so an
unset value is simply skipped server-side (no property can be
nulled through a bound parameter) — it falls back to a col = null
SQL literal, the only spelling the engine actually honors.
The only interpolated text is the column name (caller-owned schema
identifier, never data).
Sourcepub fn sql(&self) -> String
pub fn sql(&self) -> String
The SET-clause body: a = :a, b = :b. Empty string when nothing was
pushed (callers decide whether an empty SET is valid for their shape).
Sourcepub fn into_params(self) -> Params
pub fn into_params(self) -> Params
Consume into Params for query_with_values / execute_with_values.
Trait Implementations§
Auto Trait Implementations§
impl Freeze for SetClause
impl RefUnwindSafe for SetClause
impl Send for SetClause
impl Sync for SetClause
impl Unpin for SetClause
impl UnsafeUnpin for SetClause
impl UnwindSafe for SetClause
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§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoRequest<T> for T
impl<T> IntoRequest<T> for T
Source§fn into_request(self) -> Request<T>
fn into_request(self) -> Request<T>
T in a tonic::Request