Merge pull request #813 from Dynamoid/ak/review-transactions

Review transactions

Author: andrykonchin

README.md

@@ -1064,10 +1064,142 @@ resolving the fields with a second query against the table since a query
 against GSI then a query on base table is still likely faster than scan
 on the base table*
 
-### Transaction Writes
+### Transactions in Dynamoid
 
-Multiple write actions can be grouped together and submitted as an all-or-nothing operation.
-See the [transation documentation](README_transact.md).
+> [!WARNING]
+> Please note that this API is experimental and can be changed in
+> future releases.
+
+Multiple modifying actions can be grouped together and submitted as an
+all-or-nothing operation. Atomic modifying operations are supported in
+Dynamoid using transactions. If any action in the transaction fails they
+all fail.
+
+The following actions are supported:
+
+* `#create`/`#create!` - add a new model if it does not already exist
+* `#save`/`#save!` - create or update model
+* `#update_attributes`/`#update_attributes!` - modifies one or more attributes from an existig
+model
+* `#delete` - remove an model without callbacks nor validations
+* `#destroy`/`#destroy!` - remove an model
+* `#upsert` - add a new model or update an existing one, no callbacks
+* `#update_fields` - update a model without its instantiation
+
+These methods are supposed to behave exactly like their
+non-transactional counterparts.
+
+
+#### Create models
+
+Models can be created inside of a transaction. The partition and sort
+keys, if applicable, are used to determine uniqueness. Creating will
+fail with `Aws::DynamoDB::Errors::TransactionCanceledException` if a
+model already exists.
+
+This example creates a user with a unique id and unique email address by
+creating 2 models. An additional model is upserted in the same
+transaction. Upsert will update `updated_at` but will not create
+`created_at`.
+
+```ruby
+user_id = SecureRandom.uuid
+email = '[email protected]'
+
+Dynamoid::TransactionWrite.execute do |txn|
+  txn.create(User, id: user_id)
+  txn.create(UserEmail, id: "UserEmail##{email}", user_id: user_id)
+  txn.create(Address, id: 'A#2', street: '456')
+  txn.upsert(Address, 'A#1', street: '123')
+end
+```
+
+#### Save models
+
+Models can be saved in a transaction. New records are created otherwise
+the model is updated. Save, create, update, validate and destroy
+callbacks are called around the transaction as appropriate. Validation
+failures will throw `Dynamoid::Errors::DocumentNotValid`.
+
+```ruby
+user = User.find(1)
+article = Article.new(body: 'New article text', user_id: user.id)
+
+Dynamoid::TransactionWrite.execute do |txn|
+  txn.save(article)
+
+  user.last_article_id = article.id
+  txn.save(user)
+end
+```
+
+#### Update models
+
+A model can be updated by providing a model or primary key, and the fields to update.
+
+```ruby
+Dynamoid::TransactionWrite.execute do |txn|
+  # change name and title for a user
+  txn.update_attributes(user, name: 'bob', title: 'mister')
+
+  # sets the name and title for a user
+  # The user is found by id (that equals 1)
+  txn.update_fields(User, '1', name: 'bob', title: 'mister')
+end
+```
+
+#### Destroy or delete models
+
+Models can be used or the model class and key can be specified.
+`#destroy` uses callbacks and validations. Use `#delete` to skip
+callbacks and validations.
+
+```ruby
+article = Article.find('1')
+tag = article.tag
+
+Dynamoid::TransactionWrite.execute do |txn|
+  txn.destroy(article)
+  txn.delete(tag)
+
+  txn.delete(Tag, '2') # delete record with hash key '2' if it exists
+  txn.delete(Tag, 'key#abcd', 'range#1') # when sort key is required
+end
+```
+
+#### Validation failures that don't raise
+
+All of the transaction methods can be called without the `!` which
+results in `false` instead of a raised exception when validation fails.
+Ignoring validation failures can lead to confusion or bugs so always
+check return status when not using a method with `!`.
+
+```ruby
+user = User.find('1')
+user.red = true
+
+Dynamoid::TransactionWrite.execute do |txn|
+  if txn.save(user) # won't raise validation exception
+    txn.update_fields(UserCount, user.id, count: 5)
+  else
+    puts 'ALERT: user not valid, skipping'
+  end
+end
+```
+
+#### Incrementally building a transaction
+
+Transactions can also be built without a block.
+
+```ruby
+transaction = Dynamoid::TransactionWrite.new
+
+transaction.create(User, id: user_id)
+transaction.create(UserEmail, id: "UserEmail##{email}", user_id: user_id)
+transaction.upsert(Address, 'A#1', street: '123')
+
+transaction.commit # changes are persisted in this moment
+```
 
 ### PartiQL
 

README_transact.md

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
 
   spec.description = "Dynamoid is an ORM for Amazon's DynamoDB that supports offline development, associations, querying, and everything else you'd expect from an ActiveRecord-style replacement."
   spec.summary = "Dynamoid is an ORM for Amazon's DynamoDB"
-  # Ignore not commited files
+  # Ignore not committed files
   spec.files = Dir[
     'CHANGELOG.md',
     'dynamoid.gemspec',

dynamoid.gemspec

@@ -13,6 +13,7 @@ module Components
 
       define_model_callbacks :create, :save, :destroy, :update
       define_model_callbacks :initialize, :find, :touch, only: :after
+      define_model_callbacks :commit, :rollback, only: :after
 
       before_save :set_expires_field
       after_initialize :set_inheritance_field

lib/dynamoid/components.rb

@@ -23,11 +23,20 @@ def initialize(item)
       end
     end
 
+    class RecordNotSaved < Error
+      attr_reader :record
+
+      def initialize(record)
+        super('Failed to save the item')
+        @record = record
+      end
+    end
+
     class RecordNotDestroyed < Error
       attr_reader :record
 
       def initialize(record)
-        super('Failed to destroy item')
+        super('Failed to destroy the item')
         @record = record
       end
     end
@@ -80,5 +89,7 @@ class UnsupportedKeyType < Error; end
     class UnknownAttribute < Error; end
 
     class SubclassNotFound < Error; end
+
+    class Rollback < Error; end
   end
 end

lib/dynamoid/errors.rb

@@ -11,6 +11,7 @@ def load(attrs)
 
       self
     end
+    alias assign_attributes load
 
     # Reload an object from the database -- if you suspect the object has changed in the data store and you need those
     # changes to be reflected immediately, you would call this method. This is a consistent read.