lotus-dynamodb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8b6e1c051b76f678f3694e0e0cb8f70871a3dbce
+  data.tar.gz: d7e164efdaa51814a36a7c803c959ad9c21c3b71
+SHA512:
+  metadata.gz: 5a326db3a7714f0573be6b4ebadd1dc2ad5dc7fea5303be5c61c09bcfdd37435084215ff60837156f9c4481c044f24af96b8b65d504a9b4e25a3f8f5f6069771
+  data.tar.gz: d1a6068ecc5898cf70ce48ed8b751498ff405fbca62f0a60990f36197d40fe4489e21c0011fff4bd04f215f7642c20763219b624966acaf2578f62be566c308a

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.greenbar
+.ruby-gemset
+.ruby-version
+.fake_dynamo.*

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+before_script: 'bundle exec fake_dynamo -d .fake_dynamo.db -P .fake_dynamo.pid -D'
+script: 'bundle exec rake test:coverage'
+after_script: 'kill `cat .fake_dynamo.pid`'
+rvm:
+  - 2.0.0
+  - 2.1.0
+  - 2.1.1
+  - 2.1.2

data/.yardopts

@@ -0,0 +1,5 @@
+--protected
+--private
+-
+LICENSE.md
+lib/**/*.rb

data/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+gemspec
+
+if !ENV['TRAVIS']
+  gem 'byebug', require: false, platforms: :ruby if RUBY_VERSION == '2.1.2'
+  gem 'yard',   require: false
+end
+
+gem 'simplecov', require: false
+gem 'coveralls', require: false
+
+# Benchmarking
+gem 'benchmark-ips', '~> 1.2'
+
+# Fixes are not merged yet
+gem 'fake_dynamo', github: 'krasnoukhov/fake_dynamo'

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Dmitry Krasnoukhov
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Procfile

@@ -0,0 +1 @@
+fake_dynamo: bundle exec fake_dynamo -l debug -d .fake_dynamo.db

data/README.md

@@ -0,0 +1,112 @@
+# Lotus::Model DynamoDB Adapter
+
+> An adapter is a concrete implementation of persistence logic for a specific
+> database.
+>
+> -- <cite>[jodosha](https://github.com/jodosha), [Lotus::Model](https://github.com/lotus/model)</cite>
+
+This adapter implements persistence layer for a [Amazon DynamoDB](https://aws.amazon.com/dynamodb/),
+and it pretends to be a _really_ sane solution to fully experience DynamoDB advantages with Ruby.
+
+It is built using ```AWS::DynamoDB::Client```, which is a part of ```aws-sdk``` gem and implements latest version of DynamoDB protocol.
+
+## Status
+
+[![Gem Version](https://badge.fury.io/rb/lotus-dynamodb.svg)](http://badge.fury.io/rb/lotus-dynamodb)
+[![Build Status](https://secure.travis-ci.org/krasnoukhov/lotus-dynamodb.svg?branch=master)](http://travis-ci.org/krasnoukhov/lotus-dynamodb?branch=master)
+[![Coverage Status](https://img.shields.io/coveralls/krasnoukhov/lotus-dynamodb.svg)](https://coveralls.io/r/krasnoukhov/lotus-dynamodb?branch=master)
+[![Code Climate](https://img.shields.io/codeclimate/github/krasnoukhov/lotus-dynamodb.svg)](https://codeclimate.com/github/krasnoukhov/lotus-dynamodb)
+[![Inline docs](http://inch-pages.github.io/github/krasnoukhov/lotus-dynamodb.svg)](http://inch-pages.github.io/github/krasnoukhov/lotus-dynamodb)
+[![Dependencies](https://gemnasium.com/krasnoukhov/lotus-dynamodb.svg)](https://gemnasium.com/krasnoukhov/lotus-dynamodb)
+
+## Links
+
+* API Doc: [http://rdoc.info/github/krasnoukhov/lotus-dynamodb](http://rdoc.info/github/krasnoukhov/lotus-dynamodb)
+* Bugs/Issues: [https://github.com/krasnoukhov/lotus-dynamodb/issues](https://github.com/krasnoukhov/lotus-dynamodb/issues)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'lotus-dynamodb'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install lotus-dynamodb
+
+## Usage
+
+Please refer to [Lotus::Model](https://github.com/lotus/model#usage) docs for any details related to Entity, Repository, Data Mapper and Adapter.
+
+### Data types
+
+This adapter supports coercion to all DynamoDB types, including blobs and sets.
+
+List of Ruby types that are supported:
+
+* AWS::DynamoDB::Binary – ```B```
+* Array – ```S``` (via MultiJson)
+* Boolean – ```N``` (1 for true and 0 for false)
+* Date – ```N``` (Integer, seconds since Epoch)
+* DateTime – ```N``` (Float, seconds since Epoch)
+* Float – ```N```
+* Hash – ```S``` (via MultiJson)
+* Integer – ```N```
+* Set – ```SS```, ```NS```, ```BS``` (Set of String, Number or AWS::DynamoDB::Binary)
+* String – ```S```
+* Time – ```N``` (Float, seconds since Epoch)
+
+### Repository methods
+
+See [complete list](https://github.com/lotus/model#repositories) of Repository methods provided by ```Lotus::Model```.
+
+Following methods are not supported since it's incompatible with DynamoDB:
+
+* first
+* last
+
+### Query methods
+
+Generic methods supported by DynamoDB adapter:
+
+* [all](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#all-instance_method)
+* [where](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#where-instance_method) (aliases: ```eq```, ```in```, ```between```)
+* [or](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#or-instance_method)
+* [exclude](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#exclude-instance_method) (aliases: ```not```, ```ne```)
+* [select](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#select-instance_method)
+* [order](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#order-instance_method) (alias: ```asc```)
+* [desc](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#desc-instance_method)
+* [limit](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#limit-instance_method)
+* [exists?](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#exist%3F-instance_method) (alias: ```exist?```)
+* [count](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#count-instance_method)
+
+DynamoDB-specific methods:
+
+* [query](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#query-instance_method) – ensure ```query``` operation is performed instead of ```scan```
+* [consistent](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#consistent-instance_method) – require consistent read for query
+* [index](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#index-instance_method) – perform query on specific index
+* [le](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#le-instance_method)
+* [lt](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#lt-instance_method)
+* [ge](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#ge-instance_method)
+* [gt](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#gt-instance_method)
+* [contains](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#contains-instance_method)
+* [not_contains](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#not_contains-instance_method)
+* [begins_with](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#begins_with-instance_method)
+* [null](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#null-instance_method)
+* [not_null](http://rdoc.info/github/krasnoukhov/lotus-dynamodb/Lotus/Model/Adapters/Dynamodb/Query#not_null-instance_method)
+
+### Example
+
+Check out the simple example in [examples/purchase.rb](examples/purchase.rb).
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,17 @@
+require 'rake'
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+Rake::TestTask.new do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.libs.push 'test'
+end
+
+namespace :test do
+  task :coverage do
+    ENV['COVERAGE'] = 'true'
+    Rake::Task['test'].invoke
+  end
+end
+
+task default: :test

data/benchmarks/coercer.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+
+#
+# Link to original gist: https://gist.github.com/jodosha/17a8bd1a49899753f617
+#
+
+require 'benchmark'
+require 'benchmark/ips'
+require 'lotus/model'
+require 'lotus-dynamodb'
+
+GC.disable
+TIMES = (ENV['TIMES'] || 1_000_000).to_i
+
+class Project
+  include Lotus::Entity
+  self.attributes = :attr1, :attr2, :attr3, :attr4,
+    :attr5, :attr6, :attr7, :attr8, :attr9
+end
+
+default_collection = Lotus::Model::Mapping::Collection.new(:projects, Lotus::Model::Mapping::Coercer) do
+  entity Project
+
+  attribute :id,    Integer
+  attribute :attr1, String
+  attribute :attr2, String
+  attribute :attr3, String
+  attribute :attr4, String
+  attribute :attr5, String
+  attribute :attr6, String
+  attribute :attr7, String
+  attribute :attr8, String
+  attribute :attr9, String
+end
+
+dynamodb_collection = Lotus::Model::Mapping::Collection.new(:projects, Lotus::Model::Adapters::Dynamodb::Coercer) do
+  entity Project
+
+  attribute :id,    Integer
+  attribute :attr1, String
+  attribute :attr2, String
+  attribute :attr3, String
+  attribute :attr4, String
+  attribute :attr5, String
+  attribute :attr6, String
+  attribute :attr7, String
+  attribute :attr8, String
+  attribute :attr9, String
+end
+
+record = Hash[id: '23', attr1: 'attr1', attr2: 'attr2',
+              attr3: 'attr3', attr4: 'attr4', attr5: 'attr5',
+              attr6: 'attr6', attr7: 'attr7', attr8: 'attr8',
+              attr9: 'attr9']
+
+default_collection.load!
+dynamodb_collection.load!
+
+Benchmark.bm(30) do |bm|
+  bm.report 'default' do
+    TIMES.times do
+      default_collection.deserialize([record])
+    end
+  end
+
+  bm.report 'dynamodb' do
+    TIMES.times do
+      dynamodb_collection.deserialize([record])
+    end
+  end
+end
+
+Benchmark.ips do |x|
+  x.report('default') { default_collection.deserialize([record]) }
+  x.report('dynamodb') { dynamodb_collection.deserialize([record]) }
+end

data/examples/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gem 'lotus-dynamodb'

data/examples/purchase.rb

@@ -0,0 +1,164 @@
+require 'bundler'
+Bundler.require(:default)
+
+require 'lotus/model'
+require 'lotus-dynamodb'
+
+AWS.config(
+  use_ssl: false,
+  dynamo_db_endpoint: 'localhost',
+  dynamo_db_port: 4567,
+  access_key_id: '',
+  secret_access_key: '',
+)
+
+#
+# Say, we have a ```purchases``` DynamoDB table
+#
+# This table stores purchases which are split by a ```region``` and sorted by
+# creation time.
+# Local secondary index allows sorting records by subtotal, and global index is
+# used to retrieve specific records by ```uuid``` attribute, even if we don't
+# know a ```region``` of these records.
+#
+
+DB = AWS::DynamoDB::Client.new(api_version: Lotus::Dynamodb::API_VERSION)
+
+begin
+  DB.describe_table("purchases")
+rescue AWS::DynamoDB::Errors::ResourceNotFoundException
+  DB.create_table(
+    table_name: "purchases",
+
+    # List of all attributes which are used as table and indexes keys
+    attribute_definitions: [
+      { attribute_name: "region",       attribute_type: "S" },
+      { attribute_name: "created_at",   attribute_type: "N" },
+      { attribute_name: "subtotal",     attribute_type: "N" },
+      { attribute_name: "uuid",         attribute_type: "S" },
+    ],
+
+    # Key schema of table
+    key_schema: [
+      { attribute_name: "region",       key_type: "HASH" },
+      { attribute_name: "created_at",   key_type: "RANGE" },
+    ],
+
+    # List of local indexes
+    local_secondary_indexes: [{
+      index_name: "by_subtotal",
+      key_schema: [
+        { attribute_name: "region",     key_type: "HASH" },
+        { attribute_name: "subtotal",   key_type: "RANGE" },
+      ],
+      projection: {
+        projection_type: "ALL",
+      },
+    }],
+
+    # List of global indexes
+    global_secondary_indexes: [{
+      index_name: "by_uuid",
+      key_schema: [
+        { attribute_name: "uuid",       key_type: "HASH" },
+      ],
+      projection: {
+        projection_type: "ALL",
+      },
+      provisioned_throughput: {
+        read_capacity_units: 10,
+        write_capacity_units: 10,
+      },
+    }],
+
+    # Capacity
+    provisioned_throughput: {
+      read_capacity_units: 10,
+      write_capacity_units: 10,
+    },
+  )
+end
+
+#
+# Entity
+#
+
+class Purchase
+  include Lotus::Entity
+  self.attributes = :id, :region, :subtotal, :item_ids, :content, :created_at
+end
+
+#
+# Repository
+#
+
+class PurchaseRepository
+  include Lotus::Repository
+
+  class << self
+    def find_by_uuid(uuid)
+      query do
+        index("by_uuid").where(uuid: uuid).limit(1)
+      end.all.first
+    end
+
+    def top_by_subtotal(region, limit)
+      query do
+        index("by_subtotal").where(region: region).desc.limit(limit)
+      end.all
+    end
+  end
+end
+
+#
+# Mapper
+#
+
+coercer = Lotus::Model::Adapters::Dynamodb::Coercer
+mapper = Lotus::Model::Mapper.new(coercer) do
+  collection :purchases do
+    entity Purchase
+
+    attribute :id,         String, as: :uuid
+    attribute :region,     String
+    attribute :subtotal,   Float
+    attribute :item_ids,   Set
+    attribute :content,    AWS::DynamoDB::Binary
+    attribute :created_at, Time
+
+    identity :uuid
+  end
+end.load!
+
+#
+# Adapter
+#
+
+PurchaseRepository.adapter = Lotus::Model::Adapters::DynamodbAdapter.new(mapper)
+
+#
+# Create some data
+#
+
+purchases = [
+  { region: "europe", subtotal: 15.0,  item_ids: [1, 2] },
+  { region: "europe", subtotal: 10.0,  content: "Huge Blob Here" },
+  { region: "usa",    subtotal: 5.0,   item_ids: ["strings", "as", "well"] },
+  { region: "asia",   subtotal: 100.0 },
+].map do |purchase|
+  PurchaseRepository.create(
+    Purchase.new(purchase.merge(created_at: Time.new))
+  )
+end
+
+#
+# Perform queries
+#
+
+puts "Find by UUID"
+puts PurchaseRepository.find_by_uuid(purchases.first.id).inspect
+puts
+
+puts "Top by subtotal"
+puts PurchaseRepository.top_by_subtotal("europe", 50).map(&:inspect)
+puts

data/lib/lotus/dynamodb/config.rb

@@ -0,0 +1,14 @@
+# Lotus namespace
+#
+# @since 0.1.0
+module Lotus
+  # Lotus::Dynamodb namespace
+  #
+  # @since 0.1.0
+  module Dynamodb
+    # Defines the DynamoDB API version
+    #
+    # @since 0.1.0
+    API_VERSION = "2012-08-10"
+  end
+end

data/lib/lotus/dynamodb/version.rb

@@ -0,0 +1,8 @@
+module Lotus
+  module Dynamodb
+    # Defines the version
+    #
+    # @since 0.1.0
+    VERSION = '0.1.0'
+  end
+end