associate_jsonb 0.0.2 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b7b0080eb6128847d7f71444d31f97bd2b4d09ebd9e0611901867e6a7812b1d
-  data.tar.gz: b3f85301fb398025f1cd732987035def7a79ba743fe51f9c1df337a1992848bd
+  metadata.gz: 9d9a2ca078138c49415e16c98a42191a1545502f41033ab7ec73494352fda01c
+  data.tar.gz: 312f1fa2f579903c190ec72a875a000f44f32cdb9df0e218e5b276a902bb4a92
 SHA512:
-  metadata.gz: 30312348d528402aa1fb3da6c00c0f12cd9cc13fb76d1f5f2a9410d908c69aecf2eadb662d7a243f6fa486bbea093c78de8b8a0806a91390da1c9f75c4e4b0fd
-  data.tar.gz: 485c25f17feda5fdaeab8d105f923470ed28a13f73c07c851854dc6af86a86d1dcf044598748ca3a2abdca1eb64d3550734a017a941ebb64373cda8eaf10b296
+  metadata.gz: 524b2455ff9c493b76605d232af61e4dcb576b1262814d13c200db7a686026230be11f837230eb6116be1c0c8d6043360cf2f22c14209ce323d8fc7875760316
+  data.tar.gz: a76a0db4c95e3be203c397290f95110a5b8dce02a65c0fe6097df293be149e47e0d3252bf07482f679b562755f271e462f314635f3ce69ac5178a096de64965e

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,22 +12,106 @@ 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_removed, default: []
+  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.enable_jsonb_set(klass = nil, *classes)
+    add_hash_type(*Array(klass), *classes) unless klass.nil?
+    self.jsonb_set_enabled = true
+  end
+
+  def self.disable_jsonb_set(klass = nil, *classes)
+    remove_hash_type(*Array(klass), *classes) unless klass.nil?
+    self.jsonb_set_enabled = false
+  end
+
+  def self.add_hash_type(*classes)
+    self.jsonb_hash_types |= classes.flatten
+  end
+
+  def self.remove_hash_type(*classes)
+    self.jsonb_set_removed |= classes.flatten
+  end
+
+  def self.merge_hash?(v)
+    return false unless jsonb_set_enabled && v
+    self.jsonb_hash_types.any? { |type| v.is_a?(type) }
+  end
+
+  def self.is_hash?(v)
+    self.jsonb_hash_types.any? { |type| v.is_a?(type) }
+  end
 end
 
 
 # rubocop:disable Metrics/BlockLength
 ActiveSupport.on_load :active_record do
   loader.eager_load
+  AssociateJsonb.class_eval do
+    def self.enable_jsonb_set(klass = nil, *classes)
+      if klass.nil?
+        add_hash_type ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Jsonb if jsonb_hash_types.empty?
+      else
+        add_hash_type |= [*Array(klass), *classes].flatten
+      end
+      self.jsonb_set_enabled = true
+    end
+
+    self.enable_jsonb_set if jsonb_set_enabled
+
+    def self.remove_hash_type(*classes)
+      self.jsonb_hash_types -= classes.flatten
+    end
+    removed = jsonb_set_removed
+    self.remove_hash_type removed
+    self.send :remove_method, :jsonb_set_removed
+    self.send :remove_method, :jsonb_set_removed=
+  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
-  Arel::Nodes::Binary.include AssociateJsonb::ArelNodeExtensions::Binary
+
+  Arel::Nodes::Binary.prepend(
+    AssociateJsonb::ArelExtensions::Nodes::Binary
+  )
+
+  Arel::Nodes::TableAlias.prepend(
+    AssociateJsonb::ArelExtensions::Nodes::TableAlias
+  )
+
+  Arel::Table.prepend(
+    AssociateJsonb::ArelExtensions::Table
+  )
+
+  Arel::Visitors::PostgreSQL.prepend(
+    AssociateJsonb::ArelExtensions::Visitors::PostgreSQL
+  )
+
+  Arel::Visitors::Visitor.singleton_class.prepend(
+    AssociateJsonb::ArelExtensions::Visitors::Visitor
+  )
+
+
+  ActiveRecord::Associations::AliasTracker.prepend(
+    AssociateJsonb::Associations::AliasTracker
+  )
 
   ActiveRecord::Associations::Builder::BelongsTo.extend(
     AssociateJsonb::Associations::Builder::BelongsTo
@@ -64,8 +148,33 @@ ActiveSupport.on_load :active_record do
   # 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/nodes/binary.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module AssociateJsonb
+  module ArelExtensions
+    module Nodes
+      module Binary
+        def original_left
+          left
+        end
+      end
+    end
+  end
+end

data/lib/associate_jsonb/arel_extensions/nodes/table_alias.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module AssociateJsonb
+  module ArelExtensions
+    module Nodes
+      module TableAlias
+        attr_reader :store_tracker
+
+        def initialize(*args, store_columns: nil)
+          @store_columns = store_columns
+          super(*args)
+        end
+
+        def with_store_tracker(tracker)
+          @store_tracker = tracker
+          self
+        end
+
+        def [](name)
+          return super unless store_col = store_tracker&.get(name)
+
+          attr = ::Arel::Nodes::Jsonb::DashArrow.
+            new(self, self[store_col[:store]], store_col[:key])
+
+          if cast_as = (store_col[:cast] && store_col[:cast][:sql_type])
+            attr = ::Arel::Nodes::NamedFunction.new(
+              "CAST",
+              [ attr.as(cast_as) ]
+            )
+          end
+
+          Arel::Nodes::Jsonb::Attribute.new(self, name, attr)
+        end
+      end
+    end
+  end
+end

data/lib/associate_jsonb/arel_extensions/table.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module AssociateJsonb
+  module ArelExtensions
+    module Table
+      attr_reader :store_tracker
+
+      def initialize(*args, store_tracker: nil, **opts)
+        @store_tracker = store_tracker
+        super(*args, **opts)
+      end
+
+      def alias(...)
+        super(...).with_store_tracker(store_tracker)
+      end
+
+      def with_store_tracker(tracker)
+        @store_tracker = tracker
+        self
+      end
+
+      def [](name)
+        return super unless store_col = store_tracker&.get(name)
+
+        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])
+          attr = ::Arel::Nodes::NamedFunction.new(
+            "CAST",
+            [ attr.as(cast_as) ]
+          )
+        end
+
+        Arel::Nodes::Jsonb::Attribute.new(self, name, attr)
+      end
+    end
+  end
+end