Skip to main content

Transactions

Transactions are managed on a SqbConnection, not on SqbClient — acquire a connection, run your statements on it, and commit or roll back explicitly.

await client.acquire(async connection => {
  const repo = connection.getRepository(Customer);
  await connection.startTransaction();
  try {
    await repo.update(1, { active: false });
    await connection.commit();
  } catch (e) {
    await connection.rollback();
    throw e;
  }
});

(connection.getRepository() returns an ORM Repository — see the ORM guides for what you can do with it. Everything below applies equally whether you drive the connection with execute()/raw SQL or through a repository.)

startTransaction() / commit() / rollback()​

MethodDescription
startTransaction(): Promise<void>Begins a transaction on this connection via the adapter, sets inTransaction to true, and emits start-transaction.
commit(): Promise<void>Commits the transaction, sets inTransaction back to false, and emits commit.
rollback(): Promise<void>Rolls the transaction back, sets inTransaction back to false, and emits rollback.

Each of these throws if called on a connection that has already been released (its underlying adapter connection is gone).

connection.inTransaction reflects the live state (it asks the adapter connection directly when the adapter supports getInTransaction(), falling back to the last known value otherwise).

Interaction with autoCommit​

While connection.inTransaction is true, every execute() call on that connection forces its effective autoCommit to false, no matter what you pass in QueryExecuteOptions.autoCommit or what ClientDefaults.autoCommit says — see Executing Queries for the full default-resolution table. This means you don't need to (and can't) auto-commit individual statements while a transaction is open; only connection.commit() ends it.

Savepoints​

Nested rollback points are supported where the adapter implements them:

await connection.startTransaction();
await connection.setSavepoint('before_update');
try {
  await connection.execute('update customers set active = false where id = $1', {
    params: [1],
  });
  await connection.releaseSavepoint('before_update');
} catch (e) {
  await connection.rollbackSavepoint('before_update');
  throw e;
}
await connection.commit();
MethodDescription
setSavepoint(name: string): Promise<void>Creates a savepoint. If no transaction is open yet, one is started first automatically. Emits set-savepoint.
releaseSavepoint(name: string): Promise<void>Releases (discards) a savepoint. Emits release-savepoint.
rollbackSavepoint(name: string): Promise<void>Rolls back to a savepoint without ending the whole transaction. Emits rollback-savepoint.

Each throws <driver> does not support setSavepoint method (or releaseSavepoint/ rollbackSavepoint, respectively) if the underlying adapter doesn't implement that operation — check your specific database adapter's documentation for savepoint support.

Events​

A SqbConnection emits start-transaction, set-savepoint, release-savepoint, rollback-savepoint, commit and rollback as each of the corresponding methods completes successfully — useful for logging or instrumentation.

Next steps​