Atomic batch writes
Several independent writes must either all commit or all roll back.
Prisma · Function
$transaction
$transaction runs multiple Prisma Client operations atomically. Use an array for sequential independent queries or a callback for interactive transaction logic.
How it works
$transaction groups Prisma Client operations into one database transaction. Pass an array for independent queries that should run sequentially, or pass an async callback to combine Prisma queries with application logic; callback queries must use the provided transaction client.
Syntax
$transaction<R>(queries: PrismaPromise<R>[]): Promise<R[]>
$transaction<R>(fn: (prisma: PrismaClient) => R, options?: object): RParameters
| Name | Type | Description |
|---|---|---|
arg | PrismaPromise<R>[] | (prisma: PrismaClient) => R | An array of Prisma promises, or a callback receiving the transaction-scoped Prisma Client. |
options | object | Optional transaction settings such as isolation level, maximum wait, and timeout. |
Returns
A promise resolving to an array of results for the array form, or the callback's returned value for the interactive form.
Key points
- Use the array form when independent Prisma operations should execute in a defined sequence within one transaction.
- Use the callback form when business logic or control flow must run between database operations.
- The transaction is atomic: a failed operation prevents partial commits.
- Interactive callbacks receive a transaction-scoped client as their first argument.
- Call the provided
txclient for every Prisma query that belongs to the interactive transaction. - Array-form operations run in the order listed, not according to database-client scheduling.
Common mistakes
- Using
Promise.all()inside a transaction does not make its queries run concurrently; the transaction connection executes them one at a time.
Example: Interactive transaction
await prisma.$transaction(async (tx) => {
const user = await tx.user.create({ data: { email: "ada@example.com" } });
await tx.profile.create({ data: { userId: user.id } });
return user;
});Creates related records in one interactive transaction; an error causes the transaction to roll back.
When to use it
Dependent business workflows
Later operations depend on earlier results or conditional application logic.
Controlled concurrency
Concurrent updates require an explicitly selected database isolation level.
Interview questions
QWhat are the two forms of $transaction?
The array form accepts Prisma Client promises and runs them sequentially as one atomic transaction. If an operation fails, Prisma rolls back the transaction, and the returned array preserves the query order.
Follow-up: When should the callback form be preferred? Use it when the transaction needs dependent results, conditional logic, or other application code between Prisma queries.
QHow does an interactive transaction work?
The callback form receives a transaction-scoped Prisma Client, commonly named tx. Queries invoked through tx belong to the transaction, which commits when the callback completes successfully and rolls back when it throws.
Follow-up: What happens if code inside the callback uses the outer client instead? That query is not made through the transaction-scoped client and therefore is not encapsulated in the callback transaction.
QWhich options can configure an interactive transaction?
The second argument can configure transaction behavior, including isolationLevel, maxWait, and timeout. Isolation levels control how the database handles concurrent transactions, while the wait and timeout settings limit transaction-resource acquisition and execution time.
Follow-up: How can serialization conflicts be handled? Retry the transaction when the database reports a transient serialization or write-conflict error.
Related
PrismaPromisePrismaClientPrisma.TransactionIsolationLevelinteractive transactionssequential operations