dynamoid 1.3.4 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 563c512230d5a7f2485b6cf226eff77accfa2a3e
-  data.tar.gz: e2f88e774032ddf472bc81a2b9e2a5844b61933a
+  metadata.gz: 542fc1c696af080fcd65a7428ec553584d3fe48d
+  data.tar.gz: 93cca063db742ea205238443dcf98ab8e03ba627
 SHA512:
-  metadata.gz: 4a9dba2ea759a74d83f27ef984e3ca963230ddebde577084e89324eb69dd08c65c4c19690891e4086bc9cacadb17eaed5c460c03944dcc9db1eb109044ceef91
-  data.tar.gz: 314ffb14350619c950bd6615d46ccb3ca32383116f1a1dfe0aa39891694575e89d3376051bfac53b4e4a0f584257c0315a334365e5715727bcc767a31c2daa5e
+  metadata.gz: 438f005ef464d1f90f8e6ba57b3c1b2969e183828e2ad35dcb9fd5db00dea9bc394684ad1787c4c61c6ad23f8a879a933b8a18be3254fc730bc74c1d39b574e9
+  data.tar.gz: 905e8db4276d80e280fd95fb56902da845a0aa0eb496c4251d67deff3200436a83fada31f23af341fe490e4576956c9db7e5f9137d58ac53f68e7505addae7d1

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.gitignore

@@ -69,3 +69,6 @@ Gemfile.lock
 
 # For vagrant
 .vagrant
+
+# For Appraisals
+gemfiles/*.gemfile.lock

data/.travis.yml

@@ -1,3 +1,5 @@
+sudo: required
+
 language: ruby
 rvm:
   - ruby-2.0.0-p648
@@ -6,26 +8,54 @@ rvm:
   - ruby-2.3.4
   - ruby-2.4.1
   - jruby-9.1.9.0
+gemfile:
 gemfile:
   - gemfiles/rails_4_0.gemfile
   - gemfiles/rails_4_1.gemfile
   - gemfiles/rails_4_2.gemfile
   - gemfiles/rails_5_0.gemfile
+  - gemfiles/rails_5_1.gemfile
+  - gemfiles/rails_5_2.gemfile
 matrix:
   exclude:
     - rvm: ruby-2.0.0-p648
       gemfile: gemfiles/rails_5_0.gemfile
+    - rvm: ruby-2.0.0-p648
+      gemfile: gemfiles/rails_5_1.gemfile
+    - rvm: ruby-2.0.0-p648
+      gemfile: gemfiles/rails_5_2.gemfile
     - rvm: ruby-2.1.10
       gemfile: gemfiles/rails_5_0.gemfile
+    - rvm: ruby-2.1.10
+      gemfile: gemfiles/rails_5_1.gemfile
+    - rvm: ruby-2.1.10
+      gemfile: gemfiles/rails_5_2.gemfile
     - rvm: ruby-2.4.1
       gemfile: gemfiles/rails_4_0.gemfile
     - rvm: ruby-2.4.1
       gemfile: gemfiles/rails_4_1.gemfile
-before_install: gem install bundler -v 1.15.4
-install:
-  - wget http://dynamodb-local.s3-website-us-west-2.amazonaws.com/dynamodb_local_latest.zip --quiet -O spec/dynamodb_temp.zip
-  - unzip -qq spec/dynamodb_temp.zip -d spec/DynamoDBLocal-latest
-  - rm spec/dynamodb_temp.zip
-script:
+
+### BUILD LIFECYCLE STEPS ###
+
+before_install:
+  # Debugging: Print out the current docker-compose version.
+  - docker-compose --version
+
+  # If one of your containers does not build for
+  # whatever reason it's best to report that now before your tests start
+  # otherwise it can be really tricky to debug why tests are failing sometimes.
+  - docker ps
+
+after_install:
+  - gem install bundler -v 1.15.4
   - bundle install
-  - bundle exec rake unattended_spec
+
+before_script:
+  # Start Docker Compose as a daemon
+  - docker-compose up -d
+
+script:
+  - bundle exec rake spec
+
+after_script:
+  - docker-compose down

data/Appraisals

@@ -1,15 +1,26 @@
 appraise "rails-4-0" do
   gem "rails", "~> 4.0.0"
+  gem "nokogiri", "~> 1.6.8" # can be removed once we drop support for Ruby 2.0.0
 end
 
 appraise "rails-4-1" do
   gem "rails", "~> 4.1.0"
+  gem "nokogiri", "~> 1.6.8" # can be removed once we drop support for Ruby 2.0.0
 end
 
 appraise "rails-4-2" do
   gem "rails", "~> 4.2.0"
+  gem "nokogiri", "~> 1.6.8" # can be removed once we drop support for Ruby 2.0.0
 end
 
 appraise "rails-5-0" do
   gem "rails", "~> 5.0.0"
 end
+
+appraise "rails-5-1" do
+  gem "rails", "~> 5.1.0"
+end
+
+appraise "rails-5-2" do
+  gem "rails", "~> 5.2.0"
+end

data/CHANGELOG.md

@@ -1,8 +1,121 @@
 # HEAD
 
+## Breaking
+
+* N/A
+
+## Improvements
+
+* N/A
+
+## Fixes
+
+* N/A
+
+# 2.2.0
+
+## Breaking
+
+* N/A
+
+## Improvements
+
+* Feature: [#256](https://github.com/Dynamoid/Dynamoid/pull/256) Support Rails 5.2 (@andrykonchin)
+
+## Fixes
+
+* Bug: [#255](https://github.com/Dynamoid/Dynamoid/pull/255) Fix Vagrant RVM configuration and upgrade to Ruby 2.4.1 (@richardhsu)
+
+# 2.1.0
+
+## Breaking
+
+* N/A
+
+## Improvements
+
+* Feature: [#221](https://github.com/Dynamoid/Dynamoid/pull/221) Add field declaration option `of` to specify the type of `set` elements (@pratik60)
+* Feature: [#223](https://github.com/Dynamoid/Dynamoid/pull/223) Add field declaration option `store_as_string` to store `datetime` as ISO-8601 formatted strings (@william101)
+* Feature: [#228](https://github.com/Dynamoid/Dynamoid/pull/228) Add field declaration option `store_as_string` to store `date` as ISO-8601 formatted strings (@andrykonchin)
+* Feature: [#229](https://github.com/Dynamoid/Dynamoid/pull/229) Support hash argument for `start` chain method (@mnussbaumer)
+* Feature: [#236](https://github.com/Dynamoid/Dynamoid/pull/236) Change log level from `info` to `debug` for benchmark logging (@kicktheken)
+* Feature: [#239](https://github.com/Dynamoid/Dynamoid/pull/239) Add methods for low-level updating: `.update`, `.update_fields` and `.upsert` (@andrykonchin)
+* Feature: [#243](https://github.com/Dynamoid/Dynamoid/pull/243) Support `ne` condition operator (@andrykonchin)
+* Feature: [#246](https://github.com/Dynamoid/Dynamoid/pull/246) Added support of backoff in batch operations (@andrykonchin)
+    * added global config options `backoff` and `backoff_strategies` to configure backoff
+    * added `constant` and `exponential` built-in backoff strategies
+    * `.find_all` and `.import` support new backoff options
+
+## Fixes
+
+* Bug: [#216](https://github.com/Dynamoid/Dynamoid/pull/216) Fix global index detection in queries with conditions other than equal (@andrykonchin)
+* Bug: [#224](https://github.com/Dynamoid/Dynamoid/pull/224) Fix how `contains` operator works with `set` and `array` field types (@andrykonchin)
+* Bug: [#225](https://github.com/Dynamoid/Dynamoid/pull/225) Fix equal conditions for `array` fields (@andrykonchin)
+* Bug: [#229](https://github.com/Dynamoid/Dynamoid/pull/229) Repair support `start` chain method on Scan operation (@mnussbaumer)
+* Bug: [#238](https://github.com/Dynamoid/Dynamoid/pull/238) Fix default value of `models_dir` config option (@baloran)
+* Bug: [#244](https://github.com/Dynamoid/Dynamoid/pull/244) Allow to pass empty strings and sets to `.import` (@andrykonchin)
+* Bug: [#246](https://github.com/Dynamoid/Dynamoid/pull/246) Batch operations (`batch_write_item` and `batch_read_item`) handle unprocessed items themselves (@andrykonchin)
+* Bug: [#250](https://github.com/Dynamoid/Dynamoid/pull/250) Update outdated warning message about inefficient query and missing indices (@andrykonchin)
+* Bug: [252](https://github.com/Dynamoid/Dynamoid/pull/252) Don't loose nanoseconds when store DateTime as float number
+
+# 2.0.0
+
+## Breaking
+
+Breaking changes in this release generally bring Dynamoid behavior closer to the Rails-way.
+
+* Change: [#186](https://github.com/Dynamoid/Dynamoid/pull/186) Consistent behavior for `Model.where({}).all` (@andrykonchin)
+    * <= 1.3.x behaviour -
+        * load lazily if user specified batch size
+        * load all collection into memory otherwise
+    * New behaviour -
+        * always return lazy evaluated collection
+        * It means Model.where({}).all returns Enumerator instead of Array.
+        * If you need Array interface you have to convert collection to Array manually with to_a method call
+* Change: [#195](https://github.com/Dynamoid/Dynamoid/pull/195) Failed `#find` returns error (@andrykonchin)
+    * <= 1.3.x behaviour - find returns nil or smaller array.
+    * New behaviour - it raises RecordNotFound if one or more records can not be found for the requested ids
+* Change: [#196](https://github.com/Dynamoid/Dynamoid/pull/196) Return value of `#save` (@andrykonchin)
+    * <= 1.3.x behaviour - save returns self if model is saved successfully
+    * New behaviour - it returns true
+
+## Improvements
+
+* Feature: [#185](https://github.com/Dynamoid/Dynamoid/pull/185) `where`, finders and friends take into account STI (single table inheritance) now (@andrykonchin)
+    * query will return items of the model class and all subclasses
+* Feature: [#190](https://github.com/Dynamoid/Dynamoid/pull/190) Allow passing options to range when defining attributes of the document (@richardhsu)
+    * Allows for serialized fields and passing the serializer option.
+* Feature: [#198](https://github.com/Dynamoid/Dynamoid/pull/198) Enhanced `#create` and `#create!` to allow multiple document creation like `#import` (@andrykonchin)
+    * `User.create([{name: 'Josh'}, {name: 'Nick'}])`
+* Feature: [#199](https://github.com/Dynamoid/Dynamoid/pull/199) Added `Document.import` method (@andrykonchin)
+* Feature: [#205](https://github.com/Dynamoid/Dynamoid/pull/205) Use batch deletion via `batch_write_item` for `delete_all` (@andrykonchin)
+* Rename: [#205](https://github.com/Dynamoid/Dynamoid/pull/205) `Chain#destroy_all` as `Chain#delete_all`, to better match Rails conventions when no callbacks are run (@andrykonchin)
+    * kept the old name as an alias, for backwards compatibility
+* Feature: [#207](https://github.com/Dynamoid/Dynamoid/pull/207) Added slicing by 25 requests in #batch_write_item (@andrykonchin)
+* Feature: [#211](https://github.com/Dynamoid/Dynamoid/pull/211) Improved Vagrant setup for testing (@richardhsu)
+* Feature: [#212](https://github.com/Dynamoid/Dynamoid/pull/212) Add foreign_key option (@andrykonchin)
+* Feature: [#213](https://github.com/Dynamoid/Dynamoid/pull/213) Support Boolean raw type (@andrykonchin)
+* Improved Documentation (@pboling, @andrykonchin)
+
+## Fixes
+
+* Bug: [#191](https://github.com/Dynamoid/Dynamoid/pull/191), [#192](https://github.com/Dynamoid/Dynamoid/pull/192) Support lambdas as fix for value types were not able to be used as default values (@andrykonchin)(@richardhsu)
+* Bug: [#202](https://github.com/Dynamoid/Dynamoid/pull/202) Fix several issues with associations (@andrykonchin)
+    * setting `nil` value raises an exception
+    * document doesn't keep assigned model and loads it from the storage
+    * delete call doesn't update cached ids of associated models
+    * fix clearing old `has_many` association while add model to new `has_many` association
+* Bug: [#204](https://github.com/Dynamoid/Dynamoid/pull/204) Fixed issue where `Document.where(:"id.in" => [])` would do `Query` operation instead of `Scan` (@andrykonchin)
+    * Fixed `Chain#key_present?`
+* Bug: [#205](https://github.com/Dynamoid/Dynamoid/pull/205) Fixed `delete_all` (@andrykonchin)
+    * Fixed exception when makes scan and sort key is declared in model
+    * Fixed exception when makes scan and any condition is specified in where clause (like Document.where().delete_all)
+    * Fixed exception when makes query and sort key isn't declared in model
+* Bug: [#207](https://github.com/Dynamoid/Dynamoid/pull/207) Fixed `#delete` method for case `adapter.delete(table_name, [1, 2, 3], range_key: 1)` (@andrykonchin)
+
 # 1.3.4
 
-Improving
+## Improvements
 
 * Added `Chain#last` method (@andrykonchin)
 * Added `date` field type (@andrykonchin)
@@ -19,7 +132,7 @@ Improving
 * Support querying Global/Local Secondary Indices in `where` clause (@richardhsu)
 * Only query on GSI if projects all attributes in `where` clause (@richardhsu)
 
-Fixes
+## Fixes
 
 * Fix incorrect applying of default field value (#36 and #117, @andrykonchin)
 * Fix sync table creation/deletion (#160, @mirokuxy)

data/Gemfile

@@ -2,3 +2,5 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in dynamoid.gemspec
 gemspec
+
+gem "pry-byebug", platforms: :ruby

data/LICENSE.txt

@@ -1,20 +1,22 @@
+MIT License
+
 Copyright (c) 2012 Josh Symonds
+Copyright (c) 2013 - 2018 Dynamoid, https://github.com/Dynamoid
 
-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:
+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 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.
+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/README.md

@@ -1,5 +1,9 @@
 # Dynamoid
 
+You are viewing the README for version 2 of Dynamoid.  See the [CHANGELOG](https://github.com/Dynamoid/Dynamoid/blob/master/CHANGELOG.md#200) for details on breaking changes since 1.3.x.
+
+For version 1.3.x use the [1-3-stable branch](https://github.com/Dynamoid/Dynamoid/blob/1-3-stable/README.md).
+
 Dynamoid is an ORM for Amazon's DynamoDB for Ruby applications. It
 provides similar functionality to ActiveRecord and improves on
 Amazon's existing
@@ -10,21 +14,31 @@ DynamoDB is not like other document-based databases you might know, and is very
 
 But if you want a fast, scalable, simple, easy-to-use database (and a Gem that supports it) then look no further!
 
-## Call For Maintainers
 
-Please inquire within.
-https://github.com/Dynamoid/Dynamoid/issues/125
+| Project                 |  Dynamoid         |
+|------------------------ | ----------------- |
+| gem name                |  dynamoid         |
+| license                 |  MIT              |
+| download rank           |  [![Total Downloads](https://img.shields.io/gem/rt/Dynamoid.svg)](https://rubygems.org/gems/dynamoid) |
+| version                 |  [![Gem Version](https://badge.fury.io/rb/dynamoid.svg)](https://rubygems.org/gems/dynamoid) |
+| dependencies            |  [![Dependency Status](https://gemnasium.com/badges/github.com/Dynamoid/Dynamoid.svg)](https://gemnasium.com/github.com/Dynamoid/Dynamoid) [![Depfu](https://badges.depfu.com/badges/6661c063c8e77a5008344fc7283a50aa/status.svg)](https://depfu.com)|
+| code quality            |  [![Code Climate](https://codeclimate.com/github/Dynamoid/Dynamoid.svg)](https://codeclimate.com/github/Dynamoid/Dynamoid) |
+| continuous integration  |  [![Build Status](https://travis-ci.org/Dynamoid/Dynamoid.svg?branch=master)](https://travis-ci.org/Dynamoid/Dynamoid) |
+| test coverage           |  [![Coverage Status](https://coveralls.io/repos/github/Dynamoid/Dynamoid/badge.svg?branch=master)](https://coveralls.io/github/Dynamoid/Dynamoid?branch=master) |
+| triage helpers          |  [![CodeTriage Helpers](https://www.codetriage.com/dynamoid/dynamoid/badges/users.svg)](https://www.codetriage.com/dynamoid/dynamoid) |
+| homepage                |  [https://github.com/Dynamoid/Dynamoid](https://github.com/Dynamoid/Dynamoid) |
+| documentation           |  [http://rdoc.info/github/Dynamoid/Dynamoid/frames](http://rdoc.info/github/Dynamoid/Dynamoid/frames) |
 
 ## Installation
 
 Installing Dynamoid is pretty simple. First include the Gem in your Gemfile:
 
 ```ruby
-gem 'dynamoid', '~> 1'
+gem 'dynamoid', '~> 2'
 ```
 ## Prerequisities
 
-Dynamoid depends on the aws-sdk, and this is tested on the current version of aws-sdk (~> 2), rails (~> 4).
+Dynamoid depends on the aws-sdk, and this is tested on the current version of aws-sdk (~> 2), rails (>= 4).
 Hence the configuration as needed for aws to work will be dealt with by aws setup.
 
 Here are the steps to setup aws-sdk.
@@ -35,7 +49,18 @@ gem 'aws-sdk', '~>2'
 
 (or) include the aws-sdk in your Gemfile.
 
-**NOTE:** Dynamoid-1.0 doesn't support aws-sdk Version 1 (Use Dynamoid Major Version 0 for aws-sdk 1)
+### AWS SDK Version Compatibility
+
+Make sure you are using the version for the right AWS SDK.
+
+| Dynamoid version | AWS SDK Version |
+| ---------------- | --------------- |
+| 0.x              | 1.x             |
+| 1.x              | 2.x             |
+| 2.x              | 2.x             |
+| 3.x (unreleased) | 3.x             |
+
+### AWS Configuration
 
 Configure AWS access:
 [Reference](https://github.com/aws/aws-sdk-ruby)
@@ -56,6 +81,7 @@ Create config/initializers/aws.rb as follows:
 Alternatively, if you don't want Aws connection settings to be overwritten for you entire project, you can specify connection settings for Dynamoid only, by setting those in the `Dynamoid.configure` clause:
 
 ```ruby
+  require 'dynamoid'
   Dynamoid.configure do |config|
     config.access_key = 'REPLACE_WITH_ACCESS_KEY_ID'
     config.secret_key = 'REPLACE_WITH_SECRET_ACCESS_KEY'
@@ -69,6 +95,7 @@ For a full list of the DDB regions, you can go
 Then you need to initialize Dynamoid config to get it going. Put code similar to this somewhere (a Rails initializer would be a great place for this if you're using Rails):
 
 ```ruby
+  require 'dynamoid'
   Dynamoid.configure do |config|
     config.namespace = "dynamoid_app_development" # To namespace tables created by Dynamoid from other tables you might have. Set to nil to avoid namespacing.
     config.endpoint = 'http://localhost:3000' # [Optional]. If provided, it communicates with the DB listening at the endpoint. This is useful for testing with [Amazon Local DB] (http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Tools.DynamoDBLocal.html).
@@ -76,7 +103,7 @@ Then you need to initialize Dynamoid config to get it going. Put code similar to
 
 ```
 
-### Compatibility Matrix
+### Ruby  & Rails Compatibility Matrix
 
 | Ruby / Active Record  | 4.0.x | 4.1.x | 4.2.x | 5.0.x |
 |:---------------------:|:-----:|:-----:|:-----:|:-----:|
@@ -124,6 +151,61 @@ By default, fields are assumed to be of type ```:string```. Other built-in types
 If built-in types do not suit you, you can use a custom field type represented by an arbitrary class, provided that the class supports a compatible serialization interface.
 The primary use case for using a custom field type is to represent your business logic with high-level types, while ensuring portability or backward-compatibility of the serialized representation.
 
+#### Note on boolean type
+
+The boolean fields are stored as `"t", "f"` strings by default. DynamoDB
+supports boolean type natively. So if you want to use native boolean
+type or already have table with native boolean attribute you can easily
+achieve this with `store_as_native_boolean` option:
+
+```ruby
+class Document
+  include DynamoId::Document
+
+  field :active, :boolean, store_as_native_boolean: true
+end
+```
+
+#### Note on date type
+
+By default date fields are persisted as days count since 1 January 1970 like UNIX time. If you prefer dates to be stored as ISO-8601 formatted strings instead then set `store_as_string` to `true`
+
+```ruby
+class Document
+  include DynamoId::Document
+
+  field :sent_at, :datetime, store_as_string: true
+end
+```
+
+#### Note on datetime type
+
+By default datetime fields are persisted as UNIX timestamps with milisecond precission in DynamoDB. If you prefer datetimes to be stored as ISO-8601 formatted strings instead then set `store_as_string` to `true`
+
+```ruby
+class Document
+  include DynamoId::Document
+
+  field :sent_at, :datetime, store_as_string: true
+end
+```
+
+### Note on set type
+
+There is `of` option to declare the type of set elements. You can use
+`:integer` value only
+
+```ruby
+class Document
+  include DynamoId::Document
+
+  field :tags, :set, of: :integer
+end
+```
+
+
+#### Magic Columns
+
 You get magic columns of id (string), created_at (datetime), and updated_at (datetime) for free.
 
 ```ruby
@@ -140,6 +222,8 @@ class User
 end
 ```
 
+#### Default Values
+
 You can optionally set a default value on a field using either a plain value or a lambda:
 
 ```ruby
@@ -147,6 +231,8 @@ You can optionally set a default value on a field using either a plain value or
   field :joined_at, :datetime, {default: ->(){Time.now}}
 ```
 
+#### Custom Types
+
 To use a custom type for a field, suppose you have a `Money` type.
 
 ```ruby
@@ -159,7 +245,7 @@ To use a custom type for a field, suppose you have a `Money` type.
 
     def self.dynamoid_load(serialized_str)
       # parse serialized representation and return a Money instance
-      Money.new(...)
+      Money.new(1.23)
     end
   end
 
@@ -181,7 +267,7 @@ add a level of indirection for serializing.)  Example:
 
   class MoneyAdapter
     def self.dynamoid_load(money_serialized_str)
-      Money.new(...)
+      Money.new(1.23)
     end
 
     def self.dynamoid_dump(money_obj)
@@ -201,8 +287,8 @@ This is especially important if you want to use your custom field as a numeric r
 number-oriented queries.  By default custom fields are persisted as a string attribute, but
 your custom class can override this with a `.dynamoid_field_type` class method, which would
 return either `:string` or `:number`.
-(DynamoDB supports some other attribute types, but Dynamoid does not yet.)
 
+DynamoDB may support some other attribute types that are not yet supported by Dynamoid.
 
 ### Associations
 
@@ -214,12 +300,13 @@ The only supported associations (so far) are ```has_many```, ```has_one```, ```h
 class User
   include Dynamoid::Document
 
-  ...
+  # ...
 
   has_many :addresses
   has_many :students, :class => User
   belongs_to :teacher, :class_name => :user
   belongs_to :group
+  belongs_to :group, :foreign_key => :group_id
   has_one :role
   has_and_belongs_to_many :friends, :inverse_of => :friending_users
 
@@ -228,7 +315,7 @@ end
 class Address
   include Dynamoid::Document
 
-  ...
+  # ...
 
   belongs_to :user # Automatically links up with the user model
 
@@ -245,7 +332,7 @@ Dynamoid bakes in ActiveModel validations, just like ActiveRecord does.
 class User
   include Dynamoid::Document
 
-  ...
+  # ...
 
   validates_presence_of :name
   validates_format_of :email, :with => /@/
@@ -268,7 +355,7 @@ Dynamoid also employs ActiveModel callbacks. Right now, callbacks are defined on
 class User
   include Dynamoid::Document
 
-  ...
+  # ...
 
   before_save :set_default_password
   after_create :notify_friends
@@ -325,6 +412,19 @@ address.city = 'Chicago'
 address.save
 ```
 
+To create multiple documents at once:
+
+```ruby
+User.create([{name: 'Josh'}, {name: 'Nick'}])
+```
+
+There is an efficient and low-level way to create multiple documents
+(without validation and callbacks running):
+
+```ruby
+users = User.import([{name: 'Josh'}, {name: 'Nick'}])
+```
+
 ### Querying
 
 Querying can be done in one of three ways:
@@ -354,11 +454,13 @@ There are three types of limits that you can query with:
 Using these in various combinations results in the underlying requests to be made in the smallest size possible and
 the query returns once `record_limit` or `scan_limit` is satisfied. It will attempt to batch whenever possible.
 
-You can thus limit the number of evaluated records, or select a record from which to start, to support pagination:
+You can thus limit the number of evaluated records, or select a record from which to start in order to support pagination.
 
 ```ruby
 Address.record_limit(5).start(address) # Only 5 addresses starting at `address`
 ```
+Where `address` is an instance of the model or a hash `{the_model_hash_key: 'value', the_model_range_key: 'value'}`:
+Keep in mind that if you are passing a hash to `.start()` you need to explicitly define all required keys in it including range keys, depending on table or secondary indexes signatures, otherwise you'll get an `Aws::DynamoDB::Errors::ValidationException` either for `Exclusive Start Key must have same size as table's key schema` or `The provided starting key is invalid`
 
 If you are potentially running over a large data set and this is especially true when using certain filters, you may
 want to consider limiting the number of scanned records (the number of records DynamoDB infrastructure looks through
@@ -386,21 +488,21 @@ You are able to optimize query with condition for sort key. Following operators
 
 ```ruby
 Address.where(latitude: 10212)
-Address.where('latitude.gt': 10212)
-Address.where('latitude.lt': 10212)
-Address.where('latitude.gte': 10212)
-Address.where('latitude.lte': 10212)
-Address.where('city.begins_with': 'Lon')
-Address.where('latitude.between': [10212, 20000])
+Address.where('latitude.gt' => 10212)
+Address.where('latitude.lt' => 10212)
+Address.where('latitude.gte' => 10212)
+Address.where('latitude.lte' => 10212)
+Address.where('city.begins_with' => 'Lon')
+Address.where('latitude.between' => [10212, 20000])
 ```
 
 You are able to filter results on the DynamoDB side and specify conditions for non-key fields.
 Following operators are available: `in`, `contains`, `not_contains`:
 
 ```ruby
-Address.where('city.in': ['London', 'Edenburg', 'Birmingham'])
-Address.where('city.contains': [on])
-Address.where('city.not_contains': [ing])
+Address.where('city.in' => ['London', 'Edenburg', 'Birmingham'])
+Address.where('city.contains' => [on])
+Address.where('city.not_contains' => [ing])
 ```
 
 ### Consistent Reads
@@ -423,8 +525,77 @@ User.where("created_at.lt" => DateTime.now - 1.day).all
 
 It also supports .gte and .lte. Turning those into symbols and allowing a Rails SQL-style string syntax is in the works. You can only have one range argument per query, because of DynamoDB's inherent limitations, so use it sensibly!
 
+
+### Updating
+
+In order to update document you can use high level methods
+`#update_attributes`, `#update_attribute` and `.update`.
+They run validation and collbacks.
+
+```ruby
+Address.find(id).update_attributes(city: 'Chicago')
+Address.find(id).update_attribute(city, 'Chicago')
+Address.update(id, city: 'Chicago')
+Address.update(id, { city: 'Chicago' }, if: { deliverable: true })
+```
+
+There are also some low level methods `#update`, `.update_fields` and
+`.upsert`. They don't run validation and callbacks (except `#update` - it
+runs `update` callbacks). All of them support conditional updates.
+`#upsert` will create new document if document with specified `id`
+doesn't exist.
+
+```ruby
+Adderess.find(id).update do |i|
+  i.set city: 'Chicago'
+  i.add latitude: 100
+  i.delete set_of_numbers: 10
+end
+Adderess.find(id).update(if: { deliverable: true }) do |i|
+  i.set city: 'Chicago'
+end
+Address.update_fields(id, city: 'Chicago')
+Address.update_fields(id, { city: 'Chicago' }, if: { deliverable: true })
+Address.upsert(id, city: 'Chicago')
+Address.upsert(id, { city: 'Chicago' }, if: { deliverable: true })
+```
+
+### Deleting
+
+In order to delete some items `delete_all` method should be used.
+Any callback wont be called. Items delete in efficient way in batch.
+
+```ruby
+Address.where(city: "London").delete_all
+```
+
 ### Global Secondary Indexes
 
+You can define index with `global_secondary_index`:
+
+```ruby
+class User
+  include Dynamoid::Document
+
+  field :name
+  field :age, :number
+
+  global_secondary_index hash_key: :age
+end
+```
+
+There are following options:
+* `hash_key` - is used as hash key of an index,
+* `range_key` - is used as range key of an index,
+* `projected_attributes` - list of fields to store in an index or has a predefiled value `:keys_only`, `:all`; `:keys_only` is a default,
+* `name` - an index will be created with this name when a table is created; by default name is generated and contains table name and keys names,
+* `read_capacity` - is used when table creates and used as an index capacity; by default equals `Dynamoid::Config.read_capacity`,
+* `write_capacity` - is used when table creates and used as an index capacity; by default equals `Dynamoid::Config.write_capacity`
+
+The only mandatory option is `name`.
+
+To use index in `Document.where` implicitly you need to project all the fields with option `projected_attributes: :all`.
+
 There are two ways to query Global Secondary Indexes (GSI).
 
 #### Explicit
@@ -485,7 +656,7 @@ the table since a query against GSI then a query on base table is still likely f
 
 ## Configuration
 
-There are listed all the configuration options:
+Listed below are all configuration options.
 
 * `adapter` - usefull only for the gem developers to switch to a new adapter. Default and the only available value is `aws_sdk_v2`
 * `namespace` - prefix for table names, default is `dynamoid_#{application_name}_#{environment}` for Rails application and `dynamoid` otherwise
@@ -504,9 +675,13 @@ There are listed all the configuration options:
 * `sync_retry_max_times` - when Dynamoid creates or deletes table synchronously it checks for completion specified times. Default is 60 (times). It's a bit over 2 minutes by default
 * `sync_retry_wait_seconds` - time to wait between retries. Default is 2 (seconds)
 * `convert_big_decimal` - if `true` then Dynamoid converts numbers stored in `Hash` in `raw` field to float. Default is `false`
-* `models_dir` - `dynamoid:create_tables` rake task loads DynamoDb models from this directory. Default is `app/models`. In Rails application you should set `./app/models` value
+* `models_dir` - `dynamoid:create_tables` rake task loads DynamoDb models from this directory. Default is `./app/models`.
 * `application_timezone` - Dynamoid converts all `datetime` fields to specified time zone when loads data from the storage.
   Acceptable values - `utc`, `local` (to use system time zone) and time zone name e.g. `Eastern Time (US & Canada)`. Default is `local`
+* `store_datetime_as_string` - if `true` then Dynamoid stores :datetime fields in ISO 8601 string format. Default is `false`
+* `store_date_as_string` - if `true` then Dynamoid stores :date fields in ISO 8601 string format. Default is `false`
+* `backoff` - is a hash: key is a backoff strategy (symbol), value is parameters for the strategy. Is used in batch operations. Default id `nil`
+* `backoff_strategies`: is a hash and contains all available strategies. Default is { constant: ..., exponential: ...}
 
 
 ## Concurrency
@@ -515,11 +690,11 @@ Dynamoid supports basic, ActiveRecord-like optimistic locking on save operations
 
 ```ruby
 class MyTable
-  ...
+  # ...
 
   field :lock_version, :integer
 
-  ...
+  # ...
 end
 ```
 
@@ -527,6 +702,52 @@ In this example, all saves to `MyTable` will raise an `Dynamoid::Errors::StaleOb
 
 Calls to `update` and `update!` also increment the `lock_version`, however they do not check the existing value. This guarantees that a update operation will raise an exception in a concurrent save operation, however a save operation will never cause an update to fail. Thus, `update` is useful & safe only for doing atomic operations (e.g. increment a value, add/remove from a set, etc), but should not be used in a read-modify-write pattern.
 
+
+### Backoff strategies
+
+
+You can use several methods that run efficiently in batch mode like `.find_all` and `.import`.
+
+The backoff strategy will be used when, for any reason, some items could not be processed as part of a batch mode command.
+Operations will be re-run to process these items.
+
+Exponential backoff is the recommended way to handle throughput limits exceeding and throttling on the table.
+
+There are two built-in strategies - constant delay and truncated binary exponential backoff.
+By default no backoff is used but you can specify one of the built-in ones:
+
+```ruby
+Dynamoid.configure do |config|
+  config.backoff = { constant: 2.second }
+end
+
+Dynamoid.configure do |config|
+  config.backoff = { exponential: { base_backoff: 0.2.seconds, ceiling: 10 } }
+end
+
+```
+
+You can just specify strategy without any arguments to use default presets:
+
+```ruby
+Dynamoid.configure do |config|
+  config.backoff = :constant
+end
+```
+
+You can use your own strategy in following way:
+
+```ruby
+Dynamoid.configure do |config|
+  config.backoff_strategies[:custom] = lambda do |n|
+    -> { sleep rand(n) }
+  end
+
+  config.backoff = { custom: 10 }
+end
+```
+
+
 ## Rake Tasks
 
   * `rake dynamoid:create_tables`
@@ -593,14 +814,15 @@ Also, without contributors the project wouldn't be nearly as awesome. So many th
 * [Pascal Corpet](https://github.com/pcorpet)
 * [Brian Glusman](https://github.com/bglusman) *
 * [Peter Boling](https://github.com/pboling) *
+* [Andrew Konchin](https://github.com/andrykonchin) *
 
 \* Current Maintainers
 
 ## Running the tests
 
-Running the tests is fairly simple. You should have an instance of DynamoDB running locally. Follow this steps to be able to run the tests:
+Running the tests is fairly simple. You should have an instance of DynamoDB running locally. Follow these steps to setup your test environment.
 
- * First download and unpack the latest version of DynamoDB.
+ * First download and unpack the latest version of DynamoDB.  We have a script that will do this for you if you use homebrew on a Mac.
 
     ```shell
     bin/setup
@@ -624,7 +846,7 @@ Running the tests is fairly simple. You should have an instance of DynamoDB runn
     bin/stop_dynamodblocal
     ```
 
-If you want to run all the specs that travis runs, use `bundle exec wwtd`, but first you will need to setup all the rubies, for each of `%w( 2.0.0-p648 2.1.10 2.2.6 2.3.3 2.4.1 jruby-9.1.8.0 )`.  WHen you run `bundle exec wwtd` it will take care of starting and stopping the local dynamodb instance.
+If you want to run all the specs that travis runs, use `bundle exec wwtd`, but first you will need to setup all the rubies, for each of `%w( 2.0.0-p648 2.1.10 2.2.6 2.3.3 2.4.1 jruby-9.1.8.0 )`.  When you run `bundle exec wwtd` it will take care of starting and stopping the local dynamodb instance.
 
 ```shell
 rvm use 2.0.0-p648
@@ -633,9 +855,6 @@ gem install bundler
 bundle install
 ```
 
-[![Build Status](https://travis-ci.org/Dynamoid/Dynamoid.svg)](https://travis-ci.org/Dynamoid/Dynamoid)
-[![Coverage Status](https://coveralls.io/repos/Dynamoid/Dynamoid/badge.svg?branch=master&service=github)](https://coveralls.io/github/Dynamoid/Dynamoid?branch=master)
-
 ## Copyright
 
 Copyright (c) 2012 Josh Symonds.