DOCS-11540, DOCS-11605: mongo shell txn helpers and read concern

Author: kay-kim

config/redirects

@@ -1391,6 +1391,10 @@ raw: /master/release-notes/3.0-general-improvements -> ${base}/release-notes/3.0
 [v3.6-*]: /${version}/reference/method/cursor.snapshot -> ${base}/${version}/reference/method/
 [v3.6-*]: /${version}/administration/replica-sets -> ${base}/${version}/replication
 
+# Redirects for 4.0
+
+[v4.0-v4.0]: /${version}/upcoming.txt -> ${base}/${version}/core/transactions
+
 # Redirects for 4.0 and greater
 
 [v4.0-*]: /${version}/core/security-mongodb-cr -> ${base}/${version}/core/security-scram
@@ -1399,8 +1403,14 @@ raw: /master/release-notes/3.0-general-improvements -> ${base}/release-notes/3.0
 [v4.0-*]: /${version}/reference/command/resync -> ${base}/${version}/core/master-slave
 [v4.0-*]: /${version}/reference/program/mongoperf -> ${base}/${version}/reference/program
 
-# Redirects for 3.6 or earlier 
+# Redirects for 3.6 or earlier (i.e. before 4.0)
+
 [*-v3.6]: /${version}/reference/read-concern-snapshot -> ${base}/${version}/reference/read-concern
+[*-v3.6]: /${version}/core/transactions -> ${base}/${version}/core/write-operations-atomicity
+[*-v3.6]: /${version}/reference/method/Session.abortTransaction -> ${base}/${version}/core/write-operations-atomicity
+[*-v3.6]: /${version}/reference/method/Session.commitTransaction -> ${base}/${version}/core/write-operations-atomicity
+[*-v3.6]: /${version}/reference/method/Session.startTransaction -> ${base}/${version}/core/write-operations-atomicity
+
 
 # 2.8 compatibility
 [*]: /${version}/release-notes/2.8-downgrade -> ${base}/${version}/release-notes

source/contents.txt

@@ -7,14 +7,14 @@ project, this Manual and additional editions of this text.
 
 .. toctree::
    :titlesonly:
-   
-   /upcoming
+
    Introduction </introduction>
    Installation </installation>
    /mongo
    /crud
    /aggregation
    /data-modeling
+   /core/transactions
    /indexes
    /security
    /changeStreams

source/core/transactions.txt

@@ -0,0 +1,139 @@
+============
+Transactions
+============
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. meta::
+   :description: transactions, multi-document transactions, multi-statement transactions
+   :keywords: transactions, multi-document transactions, multi-statement transactions
+
+.. versionadded:: 4.0
+
+In MongoDB, an operation on a single document is atomic. Because you can
+use embedded documents and arrays to capture relationships between data
+in a single document structure instead of normalizing across multiple
+documents and collections, this single-document atomicity obviates the
+need for multi-document transactions for many practical use cases.
+
+However, for situations that require atomicity for updates to multiple
+documents or consistency between reads to multiple documents, MongoDB
+provides the ability to perform multi-document transactions against
+replica sets. Multi-document transactions can be used across multiple
+operations, collections, and documents. Multi-document transactions
+provide an "all-or-nothing" proposition. When a transaction commits,
+all data changes made in the transaction are saved. If any operation in
+the transaction fails, the transaction aborts and all data changes made
+in the transaction are discarded without ever becoming visible. Until a
+transaction commits, no write operations in the transaction are visible
+outside the transaction.
+
+.. important::
+
+   Multi-document transaction incurs a greater performance cost over
+   single document writes, and the availability of multi-document
+   transaction should not be a replacement for effective schema design.
+   For many scenarios, the denormalized data model will continue to be
+   optimal for your data and use cases.
+
+Transaction and Replica Sets
+----------------------------
+
+Multi-document transactions are available for replica sets only. 
+
+The ``featureCompatibilityVersion`` of all members of the replica set
+must be ``4.0`` or greater. To check the
+``featureCompatibilityVersion`` for a member, connect to the member and
+run the following command:
+
+.. code-block:: javascript
+
+   db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
+
+For more information on the ``featureCompatibilityVersion`` flag, see
+:dbcommand:`setFeatureCompatibilityVersion`.
+
+.. _txn-operations:
+
+Transaction and CRUD Operations
+-------------------------------
+
+For multi-document transactions, you can only specify read/write (CRUD)
+operations on existing collections.
+
+Operations that affect the database catalog, such as creating or
+dropping a collection or an index, are not allowed in multi-document
+transactions. For example, a multi-document transaction cannot include
+an insert operation that would result in the creation of a new
+collection.
+
+.. include:: /includes/transaction-operations.rst
+
+Transactions and Sessions
+-------------------------
+
+Transactions are associated with a session. That is, you start a
+transaction for a session. At any given time, you can have at most one
+open transaction for a session.
+
+
+Atomicity
+---------
+
+Multi-document transactions are atomic:
+
+- When a transaction commits, all data changes made in the transaction
+  are saved and visible outside the transaction. Until a transaction
+  commits, the data changes made in the transaction are not visible
+  outside the transaction.
+
+- When a transaction aborts, all data changes made in the transaction
+  are discarded without ever becoming visible. For example, if any
+  operation in the transaction fails, the transaction aborts and all
+  data changes made in the transaction are discarded without ever
+  becoming visible.
+
+Transactions and MongoDB Drivers
+--------------------------------
+
+Clients require MongoDB drivers updated for MongoDB 4.0.
+
+To associate read and write operations with an open transaction, you
+pass the session to the operations.
+
+Transactions and the ``mongo`` Shell
+------------------------------------
+
+The following :binary:`~bin.mongo` shell methods are available for
+transactions:
+
+- :method:`Session.startTransaction()`
+
+- :method:`Session.commitTransaction()`
+
+- :method:`Session.abortTransaction()`
+
+.. _txn-read-concern:
+
+Read Concern
+------------
+
+Multi-document transactions support read concern
+:readconcern:`"snapshot"`, :readconcern:`"local"`, and
+:readconcern:`"majority"`. For :readconcern:`"local"` and
+:readconcern:`"majority"` read concern, MongoDB may sometimes
+substitute a stronger read concern.
+
+.. note:: 
+
+   You set the read concern at the transaction level, not at the
+   individual operation level. The operations in the transaction will
+   use the the transaction level read concern; i.e. the transaction
+   level read concern overrides specific operation level read concern.
+

source/includes/transaction-operations.rst

@@ -0,0 +1,63 @@
+.. list-table::
+   :header-rows: 1
+   :widths: 50 20 30
+
+   * - Method
+     - Command
+     - Note
+
+   * - :method:`db.collection.aggregate()` 
+     - :dbcommand:`aggregate`
+     - 
+   
+   * - :method:`cursor.count()`
+     - :dbcommand:`count`
+     - 
+
+
+   * - :method:`db.collection.distinct()`
+     - :dbcommand:`distinct`
+     - 
+
+   * - :method:`db.collection.find()`
+     - :dbcommand:`find`
+     - 
+
+   * - 
+     - :dbcommand:`geoSearch`
+     - 
+
+   * - | :method:`db.collection.deleteMany()`
+       | :method:`db.collection.deleteOne()`
+       | :method:`db.collection.remove()`
+
+     - :dbcommand:`delete`
+     - 
+
+   * - | :method:`db.collection.findOneAndDelete()`
+       | :method:`db.collection.findOneAndReplace()`
+       | :method:`db.collection.findOneAndUpdate()`
+
+     - :dbcommand:`findAndModify`
+     - 
+
+   * - | :method:`db.collection.insertMany()`
+       | :method:`db.collection.insertOne()`
+       | :method:`db.collection.insert()`
+
+     - :dbcommand:`insert`
+
+     - Only when run against an existing collection.
+
+
+   * - | :method:`db.collection.updateOne()`
+       | :method:`db.collection.updateMany()`
+       | :method:`db.collection.update()`
+
+     - :dbcommand:`update`
+     - For ``upsert``, only when run against an existing collection.
+
+   * - | :method:`db.collection.bulkWrite()`
+       | Various :doc:`/reference/method/js-bulk`
+     - 
+     - For insert operations, only when run against an existing collection.

source/index.txt

@@ -11,15 +11,6 @@ The MongoDB |version| Dev Series Manual
 
    For new features in MongoDB 3.7.x, see :doc:`/release-notes/4.0`.
 
-.. admonition:: Beta Program
-   :class: note
-   
-   The upcoming MongoDB 4.0 will add :doc:`multi-document transactions
-   </upcoming>` for replica sets. Sign up for the `multi-document
-   transactions beta program <https://www.mongodb.com/transactions?jmp=docs>`__.
-
-   .. include:: /includes/fact-upcoming.rst
-
 Welcome to the MongoDB |version| Manual! MongoDB is an open-source,
 document database designed for ease of development and scaling. The
 Manual introduces key concepts in MongoDB, presents the query language,

source/reference/method/Session.abortTransaction.txt

@@ -0,0 +1,128 @@
+==========================
+Session.abortTransaction()
+==========================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. method:: Session.abortTransaction()
+
+   .. versionadded:: 4.0
+
+      :doc:`/core/transactions` are available for replica sets.
+
+   Terminates the :doc:`multi-document transaction
+   </core/transactions>` and rolls back any data changes made by the
+   operations within the transaction. That is, the transaction ends
+   without saving any of the changes made by the operations in the
+   transaction.
+
+Behavior
+--------
+
+Write Concern
+~~~~~~~~~~~~~
+
+When aborting the transaction, the session uses the write concern
+specified at the transaction start. See
+:method:`Session.startTransaction()`.
+
+Atomicity
+~~~~~~~~~
+
+When a transaction aborts, all data changes made by the writes in the
+transaction are discarded without ever becoming visible and the
+transaction ends.
+
+Example
+-------
+
+Consider a scenario where as changes are made to an employee's record
+in the ``hr`` database, you want to ensure that the ``events``
+collection in the ``reporting`` database are in sync with the ``hr``
+changes and vice versa. That is, you want to ensure that these writes are done as a
+single transaction, such that either both operations succeed or fail.
+
+The ``employees`` collection in the ``hr`` database has the following
+documents:
+
+.. code-block:: javascript
+
+   { "_id" : ObjectId("5af0776263426f87dd69319a"), "employee" : 3, "name" : { "title" : "Mr.", "name" : "Iba Ochs" }, "status" : "Active", "department" : "ABC" }
+   { "_id" : ObjectId("5af0776263426f87dd693198"), "employee" : 1, "name" : { "title" : "Miss", "name" : "Ann Thrope" }, "status" : "Active", "department" : "ABC" }
+   { "_id" : ObjectId("5af0776263426f87dd693199"), "employee" : 2, "name" : { "title" : "Mrs.", "name" : "Eppie Delta" }, "status" : "Active", "department" : "XYZ" }
+
+The ``employees`` collection has a unique index on the ``employee`` field.
+
+The ``events`` collection in the ``reporting`` database has the
+following documents:
+
+.. code-block:: javascript
+
+   { "_id" : ObjectId("5af07daa051d92f02462644a"), "employee" : 1, "status" : { "new" : "Active", "old" : null }, "department" : { "new" : "ABC", "old" : null } }
+   { "_id" : ObjectId("5af07daa051d92f02462644b"), "employee" : 2, "status" : { "new" : "Active", "old" : null }, "department" : { "new" : "XYZ", "old" : null } }
+   { "_id" : ObjectId("5af07daa051d92f02462644c"), "employee" : 3, "status" : { "new" : "Active", "old" : null }, "department" : { "new" : "ABC", "old" : null } }
+
+The following example opens a transaction, attempts to add a record to
+the ``events`` collection and add a document to the ``employees``
+collection. If the operation encounters an error in either operations
+or in committing the transaction, the session aborts the transaction.
+
+.. code-block:: javascript
+
+   // Start a session.
+   session = db.getMongo().startSession( );
+
+   employeesCollection = session.getDatabase("hr").employees;
+   eventsCollection = session.getDatabase("reporting").events;
+
+   // Start a transaction for the session that uses:
+   // - read concern "snapshot" 
+   // - write concern "majority"
+   session.startTransaction( { 
+      readConcern: { level: "snapshot" }, 
+      writeConcern: { w: "majority" } 
+   } );
+
+   try{
+
+      eventsCollection.insertOne( 
+         { employee: 3, status: { new: "Active", old: null },  department: { new: "XYZ", old: null }  }
+      );
+
+      // Count number of events for employee 3
+      var count = eventsCollection.find( { employee: 3 } ).count();
+      print ( "Within open transaction: " + count );
+
+      // The following operations should fail as an employee ``3`` already exist in employees collection
+      employeesCollection.insertOne( 
+         { employee: 3, name: { title: "Miss", name: "Terri Bachs" }, status: "Active", department: "XYZ" }
+      ); 
+
+   } catch (error) {
+      print ("Abort transaction.")
+      session.abortTransaction();  // Uses write concern "majority"
+   }
+
+   // Until commit, the data changes are not visible outside this transaction
+   session.commitTransaction(); // Uses write concern "majority"
+
+   var employeeCount = eventsCollection.find( { employees: 3 } ).count();
+
+   print ("After abort transaction: " + employeeCount);
+
+   session.endSession();
+
+.. seealso::
+
+   - :method:`Session.startTransaction()`
+
+   - :method:`Session.commitTransaction()`