DOCSP-31847: use a session with the original client (#749)

* DOCSP-31847: use a session with the original client

* small fix

* MW PR fixes 1

Author: rustagir

source/fundamentals/transactions.txt

@@ -4,8 +4,6 @@
 Transactions
 ============
 
-.. default-domain:: mongodb
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -15,38 +13,35 @@ Transactions
 Overview
 --------
 
-Read this guide to learn how to perform **transactions** in MongoDB using the
-Node.js driver. A transaction is a unit of work, composed of a series of
-operations that you want either to succeed together, or fail together when one
-or more of the operations fail. This behavior is called **atomicity**.
-Atomicity is a property in which transactions composed of one or more
-operations occur all at once, such that no other client can observe them as
-separate operations, and that it leaves no changes if one of the operations
-fails.
+In this guide, you can learn how to use the
+{+driver-short+} to perform **transactions**. Transactions allow you
+to run a series of operations that do not change any data until the
+entire transaction is committed. If any operation in the transaction fails, the 
+driver aborts the transaction and discards all data changes before they
+ever become visible. This feature is called **atomicity**.
 
 Since all write operations on a single document in MongoDB are atomic, you
-may benefit most from transactions when you must make an atomic change that
-modifies multiple documents, which is called a multi-document transaction.
-Similar to write operations on a single document, multi-document transactions
-are **ACID compliant**, which means MongoDB guarantees the data involved
-in your transaction operations remains consistent, even if it encounters
-unexpected errors. Learn more from this MongoDB article on
-`ACID transactions <https://www.mongodb.com/basics/acid-transactions>`__.
+might want to use transactions to make an atomic change that
+modifies multiple documents. This situation would require a multi-document transaction.
+Multi-document transactions are **ACID compliant** because MongoDB
+guarantees that the data involved in your transaction operations remains
+consistent, even if the driver encounters unexpected errors.
 
-You can use the driver to perform multi-document transactions.
+To learn more about ACID compliance and transactions, see our :website:`article on
+ACID transactions </basics/acid-transactions>`.
 
 .. note::
 
-   To run multi-document transactions, you must use MongoDB version 4.0 or
-   later.
+   To execute a multi-document transactions, you must be connected to a
+   deployment running MongoDB Server version 4.0 or later.
 
    For a detailed list of limitations, see the :manual:`Transactions and
    Operations </core/transactions/#transactions-and-operations>` section in
-   the server manual.
+   the Server manual.
 
 In MongoDB, multi-document transactions run within a **client session**.
 A client session is a grouping of related read or write operations that
-you want to ensure run sequentially. We recommend you reuse
+you want to execute sequentially. We recommend you reuse
 your client for multiple sessions and transactions instead of
 instantiating a new client each time.
 
@@ -256,9 +251,26 @@ shows how you can perform the following:
    :start-after: start placeOrder
    :end-before: end placeOrder
 
-Note that you must pass the session object to each CRUD operation that
+You must pass the session object to each CRUD operation that
 you want to run on that session.
 
+.. important:: Use a Session with the Client That Started It
+   
+   Starting in version 6.0 of the {+driver-short+}, the driver 
+   throws an error if you provide a session from one ``MongoClient``
+   instance to a different client instance.
+
+   For example, the following code generates an
+   ``MongoInvalidArgumentError`` error because it creates
+   a ``ClientSession`` instance from the ``client1`` client, but provides
+   this session to the ``client2`` client for a write operation:
+
+   .. code-block:: js
+      :emphasize-lines: 2
+      
+      const session = client1.startSession();
+      client2.db('myDB').collection('myColl').insertOne({ name: 'Jane Eyre' }, { session });
+
 The code and comments in the ``catch`` block demonstrate how you can identify
 the server transaction errors and where you can place your logic to handle
 them. Make sure to include the ``MongoError`` type from the driver in your

source/upgrade.txt

@@ -94,6 +94,9 @@ Version 6.x Breaking Changes
 - The ``Binary.write()`` method no longer accepts a string to write to the binary
   BSON object.
 - The ClientEncryption API returns promises instead of callbacks.
+- If you start a session on a client, then pass that session to a
+  different client, the driver throws an error when you
+  perform any operations in the session.
 
 .. _node-breaking-changes-v5.x:
 

source/whats-new.txt

@@ -76,6 +76,10 @@ What's New in 6.0
 
    - The ClientEncryption API returns promises instead of callbacks.
 
+   - If you start a session on a client, then pass that session to a
+     different client, the driver throws an error when you
+     perform any operations in the session.
+
 The {+driver-short+} v6.0 release includes the following features:
 
 .. important:: Deprecation Notice