Struct UpsertRecord 

pub struct UpsertRecord<'a, M, PK, I>
where
    M: 'static,
    PK: 'static,
{ /* private fields */ }

Implementations

impl<'a, M, PK, I> UpsertRecord<'a, M, PK, I>

where M: 'static, PK: 'static, I: UpsertModelInput<M>,

pub fn on_conflict(self, target: ConflictTarget) -> UpsertRecord<'a, M, PK, I>

Choose the conflict target. Defaults to the model’s primary key; pass ConflictTarget::columns to upsert on a composite unique key instead. The named columns must form a UNIQUE constraint/index on the target table.

pub fn do_nothing(self) -> UpsertRecordDoNothing<'a, M, PK, I>

Switch this call to ON CONFLICT ... DO NOTHING semantics (cratestack#487), independent of descriptor.upsert_update_columns: on conflict, leave the existing row completely untouched instead of merging upsert_update_columns into it. This is the idempotent-insert shape ledger-style writes need — e.g. a cash-in claim that inserts a PENDING row and treats a conflict as “already in flight” must never let a retry’s blank values overwrite an existing COMPLETED row’s transfer_ref.

Returns a distinct builder type rather than a flag on UpsertRecord because the return shape genuinely changes: a real DO NOTHING returns nothing on conflict, so the caller needs Inserted vs Existing distinguishable in the type (crate::UpsertOutcome) rather than collapsed into a plain M the way .run() returns it today. Encoding that as a separate type also means existing .upsert(..).run(..) callers keep their Result<M, CratestackError> signature unchanged — this is purely additive, not a behavior change for the DO UPDATE path.

pub fn preview_sql(&self) -> String

Render an approximate SQL preview. The actual upsert wraps a SELECT … FOR UPDATE around the INSERT … ON CONFLICT, but this preview returns only the conflict-bearing statement.

Deliberately does NOT call ConflictTarget::validate (cratestack#741 finding 3) — every other preview_sql() in this codebase (find_many, create, update, delete, …) returns a bare String, no Result, so it can never fail; matching that established shape here means cratestack-studio’s interactive SQL-preview tooling can keep calling it uniformly across every builder without a special case for upsert. The combination this would reject (a predicate on ConflictTarget::PrimaryKey) is still caught before any SQL runs — Self::run/Self::run_in_tx call .validate() via prepare_upsert_insert first — so nothing unsafe executes; only the preview string itself can show a WHERE clause paired with a target .validate() would reject. A caller that wants to know ahead of rendering can call .validate() on the same ConflictTarget value passed to .on_conflict(..).

pub async fn run(self, ctx: &CratestackContext) -> Result<M, CratestackError>

where M: for<'r> Send + for<'r> Unpin + for<'r> FromRow<'r, PgRow> + for<'r> Serialize, PK: Send + Type<Postgres> + for<'q> Encode<'q, Postgres>,

pub async fn run_in_tx<'tx>( self, tx: &mut Transaction<'tx, Postgres>, ctx: &CratestackContext, ) -> Result<RunInTxOutcome<M>, CratestackError>

where M: for<'r> Send + for<'r> Unpin + for<'r> FromRow<'r, PgRow> + for<'r> Serialize, PK: Send + Type<Postgres> + for<'q> Encode<'q, Postgres>,

Like Self::run but participates in a caller-supplied transaction. The conflict probe runs against tx, so the row lock is held until the caller commits. Neither the event outbox drain nor the AuditSink fan-out happens here — see create.rs’s run_in_tx doc comment for the full contract and how a caller opts into both after their own commit.

Trait Implementations

impl<'a, M, PK, I> Clone for UpsertRecord<'a, M, PK, I>

where M: Clone + 'static, PK: Clone + 'static, I: Clone,

fn clone(&self) -> UpsertRecord<'a, M, PK, I>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a, M, PK, I> Debug for UpsertRecord<'a, M, PK, I>

where M: Debug + 'static, PK: Debug + 'static, I: Debug,

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

Formats the value using the given formatter.