This module implements the details of the transactions api (see specs).

In case of MongoDB 3.6 or greater the driver uses sessions for each operation. If no session is created the driver will create a so-called implicit session. A session is a UUID-Number which is added to some operations. The sessions are used to manage the transaction state as well. In most situation you need not to create a session instance, so the api of the driver is not changed.

In case of multiple insert statements you can use transaction (MongoDB 4.x) to be sure that all operations are grouped like a single operation. Prerequisites for transactions are: MongoDB 4.x must be used as replica set or cluster deployment. The collection used in the operations must already exist. Some operation are not allowed (For example: create index or call count).

Example

alias Mongo.Session

{:ok, session} = Session.start_session(top, :write, [])
:ok = Session.start_transaction(session)

Mongo.insert_one(top, "dogs", %{name: "Greta"}, session: session)
Mongo.insert_one(top, "dogs", %{name: "Waldo"}, session: session)
Mongo.insert_one(top, "dogs", %{name: "Tom"}, session: session)

:ok = Session.commit_transaction(session)
:ok = Session.end_session(top, session)

First you start a explicit session and a transactions. Use the session for each insert statement as an options with key :session otherwise the insert statement won't be executed in the transaction. After that you commit the transaction and end the session by calling end_session.

Convenient API for Transactions

This method is responsible for starting a transaction, invoking a callback, and committing a transaction. The callback is expected to execute one or more operations with the transaction; however, that is not enforced. The callback is allowed to execute other operations not associated with the transaction.

Example

{:ok, ids} = Mongo.transaction(top, fn ->
  {:ok, %InsertOneResult{:inserted_id => id1}} = Mongo.insert_one(top, "dogs", %{name: "Greta"})
  {:ok, %InsertOneResult{:inserted_id => id2}} = Mongo.insert_one(top, "dogs", %{name: "Waldo"})
  {:ok, %InsertOneResult{:inserted_id => id3}} = Mongo.insert_one(top, "dogs", %{name: "Tom"})
  {:ok, [id1, id2, id3]}
end, w: 3)

If the callback is successful then it returns a tuple with the keyword :ok and a used defined result like {:ok, [id1, id2, id3]}. In this example we use the write concern w: 3. The write concern used in the insert operation will be removed by the driver. It is applied in the commit transaction command.

Implicit vs explicit sessions

In most cases the driver will create implicit sessions for you. The session is put in the process' dictionary under the key :session and the opts is extended by :session as well. This behaviour is specified by the mongodb specification for drivers.

If you use the :causal_consistency flag, then you need to create an explicit session:

alias Mongo.Session

{:ok, session} = Session.start_session(top, :write, causal_consistency: true)

Mongo.delete_many(top, "dogs", %{"Greta"}, session: session, w: :majority)
{:ok, 0} = Mongo.count(top, "dogs", %{name: "Greta"}, session: session, read_concern: %{level: :majority})

:ok = Session.end_session(top, session)

For more information about causal consistency see the officially documentation.

If you want to use transaction, then you need to create a session as well:

alias Mongo.Session

{:ok, session} = Session.start_session(top, :write, [])
:ok = Session.start_transaction(session)

Mongo.insert_one(top, "dogs", %{name: "Greta"}, session: session)
Mongo.insert_one(top, "dogs", %{name: "Waldo"}, session: session)
Mongo.insert_one(top, "dogs", %{name: "Tom"}, session: session)

:ok = Session.commit_transaction(session)
:ok = Session.end_session(top, session)

You can shorten this code by using the with_transaction function:

{:ok, ids} = Mongo.transaction(top, fn ->
  {:ok, %InsertOneResult{:inserted_id => id1}} = Mongo.insert_one(top, "dogs", %{name: "Greta"})
  {:ok, %InsertOneResult{:inserted_id => id2}} = Mongo.insert_one(top, "dogs", %{name: "Waldo"})
  {:ok, %InsertOneResult{:inserted_id => id3}} = Mongo.insert_one(top, "dogs", %{name: "Tom"})
  {:ok, [id1, id2, id3]}
end, w: 1)