diff --git a/source/includes/write/transaction.rb b/source/includes/write/transaction.rb new file mode 100644 index 00000000..a2d54cf8 --- /dev/null +++ b/source/includes/write/transaction.rb @@ -0,0 +1,45 @@ +require 'bundler/inline' +gemfile do + source 'https://rubygems.org' + gem 'mongo' +end + +uri = "" + +Mongo::Client.new(uri) do |client| + #start-txn + database = client.use('sample_mflix') + movies_collection = database[:movies] + users_collection = database[:users] + + def run_transaction(session, movies_collection, users_collection) + transaction_options = { + read_concern: { level: "snapshot" }, + write_concern: { w: "majority" } + } + + session.with_transaction(transaction_options) do + # Inserts document into the "movies" collection + insert_result = movies_collection.insert_one({ name: 'The Menu', runtime: 107 }, session: session) + puts "Insert completed: #{insert_result.inspect}" + + # Updates document in the "users" collection + update_result = users_collection.update_one({ name: 'Amy Phillips'}, { "$set" => { name: 'Amy Ryan' }}, session: session) + puts "Update completed: #{update_result.inspect}" + end + end + + # Starts a session + session = client.start_session + + begin + # Runs the transaction + run_transaction(session, movies_collection, users_collection) + puts "Transaction committed successfully." + rescue Mongo::Error::OperationFailure => e + puts "Transaction failed and was aborted. Error: #{e.message}" + ensure + session.end_session + end + #end-txn +end \ No newline at end of file diff --git a/source/write/transactions.txt b/source/write/transactions.txt new file mode 100644 index 00000000..cb8d28fe --- /dev/null +++ b/source/write/transactions.txt @@ -0,0 +1,147 @@ +.. _ruby-transactions: + +============ +Transactions +============ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, ACID compliance, multi-document + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to perform +**transactions**. Transactions allow you to perform a series of operations that +change data only if the entire transaction is committed. If any operation in the +transaction does not succeed, the driver stops the transaction and discards all +data changes before they ever become visible. This feature is called +**atomicity**. + +In MongoDB, transactions run within logical **sessions**. A session is a +grouping of related read or write operations that you want to run sequentially. +Sessions enable causal consistency for a group of operations and allow you to +run operations in an **ACID-compliant** transaction, which is a transaction that +meets an expectation of atomicity, consistency, isolation, and durability. +MongoDB guarantees that the data involved in your transaction operations remains +consistent, even if the operations encounter unexpected errors. + +When using the {+driver-short+}, you can start a session by calling the +``start_session`` method on your client. Then, you can perform transactions +within the session. + +.. warning:: + + Use a session only in operations running on the ``Mongo::Client`` that + created it. Using a session with a different ``Mongo::Client`` results in + operation errors. + +Methods +------- + +After calling the ``start_session`` method to start a session, you can use +methods from the ``Mongo::Session`` class to manage the session state. The +following table describes the methods you can use to manage a transaction: + +.. list-table:: + :widths: 25 75 + :stub-columns: 1 + :header-rows: 1 + + * - Method + - Description + + * - ``start_transaction`` + - | Starts a new transaction on this session. You cannot start a + transaction if there's already an active transaction running in + the session. + | + | You can set transaction options including read concern, write concern, + and read preference by passing a ``Hash`` as a parameter. + + * - ``commit_transaction`` + - | Commits the active transaction for this session. This method returns an + error if there is no active transaction for the session, the + transaction was previously ended, or if there is a write conflict. + + * - ``abort_transaction`` + - | Ends the active transaction for this session. This method returns an + error if there is no active transaction for the session or if the + transaction was committed or ended. + + * - ``with_transaction`` + - | 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. + +.. _ruby-txn-example: + +Transaction Example +------------------- + +This example defines a ``run_transaction`` method that modifies data in the +collections of the ``sample_mflix`` database. The code performs the following +actions: + +- Creates ``Mongo::Collection`` instances to access the ``movies`` and ``users`` + collections. +- Specifies the read and write concerns for the transaction. +- Starts the transaction. +- Inserts a document into the ``movies`` collection and prints the results. +- Updates a document in the ``users`` collection and prints the results. + +.. literalinclude:: /includes/write/transaction.rb + :language: ruby + :start-after: start-txn + :end-before: end-txn + :dedent: + :copyable: + +.. sharedinclude:: dbx/transactions-parallelism.rst + + .. TODO: + Replace content to use this wording when the bulk write guide is added: + .. replacement:: driver-specific-content + .. If you're using {+mdb-server+} v8.0 or later, you can perform + .. write operations on multiple namespaces within a single transaction by using + .. the ``bulk-write`` method. For more information, see the :ref:`` + .. guide. + +Additional Information +---------------------- + +To learn more about the concepts mentioned in this guide, see the +following pages in the {+mdb-server+} manual: + +- :manual:`Transactions ` +- :manual:`Server Sessions ` +- :manual:`Read Isolation, Consistency, and Recency + ` + +To learn more about ACID compliance, see the :website:`A Guide to ACID Properties in Database Management Systems +` article on the MongoDB website. + +To learn more about insert operations, see the +:ref:`ruby-write-insert` guide. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the methods and types mentioned in this +guide, see the following API documentation: + +- `Mongo::Session <{+api-root+}/Mongo/Session.html>`_ +- `start_transaction <{+api-root+}/Mongo/Session.html#start_transaction-instance_method>`_ +- `commit_transaction <{+api-root+}/Mongo/Session.html#commit_transaction-instance_method>`_ +- `abort_transaction <{+api-root+}/Mongo/Session.html#abort_transaction-instance_method>`_ +- `with_transaction <{+api-root+}/Mongo/Session.html#with_transaction-instance_method>`_ \ No newline at end of file