withTransaction<T>(work: TransactionWork<T>): Promise<T>
Run work inside one interactive write transaction, committing on success and
rolling back (then rethrowing) on any error. Use this — rather than a plain
batch — when a multi-step write needs conditional logic between steps, e.g.
create → check capacity → finalize, where a zero-row guard must abort and undo
everything.
Concurrent calls serialise: each waits for the previous interactive
transaction to settle before it begins, so two never overlap on the shared
connection (the documented "concurrent writers serialise rather than failing
the loser"). A genuinely contended lock — e.g. a non-transactional read racing
the commit — is still retried a few times with backoff (each retry re-runs
work on a fresh transaction, the prior attempt having rolled back), and a
database that stays locked surfaces as DatabaseBusyError. A fleeting
upstream gateway error is not retried here — see runWriteTransactionOnce
— so it surfaces as itself. Statements run
through the provided execute are tracked, and their table-scoped cache
invalidations fire once after the commit succeeds — so callers get the same
automatic invalidation as the single-statement execute, driven by the writes
themselves rather than by each call site remembering to invalidate.
work: TransactionWork<T>
Promise<T>