transactions.txt

************
Transactions
************

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol


Version 4.0 of the MongoDB server introduces
`multi-document transactions <https://mongodb.com/docs/manual/core/transactions/>`_.
(Updates to multiple fields within a single document are atomic in all
versions of MongoDB.) Ruby driver version 2.6.0 adds support for transactions.

.. _using-transactions:

Using Transactions
==================

In order to start a transaction, the application must have a :ref:`session <sessions>`.

The recommended way to use transactions is to utilize the ``with_transaction``
helper method:

.. code-block:: ruby

  session = client.start_session
  session.with_transaction do
    collection.insert_one({hello: 'world'}, session: session)
  end

The ``with_transaction`` helper does the following:

- It starts a transaction prior to calling the supplied block, and commits
  the transaction when the block finishes.
- If any of the operations in the block, or the commit operation, result in
  a transient transaction error, the block and/or the commit will be executed
  again.

The block should be idempotent, because it may be called multiple times.

The block may explicitly commit or abort the transaction, by calling
``commit_transaction`` or ``abort_transaction``; in this case ``with_transaction``
will not attempt to commit or abort (but may still retry the block on
transient transaction errors propagated out of the block).

The block will also be retried if the transaction's commit result is unknown.
This may happen, for example, if the cluster undergoes an election during the
commit. In this case when the block is retried, the primary server of the
topology would likely have changed.

Currently ``with_transaction`` will stop retrying the block and the commit once
120 seconds pass since the beginning of its execution. This time is not
configurable and may change in a future driver version. Note that this
does not guarantee the overall runtime of ``with_transactions`` will be 120
seconds or less - just that once 120 seconds of wall clock time have elapsed,
further retry attempts will not be initiated.

A low level API is also available if more control over transactions is desired.

``with_transaction`` takes the same options as ``start_transaction`` does,
which are read concern, write concern and read preference:

.. code-block:: ruby

  session = client.start_session
  session.with_transaction(
    read_concern: {level: :majority},
    write_concern: {w: 3},
    read: {mode: :primary}
  ) do
    collection.insert_one({hello: 'world'}, session: session)
  end

Handling Errors Within the ``with_transaction`` Block
-----------------------------------------------------

If a command inside the ``with_transaction`` block fails, it may cause
the transaction on the server to be aborted. This situation is normally handled
transparently by the driver. However, if the application catches such an error
and does not re-raise it, the driver will not be able to determine whether
the transaction was aborted or not. The driver will then retry the block
indefinitely.

To avoid this situation, the application must not silently handle errors within
``with_transaction`` block. If the application needs to handle errors within
the block, it must re-raise the errors.

.. code-block:: ruby

  session.with_transaction do
    collection.insert_one({hello: 'world'}, session: session)
  rescue Mongo::Error::OperationFailure => e
    # Do something in response to the error
    raise e
  end

If the applications needs to handle errors in a custom way, it should use
the low level API instead.

Low Level API
=============

A transaction can be started by calling the ``start_transaction`` method on a session:

.. code-block:: ruby

  session = client.start_session
  session.start_transaction

It is also possible to specify read concern, write concern and read preference
when starting a transaction:

.. code-block:: ruby

  session = client.start_session
  session.start_transaction(
    read_concern: {level: :majority},
    write_concern: {w: 3},
    read: {mode: :primary})

To persist changes made in a transaction to the database, the transaction
must be explicitly committed. If a session ends with an open transaction,
`the transaction is aborted <https://mongodb.com/docs/manual/core/transactions/#transactions-and-sessions>`_.
A transaction may also be aborted explicitly.

To commit or abort a transaction, call ``commit_transaction`` or
``abort_transaction`` on the session instance:

.. code-block:: ruby

  session.commit_transaction

  session.abort_transaction

Note: an outstanding transaction can hold locks to various objects in the
server, such as the database. For example, the drop call in the following
snippet will hang for `transactionLifetimeLimitSeconds
<https://mongodb.com/docs/manual/reference/parameters/#param.transactionLifetimeLimitSeconds>`_
seconds (default 60) until the server expires and aborts the transaction:

.. code-block:: ruby

  c1 = Mongo::Client.new(['127.0.0.1:27017']).use(:test_db)
  session = c1.start_session
  c1['foo'].insert_one(test: 1)
  session.start_transaction
  c1['foo'].insert_one({test: 2}, session: session)

  c2 = Mongo::Client.new(['127.0.0.1:27017']).use(:test_db)
  # hangs
  c2.database.drop

Since transactions are associated with server-side sessions, closing the client
does not abort a transaction that this client initiated - the application must
either call ``abort_transaction`` or wait for the transaction to time out on
the server side. In addition to committing or aborting the transaction, an
application can also end the session which will abort a transaction on this
session if one is in progress:

.. code-block:: ruby

  session.end_session

  c2 = Mongo::Client.new(['127.0.0.1:27017']).use(:test_db)
  # ok
  c2.database.drop

Handling Errors
---------------

If a command inside the transaction fails, the transaction may be aborted
on the server. Errors that abort transactions do not have
``TransientTransactionError`` in their error labels. An attempt to commit such a
transaction will be rejected with ``NoSuchTransaction`` error.


Retrying Commits
================

The transaction commit `can be retried
<https://mongodb.com/docs/manual/core/transactions/#retry-commit-operation>`_
if it fails. Here is the Ruby code to do so:

.. code-block:: ruby

  begin
    session.commit_transaction
  rescue Mongo::Error => e
    if e.label?('UnknownTransactionCommitResult')
      retry
    else
      raise
    end
  end


Transaction Nesting
===================

MongoDB does not support nesting transactions. Attempting to call
``start_transaction`` or ``with_transaction`` when a transaction is already
in progress will result in an error.