diff --git a/docs/06-concepts/06-database/08-transactions.md b/docs/06-concepts/06-database/08-transactions.md index 0aa3b9a7..dc2014c1 100644 --- a/docs/06-concepts/06-database/08-transactions.md +++ b/docs/06-concepts/06-database/08-transactions.md @@ -20,3 +20,40 @@ var result = await session.db.transaction((transaction) async { ``` In the example we insert a company and an employee in the same transaction. If any of the operations fail, the entire transaction will be rolled back and no changes will be made to the database. If the transaction is successful, the return value will be `true`. + +## Transaction isolation + +The transaction isolation level can be configured when initiating a transaction. The isolation level determines how the transaction interacts with concurrent database operations. If no isolation level is supplied, the level is determined by the database engine. + +:::info + +At the time of writing, the default isolation level for the PostgreSQL database engine is `IsolationLevel.readCommitted`. + +::: + +To set the isolation level, configure the `isolationLevel` property of the `TransactionSettings` object: + +```dart +var result = await session.db.transaction( + (transaction) async { + await Company.db.insertRow(session, company, transaction: transaction); + await Employee.db.insertRow(session, employee, transaction: transaction); + + return true; + }, + settings: TransactionSettings(isolationLevel: IsolationLevel.serializable), +); +``` + +In the example we set the isolation level to `IsolationLevel.serializable`. + +The available isolation levels are: + +| Isolation Level | Value | Description | +|-----------------|-----------------------|-------------| +| Read uncommitted | `IsolationLevel.readUncommitted` | Exhibits the same behavior as `IsolationLevel.readCommitted` in PostgresSQL | +| Read committed | `IsolationLevel.readCommitted` | Each statement in the transaction sees a snapshot of the database as of the beginning of that statement. | +| Repeatable read | `IsolationLevel.repeatableRead` | The transaction only observes rows committed before the first statement in the transaction was executed giving a consistent view of the database. If any conflicting writes among concurrent transactions occur, an exception is thrown. | +| Serializable | `IsolationLevel.serializable` | Gives the same guarantees as `IsolationLevel.repeatableRead` but also throws if read rows are updated by other transactions. | + +For a detailed explanation of the different isolation levels, see the [PostgreSQL documentation](https://www.postgresql.org/docs/current/transaction-iso.html).