​

Transaction Isolation

​

run_in_isolated_tx

use cratestack::{cratestack_error_from_sqlx, run_in_isolated_tx, TransactionIsolation, CratestackError};

run_in_isolated_tx(
    &pool,
    TransactionIsolation::Serializable,
    |mut tx| async move {
        let (balance,): (i64,) = sqlx::query_as("SELECT balance FROM accounts WHERE id = $1")
            .bind(account_id)
            .fetch_one(&mut *tx)
            .await
            .map_err(cratestack_error_from_sqlx)?;
        if balance < amount {
            return Err(CratestackError::Validation("insufficient funds".to_owned()));
        }
        sqlx::query("UPDATE accounts SET balance = balance - $1 WHERE id = $2")
            .bind(amount)
            .bind(account_id)
            .execute(&mut *tx)
            .await
            .map_err(cratestack_error_from_sqlx)?;
        Ok(((), tx))
    },
)
.await?;

​

Supported isolation levels

pub enum TransactionIsolation {
    ReadCommitted,
    RepeatableRead,
    Serializable,
}

​

Retry on serialization failure

1. up to 3 times via run_in_isolated_tx
2. up to a caller-chosen budget via run_in_isolated_tx_with_retries(pool, level, retries, body)
3. when a statement inside the body fails with 40001 or 40P01
4. when tx.commit() itself fails with one of them: SSI can defer the conflict to commit time (write-skew)

​

Body must use the supplied transaction

FnMut(Transaction<'static, Postgres>) -> impl Future<
    Output = Result<(T, Transaction<'static, Postgres>), CratestackError>,
>

​

When commit-time retry matters

1. Write-skew anomaly. Two transactions read overlapping rows, write disjoint rows, and SSI detects the read-write dependency only at the commit boundary.
2. Predicate-lock contention. A long-running SELECT participates in conflicts that aren’t visible until the transaction tries to land.

​

Procedure-level isolation

mutation procedure transferFunds(input: TransferInput): TransferResult
  @isolation("serializable")
  @allow(auth() != null)

1. one @isolation attribute per procedure
2. the level argument is a quoted string: "serializable", "repeatable_read", or "read_committed" (case-insensitive; "repeatable read" with a space is accepted too)
3. (since 0.14.1) not on a @stream procedure: a streamed response is produced after the procedure returns, so there is no point at which to commit, and a partly sent stream cannot be retried
4. (since 0.14.1) not in a datasource { provider = "none" } schema; and include_server_schema!(.., db = None) refuses it with a compile error

​

What the attribute does

1. its authorization: @allow / @deny and any @authorize(...) check
2. its body
3. the policy checks of every write it makes (create policies with their relation lookups, the @version probe, upsert update-policy checks)
4. the @computed fields of its output

let db = cratestack_schema::Cratestack::builder(pool)
    .with_isolation_max_retries(5) // 0 disables retry
    .build();

​

The handle: IsolatedCratestack

model Account {
  id Int @id
  balance Int

  @@allow("read", auth() != null)
  @@allow("update", auth() != null)
}

type Withdrawal {
  accountId Int
  amount Int
}

type Receipt {
  before Int
  after Int
}

mutation procedure withdraw(args: Withdrawal): Receipt
  @isolation("serializable")
  @allow(auth() != null)

use cratestack_schema::procedures as p;

impl p::ProcedureRegistry for Procedures {
    async fn withdraw(
        &self,
        db: &cratestack_schema::IsolatedCratestack,
        ctx: &CratestackContext,
        args: p::withdraw::Args,
        _authorized: p::withdraw::Authorized,
    ) -> Result<p::withdraw::Output, CratestackError> {
        let id = args.args.accountId;
        let amount = args.args.amount;
        let account = db
            .account()
            .find_unique(id)
            .run(ctx)
            .await?
            .ok_or_else(|| CratestackError::NotFound("no account".into()))?;
        if account.balance < amount {
            return Err(CratestackError::Validation("insufficient funds".into()));
        }
        let updated = db
            .account()
            .update(id)
            .set(cratestack_schema::UpdateAccountInput {
                balance: Some(account.balance - amount),
            })
            .run(ctx)
            .await?;
        Ok(cratestack_schema::Receipt {
            before: account.balance,
            after: updated.balance,
        })
    }
}

​

Retries exhausted

​

Side effects and retries

​

Upgrading

1. Find the procedures that declare it: grep -rn '@isolation' over your .cstack files.
2. Review each body, and the @computed resolvers of its output, for effects that must not repeat.
3. Change db: &Cratestack to db: &IsolatedCratestack in those methods. Replace db.pool() with db.transaction(..), and remove any hand-written run_in_isolated_tx(db.pool(), ..) wrapper: the dispatch provides it now.
4. A hand-written caller of <procedure>::invoke_with_db passes FnOnce(IsolatedCratestack, Authorized) -> Fut + Clone instead of FnOnce(Authorized) -> Fut; it is called once per attempt.
5. Treat 409 TRANSACTION_ABORTED (RPC aborted) as retryable, with the same Idempotency-Key. 409 CONFLICT keeps its meaning.
6. Size the pool: each in-flight call holds one connection for its whole transaction.

​

What this is not

1. not a replacement for application-level conflict handling — some business logic genuinely needs the user to re-confirm after a stale read; the retry loop is the safety net, not the policy
2. not a distributed transaction coordinator — PG isolation only applies inside one database
3. not free — Serializable adds locking overhead; benchmark before applying it to read-heavy procedures

​

Read Next

1. Optimistic locking — row-level version checks complement transaction-level isolation
2. Idempotency — duplicate-execution protection at the request boundary