associate_jsonb 0.0.4 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cb22feba951a6241ccada849b6d17ae06a4a84c797a49ae139844917d50474c
-  data.tar.gz: 910b39ddc0f89d8525439d9d4e74244a62bbf3f4d07cb333306879312588dfda
+  metadata.gz: 847b6c8d5410dca5511a9ab2537ea3d2d9ba5c40e681ad42a63f0e752604d1ff
+  data.tar.gz: 935adff8c21a94b4d7593a236c9e56eec29c31340a897c82851b3662b0da880e
 SHA512:
-  metadata.gz: 5382c87315fbbbc8bc52ebb5efb605e60373c7f24e9d681a008f5d5c53dc26649df89f7233ca1b3b6962fdd16a891c9072e55577a3c40e655faa54f3ec0dc375
-  data.tar.gz: 3570c685cde53a273f70f5d434d1daacbc32b260b0b0500a3e6ef801b18a50fdd007a1970ede0d692a5eee89a87eba46b73ced15019514cfafece65b01c588a8
+  metadata.gz: c614936df446af3b0bd1301037954214e973cc4522637c3578f47f775065eb9085f08b668b11bf619ba3ca7968b14c078e192579be56eee489d5bf0780097552
+  data.tar.gz: 5243289a848da4cc15d03204a6d5bc6a502d810e6f839fb2b26aabc264bea63553b040a8508cf6f6d0722d82be5ea905c9bb75caa5e9ac1038b2e9d85e535122

data/README.md

@@ -2,17 +2,98 @@
 
 [![Gem Version](https://badge.fury.io/rb/associate_jsonb.svg)](https://badge.fury.io/rb/associate_jsonb)
 
-Basic ActiveRecord Associations using PostgreSQL JSONB columns, with built-in accessors and column indexes
+#### Easy PostgreSQL JSONB extensions
+**including:**
 
-<!-- This gem was created as a solution to this [task](http://cultofmartians.com/tasks/active-record-jsonb-associations.html) from [EvilMartians](http://evilmartians.com).
+- Basic ActiveRecord Associations using PostgreSQL JSONB columns, with built-in accessors and column indexes
+- Thread-Safe JSONB updates (well, as safe as they can be) using a custom nested version of `jsonb_set` (`jsonb_nested_set`)
 
 **Requirements:**
 
-- PostgreSQL (>= 9.6)
+- PostgreSQL (>= 12)
+- Rails 6.0.3.2
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'associate_jsonb'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
 
 ## Usage
 
-### One-to-one and One-to-many associations
+### Jsonb Associations
+
+#### One-to-One and One-to-Many associations
+
+To set up your jsonb column, you can use the built in `add_reference`/`table.references` function. This will only add a new store column if it doesn't already exist
+
+```bash
+rails g migration add_foreign_key_store_to_my_table
+```
+```ruby
+class AddForeignKeyStoreToMyTable < ActiveRecord::Migration[6.0]
+  def change
+    add_reference :my_table, :user, store: :extra # => store created
+    add_reference :my_table, :label, store: :extra, null: false # => store already exists, NOT NULL check constraint added to `store->'label_id'`
+    # NOTE: you can also use a `change_table(:my_table) block`
+  end
+end
+```
+
+and
+
+```ruby
+class CreateMyTable < ActiveRecord::Migration[6.0]
+  def change
+    create_table(:my_table) do |t|
+      t.references :user, store: :extra
+      t.references :label, store: :extra, null: false
+    end
+  end
+end
+```
+
+If you add the `jsonb_foreign_key` function to your database, you can also create a foreign_key **check** constraint by using the same built-in `:foreign_key` option used in normal reference definitions.
+
+**NOTE**: true foreign key references are not possible with jsonb attributes. This will instead create a CHECK constraint that looks for the referenced column using an `EXISTS` statement
+
+```bash
+rails g migration add_jsonb_foreign_key_function
+```
+```ruby
+class AddJsonbForeignKeyFunction < ActiveRecord::Migration[6.0]
+  def up
+    add_jsonb_foreign_key_function
+  end
+end
+```
+```ruby
+class CreateMyTable < ActiveRecord::Migration[6.0]
+  def change
+    create_table(:my_table) do |t|
+      t.references :user, store: :extra, foreign_key: true, null: false
+    end
+  end
+end
+```
+```ruby
+class CreateMyTable < ActiveRecord::Migration[6.0]
+  def change
+    create_table(:my_table) do |t|
+      t.references :person, store: :extra, foreign_key: { to_table: :users }, null: false
+    end
+  end
+end
+```
+
 
 You can store all foreign keys of your model in one JSONB column, without having to create multiple columns:
 
@@ -35,49 +116,87 @@ class User < ActiveRecord::Base
 end
 ```
 
-Foreign keys for association on one model have to be unique, even if they use different store column.
+### Many-to-Many associations
+
+Due to the ease of getting out-of-sync, and the complexity needed to build it, HABTM relation functionality has not been implemented through JSONB
+
+### jsonb_set based hash updates
 
-You can also use `add_references` in your migration to add JSONB column and index for it (if `index: true` option is set):
+When enabled, *only* keys present in the updated hash and with values changed in memory will be updated.
+To completely delete a `key/value` pair from an enabled attribute, set the key's value to `nil`.
+
+e.g.
 
 ```ruby
-add_reference :profiles, :users, store: :extra, index: true
+# given: instance#data == { "key_1"=>1,
+#                           "key_2"=>2,
+#                           "key_3"=> { "key_4"=>7,
+#                                       "key_5"=>8,
+#                                       "key_6"=>9 } }
+
+instance.update({ key_1: "asdf", a: 1, key_2: nil, key_3: { key_5: nil }})
+
+# instance#data => { "key_1"=>"asdf",
+#                    "a"=>"asdf",
+#                    "key_3"=> { "key_4"=>7,
+#                                "key_6"=>9 } }
 ```
 
-### Many-to-many associations
+#### enabling/adding attribute types
 
-Due to the ease of getting out-of-sync, and the complexity needed to build it, HABTM relation functionality has not been implemented through JSONB
+first, create the sql function
 
-#### Performance
+```bash
+rails g migration add_jsonb_nested_set_function
+```
+```ruby
+class AddJsonbNestedSetFunction < ActiveRecord::Migration[6.0]
+  def up
+    add_jsonb_nested_set_function
+  end
+end
+```
 
-Compared to regular associations, fetching models associated via JSONB column has no drops in performance.
+then in an initializer, enable key based updates:
 
-Getting the count of connected records is ~35% faster with associations via JSONB (tested on associations with up to 10 000 connections).
+```ruby
+# config/initializers/associate_jsonb.rb
+AssociateJsonb.enable_jsonb_set
+```
 
-Adding new connections is slightly faster with JSONB, for scopes up to 500 records connected to another record (total count of records in the table does not matter that much. If you have more then ~500 records connected to one record on average, and you want to add new records to the scope, JSONB associations will be slower then traditional:
+- Key based updates rely on inheritance for allowed attribute types. Any attributes that respond true to `attr_type.is_a?(GivenClass)` for any enabled type classes will use `jsonb_nested_set`
 
-<img src="https://github.com/lebedev-yury/associate_jsonb/blob/master/doc/images/adding-associations.png?raw=true | width=500" alt="JSONB HAMTB is slower on adding associations" width="600">
+- To add classes to the enabled list, pass them as arguments to `AssociateJsonb.add_hash_type(*klasses)`. Any arguments passed to `AssociateJsonb.enable_jsonb_set` are forwarded to `AssociateJsonb.add_hash_type`
 
-On the other hand, unassociating models from a big amount of associated models if faster with JSONB HABTM as the associations count grows:
+- By default, calling `AssociateJsonb.enable_jsonb_set(*klasses)` without arguments, and no classes previously added, adds `ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Jsonb` to the allowed classes list
 
-<img src="https://github.com/lebedev-yury/associate_jsonb/blob/master/doc/images/deleting-associations.png?raw=true | width=500" alt="JSONB HAMTB is faster on removing associations" width="600">
+#### disabling/removing attribute types
 
-## Installation
+- by default `jsonb_nested_set` updates are disabled.
 
-Add this line to your application's Gemfile:
+- if you've enabled them and need to disable, use: `AssociateJsonb.disable_jsonb_set`
 
-```ruby
-gem 'associate_jsonb'
-```
+- To remove a class from the allowed list while leaving nested set updates enabled, use `AssociateJsonb.remove_hash_type(*klasses)`.
+Any arguments passed to `AssociateJsonb.disable_jsonb_set` are forwarded to `AssociateJsonb.remove_hash_type`
 
-And then execute:
+### Automatically delete nil value hash keys
 
-```bash
-$ bundle install
+When jsonb_set updates are disabled, jsonb columns are replaced with the current document (i.e. default rails behavior)
+
+You are also given the option to automatically clear nil/null values from the hash automatically when jsonb_set is disabled
+
+in an initializer:
+
+```ruby
+# config/initializers/associate_jsonb.rb
+AssociateJsonb.jsonb_delete_nil = true
 ```
 
+Rules for classes to which this applies are the same as for `jsonb_nested_set`; add and remove classes through `AssociateJsonb.(add|remove)_hash_type(*klasses)`
+
 ## Developing
 
-To setup development environment, just run:
+To setup development environment, run:
 
 ```bash
 $ bin/setup
@@ -89,11 +208,6 @@ To run specs:
 $ bundle exec rspec
 ```
 
-To run benchmarks (that will take a while):
-
-```bash
-$ bundle exec rake benchmarks:habtm
-``` -->
-
 ## License
+
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -4,13 +4,11 @@ rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
-Rake.add_rakelib 'benchmarks'
-
 require 'rdoc/task'
 
 RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'AssociateJsonb::Associations'
+  rdoc.title    = 'AssociateJsonb'
   rdoc.options << '--line-numbers'
   rdoc.rdoc_files.include('README.md')
   rdoc.rdoc_files.include('lib/**/*.rb')

data/lib/associate_jsonb.rb

@@ -12,19 +12,121 @@ require "mutex_m"
 
 require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
-loader.inflector.inflect "supported_rails_version" => "SUPPORTED_RAILS_VERSION"
+loader.inflector.inflect(
+  "postgresql" => "PostgreSQL",
+  "supported_rails_version" => "SUPPORTED_RAILS_VERSION"
+)
+loader.collapse("#{__dir__}/associate_jsonb/connection_adapters/schema_definitions")
 loader.setup # ready!
 
 module AssociateJsonb
+  mattr_accessor :jsonb_hash_types,  default: []
+  mattr_accessor :jsonb_set_added,   default: [] # :nodoc:
+  mattr_accessor :jsonb_set_removed, default: [] # :nodoc:
+  mattr_accessor :jsonb_set_enabled, default: false
+  mattr_accessor :jsonb_delete_nil,  default: false
+  private_class_method :jsonb_hash_types=
+  private_class_method :jsonb_set_enabled=
+
+  def self.jsonb_oid_class # :nodoc:
+    :default
+  end
+  private_class_method :jsonb_oid_class
+
+  ##
+  # Enables the use of `jsonb_nested_set` for hash updates
+  #
+  # if passed a class, or a list of classes, those classes will be added todo
+  # the enabled classes. if no argument is given, and the enabled class list is
+  # empty, `ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Jsonb` is added
+  # to the list of enabled classes
+  def self.enable_jsonb_set(klass = nil, *classes)
+    if klass.nil?
+      add_hash_type jsonb_oid_class if jsonb_hash_types.empty?
+    else
+      add_hash_type(*Array(klass), *classes)
+    end
+    self.jsonb_set_enabled = true
+  end
+
+  ##
+  # Disables the use of `jsonb_nested_set` for hash updates
+  #
+  # if passed a class, or a list of classes, those classes will be removed from
+  # the list of enabled classes
+  def self.disable_jsonb_set(klass = nil, *classes)
+    remove_hash_type(*Array(klass), *classes) unless klass.nil?
+    self.jsonb_set_enabled = false
+  end
+
+  ##
+  # Add class(es) to the list of classes that are able to be upated when
+  # `jsonb_set_enabled` is true
+  def self.add_hash_type(*classes)
+    self.jsonb_set_added |= classes.flatten
+  end
+
+  ##
+  # Remove class(es) from the list of classes that are able to be upated when
+  # `jsonb_set_enabled` is true
+  def self.remove_hash_type(*classes)
+    self.jsonb_set_removed |= classes.flatten
+  end
+
+  ##
+  # Returns true if `jsonb_set_enabled` is true and the value is an enabled hash
+  # type
+  def self.merge_hash?(value)
+    !!jsonb_set_enabled && is_hash?(value)
+  end
+
+  ##
+  # Returns true if the given value is a descendant of any of the classes
+  # in `jsonb_hash_types`
+  def self.is_hash?(value)
+    !!value && self.jsonb_hash_types.any? { |type| value.is_a?(type) }
+  end
 end
 
-
 # rubocop:disable Metrics/BlockLength
 ActiveSupport.on_load :active_record do
   loader.eager_load
+  AssociateJsonb.module_eval do
+    redefine_method = proc {|name, hide = false, &block|
+      method(name).owner.remove_method name
+      if block
+        define_singleton_method(name, &block)
+        private_class_method name if hide
+      end
+    }
+
+    redefine_method.call(:jsonb_oid_class, true) do
+      ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Jsonb
+    end
+
+    redefine_method.call(:add_hash_type) do |*classes|
+      self.jsonb_hash_types |= classes.flatten
+    end
+
+    redefine_method.call(:remove_hash_type) do |*classes|
+      self.jsonb_hash_types -= classes.flatten
+    end
+
+    self.add_hash_type jsonb_set_added.map {|k| (k == :default) ? self.jsonb_oid_class : k}
+    self.remove_hash_type jsonb_set_removed
+
+    redefine_method.call(:jsonb_set_added)
+    redefine_method.call(:jsonb_set_added=)
+    redefine_method.call(:jsonb_set_removed)
+    redefine_method.call(:jsonb_set_removed=)
+    redefine_method = nil
+  end
+
 
   ActiveRecord::Base.include AssociateJsonb::WithStoreAttribute
   ActiveRecord::Base.include AssociateJsonb::Associations
+  ActiveRecord::Base.include AssociateJsonb::AttributeMethods
+  ActiveRecord::Base.include AssociateJsonb::Persistence
 
   Arel::Nodes.include AssociateJsonb::ArelNodes
 
@@ -40,6 +142,10 @@ ActiveSupport.on_load :active_record do
     AssociateJsonb::ArelExtensions::Table
   )
 
+  Arel::Visitors::PostgreSQL.prepend(
+    AssociateJsonb::ArelExtensions::Visitors::PostgreSQL
+  )
+
   Arel::Visitors::Visitor.singleton_class.prepend(
     AssociateJsonb::ArelExtensions::Visitors::Visitor
   )
@@ -81,11 +187,33 @@ ActiveSupport.on_load :active_record do
     AssociateJsonb::Associations::Preloader::Association
   )
 
-  # ActiveRecord::Associations::Preloader::HasMany.prepend(
-  #   AssociateJsonb::Associations::Preloader::HasMany
-  # )
+  %i[
+    AlterTable
+    ConstraintDefinition
+    ReferenceDefinition
+    SchemaCreation
+    Table
+    TableDefinition
+  ].each do |m|
+    includable = AssociateJsonb::ConnectionAdapters.const_get(m)
+    including =
+      begin
+        ActiveRecord::ConnectionAdapters::PostgreSQL.const_get(m)
+      rescue NameError
+        ActiveRecord::ConnectionAdapters.const_get(m)
+      end
+    including.prepend includable
+  rescue NameError
+    ActiveRecord::ConnectionAdapters::PostgreSQL.const_set(m, includable)
+  end
+
+  ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.include(
+    AssociateJsonb::ConnectionAdapters::SchemaStatements
+  )
+
 
   ActiveRecord::Reflection::AbstractReflection.prepend AssociateJsonb::Reflection
+  ActiveRecord::PredicateBuilder.prepend AssociateJsonb::PredicateBuilder
   ActiveRecord::Relation::WhereClause.prepend AssociateJsonb::Relation::WhereClause
 
   ActiveRecord::ConnectionAdapters::ReferenceDefinition.prepend(

data/lib/associate_jsonb/arel_extensions/table.rb

@@ -23,7 +23,7 @@ module AssociateJsonb
       def [](name)
         return super unless store_col = store_tracker&.get(name)
 
-        attr = ::Arel::Nodes::Jsonb::DashArrow.
+        attr = ::Arel::Nodes::Jsonb::DashDoubleArrow.
           new(self, self[store_col[:store]], store_col[:key])
 
         if cast_as = (store_col[:cast] && store_col[:cast][:sql_type])

data/lib/associate_jsonb/arel_extensions/visitors/postgresql.rb

@@ -0,0 +1,113 @@
+module AssociateJsonb
+  module ArelExtensions
+    module Visitors
+      module PostgreSQL
+        private
+          def collect_hash_changes(original, updated, nesting = nil)
+            keys = original.keys.map(&:to_s)
+            updated_keys = updated.keys.map(&:to_s)
+            keys |= updated_keys
+            original = original.with_indifferent_access
+            updated = updated.with_indifferent_access
+            added = []
+            deleted = []
+            finished = {}
+            keys.each do |k|
+              if updated[k].is_a?(Hash)
+                finished[k], a, d = collect_hash_changes(original[k].is_a?(Hash) ? original[k] : {}, updated[k], nesting ? "#{nesting},#{k}" : k)
+                a = [[(nesting ? "{#{nesting},#{k}}" : "{#{k}}"), {}]] if original[k].nil? && a.blank?
+                added |= a
+                deleted |= d
+              elsif updated[k].nil?
+                  deleted << (nesting ? "{#{nesting},#{k}}" : "{#{k}}") if updated_keys.include?(k)
+              elsif original[k] != updated[k]
+                finished[k] = updated[k]
+                added << [(nesting ? "{#{nesting},#{k}}" : "{#{k}}"), updated[k]]
+              end
+            end
+            [ finished, added, deleted ]
+          end
+
+          def is_hash?(type)
+            AssociateJsonb.is_hash? type
+          end
+
+          def is_update?(collector)
+            collector &&
+              Array(collector.value).any? {|v| v.is_a?(String) && (v =~ /UPDATE/) }
+          rescue
+            false
+          end
+
+          def is_insert?(collector)
+            collector &&
+              Array(collector.value).any? {|v| v.is_a?(String) && (v =~ /INSERT INTO/) }
+          rescue
+            false
+          end
+
+          def visit_BindHashChanges(t, collector)
+            changes, additions, deletions =
+              collect_hash_changes(
+                t.original_value.presence || {},
+                t.value.presence || {}
+              )
+
+            base_json = +"COALESCE(#{quote_column_name(t.name)}, '{}'::jsonb)"
+            json = base_json
+
+            deletions.each do |del|
+              json = +"(#{json} #- '#{del}')"
+            end
+
+            coalesced_paths = []
+            additions.sort.each do |add, value|
+              collector.add_bind(t.with_value_from_user(value)) do |i|
+                json = +"jsonb_nested_set(#{json},'#{add}', COALESCE($#{i}, '{}'::jsonb))"
+                ''
+              end
+            end
+
+            collector << json
+          end
+
+          def visit_Arel_Nodes_BindParam(o, collector)
+            catch(:nodes_bound) do
+              if AssociateJsonb.jsonb_set_enabled
+                catch(:not_hashable) do
+                  if is_hash?(o.value.type)
+                    if is_update?(collector)
+                      visit_BindHashChanges(o.value, collector)
+
+                      throw :nodes_bound, collector
+                    elsif is_insert?(collector)
+                      value = o.value
+
+                      value, _, _ =
+                        collect_hash_changes(
+                          {},
+                          value.value.presence || {}
+                        )
+                      throw :nodes_bound, collector.add_bind(o.value.with_cast_value(value)) { |i| "$#{i}"}
+                    else
+                      throw :not_hashable
+                    end
+                  else
+                    throw :not_hashable
+                  end
+                end
+              elsif AssociateJsonb.jsonb_delete_nil && is_hash?(o.value.type)
+                value, _, _ =
+                  collect_hash_changes(
+                    {},
+                    o.value.value.presence || {}
+                  )
+                throw :nodes_bound, collector.add_bind(o.value.with_cast_value(value)) { |i| "$#{i}" }
+              end
+              throw :nodes_bound, collector.add_bind(o.value) { |i| "$#{i}" }
+            end
+          end
+      end
+    end
+  end
+end