Enum UpsertOutcome 

pub enum UpsertOutcome<M> {
    Inserted(M),
    Existing(M),
}

Outcome of a .upsert(..).do_nothing().run(..) call.

Race semantics

The runtime always resolves the conflict under a SELECT ... FOR UPDATE row lock held for the lifetime of the surrounding transaction (see upsert_do_nothing_exec::run_upsert_do_nothing_in_tx for the exact sequencing):

• If the probe finds an existing row, that row is locked before this call returns — no concurrent transaction can delete or modify it until the caller commits — so Existing is a guarantee about the row’s state at the moment this call returns, not merely “at some point during the call”.
• If the probe finds nothing, the actual INSERT ... ON CONFLICT DO NOTHING is still the statement that runs (not a plain INSERT), because the probe’s “no row” answer does not itself lock anything — a concurrent transaction can commit a conflicting row in the gap between the probe and the INSERT. When that race is lost, the runtime performs one more locked read to hand back the row the other transaction actually committed, so callers never see a phantom “existing” row invented from stale data — see Existing below for what happens if that row is deleted before the fallback read completes.

Variants

Inserted(M)

This call performed the insert. No row previously existed at the conflict target.

Existing(M)

A row already existed at the conflict target and was left completely untouched by this call — no columns written, no Updated event emitted, no audit entry recorded, because nothing about the row changed.

If this outcome was reached via the race-fallback path (the insert branch lost a concurrent-insert race and had to read the winning row back), and that row was deleted before the fallback read could complete, the call surfaces CoolError::Conflict instead of ever constructing an Existing from data that might not be current — see upsert_do_nothing_exec for that narrower race.

Implementations

impl<M> UpsertOutcome<M>

pub fn was_inserted(&self) -> bool

true for Self::Inserted.

pub fn into_record(self) -> M

Discard the inserted-vs-existing distinction and take the row. Prefer matching on the enum when the distinction matters (that’s the entire reason this type exists) — this is for callers that only ever need the record, e.g. read-modify-report call sites that already branched on Self::was_inserted.

pub fn record(&self) -> &M

Borrow the record regardless of which variant this is.

Trait Implementations

impl<M: Clone> Clone for UpsertOutcome<M>

fn clone(&self) -> UpsertOutcome<M>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<M: Debug> Debug for UpsertOutcome<M>

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

Formats the value using the given formatter.

impl<M: Eq> Eq for UpsertOutcome<M>

impl<M: PartialEq> PartialEq for UpsertOutcome<M>

fn eq(&self, other: &UpsertOutcome<M>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<M: PartialEq> StructuralPartialEq for UpsertOutcome<M>