attr_pouch 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 58a432e44f2c9f4bdcc8bcf5b505134b1c0c56ab
-  data.tar.gz: 91d784b4dfc7b673f3cb46d07fb94152dea35b09
+  metadata.gz: 1e70f1aaa49e8c698db7004d2137dff0fb396462
+  data.tar.gz: e29ed8ec737976e0e65180c79c3a4736f92d691f
 SHA512:
-  metadata.gz: 93891ecdbe1a8eb5a31ee34a956472352abbf53ce76a006dbe5e58cffe8087af64e816e425366d5b51609d472d0dd28f9333b8ac1862b2b6f8c1f89b62f26a86
-  data.tar.gz: 973525f442cfd29f521046b3fe1b6a4a5efbf4273134c752b18dab565ba1a55f0eb0ec736cc6ad708941cabdbfa5449894471246f1500ac989a29f5e177183d1
+  metadata.gz: 4961584f437d46255b6e0ce970b61b7bd9d820b943397e498c129e75176553bca6975ee52e2470fad4790ab5bfcfdb022ca920367e32a7f89b301a4fbf4ec00d
+  data.tar.gz: fd0c772494d398b7bfdfdd4e08cd52e93644cd30af48b6b98fa494b304d4ea1b8ce84d95b019098bb5f4578813a79d4d52c7707c0d7ccc1742b94f2048c0532a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    attr_pouch (0.0.1)
+    attr_pouch (0.1.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -26,11 +26,12 @@ model.
 
 ### Usage
 
-AttrPouch allows you to designate a "pouch" database `hstore` field
-that provides schema-less storage for any `Sequel::Model`
-object. Within this pouch, you define additional fields that behave
-largely like standard Sequel fields (i.e., as if they were backed by
-their own database columns), but are all in fact stored in the pouch:
+AttrPouch allows you to designate a "pouch" database field (of type
+`jsonb`, `hstore`, or `json`) that provides schema-less storage for
+any `Sequel::Model` object. Within this pouch, you can define
+sub-fields that behave largely like standard Sequel fields (i.e., as
+if they were backed by their own database columns), but are all in
+fact stored in the pouch:
 
 ```ruby
 class User < Sequel::Model
@@ -107,10 +108,10 @@ AttrPouch.configure do |config|
 end
 ```
 
-Note that your encoder and decoder do have access to the field object,
-which includes name, type, and any options you've configured in the
-field definition. Option names are not checked by `attr_vault`, so
-custom decoder or encoder options are possible.
+Note that your encoder and decoder do have access to the field
+definition object, which includes name, type, and any options you've
+configured in the field definition. Option names are not checked by
+`attr_vault`, so custom decoder or encoder options are possible.
 
 When an encoder or decoder is specified via symbol, it will only work
 for fields whose type is declared to be exactly that symbol. When
@@ -123,7 +124,7 @@ This can be illustrated via the last built-in codec, for
 ```ruby
 class User < Sequel::Model
   pouch(:preferences) do
-    field :bff, User
+    field :bff, type: User
   end
 end
 
@@ -145,7 +146,7 @@ infers types as follows:
  * `:bool`: name ends with `?`
  * `String`: anything else
 
-If this is not suitable, you can register your own type inference
+If this is not suitable, you can register your own "type inference"
 mechanism instead:
 
 ```ruby
@@ -171,7 +172,11 @@ end
 
 karen = User.create(name: 'karen')
 karen.update(proxy_address: '10.11.12.13:8001')
-karen.delete_proxy_address
+karen.delete_proxy_address # note this does not save the object
+karen.reload
+karen.proxy_address # still '10.11.12.13:8001'; we never saved
+karen.delete_proxy_address! # or call #save or #save_changes after a delete
+karen.proxy_address # now it's gone
 ```
 
 Deletable fields are automatically given a default of `nil` if no
@@ -217,7 +222,7 @@ end
 
 nils = User[name: 'nils'] # in db we have `{ ssl?: true, byzantion?: true }`
 nils.tls?                 # true
-nils.consantinople?       # true
+nils.constantinople?      # true
 ```
 
 Note that no direct accessors are defined for the old names, and if
@@ -225,9 +230,10 @@ the value is updated, it is written under the new name and any old
 values in the pouch are deleted:
 
 ```ruby
+nils.istanbul = false
 nils.tls?         # true
-nils.instanbul?   # true
-nils.save_changes # now in db as `{ tls?: true, instanbul?: true }`
+nils.instanbul?   # false
+nils.save_changes # now in db as `{ tls?: true, instanbul?: false }`
 ```
 
 #### Raw value access
@@ -244,8 +250,9 @@ absent field value deferring to the default:
 ```ruby
 class User < Sequel::Model
   pouch(:preferences) do
-    field :bff, User, raw_field: :bff_id
-    field :arch_nemesis, raw_field: :nemesis_id, default: User[name: 'donald']
+    field :bff, type: User, raw_field: :bff_id
+    field :arch_nemesis, type: User, raw_field: :nemesis_id,
+	        default: User[name: 'donald']
   end
 end
 
@@ -261,18 +268,70 @@ raw field value is updated, values present under any of the `was` keys
 will be deleted.
 
 
+### Dataset querying
+
+AttrPouch provides a dataset method to simplify querying pouch
+contents. The interface is similar to querying first-class columns:
+
+```ruby
+class User < Sequel::Model
+  pouch(:preferences) do
+    field :bff, type: User
+    field :favorite_color
+  end
+end
+
+# match on multiple fields
+User.where_pouch(bff: User[name: 'georgia'], favorite_color: 'goldenrod').all
+# match on multiple values
+User.where_pouch(favorite_color: [ 'gray', 'dark gray', 'black' ]).all
+# check for nil value (or absence of key)
+User.where_pouch(bff: nil).all
+```
+
+Note that you can speed up your queries considerably by adding an
+index. AttrPouch uses containment queries to implement dataset
+querying, so you can use GIN indexes with both
+[`hstore`](https://www.postgresql.org/docs/current/static/hstore.html#AEN160038)
+and
+[`jsonb`](https://www.postgresql.org/docs/current/static/datatype-json.html#JSON-INDEXING):
+
+```ruby
+Sequel.migration do
+  up do
+    execute <<-EOF
+CREATE INDEX users_prefs_idx ON users USING gin (preferences);
+EOF
+  end
+  down do
+    execute <<-EOF
+DROP INDEX users_prefs_idx;
+EOF
+  end
+EOF
+end
+```
+
+N.B.: For simplicity, AttrPouch treats the absence of a key and the
+presence of a key with a `NULL` value the same when querying, which
+means queries looking for `nil` values do not use the indexes.
+
+Dataset queries are not supported for fields backed by columns of
+type `json`.
+
 ### Schema
 
 AttrPouch requires a new storage field for each pouch added to a
-model. It is currently designed for and tested with `hstore`. Consider
-using a single pouch per model class unless you clearly need several
-distinct pouches.
+model. It is currently designed for and tested with `jsonb`, `hstore`,
+and `json` (although `json`-format fields do not currently support
+dataset querying, as per above). Consider using a single pouch per
+model class unless you clearly need several distinct pouches.
 
 ```ruby
 Sequel.migration do
   change do
     alter_table(:users) do
-      add_column :preferences, :hstore
+      add_column :preferences, :jsonb
     end
   end
 end
@@ -290,8 +349,8 @@ $ createdb attr_pouch_test
 $ DATABASE_URL=postgres:///attr_pouch_test bundle exec rspec
 ```
 
-Please follow the project's general coding style and open issues for
-any significant behavior or API changes.
+Please follow the project's general coding style and open issues
+beforehand to discuss any significant behavior or API changes.
 
 A pull request is understood to mean you are offering your code to the
 project under the MIT License.

data/TODO

@@ -1,6 +1,8 @@
 # TODO thoughts:
   - docs
-  - support for storage in JSON / plain text / arbitrary backing format
+    - dataset
+    - update to note json / jsonb support
+  - support for access via [] and []= methods
   - opt: eager_default on create for fields
   - opt: run tracking
   - more efficient updates via merging with structure in-database field-by-field

data/lib/attr_pouch/errors.rb

@@ -3,6 +3,8 @@ module AttrPouch
   class Error < StandardError; end
   class MissingCodecError < Error; end
   class InvalidFieldError < Error; end
+  class InvalidPouchError < Error; end
   class MissingRequiredFieldError < Error; end
   class ImmutableFieldUpdateError < Error; end
+  class UnsupportedError < Error; end
 end

data/lib/attr_pouch/version.rb

@@ -1,3 +1,3 @@
 module AttrPouch
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/attr_pouch.rb

@@ -14,10 +14,46 @@ module AttrPouch
 
   def self.included(base)
     base.extend(ClassMethods)
+    # we can't just independently define this in ClassMethods since
+    # `def_dataset_method` is only defined on Sequel::Model subclasses
+    base.def_dataset_method(:where_pouch) do |pouch_field, expr_hash|
+      ds = self
+      pouch = model.pouch(pouch_field)
+      if pouch.nil?
+        raise ArgumentError,
+              "No pouch defined for #{pouch_field}"
+      end
+      if pouch.json?
+        raise UnsupportedError, "Dataset queries not supported for columns of type json"
+      end
+
+      expr_hash.each do |key, value|
+        key = key.to_s
+        field = pouch.field_definition(key)
+        if field.nil?
+          raise ArgumentError,
+                "No field #{key} defined for pouch #{pouch_field}"
+        end
+
+        if value.respond_to?(:each)
+          value.each_with_index do |v,i|
+            condition = pouch.store.contains(pouch.wrap(key => field.encode(v)))
+            ds = i == 0 ? ds.where(condition) : ds.or(condition)
+          end
+        elsif value.nil?
+          ds = ds.where(pouch.store.has_key?(key) => false)
+               .or(pouch.store.contains(pouch.wrap(key => field.encode(value))))
+        else
+          ds = ds.where(pouch.store
+                         .contains(pouch.wrap(key => field.encode(value))))
+        end
+      end
+      ds
+    end
   end
 
   class Field
-    attr_reader :name, :type, :raw_type, :opts
+    attr_reader :pouch, :name, :type, :raw_type, :opts
 
     def self.encode(type, &block)
       @@encoders ||= {}
@@ -48,22 +84,26 @@ module AttrPouch
       end
     end
 
-    def initialize(name, opts)
-      @name = name
+    def initialize(pouch, name, opts)
+      @name = name.to_s
       if opts.has_key?(:type)
         @type = to_class(opts.fetch(:type))
       else
         @type = self.class.infer_type(self)
       end
-      @raw_type = type
+      @pouch = pouch
       @opts = opts
     end
 
+    def raw_type
+      @opts.fetch(:type, nil)
+    end
+
     def alias_as(new_name)
       if new_name == name
         self
       else
-        self.class.new(new_name, opts)
+        self.class.new(pouch, new_name, opts)
       end
     end
 
@@ -89,11 +129,12 @@ module AttrPouch
 
     def previous_aliases
       was = opts.fetch(:was, [])
-      if was.respond_to?(:to_a)
-        was.to_a
-      else
-        [ was ]
-      end
+      aliases = if was.respond_to?(:to_a)
+                  was.to_a
+                else
+                  [ was ]
+                end
+      aliases.map(&:to_s)
     end
 
     def all_names
@@ -127,11 +168,7 @@ module AttrPouch
         end
       elsif present_as == name
         raw = store.fetch(name)
-        if decode
-          decode(raw)
-        else
-          raw
-        end
+        decode ? decode(raw) : raw
       else
         alias_as(present_as).read(store)
       end
@@ -215,15 +252,62 @@ module AttrPouch
   class Pouch
     VALID_FIELD_NAME_REGEXP = %r{\A[a-zA-Z0-9_]+\??\z}
 
-    def initialize(host, storage_field, default_pouch: Sequel.hstore({}))
+    def initialize(host, storage_field)
       @host = host
-      @storage_field = storage_field
-      @default_pouch = default_pouch
+      @storage_field = storage_field.to_sym
       @fields = {}
     end
 
     def field_definition(name)
-      @fields[name]
+      @fields[name.to_s]
+    end
+
+    def hstore?
+      pouch_column_info.fetch(:db_type) == 'hstore'
+    end
+
+    def json?
+      pouch_column_info.fetch(:db_type) == 'json'
+    end
+
+    def jsonb?
+      pouch_column_info.fetch(:db_type) == 'jsonb'
+    end
+
+    def either_json?
+      json? || jsonb?
+    end
+
+    def pouch_column_info
+      @host.db_schema.find { |k,_| k == @storage_field }.last
+    end
+
+    def wrap(hash)
+      if hstore?
+        Sequel.hstore(hash)
+      elsif json?
+        Sequel.pg_json(hash)
+      elsif jsonb?
+        Sequel.pg_jsonb(hash)
+      else
+        raise InvalidPouchError, "Pouch must use hstore, json, or jsonb column"
+      end
+    end
+
+    def store
+      if hstore?
+        Sequel.hstore(@storage_field)
+      elsif json?
+        Sequel.pg_json_op(@storage_field)
+      elsif jsonb?
+        Sequel.pg_jsonb_op(@storage_field)
+      else
+        raise InvalidPouchError, "Pouch must use hstore, json, or jsonb column"
+      end
+    end
+
+    def default_pouch
+      wrap({})
     end
 
     def field(name, opts={})
@@ -231,51 +315,13 @@ module AttrPouch
         raise InvalidFieldError, "Field name must match #{VALID_FIELD_NAME_REGEXP}"
       end
 
-      field = Field.new(name, opts)
-      @fields[name] = field
+      field = Field.new(self, name, opts)
+      @fields[name.to_s] = field
 
       storage_field = @storage_field
-      default = @default_pouch
+      default = default_pouch
 
       @host.class_eval do
-        def_dataset_method(:where_pouch) do |pouch_field, expr_hash|
-          # TODO: encode the values so we can query properly
-          ds = self
-          expr_hash.each do |key, value|
-            pouch = model.pouch(pouch_field)
-            if pouch.nil?
-              raise ArgumentError,
-                    "No pouch defined for #{pouch_field}"
-            end
-            field = pouch.field_definition(key)
-            if field.nil?
-              raise ArgumentError,
-                    "No field #{key} defined for pouch #{pouch_field}"
-            end
-
-            if value.respond_to?(:each)
-              value.each_with_index do |v,i|
-                encoded_val = field.encode(v)
-                if i == 0
-                  ds = ds.where(Sequel.hstore(pouch_field)
-                                 .contains(Sequel.hstore(key => encoded_val)))
-                else
-                  ds = ds.or(Sequel.hstore(pouch_field)
-                              .contains(Sequel.hstore(key => encoded_val)))
-                end
-              end
-            elsif value.nil?
-              ds = ds.where(Sequel.hstore(pouch_field).has_key?(key.to_s) => false)
-                   .or(Sequel.hstore(pouch_field)
-                        .contains(Sequel.hstore(key => nil)))
-            else
-              ds = ds.where(Sequel.hstore(pouch_field)
-                             .contains(Sequel.hstore(key => field.encode(value))))
-            end
-          end
-          ds
-        end
-
         define_method(name) do
           store = self[storage_field]
           field.read(store)
@@ -380,7 +426,7 @@ AttrPouch.configure do |config|
     value.to_s
   end
   config.decode(:bool) do |field, value|
-    value == 'true'
+    value.to_s == 'true'
   end
 
   config.encode(Sequel::Model) do |field, value|