Transactions

On this page

Overview

Sample Data
Transaction Methods
Transaction Example
Additional Information
API Documentation

Overview

In this guide, you can learn how to use the Java Reactive Streams driver to perform transactions. Transactions allow you to run a series of operations that do not apply until all data changes are successful. If any operation in the transaction fails, the driver cancels the transaction and discards all data changes without ever becoming 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. With sessions, you can enable causal consistency for a group of operations, and run ACID transactions. MongoDB guarantees that the data involved in your transaction operations remains consistent, even if the operations encounter unexpected errors.

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

Warning

Use a ClientSession only with the MongoClient (or associated MongoDatabase or MongoCollection) that created it. Using a ClientSession with a different MongoClient results in operation errors.

Sample Data

The examples in this guide use the sample_restaurants.restaurants and sample_mflix.movies collections from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started.

Important

Project Reactor Library

This guide uses the Project Reactor library to consume Publisher instances returned by the Java Reactive Streams driver methods. To learn more about the Project Reactor library and how to use it, see Getting Started in the Reactor documentation. To learn more about how we use Project Reactor library methods in this guide, see the Write Data to MongoDB guide.

Transaction 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 details the methods you can use to manage your transaction:

Method	Description
`startTransaction()`	Starts a new transaction, configured with the given options, on this session. Throws an exception if there is already a transaction in progress for the session. To learn more about this method, see the startTransaction() page in the MongoDB Server manual.
`abortTransaction()`	Ends the active transaction for this session. Throws an exception if there is no active transaction for the session or if the transaction is already committed or ended. To learn more about this method, see the abortTransaction() page in the MongoDB Server manual.
`commitTransaction()`	Commits the active transaction for this session. Throws an exception if there is no active transaction for the session or if the transaction was ended. To learn more about this method, see the commitTransaction() page in the MongoDB Server manual.

Transaction Example

The following example demonstrates how to create a session, create a transaction, and insert documents into multiple collections in one transaction. The code executes the following steps:

Creates a session from the client by using the startSession() method
Starts a transaction by using the startTransaction() method
Inserts documents into the restaurants and movies collections
Commits the transaction by using the commitTransaction() method

MongoClient mongoClient = MongoClients.create(settings);
MongoDatabase restaurantsDatabase = mongoClient.getDatabase("sample_restaurants");
MongoCollection<Document> restaurants = restaurantsDatabase.getCollection("restaurants");
MongoDatabase moviesDatabase = mongoClient.getDatabase("sample_mflix");
MongoCollection<Document> movies = moviesDatabase.getCollection("movies");
Mono.from(mongoClient.startSession())
        .flatMap(session -> {
            // Begins the transaction
            session.startTransaction();
            // Inserts documents in the given order
            return Mono.from(restaurants.insertOne(session, new Document("name", "Reactive Streams Pizza").append("cuisine", "Pizza")))
                    .then(Mono.from(movies.insertOne(session, new Document("title", "Java: Into the Streams").append("type", "Movie"))))
                    // Commits the transaction
                    .flatMap(result -> Mono.from(session.commitTransaction())
                            .thenReturn(result))
                    .onErrorResume(error -> Mono.from(session.abortTransaction()).then(Mono.error(error)))
                    .doFinally(signalType -> session.close());
        })
        // Closes the client after the transaction completes
        .doFinally(signalType -> mongoClient.close())
        // Prints the results of the transaction
        .subscribe(
                result -> System.out.println("Transaction succeeded"),
                error -> System.err.println("Transaction failed: " + error)
        );

Additional Information

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

API Documentation

To learn more about any of the types or methods discussed in this guide, see the following API Documentation:

Back

Bulk Write

GridFS