MONGOID-4766 Document new transactions API (#5532)

Author: comandeo-mongo

source/reference/transactions.txt

@@ -15,12 +15,122 @@ Transactions
 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). Transactions require Mongoid version 6.4 or higher and Ruby driver version
-2.6 or higher.
+versions of MongoDB). Transactions require a non-standalone MongoDB topology
+and Ruby driver version 2.6 or higher. A higher level transaction API requires
+Mongoid version 9.0 or higher, while a lower level API requires Mongoid
+version 6.4 or higher.
 
 Using Transactions
 ==================
 
+Higher Level API
+----------------
+
+A transaction can be started by calling the ``transaction`` method on an instance
+of a Mongoid document class, on a Mongoid document class, on or ``Mongoid`` module:
+
+.. code-block:: ruby
+
+  Band.transaction do
+    Band.create(title: 'Led Zeppelin')
+  end
+
+  band = Band.create(title: 'Deep Purple')
+  band.transaction do
+    band.active = false
+    band.save!
+  end
+
+  Mongoid.transaction do
+    band.destroy
+  end
+
+When the ``transaction`` method is called, Mongoid does the following:
+
+* creates a session on a client that is used by the receiver of the
+  ``transaction`` method call;
+* starts a transaction on the session;
+* executes the given block;
+* commits the transaction if no exception raised in the block;
+
+  * calls ``after_commit`` callbacks for all objects modified inside the transaction
+* aborts the transaction if an exception is raised in the block;
+
+  * calls ``after_rollback`` callbacks for all objects modified inside the transaction
+* closes the session
+
+.. note::
+
+  Since a transaction is tied to a particular client, _only_ operations on
+  the same client will be in scope of the transaction. Therefore it
+  is recommended that only objects that use the same client are used inside the
+  ``transaction`` method block.
+
+  .. code-block:: ruby
+
+    class Author
+      include Mongoid::Document
+      store_in client: :encrypted_client
+    end
+
+    class User
+      include Mongoid::Document
+      store_in client: :encrypted_client
+    end
+
+    class Article
+      include Mongoid::Document
+      # This class uses the :default client
+    end
+
+    # Transaction is started on the :encrypted_client
+    Author.transaction do
+      # This operation uses the same client, so it is in the transaction
+      Author.create!
+      # This operation also uses the same client, so it is in the transaction
+      User.create!
+      # This operation uses a different client, so it is NOT in the transaction
+      Article.create!
+    end
+
+.. note::
+  When ``transaction`` method is called on ``Mongoid`` module, the transaction
+  is created using the ``:default`` client.
+
+Aborting Transaction
+~~~~~~~~~~~~~~~~~~~~
+
+Any exception raised inside the ``transaction`` method block aborts the
+transaction. Normally the raised exception passed on, except for the
+``Mongoid::Errors::Rollback``. This error should be raised if you  want to
+explicitly abort the transaction without passing on an exception.
+
+Callbacks
+~~~~~~~~~
+
+Transaction API introduces two new callbacks - ``after_commit`` and ``after_rollback``.
+
+``after_commit`` callback is triggered for an object that was created, saved,
+or destroyed:
+
+* after transaction is committed if the object was modified inside the transaction;
+* after the object was persisted if the object was modified outside a transaction.
+
+.. note::
+  In any case ``after_commit`` callback is triggered only after all other callbacks
+  were executed successfully. Therefore, if the object is modified without a
+  transaction, it is possible that the object was persisted, but ``after_commit``
+  callback was not triggered (for example, an exception raised in ``after_save``
+  callback).
+
+``after_rollback`` callback is triggered for an object that was created, saved,
+or destroyed inside a transaction if the transaction was aborted. ``after_rollback``
+is never triggered without a transaction.
+
+
+Lower Level API
+---------------
+
 In order to start a transaction, the application must have a :ref:`session <sessions>`.
 
 A transaction can be started by calling the ``start_transaction`` method on a session, which can be

source/release-notes/mongoid-9.0.txt

@@ -17,6 +17,46 @@ The complete list of releases is available `on GitHub
 please consult GitHub releases for detailed release notes and JIRA for
 the complete list of issues fixed in each release, including bug fixes.
 
+Sandbox Mode for Rails Console
+------------------------------
+
+Mongoid now supports Rails console sandbox mode. If the Rails console started
+with ``--sandbox`` flag, Mongoid starts a transaction on the ``:default`` client
+before opening the console. This transaction won't be committed; therefore, all
+the commands executed in the console using the ``:default`` client won't
+be persisted in the database.
+
+.. note::
+  If you execute commands in the sandbox mode *using any other client than default*,
+  these changes will be persisted as usual.
+
+New Transactions API
+--------------------
+
+Mongoid 9.0 introduces new transactions API that is inspired by ActiveRecord:
+
+.. code-block:: ruby
+
+  Band.transaction do
+    Band.create(title: 'Led Zeppelin')
+  end
+
+  band = Band.create(title: 'Deep Purple')
+  band.transaction do
+    band.active = false
+    band.save!
+  end
+
+Please consult :ref:`transactions documentation <transactions>` for more details.
+
+Embedded Documents Always Use Parent Persistence Context
+--------------------------------------------------------
+
+Mongoid 8.x and older allows user to specify persistence context for an
+embedded document (using ``store_in`` macro). In Mongoid 9.0 these settings are
+ignored for embedded documents; an embedded document now always uses the persistence
+context of its parent.
+
 
 Raise AttributeNotLoaded error when accessing fields omitted from query projection
 ----------------------------------------------------------------------------------