Transactions and ORMs

Commit jobs, application writes, effects, and checkpoints atomically.

PostgreSQL and MySQL expose transactional adapters. Redis deliberately does not: a method that cannot join the application’s transaction would create a false atomicity guarantee.

Transactional enqueue

Wrap the transaction handle already owned by the application, then enqueue through the transactional port before committing. If the application write rolls back, the job rolls back with it.

Rust

let tx = client.transaction().await?;
tx.execute("INSERT INTO orders (id) VALUES ($1)", &[&order.id]).await?;
store.enqueue_on(&tx, &batch).await?;
tx.commit().await?;

Stack	Handle passed to Headgate
Rust + PostgreSQL	tokio_postgres::Transaction
Rust + MySQL	mysql_async::Transaction
Go + PostgreSQL	pgx.Tx through headgatepgx.WrapTx
Go + MySQL	*sql.Tx through headgatemysql.WrapTx

GORM and Bun expose the underlying *sql.Tx on MySQL. SQL builders that retain the native pgx handle can use the PostgreSQL adapter. An ORM that does not expose a compatible raw connection needs a small second pool or enqueue-after-commit, with the corresponding job-loss window made explicit.

Do not hand-write rows into Headgate tables. That bypasses uniqueness, quarantine, partition maintenance, arrival counters, and future schema invariants.

Transactional handler effects

The once helper claims an effect key, runs application writes, and completes the job in one fence-verified transaction. Step-scoped idempotency commits a named step’s effect with its checkpoint. If ownership changes before commit, both the application write and the Headgate completion roll back.

Inside such a callback, use the supplied transaction. Calling an ordinary store method may try to acquire a second connection while the first is retained and can exhaust a small pool.

Connection budget

Size SQL pools for transactional callbacks, renewal, admission, and notifications.