dynamoid 3.10.0 → 3.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2cc1feec6853b756fff467fa687cf2eaa3a2dc5f0a88dac948e5a92a4aa1073
-  data.tar.gz: 7165e081fa9979c45e7402265138e62cb6ee3c1f6f594ab6949c1f984621bc89
+  metadata.gz: f3e330233bdd01c0bb962fb7253b48629fe9f0aeb1ecdcb6cfe7d3272ddddbe0
+  data.tar.gz: 7f6ee27e8d6dedb5fe21bce21a6c00397f42d85dfa40b8d30dae4e13a8294d15
 SHA512:
-  metadata.gz: e18700ff74b9466e1ec166706446a1dca5248c6b8c33365e469c74e9a67b92f4afc9cacb0a06c2698d5165f4b68a93cdd214b83f5e3b749b92bcaff06fbc7628
-  data.tar.gz: 9b18fb2522f90eb3cf9b0b6014ca24beb08bcdebf403c57487222c46ec71d306f4e85e686aa89607c77ad7d994359a934537e8d22202b145bd478c0862bf497b
+  metadata.gz: f84a868794dd6b812ccd6936eaa16c91a8d0f87b2ae959b89a8b01802537490168449bfa83f62d92f8643a6c47043cefeb9168da3301ca4f005400bc1086406f
+  data.tar.gz: 528587c73879f49d25e660974fa5832464eed5773da06535a76bfe3c9c96311a1877eb801e68362c94eadc479cf65a8df053a0f47574c78fbf5919859cb88e66

data/CHANGELOG.md

@@ -11,7 +11,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 ### Removed
 
-## 3.10.0
+## 3.12.0
+
+### Fixed
+* [#849](https://github.com/Dynamoid/dynamoid/pull/849) Fixed saving a field of custom type when it implements both `.dynamoid_dump()` and `#dynamoid_dump` method and use the former one.
+A proper behaviour is to use adapter's .dynamoid_dump method instead of a value's #dynamoid_dump method.
+* [#851](https://github.com/Dynamoid/dynamoid/pull/851) Fixed Dirty API and don't require custom types to implement `#==` method. Add field option `:comparable`.
+* [#913](https://github.com/Dynamoid/dynamoid/pull/913) Fixed saving partition keys of Dynamoid-specific types (e.g. `date` or `datetime`) and always convert them into a proper DynamoDB type
+* [#917](https://github.com/Dynamoid/dynamoid/pull/917) Fixed transactional write operations when primary key is of non-native DynamoDB type
+* [#927](https://github.com/Dynamoid/dynamoid/pull/927) Multiple fixes in transactional and non-transactional write methods and finders:
+  * Changed non-transactional method `#find` and raise `MissingHashKey` when a given partition key is `nil`
+  * Fixed non-transactional method `#save!` and raise `RecordNotSaved` when a callback throws `:abort` and terminates the process
+  * Check whether partition and sort key are specified in the non-transactional persistence methods and raise a proper exception (`MissingHashKey` or `MissingRangeKey`)
+  * Fixed methods `#inc`, `#increment!` and `#decrement!`, `#update` and `#update!` to not create a new item when an item with specified primary key is already deleted
+  * Fixed method `#update_attribute` to not raise `StaleObjectError` when an item with specified primary key is already deleted
+  * Fixed method `#where` with condition on a `:serialized` field to not raise an exception
+### Added
+* [#910](https://github.com/Dynamoid/dynamoid/pull/910) Added `key_type` option to the `table` method to change type of a partition key field (@ogidow)
+* [#916](https://github.com/Dynamoid/dynamoid/pull/916) Added new `error_on_scan` config option to raises an error and prevent table scans (DynamoDB's `Scan` operation) (@aaronalberg)
+* [#926](https://github.com/Dynamoid/dynamoid/pull/926) Implemented read transactions (using DynamoDB's `TransactGetItems` operation)
+### Changed
+* [#846](https://github.com/Dynamoid/dynamoid/pull/846) Changed transactional `update_fields()` method to accept a block and support low-level operations `set`, `add`, `delete`, `remove` (similar to the non-transactional `#update()` method) (@ckhsponge)
+### Removed
+
+## 3.11.0 / 2025-01-12
+### Fixed
+* [#829](https://github.com/Dynamoid/dynamoid/pull/829) Fixed saving of in-place field changes
+* [#812](https://github.com/Dynamoid/dynamoid/pull/812) Restored sanitizing of attribute names in `#where` conditions
+* [#721](https://github.com/Dynamoid/dynamoid/pull/721) Fixed code examples in README.md (@ndjndj)
+### Added
+* [#688](https://github.com/Dynamoid/dynamoid/pull/688) Implemented write transactions (using DynamoDB's `TransactWriteItems` operation) (@ckhsponge)
+* [#794](https://github.com/Dynamoid/dynamoid/pull/794) Added new config option `store_empty_string_as_nil`
+* [#828](https://github.com/Dynamoid/dynamoid/pull/828) Added Ruby 3.4, Rails 8.0 and Rails 7.2 in CI
+### Changed
+* [#832](https://github.com/Dynamoid/dynamoid/pull/832) Support String condition expressions with `#where`
+* [#822](https://github.com/Dynamoid/dynamoid/pull/822) Support binary type natively. Also added new config option `store_binary_as_native` (@dalibor)
+
+## 3.10.0 / 2024-02-10
 ### Fixed
 * [#681](https://github.com/Dynamoid/dynamoid/pull/681) Fixed saving persisted model and deleting attributes with `nil` value if `config.store_attribute_with_nil_value` is `false`
 * [#716](https://github.com/Dynamoid/dynamoid/pull/716), [#691](https://github.com/Dynamoid/dynamoid/pull/691), [#687](https://github.com/Dynamoid/dynamoid/pull/687), [#660](https://github.com/Dynamoid/dynamoid/pull/660) Numerous fixes in README.md and RDoc documentation (@ndjndj, @kiharito, @dunkOnIT)

data/README.md

@@ -24,8 +24,8 @@ DynamoDB is not like other document-based databases you might know, and
 is very different indeed from relational databases. It sacrifices
 anything beyond the simplest relational queries and transactional
 support to provide a fast, cost-efficient, and highly durable storage
-solution. If your database requires complicated relational queries and
-transaction support, then this modest Gem cannot provide them for you,
+solution. If your database requires complicated relational queries
+then this modest Gem cannot provide them for you
 and neither can DynamoDB. In those cases you would do better to look
 elsewhere for your database needs.
 
@@ -102,8 +102,8 @@ credentials = Aws::AssumeRoleCredentials.new(
 )
 
 Dynamoid.configure do |config|
-  config.region = 'us-west-2',
-                  config.credentials = credentials
+  config.region = 'us-west-2'
+  config.credentials = credentials
 end
 ```
 
@@ -132,8 +132,8 @@ end
 Dynamoid supports Ruby >= 2.3 and Rails >= 4.2.
 
 Its compatibility is tested against following Ruby versions: 2.3, 2.4,
-2.5, 2.6, 2.7, 3.0, 3.1, 3.2 and 3.3, JRuby 9.4.x and against Rails versions: 4.2, 5.0, 5.1,
-5.2, 6.0, 6.1, 7.0 and 7.1.
+2.5, 2.6, 2.7, 3.0, 3.1, 3.2, 3.3, and 3.4, JRuby 9.4.x and against Rails versions: 4.2, 5.0, 5.1,
+5.2, 6.0, 6.1, 7.0, 7.1, 7.2, and 8.0.
 
 ## Setup
 
@@ -342,6 +342,24 @@ class Document
 end
 ```
 
+#### Note on binary type
+
+By default binary fields are persisted as DynamoDB String value encoded
+in the Base64 encoding. DynamoDB supports binary data natively. To use
+it instead of String a `store_binary_as_native` field option should be
+set:
+
+```ruby
+class Document
+  include Dynamoid::Document
+
+  field :image, :binary, store_binary_as_native: true
+end
+```
+
+There is also a global config option `store_binary_as_native` that is
+`false` by default as well.
+
 #### Magic Columns
 
 You get magic columns of `id` (`string`), `created_at` (`datetime`), and
@@ -453,6 +471,27 @@ method, which would return either `:string` or `:number`.
 DynamoDB may support some other attribute types that are not yet
 supported by Dynamoid.
 
+If a custom type implements `#==` method you can specify `comparable:
+true` option in a field declaration to specify that an object is safely
+comparable for the purpose of detecting changes. By default old and new
+objects will be compared by their serialized representation.
+
+```ruby
+class Money
+  # ...
+
+  def ==(other)
+    # comparison logic
+  end
+end
+
+class User
+  # ...
+
+  field :balance, Money, comparable: true
+end
+```
+
 ### Sort key
 
 Along with partition key table may have a sort key. In order to declare
@@ -602,6 +641,7 @@ with `inheritance_field` table option:
 ```ruby
 class Car
   include Dynamoid::Document
+
   table inheritance_field: :my_new_type
 
   field :my_new_type
@@ -701,7 +741,7 @@ users = User.import([{ name: 'Josh' }, { name: 'Nick' }])
 
 ### Querying
 
-Querying can be done in one of three ways:
+Querying can be done in one of the following ways:
 
 ```ruby
 Address.find(address.id)              # Find directly by ID.
@@ -710,6 +750,27 @@ Address.where(city: 'Chicago').all    # Find by any number of matching criteria.
 Address.find_by_city('Chicago')       # The same as above, but using ActiveRecord's older syntax.
 ```
 
+There is also a way to `#where` with a condition expression:
+
+```ruby
+Address.where('city = :c', c: 'Chicago')
+```
+
+A condition expression may contain operators (e.g. `<`, `>=`, `<>`),
+keywords (e.g. `AND`, `OR`, `BETWEEN`) and built-in functions (e.g.
+`begins_with`, `contains`) (see (documentation
+)[https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html]
+for full syntax description).
+
+**Warning:** Values (specified for a String condition expression) are
+sent as is so Dynamoid field types that aren't supported natively by
+DynamoDB (e.g. `datetime` and `date`) require explicit casting.
+
+**Warning:** String condition expressions will be used by DynamoDB only
+at filtering, so conditions on key attributes should be specified as a
+Hash to perform Query operation instead of Scan. Don't use key
+attributes in `#where`'s String condition expressions.
+
 And you can also query on associations:
 
 ```ruby
@@ -875,6 +936,7 @@ It could be done with `project` method:
 ```ruby
 class User
   include Dynamoid::Document
+
   field :name
 end
 
@@ -934,7 +996,6 @@ validation and callbacks.
 Address.find(id).update_attributes(city: 'Chicago')
 Address.find(id).update_attribute(:city, 'Chicago')
 Address.update(id, city: 'Chicago')
-Address.update(id, { city: 'Chicago' }, if: { deliverable: true })
 ```
 
 There are also some low level methods `#update`, `.update_fields` and
@@ -1047,6 +1108,198 @@ 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*
 
+### Transactions in Dynamoid
+
+> [!WARNING]
+> Please note that this API is experimental and can be changed in
+> future releases.
+
+DynamoDB supports modifying and reading operations but there are some
+limitations:
+- read and write operation cannot be combined in the same transaction
+- operations are executed in batch, so operations should be given before
+  actual execution and cannot be changed on the fly
+
+#### Modifying transactions
+
+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 = 'bob@bob.bob'
+
+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')
+
+  # sets the name, increments a count and deletes a field
+  txn.update_fields(User, 1) do |t|
+    t.set(name: 'bob')
+    t.add(article_count: 1)
+    t.delete(:title)
+  end
+
+  # adds to a set of integers and deletes from a set of strings
+  txn.update_fields(User, 2) do |t|
+    t.add(friend_ids: [1, 2])
+    t.delete(child_names: ['bebe'])
+  end
+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
+```
+
+#### Reading transactions
+
+Multiple reading actions can be grouped together and submitted as an
+all-or-nothing operation. Atomic  operations are supported in Dynamoid
+using transactions. If any action in the transaction fails they all
+fail.
+
+The following actions are supported:
+
+* `#find` - load a single model or multiple models by its primary key
+
+These methods are supposed to behave exactly like their
+non-transactional counterparts.
+
+##### Find a model
+
+The `#find` action can load single model or multiple ones. Different
+model classes can be mixed in the same transactions. Result is returned
+as a plain list of all the found models. The order is preserved.
+
+```ruby
+user, address = Dynamoid::TransactionRead.execute do |t|
+  t.find(User, user_id)
+  t.find(Address, address_id)
+end
+```
+
+Multiple primary keys can be specified at once:
+
+```ruby
+users = Dynamoid::TransactionRead.execute do |t|
+  t.find(User, [id1, id2, id3])
+end
+```
+
 ### PartiQL
 
 To run PartiQL statements `Dynamoid.adapter.execute` method should be
@@ -1094,6 +1347,7 @@ Listed below are all configuration options.
 * `write_capacity` - is used at table or indices creation. Default is 20
   (units)
 * `warn_on_scan` - log warnings when scan table. Default is `true`
+* `error_on_scan` - raises an error when scan table. Default is `false`
 * `endpoint` - if provided, it communicates with the DynamoDB listening
   at the endpoint. This is useful for testing with
   [DynamoDB Local](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Tools.DynamoDBLocal.html)
@@ -1130,9 +1384,13 @@ Listed below are all configuration options.
   fields in ISO 8601 string format. Default is `false`
 * `store_date_as_string` - if `true` then Dynamoid stores :date fields
   in ISO 8601 string format. Default is `false`
+* `store_empty_string_as_nil` - store attribute's empty String value as NULL. Default is `true`
 * `store_boolean_as_native` - if `true` Dynamoid stores boolean fields
   as native DynamoDB boolean values. Otherwise boolean fields are stored
   as string values `'t'` and `'f'`. Default is `true`
+* `store_binary_as_native` - if `true` Dynamoid stores binary fields
+  as native DynamoDB binary values. Otherwise binary fields are stored
+  as Base64 encoded string values. Default is `false`
 * `backoff` - is a hash: key is a backoff strategy (symbol), value is
   parameters for the strategy. Is used in batch operations. Default id
   `nil`
@@ -1322,6 +1580,7 @@ order to troubleshoot and debug issues just set it:
 ```ruby
 class User
   include Dynamoid::Document
+
   field name
 end
 
@@ -1350,6 +1609,7 @@ just as accessible to the Ruby world as MongoDB.
 Also, without contributors the project wouldn't be nearly as awesome. So
 many thanks to:
 
+* [Chris Hobbs](https://github.com/ckhsponge)
 * [Logan Bowers](https://github.com/loganb)
 * [Lane LaRue](https://github.com/luxx)
 * [Craig Heneveld](https://github.com/cheneveld)

data/dynamoid.gemspec

@@ -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',
@@ -51,9 +51,9 @@ Gem::Specification.new do |spec|
   spec.metadata['wiki_uri'] = 'https://github.com/Dynamoid/dynamoid/wiki'
   spec.metadata['rubygems_mfa_required'] = 'true'
 
-  spec.add_runtime_dependency 'activemodel', '>=4'
-  spec.add_runtime_dependency 'aws-sdk-dynamodb', '~> 1.0'
-  spec.add_runtime_dependency 'concurrent-ruby', '>= 1.0'
+  spec.add_dependency 'activemodel', '>=4'
+  spec.add_dependency 'aws-sdk-dynamodb', '~> 1.0'
+  spec.add_dependency 'concurrent-ruby', '>= 1.0'
 
   spec.add_development_dependency 'appraisal'
   spec.add_development_dependency 'bundler'

data/lib/dynamoid/adapter.rb

@@ -118,7 +118,7 @@ module Dynamoid
     # @param [Hash] query a hash of attributes: matching records will be returned by the scan
     #
     # @since 0.2.0
-    def scan(table, query = {}, opts = {})
+    def scan(table, query = [], opts = {})
       benchmark('Scan', table, query) { adapter.scan(table, query, opts) }
     end
 

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/filter_expression_convertor.rb

@@ -20,48 +20,83 @@ module Dynamoid
         private
 
         def build
-          clauses = @conditions.map do |name, attribute_conditions|
+          clauses = []
+
+          @conditions.each do |conditions|
+            if conditions.is_a? Hash
+              clauses << build_for_hash(conditions) unless conditions.empty?
+            elsif conditions.is_a? Array
+              query, placeholders = conditions
+              clauses << build_for_string(query, placeholders)
+            else
+              raise ArgumentError, "expected Hash or Array but actual value is #{conditions}"
+            end
+          end
+
+          @expression = clauses.join(' AND ')
+        end
+
+        def build_for_hash(hash)
+          clauses = hash.map do |name, attribute_conditions|
             attribute_conditions.map do |operator, value|
-              name_or_placeholder = name_or_placeholder_for(name)
+              # replace attribute names with placeholders unconditionally to support
+              # - special characters (e.g. '.', ':', and '#') and
+              # - leading '_'
+              # See
+              # - https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.NamingRules
+              # - https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html#Expressions.ExpressionAttributeNames.AttributeNamesContainingSpecialCharacters
+              name_placeholder = name_placeholder_for(name)
 
               case operator
               when :eq
-                "#{name_or_placeholder} = #{value_placeholder_for(value)}"
+                "#{name_placeholder} = #{value_placeholder_for(value)}"
               when :ne
-                "#{name_or_placeholder} <> #{value_placeholder_for(value)}"
+                "#{name_placeholder} <> #{value_placeholder_for(value)}"
               when :gt
-                "#{name_or_placeholder} > #{value_placeholder_for(value)}"
+                "#{name_placeholder} > #{value_placeholder_for(value)}"
               when :lt
-                "#{name_or_placeholder} < #{value_placeholder_for(value)}"
+                "#{name_placeholder} < #{value_placeholder_for(value)}"
               when :gte
-                "#{name_or_placeholder} >= #{value_placeholder_for(value)}"
+                "#{name_placeholder} >= #{value_placeholder_for(value)}"
               when :lte
-                "#{name_or_placeholder} <= #{value_placeholder_for(value)}"
+                "#{name_placeholder} <= #{value_placeholder_for(value)}"
               when :between
-                "#{name_or_placeholder} BETWEEN #{value_placeholder_for(value[0])} AND #{value_placeholder_for(value[1])}"
+                "#{name_placeholder} BETWEEN #{value_placeholder_for(value[0])} AND #{value_placeholder_for(value[1])}"
               when :begins_with
-                "begins_with (#{name_or_placeholder}, #{value_placeholder_for(value)})"
+                "begins_with (#{name_placeholder}, #{value_placeholder_for(value)})"
               when :in
                 list = value.map(&method(:value_placeholder_for)).join(' , ')
-                "#{name_or_placeholder} IN (#{list})"
+                "#{name_placeholder} IN (#{list})"
               when :contains
-                "contains (#{name_or_placeholder}, #{value_placeholder_for(value)})"
+                "contains (#{name_placeholder}, #{value_placeholder_for(value)})"
               when :not_contains
-                "NOT contains (#{name_or_placeholder}, #{value_placeholder_for(value)})"
+                "NOT contains (#{name_placeholder}, #{value_placeholder_for(value)})"
               when :null
-                "attribute_not_exists (#{name_or_placeholder})"
+                "attribute_not_exists (#{name_placeholder})"
               when :not_null
-                "attribute_exists (#{name_or_placeholder})"
+                "attribute_exists (#{name_placeholder})"
               end
             end
           end.flatten
 
-          @expression = clauses.join(' AND ')
+          if clauses.empty?
+            nil
+          else
+            clauses.join(' AND ')
+          end
         end
 
-        def name_or_placeholder_for(name)
-          return name unless name.upcase.in?(Dynamoid::AdapterPlugin::AwsSdkV3::RESERVED_WORDS)
+        def build_for_string(query, placeholders)
+          placeholders.each do |(k, v)|
+            k = k.to_s
+            k = ":#{k}" unless k.start_with?(':')
+            @value_placeholders[k] = v
+          end
+
+          "(#{query})"
+        end
 
+        def name_placeholder_for(name)
           placeholder = @name_placeholder_sequence.call
           @name_placeholders[placeholder] = name
           placeholder

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/item_updater.rb

@@ -97,10 +97,11 @@ module Dynamoid
 
         private
 
-        # Keep in sync with AwsSdkV3.sanitize_item.
+        # It's a single low level component available in a public API (with
+        # Document#update/#update! methods). So duplicate sanitizing to some
+        # degree.
         #
-        # The only difference is that to update item we need to track whether
-        # attribute value is nil or not.
+        # Keep in sync with AwsSdkV3.sanitize_item.
         def sanitize_attributes(attributes)
           # rubocop:disable Lint/DuplicateBranch
           attributes.transform_values do |v|
@@ -108,7 +109,7 @@ module Dynamoid
               v.stringify_keys
             elsif v.is_a?(Set) && v.empty?
               nil
-            elsif v.is_a?(String) && v.empty?
+            elsif v.is_a?(String) && v.empty? && Config.store_empty_string_as_nil
               nil
             else
               v

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/projection_expression_convertor.rb

@@ -21,13 +21,15 @@ module Dynamoid
           return if @names.nil? || @names.empty?
 
           clauses = @names.map do |name|
-            if name.upcase.in?(Dynamoid::AdapterPlugin::AwsSdkV3::RESERVED_WORDS)
-              placeholder = @name_placeholder_sequence.call
-              @name_placeholders[placeholder] = name
-              placeholder
-            else
-              name.to_s
-            end
+            # replace attribute names with placeholders unconditionally to support
+            # - special characters (e.g. '.', ':', and '#') and
+            # - leading '_'
+            # See
+            # - https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.NamingRules
+            # - https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html#Expressions.ExpressionAttributeNames.AttributeNamesContainingSpecialCharacters
+            placeholder = @name_placeholder_sequence.call
+            @name_placeholders[placeholder] = name
+            placeholder
           end
 
           @expression = clauses.join(' , ')

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/query.rb

@@ -69,7 +69,7 @@ module Dynamoid
           limit = [record_limit, scan_limit, batch_size].compact.min
 
           # key condition expression
-          convertor = FilterExpressionConvertor.new(@key_conditions, name_placeholders, value_placeholders, name_placeholder_sequence, value_placeholder_sequence)
+          convertor = FilterExpressionConvertor.new([@key_conditions], name_placeholders, value_placeholders, name_placeholder_sequence, value_placeholder_sequence)
           key_condition_expression = convertor.expression
           value_placeholders = convertor.value_placeholders
           name_placeholders = convertor.name_placeholders

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/scan.rb

@@ -13,7 +13,7 @@ module Dynamoid
       class Scan
         attr_reader :client, :table, :conditions, :options
 
-        def initialize(client, table, conditions = {}, options = {})
+        def initialize(client, table, conditions = [], options = {})
           @client = client
           @table = table
           @conditions = conditions

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/transact.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Prepare all the actions of the transaction for sending to the AWS SDK.
+module Dynamoid
+  module AdapterPlugin
+    class AwsSdkV3
+      class Transact
+        attr_reader :client
+
+        def initialize(client)
+          @client = client
+        end
+
+        # Perform all of the item actions in a single transaction.
+        #
+        # @param [Array] items of type Dynamoid::Transaction::Action or
+        # any other object whose to_h is a transact_item hash
+        #
+        def transact_write_items(items)
+          transact_items = items.map(&:to_h)
+          params = {
+            transact_items: transact_items,
+            return_consumed_capacity: 'TOTAL',
+            return_item_collection_metrics: 'SIZE'
+          }
+          client.transact_write_items(params) # returns this
+        end
+      end
+    end
+  end
+end