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.
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.
To create a model that uses aws-record features, simply include the provided module:
classMyModelincludeAws::RecordendYou can then specify attributes using the aws-record DSL:
classMyModelincludeAws::Recordinteger_attr:id,hash_key: truestring_attr:name,range_key: trueboolean_attr:active,database_attribute_name: 'is_active_flag'endIf a matching table does not exist in DynamoDB, you can use the TableConfig DSL to create your table:
cfg=Aws::Record::TableConfig.definedo |t| t.model_class(MyModel)t.read_capacity_units(5)t.write_capacity_units(2)endcfg.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=trueitem.saveitem.delete!MyModel.find(id: 1,name: 'Hello Record')# => nilitem=MyModel.newitem.id=2item.name='Item'item.active=falseitem.saveYou can use item operations on your model class to read and manipulate item(s).
More info under following documentation:
Example usage
classMyModelincludeAws::Recordinteger_attr:uuid,hash_key: truestring_attr:name,range_key: trueinteger_attr:ageenditem=MyModel.find(id: 1,name: 'Foo')item.update(id: 1,name: 'Foo',age: 1)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
classLunchincludeAws::Recordinteger_attr:id,hash_key: truestring_attr:name,range_key: trueendclassDessertincludeAws::Recordinteger_attr:id,hash_key: truestring_attr:name,range_key: trueend# batch operationsoperation=Aws::Record::Batch.readdo |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 paginationoperation.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!untiloperation.complete?BatchWriteItem Example
classBreakfastincludeAws::Recordinteger_attr:id,hash_key: truestring_attr:name,range_key: truestring_attr:bodyend# setupeggs=Breakfast.new(id: 1,name: 'eggs').save!waffles=Breakfast.new(id: 2,name: 'waffles')pancakes=Breakfast.new(id: 3,name: 'pancakes')# batch operationsoperation=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!untiloperation.complete?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
classTableOneincludeAws::Recordstring_attr:uuid,hash_key: trueendclassTableTwoincludeAws::Recordstring_attr:hk,hash_key: truestring_attr:rk,range_key: trueendresults=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 itemsresults.responses.map{ |r| r.class}# [TableOne, TableTwo, TableTwo]TransactWriteItems Example
# same models as `TransactGetItems` Examplecheck_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}])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:
- local_secondary_indexes
- global_secondary_indexes
- configure_client
See example below to see the feature in action.
classAnimalincludeAws::Recordstring_attr:name,hash_key: trueinteger_attr:ageendclassDog < AnimalincludeAws::Recordboolean_attr:family_friendlyenddog=Dog.find(name: 'Sunflower')dog.age=3dog.family_friendly=true