Transactions

Overview

In this guide, you can learn how to use the Kotlin Sync driver to perform transactions. Transactions allow you to run a series of operations that do not change any data until the transaction is committed. If any operation in the transaction returns an error, the driver cancels the transaction and discards all data changes before they ever become visible.

In MongoDB, transactions run within logical sessions. A session is a grouping of related read or write operations that you intend to run sequentially. Sessions enable causal consistency for a group of operations and allow you to run operations in an ACID-compliant transaction, which is a transaction that meets an expectation of atomicity, consistency, isolation, and durability. MongoDB guarantees that the data involved in your transaction operations remains consistent, even if the operations encounter unexpected errors.

When using the Kotlin Sync driver, you can create a new session from a MongoClient instance as a ClientSession type. We recommend that you reuse your MongoClient for multiple sessions and transactions instead of creating a new client each time.

data class Restaurant(val name: String, val cuisine: String)

Methods

Create a ClientSession by using the startSession() method on your MongoClient instance. You can then modify the session state by using the methods provided by the ClientSession. The following table describes the methods you can use to manage your transaction:

Example

The following example demonstrates how to create a session, create a transaction, and insert documents into a collection in one transaction through the following steps:

1. Create a session from the client by using the startSession() method.

2. Define the insertRestaurantsInTransaction() method to insert multiple documents into the restaurants collection.

3. Use the withTransaction() method to start a transaction. The withTransaction() method runs the insert operations and commits the transaction. If any operation results in errors, withTransaction() cancels the transaction.

4. Close the connection to the server by using the MongoClient.close() method.

// Creates a new MongoClient to manage your connection
val client = MongoClient.create("<connection string>")
// Gets the database and collection
val database = client.getDatabase("sample_restaurants")
val collection = database.getCollection<Restaurant>("restaurants")
// Inserts restaurants into the collection
fun insertRestaurantsInTransaction(session: ClientSession) {
    // Inserts restaurants within the transaction
    collection.insertOne(
        session,
        Restaurant("Kotlin Sync Pizza", "Pizza")
    )
    collection.insertOne(
        session,
        Restaurant("Kotlin Sync Burger", "Burger")
    )
}
// Starts a client session
client.startSession().use { session ->
    try {
        // Sets transaction options
        val txnOptions = TransactionOptions.builder()
            .readConcern(ReadConcern.LOCAL)
            .writeConcern(WriteConcern.MAJORITY)
            .build()
        // Uses the withTransaction method to start a transaction and run the given function
        session.withTransaction({
            insertRestaurantsInTransaction(session)
            println("Transaction succeeded")
        }, txnOptions)
    } catch (e: Exception) {
        println("Transaction failed: ${e.message}")
    }
}
// Closes the MongoClient
client.close()

If you require more control over your transactions, you can use the startTransaction() method. You can use this method with the commitTransaction() and abortTransaction() methods described in the preceding section to manually manage the transaction lifecycle.

Additional Information

To learn more about the concepts mentioned in this guide, see the following pages in the Server manual:

• Transactions

• Server Sessions

• Read Isolation, Consistency, and Recency

To learn more about ACID compliance, see the What are ACID Properties in Database Management Systems? article on the MongoDB website.