{"id":17508137,"url":"https://github.com/aws/aws-record-ruby","last_synced_at":"2025-05-16T03:05:37.888Z","repository":{"id":34251626,"uuid":"38135511","full_name":"aws/aws-record-ruby","owner":"aws","description":"Official repository for the aws-record gem, an abstraction for Amazon DynamoDB.","archived":false,"fork":false,"pushed_at":"2025-01-16T23:17:21.000Z","size":659,"stargazers_count":322,"open_issues_count":11,"forks_count":41,"subscribers_count":31,"default_branch":"main","last_synced_at":"2025-05-15T16:21:51.692Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-26T21:47:23.000Z","updated_at":"2025-05-11T21:24:28.000Z","dependencies_parsed_at":"2025-01-13T04:04:48.381Z","dependency_job_id":"71f64b0b-b6f9-41aa-8970-7d0f14c333c5","html_url":"https://github.com/aws/aws-record-ruby","commit_stats":{"total_commits":336,"total_committers":23,"mean_commits":"14.608695652173912","dds":0.3035714285714286,"last_synced_commit":"445de8e63f218f95afd53f121d84b2ab1a6b1ca9"},"previous_names":["aws/aws-record-ruby","aws/aws-sdk-ruby-record"],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-record-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-record-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-record-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-record-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/aws-record-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254459088,"owners_count":22074605,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-20T04:01:44.674Z","updated_at":"2025-05-16T03:05:32.879Z","avatar_url":"https://github.com/aws.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Aws::Record\n\n[![Build Status](https://travis-ci.org/aws/aws-sdk-ruby-record.svg?branch=main)](https://travis-ci.org/aws/aws-sdk-ruby-record) [![Code Climate](https://codeclimate.com/github/aws/aws-sdk-ruby-record.svg)](https://codeclimate.com/github/aws/aws-sdk-ruby-record) [![Coverage Status](https://coveralls.io/repos/github/aws/aws-sdk-ruby-record/badge.svg?branch=main)](https://coveralls.io/github/aws/aws-sdk-ruby-record?branch=main)\n\nA data mapping abstraction over the AWS SDK for Ruby's client for Amazon\nDynamoDB.\n\nThis library is currently under development. More features will be added as we\napproach general availability, and while our initial release has as small of an\nAPI surface area as possible, the interface may change before the GA release.\n\nWe would like to invite you to be a part of the ongoing development of this gem.\nWe welcome your contributions, and would also be happy to hear from you about\nhow you would like to use this gem. Feature requests are welcome.\n\n## Table of Contents\n\n* [Installation](https://github.com/aws/aws-sdk-ruby-record#installation)\n* [Usage](https://github.com/aws/aws-sdk-ruby-record#usage)\n  * [Item Operations](https://github.com/aws/aws-sdk-ruby-record#item-operations) \n  * [BatchGetItem / BatchWriteItem](https://github.com/aws/aws-sdk-ruby-record#batchgetitem-and-batchwriteitem)\n  * [Transactions](https://github.com/aws/aws-sdk-ruby-record#transactions)\n  * [Inheritance Support](https://github.com/aws/aws-sdk-ruby-record#inheritance-support)\n\n## Links of Interest\n\n* [Documentation](http://docs.aws.amazon.com/awssdkrubyrecord/api/)\n* [Change Log](https://github.com/aws/aws-sdk-ruby-record/blob/main/CHANGELOG.md)\n* [Issues](https://github.com/aws/aws-sdk-ruby-record/issues)\n* [License](http://aws.amazon.com/apache2.0/)\n\n---\n## Installation\n\n`Aws::Record` is available as the `aws-record` gem from RubyGems.\n\n```shell\ngem install 'aws-record'\n```\n\n```ruby\ngem 'aws-record', '~\u003e 2.0'\n```\n\nThis automatically includes a dependency on the `aws-sdk-dynamodb` gem (part of the modular version-3 of \nthe [AWS SDK for Ruby](https://aws.amazon.com/sdk-for-ruby/). If you need to pin to a specific version, \nyou can add [aws-sdk-dynamodb](https://rubygems.org/gems/aws-sdk-dynamodb) \nor [aws-sdk-core](https://rubygems.org/gems/aws-sdk-core) gem in your\nGemfile.\n\n---\n## Usage\n\nTo create a model that uses `aws-record` features, simply include the provided\nmodule:\n\n```ruby\nclass MyModel\n  include Aws::Record\nend\n```\n\nYou can then specify attributes using the `aws-record` DSL:\n\n```ruby\nclass MyModel\n  include Aws::Record\n  integer_attr :id, hash_key: true\n  string_attr  :name, range_key: true\n  boolean_attr :active, database_attribute_name: 'is_active_flag'\nend\n```\n\nIf a matching table does not exist in DynamoDB, you can use the TableConfig DSL to create your table:\n\n```ruby\ncfg = Aws::Record::TableConfig.define do |t|\n  t.model_class(MyModel)\n  t.read_capacity_units(5)\n  t.write_capacity_units(2)\nend\ncfg.migrate!\n```\n\nWith a table in place, you can then use your model class to manipulate items in\nyour table:\n\n```ruby\nitem = MyModel.find(id: 1, name: 'Hello Record')\nitem.active = true\nitem.save\nitem.delete!\n\nMyModel.find(id: 1, name: 'Hello Record') # =\u003e nil\n\nitem = MyModel.new\nitem.id = 2\nitem.name = 'Item'\nitem.active = false\nitem.save\n```\n---\n### Item Operations\nYou can use item operations on your model class to read and manipulate item(s).\n\nMore info under following documentation:\n* [Item Operations](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/ItemOperations.html)\n* [Item Operations Class Methods](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/ItemOperations/ItemOperationsClassMethods.html)\n\n**Example usage**\n```ruby\nclass MyModel\n  include Aws::Record\n  integer_attr :uuid,   hash_key: true\n  string_attr  :name, range_key: true\n  integer_attr :age\nend\n\nitem = MyModel.find(id: 1, name: 'Foo')\nitem.update(id: 1, name: 'Foo', age: 1)\n```\n\n---\n\n### `BatchGetItem` and `BatchWriteItem`\nAws Record provides [BatchGetItem](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#batch_get_item-instance_method)\nand [BatchWriteItem](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#batch_write_item-instance_method)\nsupport for aws-record models.\n\nMore info under the following documentation:\n\n* [Batch](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/Batch.html)\n* [BatchWrite](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/BatchWrite.html)\n* [BatchRead](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/BatchRead.html)\n\nSee examples below to see the feature in action.\n\n**`BatchGetItem` Example**\n```ruby\nclass Lunch\n  include Aws::Record\n  integer_attr :id,   hash_key: true\n  string_attr  :name, range_key: true\nend\n\nclass Dessert\n  include Aws::Record\n  integer_attr :id,   hash_key: true\n  string_attr  :name, range_key: true\nend\n\n# batch operations\noperation = Aws::Record::Batch.read do |db|\n  db.find(Lunch, id: 1, name: 'Papaya Salad')\n  db.find(Lunch, id: 2, name: 'BLT Sandwich')\n  db.find(Dessert, id: 1, name: 'Apple Pie')\nend\n\n# BatchRead is enumerable and handles pagination\noperation.each { |item| item.id }\n\n# Alternatively, BatchRead provides a lower level interface \n# through: execute!, complete? and items.\n# Unprocessed items can be processed by calling:\noperation.execute! until operation.complete?\n```\n\n**`BatchWriteItem` Example**\n```ruby\nclass Breakfast\n  include Aws::Record\n  integer_attr :id,   hash_key: true\n  string_attr  :name, range_key: true\n  string_attr  :body\nend\n\n# setup\neggs = Breakfast.new(id: 1, name: 'eggs').save!\nwaffles = Breakfast.new(id: 2, name: 'waffles')\npancakes = Breakfast.new(id: 3, name: 'pancakes')\n\n# batch operations\noperation = Aws::Record::Batch.write(client: Breakfast.dynamodb_client) do |db|\n  db.put(waffles)\n  db.delete(eggs)\n  db.put(pancakes)\nend\n\n# unprocessed items can be retried by calling Aws::Record::BatchWrite#execute!\noperation.execute! until operation.complete?\n```\n---\n### Transactions\nAws Record provides [TransactGetItems](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#transact_get_items-instance_method)\nand [TransactWriteItems](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#transact_write_items-instance_method)\nsupport for aws-record models.\n\nMore info under the [Transactions](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/Transactions.html) \ndocumentation.\n\nSee examples below to see the feature in action.\n\n**`TransactGetItems` Example**\n```ruby\nclass TableOne\n  include Aws::Record\n  string_attr :uuid, hash_key: true\nend\n\nclass TableTwo\n  include Aws::Record\n  string_attr :hk, hash_key: true\n  string_attr :rk, range_key: true\nend\n\nresults = Aws::Record::Transactions.transact_find(\n  transact_items: [\n    TableOne.tfind_opts(key: { uuid: 'uuid1234' }),\n    TableTwo.tfind_opts(key: { hk: 'hk1', rk: 'rk1'}),\n    TableTwo.tfind_opts(key: { hk: 'hk2', rk: 'rk2'})\n  ]\n) # =\u003e results.responses contains nil or marshalled items\nresults.responses.map { |r| r.class } # [TableOne, TableTwo, TableTwo]\n```\n\n**`TransactWriteItems` Example**\n```ruby\n# same models as `TransactGetItems` Example\ncheck_exp = TableOne.transact_check_expression(\n  key: { uuid: 'foo' },\n  condition_expression: 'size(#T) \u003c= :v',\n  expression_attribute_names: {\n    '#T' =\u003e 'body'\n  },\n  expression_attribute_values: {\n    ':v' =\u003e 1024\n  }\n)\nnew_item = TableTwo.new(hk: 'hk1', rk: 'rk1', body: 'Hello!')\nupdate_item_1 = TableOne.find(uuid: 'bar')\nupdate_item_1.body = 'Updated the body!'\nput_item = TableOne.new(uuid: 'foobar', body: 'Content!')\nupdate_item_2 = TableTwo.find(hk: 'hk2', rk: 'rk2')\nupdate_item_2.body = 'Update!'\ndelete_item = TableOne.find(uuid: 'to_be_deleted')\n\nAws::Record::Transactions.transact_write(\n  transact_items: [\n    { check: check_exp },\n    { save: new_item },\n    { save: update_item_1 },\n    {\n      put: put_item,\n      condition_expression: 'attribute_not_exists(#H)',\n      expression_attribute_names: { '#H' =\u003e 'uuid' },\n      return_values_on_condition_check_failure: 'ALL_OLD'\n    },\n      { update: update_item_2 },\n      { delete: delete_item }\n  ]\n)\n```\n---\n### Inheritance Support\nAws Record models can be extended using standard ruby inheritance. The child model must \ninclude `Aws::Record` in their model and the following will be inherited:\n\n* [set_table_name](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/RecordClassMethods.html#set_table_name-instance_method)\n* [Attributes and Keys](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/Attributes.html#initialize-instance_method)\n* Mutation Tracking:\n  * [enable_mutation_tracking](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/RecordClassMethods.html#enable_mutation_tracking-instance_method)\n  * [disable_mutation_tracking](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/RecordClassMethods.html#disable_mutation_tracking-instance_method)\n* [local_secondary_indexes](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/SecondaryIndexes/SecondaryIndexesClassMethods.html#local_secondary_indexes-instance_method)\n* [global_secondary_indexes](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/SecondaryIndexes/SecondaryIndexesClassMethods.html#global_secondary_indexes-instance_method)\n* [configure_client](https://docs.aws.amazon.com/sdk-for-ruby/aws-record/api/Aws/Record/ClientConfiguration.html#configure_client-instance_method)\n\nSee example below to see the feature in action.\n\n```ruby\nclass Animal\n  include Aws::Record\n  string_attr :name, hash_key: true\n  integer_attr :age\nend\n\nclass Dog \u003c Animal\n  include Aws::Record\n  boolean_attr :family_friendly\nend\n\ndog = Dog.find(name: 'Sunflower')\ndog.age = 3\ndog.family_friendly = true\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-record-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Faws-record-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-record-ruby/lists"}