Transactions
Ghuri runs in autocommit mode by default: each query is committed immediately. To make a group
of writes all-or-nothing on Postgres and SQLite, wrap them in atomic(). On D1, atomic()
cannot roll back; use connection.batch() instead.
import { atomic, F } from '@ghuri/orm'
await atomic(async () => { const order = await Order.objects.create({ customer: user, total: '49.00' }) await OrderLine.objects.bulkCreate(lines.map((l) => new OrderLine({ ...l, order }))) await Product.objects.filter({ id__in: lines.map((l) => l.productId) }) .update({ stock: F('stock').sub(1) })})If the callback throws, everything inside it is rolled back (except on D1) and the error propagates. If it
returns, the transaction commits and atomic() resolves to the callback’s return value.
Nested atomic() calls create savepoints, so an inner block can fail and roll back without
aborting the outer one:
await atomic(async () => { await post.save() try { await atomic(async () => { await notifySubscribers(post) // may throw }) } catch { // the post is still saved; only the inner block was rolled back }})Use a different database alias with atomic(fn, { using: 'analytics' }). Pass
{ savepoint: false } to make a nested block join the outer transaction without a savepoint.
Behaviour by database
Section titled “Behaviour by database”Transactions depend on what the database underneath supports. Each connection reports it as
connection.supportsTransactions (and connection.features.supportsSavepoints).
| Database | atomic() |
Savepoints |
|---|---|---|
Postgres (postgres(), Hyperdrive) |
real BEGIN / COMMIT / ROLLBACK |
yes |
SQLite (@ghuri/orm/sqlite), PGlite (@ghuri/orm/pglite) |
real transactions | yes |
D1 (d1()) |
no transaction, no rollback, see below | no |
connections.inAtomicBlock(alias) tells you whether code is running inside atomic().
What D1 does offer is a batch: a list of statements that D1 executes atomically, all or
nothing. Use connection.batch() when a group of writes must not be applied partially:
import { connections } from '@ghuri/orm'
const conn = await connections.get()await conn.batch([ { sql: 'UPDATE shop_product SET stock = stock - ? WHERE id = ? AND stock >= ?', params: [1, productId, 1] }, { sql: 'INSERT INTO shop_orderline (order_id, product_id, quantity) VALUES (?, ?, ?)', params: [orderId, productId, 1] },])A batch cannot read in between statements (each statement’s parameters are fixed when you
build it), and it takes raw SQL, so its statements are dialect-specific. On the other
backends batch() runs the statements in a transaction, so the same call is all-or-nothing
everywhere. Migrations (one batch per migration) and loaddata (one batch per 5,000
statements) use batches on D1 for the same reason.
Design write paths on D1 accordingly:
- Prefer single statements that do the whole job:
qs.update()withF()expressions, orbulkCreate(). - Group writes that must succeed together into one
connection.batch(). - Make multi-step operations idempotent, so a retry after a failure converges.
- When you need strict multi-statement atomicity with reads in between, that is a strong signal to move to Postgres, possibly through Hyperdrive while staying on Workers.
Running code after commit
Section titled “Running code after commit”Sending an email or enqueueing a job should happen only if the transaction commits. Use
onCommit():
import { atomic, onCommit } from '@ghuri/orm'
await atomic(async () => { const user = await User.objects.create({ ... }) await onCommit(() => sendWelcomeEmail(user))})Callbacks run in order after the outermost atomic() block commits, and are dropped if the
block (or the savepoint that registered them) rolls back. Outside a transaction the callback
runs immediately, which is why onCommit() returns a promise you should await. Pass
{ using: 'analytics' } for another alias. On Workers, if the callback returns a
promise that should outlive the response, pass it to
getContext().executionCtx?.waitUntil().