DOCSP-42774: transactions

source/includes/interact-data/transaction.rb

@@ -0,0 +1,129 @@
+# start-example-models
+class Book
+    include Mongoid::Document
+
+    field :title, type: String
+    field :author, type: String
+    field :length, type: Integer
+end
+
+class Film
+    include Mongoid::Document
+
+    field :title, type: String
+    field :year, type: Integer
+end
+# end-example-models
+
+# start-txn-operations
+# Starts a transaction from the model class
+Book.transaction do
+    Book.create(title: 'Covert Joy', author: 'Clarice Lispector')
+    Film.create(title: 'Nostalgia', year: 1983)
+end
+
+# Starts a transaction from an instance of Book
+book = Book.create(title: 'Sula', author: 'Toni Morrison')
+book.transaction do
+  book.length = 192
+  book.save!
+end
+
+# Starts a transaction from the Mongoid instance
+Mongoid.transaction do
+  book.destroy
+end
+# end-txn-operations
+
+# start-different-clients
+# Defines a class by using the :default client
+class Post
+  include Mongoid::Document
+end
+
+# Defines a class by using the :encrypted_client
+class User
+  include Mongoid::Document
+
+  store_in client: :encrypted_client
+end
+
+# Starts a transaction on the :encrypted_client
+User.transaction do
+  # Uses the same client, so the operation is in the transaction
+  User.create!
+  # Uses a different client, so it is *not* in the transaction
+  Post.create!
+end
+# end-different-clients
+
+# start-lower-lvl-api
+# Starts a session from the model class
+Book.with_session do |session|
+  # Starts the transaction in the session
+  session.start_transaction
+end
+
+book = Book.new
+# Starts a session from an instance of Book
+book.with_session do |session|
+  # Starts the transaction in the session
+  session.start_transaction
+end
+# end-lower-lvl-api
+
+# start-commit-abort
+Book.with_session do |session|
+  session.commit_transaction
+end
+
+Book.with_session do |session|
+  session.abort_transaction
+end
+# end-commit-abort
+
+# start-commit-retry
+begin
+  session.commit_transaction
+rescue Mongo::Error => e
+  if e.label?(Mongo::Error::UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL)
+    retry
+  else
+    raise
+  end
+end
+# end-commit-retry
+
+# start-other-client
+# Specifies that the operation should use the "other" client instead of
+# the default client
+User.with(client: :other) do
+  Post.with(client: :other) do
+    Post.with_session do |session|
+      session.start_transaction
+      Post.create!
+      Post.create!
+      User.create!
+      session.commit_transaction
+    end
+  end
+end
+# end-other-client
+
+# start-model-session
+Book.with_session(causal_consistency: true) do
+  Book.create!
+  book = Person.first
+  book.title = "Swann's Way"
+  book.save
+end
+# end-model-session
+
+# start-instance-session
+book = Book.new
+book.with_session(causal_consistency: true) do
+  book.title = 'Catch-22'
+  book.save
+  book.sellers << Shop.create!
+end
+# end-instance-session

source/interact-data.txt

@@ -16,6 +16,7 @@ Interact with Data
 
    /interact-data/specify-query
    /interact-data/modify-results
+   /interact-data/transaction
 
 In this section, you can learn how to use {+odm+} to interact with your
 MongoDB data.
@@ -25,3 +26,6 @@ MongoDB data.
 
 - :ref:`mongoid-data-modify-results`: Learn how to modify the way that
   {+odm+} returns results from queries.
+
+- :ref:`mongoid-data-txn`: Learn how to perform multi-document
+  transactions to make atomic data changes.