Transactions

Overview

In this guide, you can learn how to use the MongoDB Go 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 or allow you to execute operations in an ACID transaction. MongoDB guarantees that the data involved in your transaction operations remains consistent, even if the operations encounter unexpected errors.

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

Session Methods

After you start a session by using the StartSession() method on your client, you can modify the session state by using the method set provided by the returned Session. The following table describes these methods:

A Session also has methods to retrieve session properties and modify mutable session properties. View the API documentation to learn more about these methods.

txnOpts := options.Transaction().SetReadConcern(readconcern.Majority())
sessOpts := options.Session().SetDefaultTransactionOptions(txnOpts)
session, err := client.StartSession(sessOpts)
if err != nil {
	return err
}

Example

The following example shows how you can create a session, create a transaction, and commit a multi-document insert operation through the following steps:

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

2. Use the WithTransaction() method to start a transaction.

3. Insert multiple documents. The WithTransaction() method executes the insert and commits the transaction. If any operation results in errors, WithTransaction() handles canceling the transaction.

4. Close the transaction and session using the EndSession() method.

wc := writeconcern.Majority()
txnOptions := options.Transaction().SetWriteConcern(wc)
// Starts a session on the client
session, err := client.StartSession()
if err != nil {
	panic(err)
}
// Defers ending the session after the transaction is committed or ended
defer session.EndSession(context.TODO())
// Inserts multiple documents into a collection within a transaction,
// then commits or ends the transaction
result, err := session.WithTransaction(context.TODO(), func(ctx context.Context) (interface{}, error) {
	result, err := coll.InsertMany(ctx, []interface{}{
		bson.D{{"title", "The Bluest Eye"}, {"author", "Toni Morrison"}},
		bson.D{{"title", "Sula"}, {"author", "Toni Morrison"}},
		bson.D{{"title", "Song of Solomon"}, {"author", "Toni Morrison"}},
	})
	return result, err
}, txnOptions)

If you require more control over your transactions, you can find an example showing how to manually create, commit, and end transactions in the full code example.

Additional Information

For more information about insert operations, see the Insert a Document fundamentals page.

For more information about specifying write concerns in the Go driver, see Write Concern.

For an additional example using sessions and transactions with the Go driver, see the developer blog post on Multi-Document ACID Transactions.