Transactions

Run multiple operations atomically — if anything fails, everything rolls back. The transaction context gives you the same API as the main client.

#Why transactions?

Imagine you're creating a user and their first post. If the post creation fails (say, a constraint violation), you don't want a user record sitting in the database with no post. A transaction ensures both operations succeed or neither does.

BEGIN

Create User

INSERT

Create Post

INSERT

COMMIT

all succeed

If any step throws an error, PostgreSQL automatically rolls back all changes:

BEGIN

Create User

INSERT ✓

Create Post

ERROR ✗

ROLLBACK

user removed

#Basic usage

Inside the transaction callback, you get the same API as the main client — model queries, inserts, raw SQL, everything works. The only difference is everything runs on the same database connection.

TSatomic user + post creation

21 lines


1await db.transaction(async (tx) => {
2  // Create the user
3  const user = await tx.user.create({
4    data: { email: '[email protected]', name: 'Alice' },
5  });
6 
7  // Create their first post (uses the user's ID)
8  await tx.post.create({
9    data: {
10      title: 'Hello World',
11      authorId: user.id,    // guaranteed to exist
12    },
13  });
14 
15  // Raw SQL works inside transactions too
16  await tx.raw`
17    UPDATE counters SET n = n + 1 WHERE name = 'users'
18  `;
19 
20  // If ANY operation throws, EVERYTHING rolls back automatically
21});

#Error handling

If the callback throws, the transaction is rolled back and the error is re-thrown. You can catch it outside:

11 lines


1try {
2  await db.transaction(async (tx) => {
3    await tx.user.create({ data: { email: '[email protected]' } });
4    // If email already exists → UniqueConstraintError
5  });
6} catch (err) {
7  if (err instanceof UniqueConstraintError) {
8    console.log('Email already taken:', err.fields);
9  }
10  // The transaction was already rolled back at this point
11}

#What's available inside tx

The transaction context (tx) provides the same interface as the maindb client:

15 lines


1await db.transaction(async (tx) => {
2  // Model CRUD
3  await tx.user.findMany({ where: { role: 'ADMIN' } });
4  await tx.user.create({ data: { ... } });
5  await tx.user.update({ where: { id: '...' }, data: { ... } });
6  await tx.user.delete({ where: { id: '...' } });
7 
8  // Insert builder
9  await tx.user.insert({ email: '[email protected]' })
10    .onConflict({ columns: ['email'], action: 'nothing' })
11    .execute();
12 
13  // Raw SQL
14  await tx.raw`SELECT COUNT(*) FROM users`;
15});

#When to use transactions

Use transactions when:

Multiple related writes — creating a user and their profile together
Transfer operations — deducting from one account and adding to another
Conditional updates — check a value, then update based on it (no race condition)
Batch operations — processing a list of items where all must succeed