ocean-dynamo 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75ca78788e4c6fede73f78af4d7c8730e9f868198cd95f8905094f9e0032e45d
-  data.tar.gz: 798dc05815ecb753dcbe7062ecff1906108cde3ea498a25c53c0c4cea6588985
+  metadata.gz: a7ade2e3ad29ce511cb3537e6d800280da158c8a1eeb676ac767b0489c7c25d1
+  data.tar.gz: d1f727f3fcf58637e9888eeffcb3a4120b5107a79c400b7ae845936bd2f8eab7
 SHA512:
-  metadata.gz: 99a4b8a30c990f58440f15245c90e3fd66aff7484d197a40dc48af85972bd2066858e8b4720a3273a35ee779300234e79d9ca79d21517c41f855441dc7ca2b71
-  data.tar.gz: 1e8df34da4547b6d00108a844b73c195ba25334866cc2f3f44016de9216ced945e67e59e20097590b19e96a2ec7fa5e439b217dd82ccb591d6c0bd414c387910
+  metadata.gz: 7938d1e380cb4f93fa99682cc667f29480c73ee3dcb99e06f74b5fd8092c4f91f03039831e3391112f1c11d3d9f6f11a0a1e57b0c2343e59c3889bb435df2a89
+  data.tar.gz: 15eb31c9595bbabe5feed8474bb75b69139393dfeb262202ee5416162c66de998cc954558132b6c2589ebea4afc46a01d072ede7b08edaddef6eeaf4a80b5fc6

data/README.md

@@ -1,4 +1,4 @@
-== ocean-dynamo
+# ocean-dynamo
 
 OceanDynamo is a massively scalable Amazon DynamoDB near drop-in replacement for
 ActiveRecord.
@@ -9,7 +9,7 @@ but 5.1 will require a couple of changes.
 {<img src="https://badge.fury.io/rb/ocean-dynamo.png" alt="Gem Version" />}[http://badge.fury.io/rb/ocean-dynamo]
 
 
-=== Features
+## Features
 
 As one important use case for OceanDynamo is to facilitate the conversion of SQL
 databases to no-SQL DynamoDB databases, it is important that the syntax and semantics
@@ -18,8 +18,8 @@ callbacks, exceptions and method chaining semantics. OceanDynamo follows this pa
 closely and is of course based on ActiveModel.
 
 The attribute and persistence layer of OceanDynamo is modeled on that of ActiveRecord:
-there's +save+, +save!+, +create+, +update+, +update!+, +update_attributes+, +find_each+,
-+destroy_all+, +delete_all+, +read_attribute+, +write_attribute+ and all the other
+there's `save`, `save!`, `create`, `update`, `update!`, `update_attributes`, `find_each`,
+`destroy_all`, `delete_all`, `read_attribute`, `write_attribute` and all the other
 methods you're used to. The design goal is always to implement as much of the ActiveRecord
 interface as possible, without compromising scalability. This makes the task of switching
 from SQL to no-SQL much easier.
@@ -34,22 +34,22 @@ with FactoryBot.
 OceanDynamo supports optimistic record locking via a combination of DynamoDB conditional
 writes and atomic updates. This is activated by default.
 
-=== Current State
+## Current State
 
 * Secondary indices are now fully supported! See below for more information.
 * Version 2 of the AWS Ruby SDK is now used.
 * Work begun on association proxies, etc.
 
 
-=== Future milestones
+## Future milestones
 
 * Direct support for the DynamoDB JSON attribute types for arrays and hashes
 * Collection proxies, to implement ActiveRecord-style method chaining, e.g.:
   <code>blog_entry.comments.build(body: "Cool!").save!</code>
-* The +has_and_belongs_to_many+ assocation.
+* The `has_and_belongs_to_many` assocation.
 
 
-=== Current use
+## Current use
 
 OceanDynamo is used as a central component in Ocean, a Rails framework and development,
 testing, and production pipeline for creating massively scalable HATEOAS microservice
@@ -59,15 +59,15 @@ SOAs in the cloud.
 However, OceanDynamo can of course also be used stand-alone.
 
 
-== Documentation
+# Documentation
 
 * Ocean-dynamo gem on Rubygems: https://rubygems.org/gems/ocean-dynamo
 * Ocean-dynamo gem API: http://rubydoc.info/gems/ocean-dynamo/frames
-* Ocean-dynamo source and wiki: https://github.org/OceanDev/ocean-dynamo
+* Ocean-dynamo source: https://gitlab.com/ocean-dev/ocean-dynamo
 * AWS DynamoDB Ruby SDK v2: http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB.html
 
 
-== Contributing
+# Contributing
 
 Contributions are welcome. Fork in the usual way. OceanDynamo is developed using
 TDD: the specs are extensive and test coverage is very near to 100 percent. Pull requests
@@ -75,12 +75,12 @@ will not be considered unless all tests pass and coverage is equally high or hig
 All contributed code must therefore also be exhaustively tested.
 
 
-== Examples
+# Examples
 
-=== Basic syntax
+## Basic syntax
 
 The following example shows the basic syntax for declaring a DynamoDB-based schema.
-
+```
   class AsyncJob < OceanDynamo::Table
 
     dynamo_schema(:guid) do
@@ -104,24 +104,25 @@ The following example shows the basic syntax for declaring a DynamoDB-based sche
     end
 
   end
+```
 
-=== Attributes
+## Attributes
 
-Each attribute has a name, a type (+:string+, +:integer+, +:float+, +:datetime+, +:boolean+,
-or +:serialized+) where +:string+ is the default. Each attribute also optionally has a default
-value, which can be a Proc. The hash key attribute is by default +:id+ (overridden as +:guid+ in
-the example above) and is a +:string+.
+Each attribute has a name, a type (`:string`, `:integer`, `:float`, `:datetime`, `:boolean`,
+or `:serialized`) where `:string` is the default. Each attribute also optionally has a default
+value, which can be a Proc. The hash key attribute is by default `:id` (overridden as `:guid` in
+the example above) and is a `:string`.
 
-The +:string+, +:integer+, +:float+ and +:datetime+ types can also store sets of their type.
+The `:string`, `:integer`, `:float` and `:datetime` types can also store sets of their type.
 Sets are represented as arrays, may not contain duplicates and may not be empty.
 
-All attributes except the +:string+ type can take the value +nil+. Storing +nil+ for a string
+All attributes except the `:string` type can take the value `nil`. Storing `nil` for a string
 value will return the empty string, <tt>""</tt>.
 
-=== Schema args and options
-
-+dynamo_schema+ takes args and many options. Here's the full syntax:
+## Schema args and options
 
+`dynamo_schema` takes args and many options. Here's the full syntax:
+```
  dynamo_schema(
    table_hash_key = :id,                   # The name of the hash key attribute
    table_range_key = nil,                  # The name of the range key attribute (or nil)
@@ -139,22 +140,23 @@ value will return the empty string, <tt>""</tt>.
    ...
    ...
  end
-
-Tip: you might want to use the following idiom when declaring a +dynamo_schema+. It is used everywhere in Ocean:
-
- dynamo_schema(:id, table_name_suffix: Api.basename_suffix,
-                    create: Rails.env != "production") do
+```
+Tip: you might want to use the following idiom when declaring a `dynamo_schema`. It is used everywhere in Ocean:
+```
+ dynamo_schema(:id, table_name_suffix: Api.basename_suffix, create: true) do
    ...
  end
+```
+This will auto-create the DynamoDB table in all environments and also add a
+suffix to the table name in order to prevent collisions during tests.
+Cf `Api.basename_suffix` in the `ocean-rails` gem for more information.
 
-This will auto-create the DynamoDB table in all environments except production, and it will also add a suffix to the table name in order to prevent tests from colliding. Cf +Api.basename_suffix+ in the +ocean-rails+ gem for more information.
-
-== +has_many+ and +belongs_to+
-
-=== Example
+# has_many and belongs_to
 
-The following example shows how to set up +has_many+ / +belongs_to+ relations:
+## Example
 
+The following example shows how to set up `has_many` / `belongs_to` relations:
+```
  class Forum < OceanDynamo::Table
    dynamo_schema do
      attribute :name
@@ -179,38 +181,38 @@ The following example shows how to set up +has_many+ / +belongs_to+ relations:
    end
    belongs_to :topic, composite_key: true
  end
-
+```
 The only non-standard aspect of the above is <tt>composite_key: true</tt>, which
-is required as the Topic class itself has a +belongs_to+ relation and thus has
+is required as the Topic class itself has a `belongs_to` relation and thus has
 a composite key. This must be declared in the child class as it needs to know
 how to retrieve its parent.
 
 
-=== Restrictions
+## Restrictions
 
-Restrictions for +belongs_to+ tables:
-* The hash key must be specified and must not be +:id+.
+Restrictions for `belongs_to` tables:
+* The hash key must be specified and must not be `:id`.
 * The range key must not be specified at all.
-* +belongs_to+ can be specified only once in each class.
-* +belongs_to+ must be placed after the +dynamo_schema+ attribute block.
+* `belongs_to` can be specified only once in each class.
+* `belongs_to` must be placed after the `dynamo_schema` attribute block.
 
-Restrictions for +has_many+ tables:
-* +has_many+ must be placed after the +dynamo_schema+ attribute block.
+Restrictions for `has_many` tables:
+* `has_many` must be placed after the `dynamo_schema` attribute block.
 
-These restrictions allow OceanDynamo to implement the +has_many+ / +belongs_to+
+These restrictions allow OceanDynamo to implement the `has_many` / `belongs_to`
 relation in a very efficient and massively scalable way.
 
 
-=== Implementation
+## Implementation
 
-+belongs_to+ claims the range key and uses it to store its own id, which normally
+`belongs_to` claims the range key and uses it to store its own id, which normally
 would be stored in the hash key attribute. Instead, the hash key attribute holds the
 id of the parent. We have thus reversed the roles of these two fields. As a result,
 all children store their parent id in the hash key, and their own id in the
 range key.
 
 This type of relation is even more efficient than its ActiveRecord counterpart as
-it uses only primary indices in both directions of the +has_many+ / +belongs_to+
+it uses only primary indices in both directions of the `has_many` / `belongs_to`
 association. No scans.
 
 Furthermore, since DynamoDB has powerful primary index searches involving substrings
@@ -218,18 +220,18 @@ and matching, the fact that the range key is a string can be used to implement
 wildcard matching of additional attributes. This gives, amongst other things, the
 equivalent of an SQL GROUP BY request, again without requiring any secondary indices.
 
-It's our goal to use a similar technique to implement +has_and_belongs_to_many+ relations,
+It's our goal to use a similar technique to implement `has_and_belongs_to_many` relations,
 which means that secondary indices won't be necessary for the vast majority of
 DynamoDB tables. This ultimately means reduced operational costs, as well as
 reduced complexity.
 
 
-== Secondary Indices
+# Secondary Indices
 
-=== Local Secondary Indices
+## Local Secondary Indices
 
 Up to five attributes can be declared as local secondary indices, in the following manner:
-
+```
   class Authentication < OceanDynamo::Table
     dynamo_schema(:username, :expires_at) do
       attribute :token,       :string,   local_secondary_index: true
@@ -239,10 +241,10 @@ Up to five attributes can be declared as local secondary indices, in the followi
       attribute :api_user_id, :string
     end
   end
-
-The items of the above table can be accessed by using the hash key +:username+ and
-the range key +:expires_at+. The +local_secondary_index+ declaration makes it possible
-to access items using the same hash key +:username+ but with +:token+ as an alternate
+```
+The items of the above table can be accessed by using the hash key `:username` and
+the range key `:expires_at`. The `local_secondary_index` declaration makes it possible
+to access items using the same hash key `:username` but with `:token` as an alternate
 range key. Local secondary indices all use the same hash key as the primary index,
 substituting another attribute instead as the range key.
 
@@ -251,29 +253,29 @@ combination of keys. Secondary indices don't require the range key to be unique
 the same hash key. This means that secondary index searches always will return a
 collection.
 
-Local secondary indices are queried through +find_local_each+ and +find_local+.
+Local secondary indices are queried through `find_local_each` and `find_local`.
 They take the same arguments; the former yields to a block for each item,
 the other returns all items in an array.
 
-The following finds all Authentications where +:username+ is "joe" and +:token+ is "quux":
-
+The following finds all Authentications where `:username` is "joe" and `:token` is "quux":
+```
  Authentication.find_local(:username, "joe", :token, "=", "quux")
-
-This retrieves all Authentications belonging to Joe, sorted on +:token+:
-
+```
+This retrieves all Authentications belonging to Joe, sorted on `:token`:
+```
  Authentication.find_local(:username, "joe", :token, ">=", "0")
-
+```
 The same thing but with the only the item with the highest token value:
-
+```
  Authentication.find_local(:username, "joe", :token, ">=", "0",
                            scan_index_forward: false, limit: 1)
+```
 
+## Global Secondary Indices
 
-=== Global Secondary Indices
-
-Global secondary indices are declared after all attributes, but still within the +do+
+Global secondary indices are declared after all attributes, but still within the `do`
 block:
-
+```
   class Authentication < OceanDynamo::Table
     dynamo_schema(:username, :expires_at) do
       attribute :token,       :string,   local_secondary_index: true
@@ -287,41 +289,40 @@ block:
       global_secondary_index :expires_at, write_capacity_units: 50
     end
   end
-
-Each +global_secondary_index+ clause (there can be a maximum of 5 per table) takes
+```
+Each `global_secondary_index` clause (there can be a maximum of 5 per table) takes
 the following arguments:
-* +hash_value+ (required),
-* +range_value+ (optional),
-* +:projection+ (default +:keys_only+, +:all+ for all attributes)
-* +:read_capacity_units+ (defaults to the table's read capacity, normally 10)
-* +:write_capacity_units+ (default to the table's write capacity, normally 5)
+* `hash_value` (required),
+* `range_value` (optional),
+* `:projection` (default `:keys_only`, `:all` for all attributes)
+* `:read_capacity_units` (defaults to the table's read capacity, normally 10)
+* `:write_capacity_units` (default to the table's write capacity, normally 5)
 
-Global secondary indices are queried through +find_global_each+ and +find_global+.
+Global secondary indices are queried through `find_global_each` and `find_global`.
 They take the same arguments; the former yields to a block for each item,
 the other returns all items in an array.
 
-The following finds all Authentications whose +:token+ is +"quux"+:
-
+The following finds all Authentications whose `:token` is `"quux"`:
+```
  Authentication.find_global(:token, "quux")
-
-This retrieves all Authentications belonging to the user with the ID +"dfstw-ruyhdf-ewijf"+,
-sorted in ascending order of the +:expires_at+ attribute:
-
+```
+This retrieves all Authentications belonging to the user with the ID `"dfstw-ruyhdf-ewijf"`,
+sorted in ascending order of the `:expires_at` attribute:
+```
  Authentication.find_global(:api_user_id, "dfstw-ruyhdf-ewijf",
                             :expires_at, ">=", 0)
-
-To get the highest +:expires_at+ record:
-
+```
+To get the highest `:expires_at` record:
+```
  Authentication.find_global(:api_user_id, "dfstw-ruyhdf-ewijf",
                             :expires_at, ">=", 0,
                             scan_index_forward: false, limit: 1)
+```
 
-
-== Installation
+# Installation
 ```
 gem install ocean-dynamo
 ```
-
 Ocean-dynamo relies on Aws.config to fetch configuration data. In Ocean, we use
 an init file similar to this one:
 ```
@@ -347,12 +348,12 @@ Aws.config.update(cfg)
 ```
 As you can see, this relies on ENV variables to choose from three different
 setups:
-#. If you're using discrete AWS credentials, set AWS_REGION, AWS_ACCESS_KEY_ID,
+1. If you're using discrete AWS credentials, set AWS_REGION, AWS_ACCESS_KEY_ID,
    and AWS_SECRET_ACCESS_KEY.
-#. If you're using localstack, provide AWS_DYNAMODB_ENDPOINT (http://localhost:4569).
-#. If you're using EC2 or ECS instance profile credentials, set only AWS_REGION.
+2. If you're using localstack, provide AWS_DYNAMODB_ENDPOINT (http://localhost:4569).
+3. If you're using EC2 or ECS instance profile credentials, set only AWS_REGION.
 
-== Running the specs
+# Running the specs
 
 We're using localstack (https://github.com/localstack/localstack) for development
 and testing. Install (we use a Docker container) and run it. If you're using
@@ -360,18 +361,18 @@ ocean-dynamo with the Ocean Rails context, you can install and start it by
 following the instructions in the `ocean` repo.
 
 With localstack running, you should now be able to do
-
+```
  bundle exec rspec
-
+```
 All tests should pass.
 
-== Rails console
+# Rails console
 
 The Rails console is available from the built-in dummy application:
-
+```
  cd spec/dummy
  rails console
-
+```
 This will, amongst other things, also create the CloudModel table if it doesn't already
 exist. On Amazon, this will take a little while. With DynamoDB Local, it's practically
 instant.

data/lib/ocean-dynamo/tables.rb

@@ -4,7 +4,7 @@ module OceanDynamo
     def self.included(base)
       base.extend(ClassMethods)
     end
-  
+
 
     # ---------------------------------------------------------
     #
@@ -14,7 +14,7 @@ module OceanDynamo
 
     module ClassMethods
 
-      def dynamo_schema(table_hash_key=:id, 
+      def dynamo_schema(table_hash_key=:id,
                         table_range_key=nil,
                         table_name: compute_table_name,
                         table_name_prefix: nil,
@@ -23,9 +23,10 @@ module OceanDynamo
                         write_capacity_units: 5,
                         connect: :late,
                         create: false,
+                        client: nil,
                         **keywords,
                         &block)
-        self.dynamo_client = nil
+        self.dynamo_client = client
         self.dynamo_resource = nil
         self.dynamo_table = nil
         self.table_connected = false
@@ -131,7 +132,7 @@ module OceanDynamo
         #puts "Updating table #{table_full_name}"
         # attrs = table_attribute_definitions
         # active_attrs = []
-        # dynamo_table.attribute_definitions.each do |k| 
+        # dynamo_table.attribute_definitions.each do |k|
         #   active_attrs << { attribute_name: k.attribute_name, attribute_type: k.attribute_type }
         # end
         # return false if active_attrs == attrs
@@ -149,7 +150,7 @@ module OceanDynamo
           attrs << { attribute_name: name, attribute_type: attribute_type(name) }
         end
         global_secondary_indexes.each do |index_name, data|
-          data["keys"].each do |name| 
+          data["keys"].each do |name|
             next if attrs.any? { |a| a[:attribute_name] == name }
             attrs << { attribute_name: name, attribute_type: attribute_type(name) }
           end
@@ -221,7 +222,7 @@ module OceanDynamo
       end
 
     end
-  
+
 
     # ---------------------------------------------------------
     #

data/lib/ocean-dynamo/version.rb

@@ -1,3 +1,3 @@
 module OceanDynamo
-  VERSION = "1.6.1"
+  VERSION = "1.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ocean-dynamo
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Peter Bengtson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-28 00:00:00.000000000 Z
+date: 2018-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk