Aws::Record

A data mapping abstraction over the AWS SDK for Ruby’s client for Amazon DynamoDB.

Table of Contents

• Installation
• Usage
  • Item Operations
  • BatchGetItem / BatchWriteItem
  • Transactions
  • Inheritance Support

Links of Interest

• Documentation
• Change Log
• Issues
• License

---

Installation

Aws::Record is available as the aws-record gem from RubyGems.

gem install 'aws-record'

gem 'aws-record', '~> 2.0'

This automatically includes a dependency on the aws-sdk-dynamodb gem (part of the modular version-3 of the AWS SDK for Ruby. If you need to pin to a specific version, you can add aws-sdk-dynamodb or aws-sdk-core gem in your Gemfile.

---

Usage

To create a model that uses aws-record features, simply include the provided module:

class MyModel
  include Aws::Record
end

You can then specify attributes using the aws-record DSL:

class MyModel
  include Aws::Record
  integer_attr :id, hash_key: true
  string_attr  :name, range_key: true
  boolean_attr :active, database_attribute_name: 'is_active_flag'
end

If a matching table does not exist in DynamoDB, you can use the TableConfig DSL to create your table:

cfg = Aws::Record::TableConfig.define do |t|
  t.model_class(MyModel)
  t.read_capacity_units(5)
  t.write_capacity_units(2)
end
cfg.migrate!

With a table in place, you can then use your model class to manipulate items in your table:

item = MyModel.find(id: 1, name: 'Hello Record')
item.active = true
item.save
item.delete!

MyModel.find(id: 1, name: 'Hello Record') # => nil

item = MyModel.new
item.id = 2
item.name = 'Item'
item.active = false
item.save

---

Item Operations

You can use item operations on your model class to read and manipulate item(s).

More info under following documentation:

• Item Operations
• Item Operations Class Methods

Example usage

class MyModel
  include Aws::Record
  integer_attr :uuid,   hash_key: true
  string_attr  :name, range_key: true
  integer_attr :age
end

item = MyModel.find(id: 1, name: 'Foo')
item.update(id: 1, name: 'Foo', age: 1)

---

BatchGetItem and BatchWriteItem

Aws Record provides BatchGetItem and BatchWriteItem support for aws-record models.

More info under the following documentation:

• Batch
• BatchWrite
• BatchRead

See examples below to see the feature in action.

BatchGetItem Example

class Lunch
  include Aws::Record
  integer_attr :id,   hash_key: true
  string_attr  :name, range_key: true
end

class Dessert
  include Aws::Record
  integer_attr :id,   hash_key: true
  string_attr  :name, range_key: true
end

# batch operations
operation = Aws::Record::Batch.read do |db|
  db.find(Lunch, id: 1, name: 'Papaya Salad')
  db.find(Lunch, id: 2, name: 'BLT Sandwich')
  db.find(Dessert, id: 1, name: 'Apple Pie')
end

# BatchRead is enumerable and handles pagination
operation.each { |item| item.id }

# Alternatively, BatchRead provides a lower level interface 
# through: execute!, complete? and items.
# Unprocessed items can be processed by calling:
operation.execute! until operation.complete?

BatchWriteItem Example

class Breakfast
  include Aws::Record
  integer_attr :id,   hash_key: true
  string_attr  :name, range_key: true
  string_attr  :body
end

# setup
eggs = Breakfast.new(id: 1, name: 'eggs').save!
waffles = Breakfast.new(id: 2, name: 'waffles')
pancakes = Breakfast.new(id: 3, name: 'pancakes')

# batch operations
operation = Aws::Record::Batch.write(client: Breakfast.dynamodb_client) do |db|
  db.put(waffles)
  db.delete(eggs)
  db.put(pancakes)
end

# unprocessed items can be retried by calling Aws::Record::BatchWrite#execute!
operation.execute! until operation.complete?

---

Transactions

Aws Record provides TransactGetItems and TransactWriteItems support for aws-record models.

More info under the Transactions documentation.

See examples below to see the feature in action.

TransactGetItems Example

class TableOne
  include Aws::Record
  string_attr :uuid, hash_key: true
end

class TableTwo
  include Aws::Record
  string_attr :hk, hash_key: true
  string_attr :rk, range_key: true
end

results = Aws::Record::Transactions.transact_find(
  transact_items: [
    TableOne.tfind_opts(key: { uuid: 'uuid1234' }),
    TableTwo.tfind_opts(key: { hk: 'hk1', rk: 'rk1'}),
    TableTwo.tfind_opts(key: { hk: 'hk2', rk: 'rk2'})
  ]
) # => results.responses contains nil or marshalled items
results.responses.map { |r| r.class } # [TableOne, TableTwo, TableTwo]

TransactWriteItems Example

# same models as `TransactGetItems` Example
check_exp = TableOne.transact_check_expression(
  key: { uuid: 'foo' },
  condition_expression: 'size(#T) <= :v',
  expression_attribute_names: {
    '#T' => 'body'
  },
  expression_attribute_values: {
    ':v' => 1024
  }
)
new_item = TableTwo.new(hk: 'hk1', rk: 'rk1', body: 'Hello!')
update_item_1 = TableOne.find(uuid: 'bar')
update_item_1.body = 'Updated the body!'
put_item = TableOne.new(uuid: 'foobar', body: 'Content!')
update_item_2 = TableTwo.find(hk: 'hk2', rk: 'rk2')
update_item_2.body = 'Update!'
delete_item = TableOne.find(uuid: 'to_be_deleted')

Aws::Record::Transactions.transact_write(
  transact_items: [
    { check: check_exp },
    { save: new_item },
    { save: update_item_1 },
    {
      put: put_item,
      condition_expression: 'attribute_not_exists(#H)',
      expression_attribute_names: { '#H' => 'uuid' },
      return_values_on_condition_check_failure: 'ALL_OLD'
    },
      { update: update_item_2 },
      { delete: delete_item }
  ]
)

---

Inheritance Support

Aws Record models can be extended using standard ruby inheritance. The child model must include Aws::Record in their model and the following will be inherited:

• set_table_name
• Attributes and Keys
• Mutation Tracking:
  • enable_mutation_tracking
  • disable_mutation_tracking
• local_secondary_indexes
• global_secondary_indexes
• configure_client

See example below to see the feature in action.

class Animal
  include Aws::Record
  string_attr :name, hash_key: true
  integer_attr :age
end

class Dog < Animal
  include Aws::Record
  boolean_attr :family_friendly
end

dog = Dog.find(name: 'Sunflower')
dog.age = 3
dog.family_friendly = true