dynamodb_model 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7f4086919c79934456c55927f2c127cb983f3f16
+  data.tar.gz: 00da845314f039d065ff7c122c7a7f7d85d33e08
+SHA512:
+  metadata.gz: c47587fa7275602096f3626175abfaf96e8f1c2e538c20558bcee5dc15c69218d92c3dc04c916afad8871a369e0fb1c2a8b84c866e80def1ec316fbffe870be4
+  data.tar.gz: 4b9f9f3754e5d8ec6fd8b6492c40d877fa9d3d4c4b2a310f4addbf677046725c30534a81fc9c78fc57b4c4282db310f77280f483a067eb946c8ba205ecd40d88

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in dynamodb_model.gemspec
+gemspec

data/README.md

@@ -0,0 +1,99 @@
+# DynamodbModel
+
+A simple wrapper library to make DynamoDB usage a little more friendly.  The modeling is ActiveRecord-ish but not exactly because DynamoDB is a different type of database.  Examples and the [item_spec.rb](spec/lib/dynamodb_model/item_spec.rb) explain it best:
+
+## Examples
+
+First define a class:
+
+```ruby
+class Post < DynamodbModel::Item
+  # partition_key "id" # optional, defaults to id
+end
+```
+
+### Create
+
+```ruby
+post = Post.new
+post = post.replace(title: "test title")
+post.attrs # {"id" => "generated-id", title" => "my title"}
+```
+
+`post.attrs[:id]` now contain a generated unique partition_key id.  Usually the partition_key is 'id'. You can set your own unique id also by specifying id.
+
+```ruby
+post = Post.new(id: "myid", title: "my title")
+post.replace
+post.attrs # {"id" => "myid", title" => "my title"}
+```
+
+Note that the replace method replaces the entire item, so you need to merge the attributes if you want to keep the other attributes.  Know this is weird, but this is how DynamoDB works.
+
+### Find
+
+```ruby
+post = Post.find("myid")
+post.attrs = post.attrs.deep_merge("desc": "my desc") # keeps title field
+post.replace
+post.attrs # {"id" => "myid", title" => "my title", desc: "my desc"}
+```
+
+The convenience `attrs` method performs a deep_merge:
+
+```ruby
+post = Post.find("myid")
+post.attrs("desc": "my desc 2") # <= does a deep_merge
+post.replace
+post.attrs # {"id" => "myid", title" => "my title", desc: "my desc 2"}
+```
+
+Note, a race condition edge case can exist when several concurrent replace
+calls are happening.  This is why the interface is called replace to
+emphasis that possibility.
+
+### Delete
+
+```ruby
+resp = Post.delete("myid")
+resp # dynamodb client resp
+```
+
+### Scan
+
+```ruby
+options = {}
+posts = Post.scan(options)
+posts # Array of Post items.  [Post.new, Post.new, ...]
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dynamodb_model'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install dynamodb_model
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/tongueroo/dynamodb_model.
+
+TODO
+
+* implement Post.query
+* implement `post.update` with `db.update_item` in a Ruby-ish way

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "dynamodb_model"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/dynamodb_model.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "dynamodb_model/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "dynamodb_model"
+  spec.version       = DynamodbModel::VERSION
+  spec.authors       = ["Tung Nguyen"]
+  spec.email         = ["tongueroo@gmail.com"]
+
+  spec.summary       = %q{ActiveRecord-ish Dynamodb Model}
+  spec.description   = %q{ActiveRecord-ish Dynamodb Model}
+  spec.homepage      = "https://github.com/tongueroo/dynamodb_model"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport"
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/lib/dynamodb_model.rb

@@ -0,0 +1,9 @@
+$:.unshift(File.expand_path("../", __FILE__))
+require "dynamodb_model/version"
+
+module DynamodbModel
+  autoload :Migration, "dynamodb_model/migration"
+  autoload :Dsl, "dynamodb_model/dsl"
+  autoload :DbConfig, "dynamodb_model/db_config"
+  autoload :Item, "dynamodb_model/item"
+end

data/lib/dynamodb_model/db_config.rb

@@ -0,0 +1,45 @@
+module DynamodbModel::DbConfig
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  def db
+    self.class.db
+  end
+
+  module ClassMethods
+    @@db = nil
+    def db
+      return @@db if @@db
+
+      config = db_config
+      endpoint = ENV['DYNAMODB_ENDPOINT'] || config['endpoint']
+      Aws.config.update(endpoint: endpoint) if endpoint
+
+      @@db ||= Aws::DynamoDB::Client.new
+    end
+
+    # useful for specs
+    def db=(db)
+      @@db = db
+    end
+
+    def db_config
+      if defined?(Jets)
+        YAML.load_file("#{Jets.root}config/dynamodb.yml")[Jets.env] || {}
+      else
+        config_path = ENV['DYNAMODB_MODEL_CONFIG'] || "./config/dynamodb.yml"
+        env = ENV['DYNAMODB_MODEL_ENV'] || "development"
+        YAML.load_file(config_path)[env] || {}
+      end
+    end
+
+    @table_namespace = nil
+    def table_namespace
+      return @table_namespace if @table_namespace
+
+      config = db_config
+      @table_namespace = config['table_namespace']
+    end
+  end
+end

data/lib/dynamodb_model/item.rb

@@ -0,0 +1,207 @@
+require "active_support/core_ext/hash"
+require "aws-sdk-dynamodb"
+require "digest"
+require "yaml"
+
+# The modeling is ActiveRecord-ish but not exactly because DynamoDB is a
+# different type of database.
+#
+# Examples:
+#
+#   post = Post.new
+#   post = post.replace(title: "test title")
+#
+# post.attrs[:id] now contain a generaetd unique partition_key id.
+# Usually the partition_key is 'id'. You can set your own unique id also:
+#
+#   post = Post.new(id: "myid", title: "my title")
+#   post.replace
+#
+# Note that the replace method replaces the entire item, so you
+# need to merge the attributes if you want to keep the other attributes.
+#
+#   post = Post.find("myid")
+#   post.attrs = post.attrs.deep_merge("desc": "my desc") # keeps title field
+#   post.replace
+#
+# The convenience `attrs` method performs a deep_merge:
+#
+#   post = Post.find("myid")
+#   post.attrs("desc": "my desc") # <= does a deep_merge
+#   post.replace
+#
+# Note, a race condition edge case can exist when several concurrent replace
+# calls are happening.  This is why the interface is called replace to
+# emphasis that possibility.
+# TODO: implement post.update with db.update_item in a Ruby-ish way.
+#
+module DynamodbModel
+  class Item
+    include DbConfig
+
+    def initialize(attrs={})
+      @attrs = attrs
+    end
+
+    # Defining our own reader so we can do a deep merge if user passes in attrs
+    def attrs(*args)
+      case args.size
+      when 0
+        ActiveSupport::HashWithIndifferentAccess.new(@attrs)
+      when 1
+        attributes = args[0] # Hash
+        if attributes.empty?
+          ActiveSupport::HashWithIndifferentAccess.new
+        else
+          @attrs = attrs.deep_merge!(attributes)
+        end
+      end
+    end
+
+    # Not using method_missing to allow usage of dot notation and assign
+    # @attrs because it might hide actual missing methods errors.
+    # DynamoDB attrs can go many levels deep so it makes less make sense to
+    # use to dot notation.
+
+    # The method is named replace to clearly indicate that the item is
+    # fully replaced.
+    def replace
+      attrs = self.class.replace(@attrs)
+      @attrs = attrs # refresh attrs because it now has the id
+    end
+
+    def find(id)
+      self.class.find(id)
+    end
+
+    def table_name
+      self.class.table_name
+    end
+
+    def partition_key
+      self.class.partition_key
+    end
+
+    def to_attrs
+      @attrs
+    end
+
+    # Longer hand methods for completeness.
+    # Internallly encourage the shorter attrs method.
+    def attributes=(attributes)
+      @attributes = attributes
+    end
+
+    def attributes
+      @attributes
+    end
+
+    # AWS Docs examples: http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStarted.Ruby.04.html
+    # Usage:
+    #
+    #   Post.scan(
+    #     expression_attribute_names: {"#updated_at"=>"updated_at"},
+    #     filter_expression: "#updated_at between :start_time and :end_time",
+    #     expression_attribute_values: {
+    #       ":start_time" => "2010-01-01T00:00:00",
+    #       ":end_time" => "2020-01-01T00:00:00"
+    #     }
+    #   )
+    #
+    # TODO: pretty lame interface, improve it somehow. Maybe:
+    #
+    #   Post.scan(filter: "updated_at between :start_time and :end_time")
+    #
+    # which automatically maps the structure.
+    def self.scan(params={})
+      puts("Should not use scan for production. It's slow and expensive. You should create either a LSI or GSI and use query the index instead.")
+
+      defaults = {
+        table_name: table_name
+      }
+      params = defaults.merge(params)
+      resp = db.scan(params)
+      resp.items.map {|i| Post.new(i) }
+    end
+
+    def self.replace(attrs)
+      # Automatically adds some attributes:
+      #   partition key unique id
+      #   created_at and updated_at timestamps. Timestamp format from AWS docs: http://amzn.to/2z98Bdc
+      defaults = {
+        partition_key => Digest::SHA1.hexdigest([Time.now, rand].join)
+      }
+      item = defaults.merge(attrs)
+      item["created_at"] ||= Time.now.utc.strftime('%Y-%m-%dT%TZ')
+      item["updated_at"] = Time.now.utc.strftime('%Y-%m-%dT%TZ')
+
+      # put_item full replaces the item
+      resp = db.put_item(
+        table_name: table_name,
+        item: item
+      )
+
+      # The resp does not contain the attrs. So might as well return
+      # the original item with the generated partition_key value
+      item
+    end
+
+    def self.find(id)
+      resp = db.get_item(
+        table_name: table_name,
+        key: {partition_key => id}
+      )
+      attributes = resp.item # unwraps the item's attributes
+      Post.new(attributes) if attributes
+    end
+
+    # Two ways to use the delete method:
+    #
+    # 1. Specify the key as a String. In this case the key will is the partition_key
+    # set on the model.
+    #   MyModel.delete("728e7b5df40b93c3ea6407da8ac3e520e00d7351")
+    #
+    # 2. Specify the key as a Hash, you can arbitrarily specific the key structure this way
+    # MyModel.delete("728e7b5df40b93c3ea6407da8ac3e520e00d7351")
+    #
+    # options is provided in case you want to specific condition_expression or
+    # expression_attribute_values.
+    def self.delete(key_object, options={})
+      if key_object.is_a?(String)
+        key = {
+          partition_key => key_object
+        }
+      else # it should be a Hash
+        key = key_object
+      end
+
+      params = {
+        table_name: table_name,
+        key: key
+      }
+      # In case you want to specify condition_expression or expression_attribute_values
+      params = params.merge(options)
+
+      resp = db.delete_item(params)
+    end
+
+    # When called with an argument we'll set the internal @partition_key value
+    # When called without an argument just retun it.
+    # class Comment < DynamodbModel::Item
+    #   partition_key "post_id"
+    # end
+    def self.partition_key(*args)
+      case args.size
+      when 0
+        @partition_key || "id" # defaults to id
+      when 1
+        @partition_key = args[0].to_s
+      end
+    end
+
+    def self.table_name
+      @table_name = self.name.pluralize.underscore
+      [table_namespace, @table_name].reject {|s| s.nil? || s.empty?}.join('-')
+    end
+  end
+end

data/lib/dynamodb_model/migration.rb

@@ -0,0 +1,17 @@
+module DynamodbModel
+  class Migration
+    autoload :Dsl, "dynamodb_model/migration/dsl"
+
+    class << self
+      def up
+        puts "Running up migration for #{self.class.name}"
+      end
+
+      def create_table(table_name)
+        dsl = Dsl.new(table_name)
+        yield(dsl)
+        dsl.execute
+      end
+    end
+  end
+end

data/lib/dynamodb_model/migration/dsl.rb

@@ -0,0 +1,112 @@
+class DynamodbModel::Migration
+  class Dsl
+    include DynamodbModel::DbConfig
+
+    ATTRIBUTE_TYPE_MAP = {
+      'string' => 'S',
+      'number' => 'N',
+      'binary' => 'B',
+      's' => 'S',
+      'n' => 'N',
+      'b' => 'B',
+    }
+
+    attr_accessor :key_schema, :attribute_definitions
+    # db is the dynamodb client
+    def initialize(table_name)
+      @table_name = table_name
+      @key_schema = []
+      @attribute_definitions = []
+      @provisioned_throughput = {
+        read_capacity_units: 10,
+        write_capacity_units: 10
+      }
+    end
+
+    # http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Types/KeySchemaElement.html
+    # partition_key is required
+    def partition_key(identifier)
+      adjust_schema_and_attributes(identifier, "hash")
+    end
+
+    # sort_key is optional
+    def sort_key(identifier)
+      adjust_schema_and_attributes(identifier, "range")
+    end
+
+    # Parameters:
+    #   identifier: "id:string" or "id"
+    #   key_type: "hash" or "range"
+    #
+    # Adjusts the parameters for create_table to add the
+    # partition_key and sort_key
+    def adjust_schema_and_attributes(identifier, key_type)
+      name, attribute_type = identifier.split(':')
+      attribute_type = "string" if attribute_type.nil?
+
+      partition_key = {
+        attribute_name: name,
+        key_type: key_type.upcase
+      }
+      @key_schema << partition_key
+
+      attribute_definition = {
+        attribute_name: name,
+        attribute_type: ATTRIBUTE_TYPE_MAP[attribute_type]
+      }
+      @attribute_definitions << attribute_definition
+    end
+
+    # t.provisioned_throughput(5) # both
+    # t.provisioned_throughput(:read, 5)
+    # t.provisioned_throughput(:write, 5)
+    # t.provisioned_throughput(:both, 5)
+    def provisioned_throughput(*params)
+      case params.size
+      when 2
+        capacity_type, capacity_units = params
+      when 1
+        arg = params[0]
+        if arg.is_a?(Hash)
+          @provisioned_throughput = arg # set directly
+          return
+        else # assume parameter is an Integer
+          capacity_type = :both
+          capacity_units = arg
+        end
+      when 0 # reader method
+        return @provisioned_throughput
+      end
+
+      map = {
+        read: :read_capacity_units,
+        write: :write_capacity_units,
+      }
+
+      if capacity_type = :both
+        @provisioned_throughput[map[:read]] = capacity_units
+        @provisioned_throughput[map[:write]] = capacity_units
+      else
+        @provisioned_throughput[capacity_type] = capacity_units
+      end
+    end
+
+    def execute
+      params = {
+        table_name: @table_ame,
+        key_schema: @key_schema,
+        attribute_definitions: @attribute_definitions,
+        provisioned_throughput: @provisioned_throughput
+      }
+      begin
+        result = db.create_table(params)
+
+        puts 'DynamoDB Table: proj-posts Status: ' +
+              result.table_description.table_status;
+      rescue Aws::DynamoDB::Errors::ServiceError => error
+        puts 'Unable to create table:'
+        puts error.message
+      end
+    end
+  end
+end

data/lib/dynamodb_model/version.rb

@@ -0,0 +1,3 @@
+module DynamodbModel
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: dynamodb_model
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tung Nguyen
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-11-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ActiveRecord-ish Dynamodb Model
+email:
+- tongueroo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- dynamodb_model.gemspec
+- lib/dynamodb_model.rb
+- lib/dynamodb_model/db_config.rb
+- lib/dynamodb_model/item.rb
+- lib/dynamodb_model/migration.rb
+- lib/dynamodb_model/migration/dsl.rb
+- lib/dynamodb_model/version.rb
+homepage: https://github.com/tongueroo/dynamodb_model
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.14
+signing_key: 
+specification_version: 4
+summary: ActiveRecord-ish Dynamodb Model
+test_files: []