Skip to main content

Transactions

Creating and using transactions​

Transactions are created using DataSource or EntityManager. Examples:

await myDataSource.transaction(async (transactionalEntityManager) => {
    // execute queries using transactionalEntityManager
})

or

await myDataSource.manager.transaction(async (transactionalEntityManager) => {
    // execute queries using transactionalEntityManager
})

Everything you want to run in a transaction must be executed in a callback:

await myDataSource.manager.transaction(async (transactionalEntityManager) => {
    await transactionalEntityManager.save(users)
    await transactionalEntityManager.save(photos)
    // ...
})

The most important restriction when working in a transaction is to ALWAYS use the provided instance of entity manager - transactionalEntityManager in this example. DO NOT USE GLOBAL ENTITY MANAGER. All operations MUST be executed using the provided transactional entity manager.

Specifying isolation level​

Specifying the isolation level for the transaction can be done by supplying it as the first parameter:

await myDataSource.manager.transaction(
    "SERIALIZABLE",
    (transactionalEntityManager) => {},
)

Supported isolation levels​

Isolation level implementations are not agnostic across all databases. Each driver declares which levels it supports, and TypeORM will throw an error if you request an unsupported level.

CockroachDB

  • READ COMMITTED — requires the cluster setting sql.txn.read_committed_isolation.enabled, which is enabled by default in recent versions
  • SERIALIZABLE (default)

CockroachDB does not implement weaker isolation levels at all. When you request READ UNCOMMITTED or REPEATABLE READ via SQL (e.g. BEGIN TRANSACTION ISOLATION LEVEL READ UNCOMMITTED), CockroachDB accepts the syntax, silently ignores the requested weakness, and runs the transaction at a stricter level instead — no warning, no error:

  • READ UNCOMMITTED → runs as READ COMMITTED
  • REPEATABLE READ → runs as SERIALIZABLE
Learn more

Default isolation level​

You can configure a default isolation level for all transactions by setting isolationLevel in the DataSource options:

const dataSource = new DataSource({
    type: "postgres",
    isolationLevel: "SERIALIZABLE",
    // ...
})

When set, all transactions started without an explicit isolation level will use this default. An explicit isolation level passed to transaction() or startTransaction() will override the default.

Using QueryRunner to create and control state of single database connection​

QueryRunner provides a single database connection. Transactions are organized using query runners. Single transactions can only be established on a single query runner. You can manually create a query runner instance and use it to manually control transaction state. Example:

// create a new query runner
const queryRunner = dataSource.createQueryRunner()

// establish real database connection using our new query runner
await queryRunner.connect()

// now we can execute any queries on a query runner, for example:
await queryRunner.query("SELECT * FROM users")

// we can also access entity manager that works with connection created by a query runner:
const users = await queryRunner.manager.find(User)

// lets now open a new transaction:
await queryRunner.startTransaction()

try {
    // execute some operations on this transaction:
    await queryRunner.manager.save(user1)
    await queryRunner.manager.save(user2)
    await queryRunner.manager.save(photos)

    // commit transaction now:
    await queryRunner.commitTransaction()
} catch (err) {
    // since we have errors let's rollback changes we made
    await queryRunner.rollbackTransaction()
} finally {
    // you need to release query runner which is manually created:
    await queryRunner.release()
}

There are 3 methods to control transactions in QueryRunner:

  • startTransaction - starts a new transaction inside the query runner instance.
  • commitTransaction - commits all changes made using the query runner instance.
  • rollbackTransaction - rolls all changes made using the query runner instance back.

Learn more about Query Runner.