Transactions

orm.transaction() wraps an async callback in a database transaction.orm.batch() runs a flat list of SQL statements in one transaction.

orm.transaction()

The callback receives a trx object with the same model API as orm.db. On success the transaction is committed. Any thrown error triggers automatic rollback.

// orm.transaction(async (trx) => { ... })
// BEGIN on entry, COMMIT on success, ROLLBACK on any throw

await orm.transaction(async (trx) => {
  const user = await trx.User.insert({
    email: 'joe@example.com',
    name: 'Joe',
  });

  await trx.Post.insert({
    title: 'First post',
    userId: user.id,
  });

  // If anything throws here, both inserts are rolled back
});

Automatic rollback

// Any thrown error triggers automatic ROLLBACK
try {
  await orm.transaction(async (trx) => {
    await trx.Account.update(
      { id: fromAccountId },
      { balance: fromBalance - amount }
    );

    await trx.Account.update(
      { id: toAccountId },
      { balance: toBalance + amount }
    );

    // If toAccountId doesn't exist, this throws
    // -> ROLLBACK — fromAccount balance is restored
    await trx.Transaction.insert({
      from: fromAccountId,
      to: toAccountId,
      amount,
    });
  });
} catch (err) {
  console.error('Transfer failed, rolled back:', err);
}

orm.batch()

For bulk operations with raw SQL. All statements execute in a single transaction. Useful for seeding, data migrations, or operations outside the model API.

// orm.batch(statements) — flat list of SQL statements
// Wrapped in a single transaction
// Each statement: { sql: string, params?: unknown[] }

await orm.batch([
  {
    sql: 'INSERT INTO tags (name) VALUES (?)',
    params: ['typescript'],
  },
  {
    sql: 'INSERT INTO tags (name) VALUES (?)',
    params: ['orm'],
  },
  {
    sql: 'UPDATE posts SET tagCount = tagCount + 2 WHERE id = ?',
    params: [postId],
  },
]);

Raw adapter access

// Raw escape hatch via orm.adapter.exec()
// Use for DDL or statements not covered by the query builder

const result = await orm.adapter.exec(
  'ALTER TABLE users ADD COLUMN lastLoginAt TEXT',
  []
);

// exec returns SQLExecResult:
// { rows: any[], rowsAffected: number, lastInsertId: number | null }

MongoDB

// MongoDB note
// MongoDB does not support multi-document transactions via orm.transaction()
// in the current implementation — the callback runs without a transaction.
// Use the MongoDB driver's session API directly for atomic multi-document ops.

// orm.batch() is a no-op on MongoDB (documents are atomic individually).

PreviousHooks NextError Handling