aws record ruby

Official repository for the aws-record gem, an abstraction for Amazon DynamoDB.

aws
321
41
Ruby

Aws::Record

Build Status Code Climate Coverage Status

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

This library is currently under development. More features will be added as we
approach general availability, and while our initial release has as small of an
API surface area as possible, the interface may change before the GA release.

We would like to invite you to be a part of the ongoing development of this gem.
We welcome your contributions, and would also be happy to hear from you about
how you would like to use this gem. Feature requests are welcome.

Table of Contents

Links of Interest

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:

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:

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:

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