sequel 5.45.0 → 5.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b37b49ac4a53cefbee674e57e1b64f3733ee7c330d548c59e370efe6b557cc5a
-  data.tar.gz: 0f7de640673c6dff3affc0c494609d96502f62d36d7c6b639c4e3dba2d90a89f
+  metadata.gz: 8202d77fff48270013e8d06b75c5ab51933ff9e3fda72f99139211c9cb00de65
+  data.tar.gz: 15393a6189c83eb324e243d81805da38deced274d3f3a1b64bbf3cee54a27fa6
 SHA512:
-  metadata.gz: 342e7413e9a93cea694f1d1062803d4729b28f3d8adfc2f537ecd24dc988c448754c13046709d0a6505a78c0b21fb3383a1e5d55f73ee5e8364dbd0efb84fa7d
-  data.tar.gz: 9ea9cd35c75b670053804399f27475e38e28ea7b21062cf736e9bbea641c9d0862ef77edab6007d224a3a669a7469cab0c94658c4477e4d97a93c1c0355f031f
+  metadata.gz: 35aa602f835100be3a01bec05ecfb3a0d53555774d1dff520963c254d79c8123328f61e2252c8cb9c69b935f015de7c53f5cbeaec378d425666e7c96bcd0dba7
+  data.tar.gz: b52d0a0e2ea2fe6e388bd8fc694bac86d66f960cba0ed6c952213ba2414395862d3ba734b1763f13883ec7f7983cf69fe75a39a0f8e9406af46e2a2974f7210e

data/CHANGELOG

@@ -1,3 +1,9 @@
+=== 5.46.0 (2021-07-01)
+
+* Add unused_associations plugin, for determining which associations and association methods are not used (jeremyevans)
+
+* Make nil :setter/:adder/:remover/:clearer association options not create related methods (jeremyevans)
+
 === 5.45.0 (2021-06-01)
 
 * Fix handling of NULL values in boolean columns in the ODBC adapter (jeremyevans) (#1765)

data/README.rdoc

@@ -22,10 +22,9 @@ RDoc Documentation :: http://sequel.jeremyevans.net/rdoc
 Source Code :: https://github.com/jeremyevans/sequel
 Bug tracking (GitHub Issues) :: http://github.com/jeremyevans/sequel/issues
 Discussion Forum (sequel-talk Google Group) :: http://groups.google.com/group/sequel-talk
-IRC Channel (#sequel) :: irc://irc.freenode.net/sequel
 
 If you have questions about how to use Sequel, please ask on the
-sequel-talk Google Group or IRC.  Only use the the bug tracker to report
+sequel-talk Google Group.  Only use the the bug tracker to report
 bugs in Sequel, not to ask for help on using Sequel.
 
 To check out the source code:

data/doc/association_basics.rdoc

@@ -826,6 +826,8 @@ you also wanted to handle the Artist#add_album method:
     end)
   end
 
+You can set this to +nil+ to not create a add_<i>association</i> method.
+
 === :remover (\_remove_<i>association</i> method)
 
 Continuing with the same example, here's how you would handle the same case if
@@ -837,6 +839,8 @@ you also wanted to handle the Artist#remove_album method:
     end)
   end
 
+You can set this to +nil+ to not create a remove_<i>association</i> method.
+
 === :clearer (\_remove_all_<i>association</i> method)
 
 Continuing with the same example, here's how you would handle the same case if
@@ -850,6 +854,22 @@ you also wanted to handle the Artist#remove_all_albums method:
     end)
   end
 
+You can set this to +nil+ to not create a remove_all_<i>association</i> method.
+
+=== :no_dataset_method
+
+Setting this to true will not result in the <i>association</i>_dataset method
+not being defined. This can save memory if you only use the <i>association</i>
+method and do not call the <i>association</i>_dataset method directly or
+indirectly.
+
+=== :no_association_method
+
+Setting this to true will not result in the <i>association</i> method
+not being defined. This can save memory if you only use the
+<i>association</i>_dataset method and do not call the <i>association</i> method
+directly or indirectly.
+
 == Association Options
 
 Sequel's associations mostly share the same options.  For ease of understanding,
@@ -1638,9 +1658,8 @@ For +many_to_one+ and +one_to_one+ associations, do not add a setter method.
 For +one_to_many+ and +many_to_many+, do not add the add_<i>association</i>,
 remove_<i>association</i>, or remove_all_<i>association</i> methods.
 
-If the default modification methods would not do what you want, and you
-don't plan on overriding the internal modification methods to do what you
-want, it may be best to set this option to true.
+If you are not using the association modification methods, setting this
+value to true will save memory.
 
 ==== :validate
 

data/doc/release_notes/5.46.0.txt

@@ -0,0 +1,87 @@
+= New Features
+
+* An unused_associations plugin has been added, which allows you to
+  determine which associations and association methods are not used.
+  You can use this to avoid defining the unused associations and
+  association methods, which can save memory.
+
+  This plugin is supported on Ruby 2.5+, and uses method coverage to
+  determine if the plugin's methods are called.  Because Sequel::Model
+  adds association methods to an anonymous module included in the
+  class, directly using the method coverage data to determine which
+  associations are used is challenging.
+
+  This plugin is mostly designed for reporting.  You can have a
+  test suite that runs with method coverage enabled, and use the
+  coverage information to get data on unused associations:
+
+    # Calls Coverage.result
+    cov_data = Sequel::Model.update_associations_coverage
+    unused_associations_data = Sequel::Model.update_unused_associations_data(coverage_data: cov_data)
+    Sequel::Model.unused_associations(unused_associations_data: unused_associations_data)
+    # => [["Class1", "assoc1"], ...]
+
+  unused_associations returns an array of two element arrays, where
+  the first element is the class name and the second element is the
+  association name.  The returned values will be associations where
+  all of the association methods are not used.
+
+  In addition to determining which associations are not used, you can
+  also use this to determine if you are defining association methods
+  that are not used:
+
+    Sequel::Model.unused_association_options(unused_associations_data: unused_associations_data)
+    # => [["Class2", "assoc2", {:read_only=>true}], ...]
+
+  unused_association_options is similar to unused_associations, but
+  returns an array of three element arrays, where the third element
+  is a hash of association options that should be used to avoid
+  defining the unused association methods.  It's common in Sequel to
+  define associations and only use them for reading data and not for
+  modifications, and you can use this to easily see which associations
+  are only used for reading data.
+
+  As the determination of whether associations are used is based on
+  method coverage, this will report as unused any associations that are
+  used but where the association methods are not called.  These cases
+  are rare, but can happen if you have libraries that use the
+  association reflection metadata without calling the association
+  methods, or use the association only in combination with another
+  plugin such as dataset_associations.  You can set the :is_used
+  association option to explicitly mark an association as used, and
+  have this plugin avoid reporting it as unused.
+
+  In addition to just reporting on unused associations, you can also
+  directly use the unused associations metadata to automatically avoid
+  defining unused associations or unused associations methods.  You
+  can set a :file option when loading the plugin:
+
+    Sequel::Model.plugin :unused_associations, file: 'unused_associations.json'
+
+  Then run the method coverage testing.  This will save the unused
+  associations metadata to the file.  Then you can use this metadata
+  automatically by also setting the :modify_associations option:
+
+    Sequel::Model.plugin :unused_associations, file: 'unused_associations.json',
+      modify_associations: true
+
+  With the :modify_associations option, unused associations are
+  skipped instead of being defined, and the options returned by
+  unused_association_options are automatically used.  Note that using
+  the :modify_associations option is risky unless you have complete 
+  coverage and do not have cases where the associations are used
+  without calling methods.
+
+  It is common to have multiple test suites where you need to combine
+  coverage.  The plugin supports this by using a :coverage_file option:
+
+    Sequel::Model.plugin :unused_associations, coverage_file: 'unused_associations_coverage.json'
+
+  In this case, you would run update_associations_coverage after each
+  test suite, and update_unused_associations_data only after all test
+  suites have been run.
+
+* Passing nil as the value of the :setter, :adder, :remover, or
+  :clearer association options will cause the related method to not be
+  defined, instead of using the default value.  This allows you to
+  only define the methods you will actually be using.

data/lib/sequel/model/associations.rb

@@ -1595,6 +1595,7 @@ module Sequel
         # === Multiple Types
         # :adder :: Proc used to define the private _add_* method for doing the database work
         #           to associate the given object to the current object (*_to_many assocations).
+        #           Set to nil to not define a add_* method for the association.
         # :after_add :: Symbol, Proc, or array of both/either specifying a callback to call
         #               after a new item is added to the association.
         # :after_load :: Symbol, Proc, or array of both/either specifying a callback to call
@@ -1623,6 +1624,7 @@ module Sequel
         #                     the class.  <tt>class: 'Foo', class_namespace: 'Bar'</tt> looks for <tt>::Bar::Foo</tt>.)
         # :clearer :: Proc used to define the private _remove_all_* method for doing the database work
         #             to remove all objects associated to the current object (*_to_many assocations).
+        #             Set to nil to not define a remove_all_* method for the association.
         # :clone :: Merge the current options and block into the options and block used in defining
         #           the given association.  Can be used to DRY up a bunch of similar associations that
         #           all share the same options such as :class and :key, while changing the order and block used.
@@ -1677,7 +1679,7 @@ module Sequel
         # :graph_only_conditions :: The conditions to use on the SQL join when eagerly loading
         #                           the association via +eager_graph+, instead of the default conditions specified by the
         #                           foreign/primary keys.  This option causes the :graph_conditions option to be ignored.
-        # :graph_order :: Over the order to use when using eager_graph, instead of the default order.  This should be used
+        # :graph_order :: the order to use when using eager_graph, instead of the default order.  This should be used
         #                 in the case where :order contains an identifier qualified by the table's name, which may not match
         #                 the alias used when eager graphing.  By setting this to the unqualified identifier, it will be
         #                 automatically qualified when using eager_graph.
@@ -1689,6 +1691,10 @@ module Sequel
         #           limit (first element) and an offset (second element).
         # :methods_module :: The module that methods the association creates will be placed into. Defaults
         #                    to the module containing the model's columns.
+        # :no_association_method :: Do not add a method for the association. This can save memory if the association
+        #                           method is never used.
+        # :no_dataset_method :: Do not add a method for the association dataset. This can save memory if the dataset
+        #                       method is never used.
         # :order :: the column(s) by which to order the association dataset.  Can be a
         #           singular column symbol or an array of column symbols.
         # :order_eager_graph :: Whether to add the association's order to the graphed dataset's order when graphing
@@ -1701,6 +1707,7 @@ module Sequel
         #                the current association's key(s).  Set to nil to not use a reciprocal.
         # :remover :: Proc used to define the private _remove_* method for doing the database work
         #             to remove the association between the given object and the current object (*_to_many assocations).
+        #             Set to nil to not define a remove_* method for the association.
         # :select :: the columns to select.  Defaults to the associated class's table_name.* in an association
         #            that uses joins, which means it doesn't include the attributes from the
         #            join table.  If you want to include the join table attributes, you can
@@ -1709,6 +1716,7 @@ module Sequel
         #            the same name in both the join table and the associated table.
         # :setter :: Proc used to define the private _*= method for doing the work to setup the assocation
         #            between the given object and the current object (*_to_one associations).
+        #            Set to nil to not define a setter method for the association.
         # :subqueries_per_union :: The number of subqueries to use in each UNION query, for eager
         #                          loading limited associations using the default :union strategy.
         # :validate :: Set to false to not validate when implicitly saving any associated object.
@@ -1841,8 +1849,7 @@ module Sequel
           # Remove :class entry if it exists and is nil, to work with cached_fetch
           opts.delete(:class) unless opts[:class]
 
-          send(:"def_#{type}", opts)
-          def_association_instance_methods(opts)
+          def_association(opts)
       
           orig_opts.delete(:clone)
           opts[:orig_class] = orig_opts[:class] || orig_opts[:class_name]
@@ -1956,6 +1963,13 @@ module Sequel
           association_module(opts).send(:private, name)
         end
 
+        # Delegate to the type-specific association method to setup the
+        # association, and define the association instance methods.
+        def def_association(opts)
+          send(:"def_#{opts[:type]}", opts)
+          def_association_instance_methods(opts)
+        end
+        
         # Adds the association method to the association methods module.
         def def_association_method(opts)
           association_module_def(opts.association_method, opts) do |dynamic_opts=OPTS, &block|
@@ -1981,13 +1995,13 @@ module Sequel
             opts[:setter_method] = :"#{opts[:name]}="
           end
 
-          association_module_def(opts.dataset_method, opts){_dataset(opts)}
+          association_module_def(opts.dataset_method, opts){_dataset(opts)} unless opts[:no_dataset_method]
           if opts[:block]
             opts[:block_method] = Plugins.def_sequel_method(association_module(opts), "#{opts[:name]}_block", 1, &opts[:block])
           end
           opts[:dataset_opt_arity] = opts[:dataset].arity == 0 ? 0 : 1
           opts[:dataset_opt_method] = Plugins.def_sequel_method(association_module(opts), "#{opts[:name]}_dataset_opt", opts[:dataset_opt_arity], &opts[:dataset])
-          def_association_method(opts)
+          def_association_method(opts) unless opts[:no_association_method]
 
           return if opts[:read_only]
 
@@ -2075,50 +2089,60 @@ module Sequel
           return if opts[:read_only]
       
           if one_through_one
-            opts[:setter] ||= proc do |o|
-              h = {}
-              lh = lcks.zip(lcpks.map{|k| get_column_value(k)})
-              jtds = _join_table_dataset(opts).where(lh)
+            unless opts.has_key?(:setter)
+              opts[:setter] = proc do |o|
+                h = {}
+                lh = lcks.zip(lcpks.map{|k| get_column_value(k)})
+                jtds = _join_table_dataset(opts).where(lh)
 
-              checked_transaction do
-                current = jtds.first
+                checked_transaction do
+                  current = jtds.first
 
-                if o
-                  new_values = []
-                  rcks.zip(opts.right_primary_key_methods).each{|k, pk| new_values << (h[k] = o.get_column_value(pk))}
-                end
-
-                if current
-                  current_values = rcks.map{|k| current[k]}
-                  jtds = jtds.where(rcks.zip(current_values))
                   if o
-                    if current_values != new_values
-                      jtds.update(h)
+                    new_values = []
+                    rcks.zip(opts.right_primary_key_methods).each{|k, pk| new_values << (h[k] = o.get_column_value(pk))}
+                  end
+
+                  if current
+                    current_values = rcks.map{|k| current[k]}
+                    jtds = jtds.where(rcks.zip(current_values))
+                    if o
+                      if current_values != new_values
+                        jtds.update(h)
+                      end
+                    else
+                      jtds.delete
                     end
-                  else
-                    jtds.delete
+                  elsif o
+                    lh.each{|k,v| h[k] = v}
+                    jtds.insert(h)
                   end
-                elsif o
-                  lh.each{|k,v| h[k] = v}
-                  jtds.insert(h)
                 end
               end
             end
-            opts[:_setter] = proc{|o| set_one_through_one_associated_object(opts, o)}
+            if opts.fetch(:setter, true)
+              opts[:_setter] = proc{|o| set_one_through_one_associated_object(opts, o)}
+            end
           else 
-            opts[:adder] ||= proc do |o|
-              h = {}
-              lcks.zip(lcpks).each{|k, pk| h[k] = get_column_value(pk)}
-              rcks.zip(opts.right_primary_key_methods).each{|k, pk| h[k] = o.get_column_value(pk)}
-              _join_table_dataset(opts).insert(h)
+            unless opts.has_key?(:adder)
+              opts[:adder] = proc do |o|
+                h = {}
+                lcks.zip(lcpks).each{|k, pk| h[k] = get_column_value(pk)}
+                rcks.zip(opts.right_primary_key_methods).each{|k, pk| h[k] = o.get_column_value(pk)}
+                _join_table_dataset(opts).insert(h)
+              end
             end
 
-            opts[:remover] ||= proc do |o|
-              _join_table_dataset(opts).where(lcks.zip(lcpks.map{|k| get_column_value(k)}) + rcks.zip(opts.right_primary_key_methods.map{|k| o.get_column_value(k)})).delete
+            unless opts.has_key?(:remover)
+              opts[:remover] = proc do |o|
+                _join_table_dataset(opts).where(lcks.zip(lcpks.map{|k| get_column_value(k)}) + rcks.zip(opts.right_primary_key_methods.map{|k| o.get_column_value(k)})).delete
+              end
             end
 
-            opts[:clearer] ||= proc do
-              _join_table_dataset(opts).where(lcks.zip(lcpks.map{|k| get_column_value(k)})).delete
+            unless opts.has_key?(:clearer)
+              opts[:clearer] = proc do
+                _join_table_dataset(opts).where(lcks.zip(lcpks.map{|k| get_column_value(k)})).delete
+              end
             end
           end
         end
@@ -2175,8 +2199,12 @@ module Sequel
       
           return if opts[:read_only]
       
-          opts[:setter] ||= proc{|o| cks.zip(opts.primary_key_methods).each{|k, pk| set_column_value(:"#{k}=", (o.get_column_value(pk) if o))}}
-          opts[:_setter] = proc{|o| set_associated_object(opts, o)}
+          unless opts.has_key?(:setter)
+            opts[:setter] = proc{|o| cks.zip(opts.primary_key_methods).each{|k, pk| set_column_value(:"#{k}=", (o.get_column_value(pk) if o))}}
+          end
+          if opts.fetch(:setter, true)
+            opts[:_setter] = proc{|o| set_associated_object(opts, o)}
+          end
         end
         
         # Configures one_to_many and one_to_one association reflections and adds the related association methods
@@ -2243,49 +2271,59 @@ module Sequel
           cks.each{|k| ck_nil_hash[k] = nil}
 
           if one_to_one
-            opts[:setter] ||= proc do |o|
-              up_ds = _apply_association_options(opts, opts.associated_dataset.where(cks.zip(cpks.map{|k| get_column_value(k)})))
+            unless opts.has_key?(:setter)
+              opts[:setter] = proc do |o|
+                up_ds = _apply_association_options(opts, opts.associated_dataset.where(cks.zip(cpks.map{|k| get_column_value(k)})))
 
-              if (froms = up_ds.opts[:from]) && (from = froms[0]) && (from.is_a?(Sequel::Dataset) || (from.is_a?(Sequel::SQL::AliasedExpression) && from.expression.is_a?(Sequel::Dataset)))
-                if old = up_ds.first
-                  cks.each{|k| old.set_column_value(:"#{k}=", nil)}
+                if (froms = up_ds.opts[:from]) && (from = froms[0]) && (from.is_a?(Sequel::Dataset) || (from.is_a?(Sequel::SQL::AliasedExpression) && from.expression.is_a?(Sequel::Dataset)))
+                  if old = up_ds.first
+                    cks.each{|k| old.set_column_value(:"#{k}=", nil)}
+                  end
+                  save_old = true
                 end
-                save_old = true
-              end
 
-              if o
-                if !o.new? && !save_old
-                  up_ds = up_ds.exclude(o.pk_hash)
+                if o
+                  if !o.new? && !save_old
+                    up_ds = up_ds.exclude(o.pk_hash)
+                  end
+                  cks.zip(cpks).each{|k, pk| o.set_column_value(:"#{k}=", get_column_value(pk))}
                 end
-                cks.zip(cpks).each{|k, pk| o.set_column_value(:"#{k}=", get_column_value(pk))}
-              end
 
-              checked_transaction do
-                if save_old
-                  old.save(save_opts) || raise(Sequel::Error, "invalid previously associated object, cannot save") if old
-                else
-                  up_ds.skip_limit_check.update(ck_nil_hash)
-                end
+                checked_transaction do
+                  if save_old
+                    old.save(save_opts) || raise(Sequel::Error, "invalid previously associated object, cannot save") if old
+                  else
+                    up_ds.skip_limit_check.update(ck_nil_hash)
+                  end
 
-                o.save(save_opts) || raise(Sequel::Error, "invalid associated object, cannot save") if o
+                  o.save(save_opts) || raise(Sequel::Error, "invalid associated object, cannot save") if o
+                end
               end
             end
-            opts[:_setter] = proc{|o| set_one_to_one_associated_object(opts, o)}
+            if opts.fetch(:setter, true)
+              opts[:_setter] = proc{|o| set_one_to_one_associated_object(opts, o)}
+            end
           else 
             save_opts[:raise_on_failure] = opts[:raise_on_save_failure] != false
 
-            opts[:adder] ||= proc do |o|
-              cks.zip(cpks).each{|k, pk| o.set_column_value(:"#{k}=", get_column_value(pk))}
-              o.save(save_opts)
+            unless opts.has_key?(:adder)
+              opts[:adder] = proc do |o|
+                cks.zip(cpks).each{|k, pk| o.set_column_value(:"#{k}=", get_column_value(pk))}
+                o.save(save_opts)
+              end
             end
     
-            opts[:remover] ||= proc do |o|
-              cks.each{|k| o.set_column_value(:"#{k}=", nil)}
-              o.save(save_opts)
+            unless opts.has_key?(:remover)
+              opts[:remover] = proc do |o|
+                cks.each{|k| o.set_column_value(:"#{k}=", nil)}
+                o.save(save_opts)
+              end
             end
 
-            opts[:clearer] ||= proc do
-              _apply_association_options(opts, opts.associated_dataset.where(cks.zip(cpks.map{|k| get_column_value(k)}))).update(ck_nil_hash)
+            unless opts.has_key?(:clearer)
+              opts[:clearer] = proc do
+                _apply_association_options(opts, opts.associated_dataset.where(cks.zip(cpks.map{|k| get_column_value(k)}))).update(ck_nil_hash)
+              end
             end
           end
         end

data/lib/sequel/plugins/pg_array_associations.rb

@@ -384,26 +384,32 @@ module Sequel
           save_opts = {:validate=>opts[:validate]}
           save_opts[:raise_on_failure] = opts[:raise_on_save_failure] != false
 
-          opts[:adder] ||= proc do |o|
-            if array = o.get_column_value(key)
-              array << get_column_value(pk)
-            else
-              o.set_column_value("#{key}=", Sequel.pg_array([get_column_value(pk)], opts.array_type))
+          unless opts.has_key?(:adder)
+            opts[:adder] = proc do |o|
+              if array = o.get_column_value(key)
+                array << get_column_value(pk)
+              else
+                o.set_column_value("#{key}=", Sequel.pg_array([get_column_value(pk)], opts.array_type))
+              end
+              o.save(save_opts)
             end
-            o.save(save_opts)
           end
-  
-          opts[:remover] ||= proc do |o|
-            if (array = o.get_column_value(key)) && !array.empty?
-              array.delete(get_column_value(pk))
-              o.save(save_opts)
+    
+          unless opts.has_key?(:remover)
+            opts[:remover] = proc do |o|
+              if (array = o.get_column_value(key)) && !array.empty?
+                array.delete(get_column_value(pk))
+                o.save(save_opts)
+              end
             end
           end
 
-          opts[:clearer] ||= proc do
-            pk_value = get_column_value(pk)
-            db_type = opts.array_type
-            opts.associated_dataset.where(Sequel.pg_array_op(key).contains(Sequel.pg_array([pk_value], db_type))).update(key=>Sequel.function(:array_remove, key, Sequel.cast(pk_value, db_type)))
+          unless opts.has_key?(:clearer)
+            opts[:clearer] = proc do
+              pk_value = get_column_value(pk)
+              db_type = opts.array_type
+              opts.associated_dataset.where(Sequel.pg_array_op(key).contains(Sequel.pg_array([pk_value], db_type))).update(key=>Sequel.function(:array_remove, key, Sequel.cast(pk_value, db_type)))
+            end
           end
         end
 
@@ -486,30 +492,36 @@ module Sequel
             end
           end
 
-          opts[:adder] ||= proc do |o|
-            opk = o.get_column_value(opts.primary_key) 
-            if array = get_column_value(key)
-              modified!(key)
-              array << opk
-            else
-              set_column_value("#{key}=", Sequel.pg_array([opk], opts.array_type))
+          unless opts.has_key?(:adder)
+            opts[:adder] = proc do |o|
+              opk = o.get_column_value(opts.primary_key) 
+              if array = get_column_value(key)
+                modified!(key)
+                array << opk
+              else
+                set_column_value("#{key}=", Sequel.pg_array([opk], opts.array_type))
+              end
+              save_after_modify.call(self) if save_after_modify
             end
-            save_after_modify.call(self) if save_after_modify
           end
-  
-          opts[:remover] ||= proc do |o|
-            if (array = get_column_value(key)) && !array.empty?
-              modified!(key)
-              array.delete(o.get_column_value(opts.primary_key))
-              save_after_modify.call(self) if save_after_modify
+    
+          unless opts.has_key?(:remover)
+            opts[:remover] = proc do |o|
+              if (array = get_column_value(key)) && !array.empty?
+                modified!(key)
+                array.delete(o.get_column_value(opts.primary_key))
+                save_after_modify.call(self) if save_after_modify
+              end
             end
           end
 
-          opts[:clearer] ||= proc do
-            if (array = get_column_value(key)) && !array.empty?
-              modified!(key)
-              array.clear
-              save_after_modify.call(self) if save_after_modify
+          unless opts.has_key?(:clearer)
+            opts[:clearer] = proc do
+              if (array = get_column_value(key)) && !array.empty?
+                modified!(key)
+                array.clear
+                save_after_modify.call(self) if save_after_modify
+              end
             end
           end
         end

data/lib/sequel/plugins/unused_associations.rb

@@ -0,0 +1,500 @@
+# frozen-string-literal: true
+
+# :nocov:
+
+# This entire file is excluded from coverage testing.  This is because it
+# requires coverage testing to work, and if you've already loaded Sequel
+# without enabling coverage, then coverage testing won't work correctly
+# for methods defined by Sequel.
+#
+# While automated coverage testing is disabled, manual coverage testing
+# was used during spec development to make sure this code is 100% covered.
+
+if RUBY_VERSION < '2.5'
+  raise LoadError, "The Sequel unused_associations plugin depends on Ruby 2.5+ method coverage"
+end
+
+require 'coverage'
+require 'json'
+
+module Sequel
+  module Plugins
+    # The unused_associations plugin detects which model associations are not
+    # used and can be removed, and which model association methods are not used
+    # and can skip being defined. The advantage of removing unused associations
+    # and unused association methods is decreased memory usage, since each
+    # method defined takes memory and adds more work for the garbage collector.
+    #
+    # In order to detect which associations are used, this relies on the method
+    # coverage support added in Ruby 2.5. To allow flexibility to override
+    # association methods, the association methods that Sequel defines are
+    # defined in a module included in the class instead of directly in the
+    # class.  Unfortunately, that makes it difficult to directly use the
+    # coverage data to find unused associations. The advantage of this plugin
+    # is that it is able to figure out from the coverage information whether
+    # the association methods Sequel defines are actually used.
+    #
+    # = Basic Usage
+    #
+    # The expected usage of the unused_associations plugin is to load it
+    # into the base class for models in your application, which will often
+    # be Sequel::Model:
+    # 
+    #   Sequel::Model.plugin :unused_associations
+    #
+    # Then you run your test suite with method coverage enabled, passing the
+    # coverage result to +update_associations_coverage+.
+    # +update_associations_coverage+ returns a data structure containing
+    # method coverage information for all subclasses of the base class.
+    # You can pass the coverage information to
+    # +update_unused_associations_data+, which will return a data structure
+    # with information on unused associations.
+    #
+    #   require 'coverage'
+    #   Coverage.start(methods: true)
+    #   # load sequel after starting coverage, then run your tests
+    #   cov_data = Sequel::Model.update_associations_coverage
+    #   unused_associations_data = Sequel::Model.update_unused_associations_data(coverage_data: cov_data)
+    #
+    # You can take that unused association data and pass it to the
+    # +unused_associations+ method to get a array of information on
+    # associations which have not been used.  Each entry in the array
+    # will contain a class name and association name for each unused
+    # association, both as a string:
+    #
+    #   Sequel::Model.unused_associations(unused_associations_data: unused_associations_data)
+    #   # => [["Class1", "assoc1"], ...]
+    #
+    # You can use the output of the +unused_associations+ method to determine
+    # which associations are not used at all in your application, and can
+    # be eliminiated.
+    #
+    # You can also take that unused association data and pass it to the
+    # +unused_association_options+ method, which will return an array of
+    # information on associations which are used, but have related methods
+    # defined that are not used. The first two entries in each array are
+    # the class name and association name as a string, and the third
+    # entry is a hash of association options:
+    #
+    #   Sequel::Model.unused_association_options(unused_associations_data: unused_associations_data)
+    #   # => [["Class2", "assoc2", {:read_only=>true}], ...]
+    #
+    # You can use the output of the +unused_association_options+ to
+    # find out which association options can be provided when defining
+    # the association so that the association method will not define
+    # methods that are not used.
+    #
+    # = Combining Coverage Results
+    #
+    # It is common to want to combine results from multiple separate
+    # coverage runs.  For example, if you have multiple test suites
+    # for your application, one for model or unit tests and one for
+    # web or integration tests, you would want to combine the
+    # coverage information from all test suites before determining
+    # that the associations are not used.
+    #
+    # The unused_associations plugin supports combining multiple
+    # coverage results using the :coverage_file plugin option:
+    #
+    #   Sequel::Model.plugin :unused_associations,
+    #     coverage_file: 'unused_associations_coverage.json'
+    #
+    # With the coverage file option, +update_associations_coverage+
+    # will look in the given file for existing coverage information,
+    # if it exists.  If the file exists, the data from it will be
+    # merged with the coverage result passed to the method.
+    # Before returning, the coverage file will be updated with the
+    # merged result.  When using the :coverage_file plugin option,
+    # you can each of your test suites update the coverage
+    # information:
+    #
+    #   require 'coverage'
+    #   Coverage.start(methods: true)
+    #   # run this test suite
+    #   Sequel::Model.update_associations_coverage
+    #
+    # After all test suites have been run, you can run
+    # +update_unused_associations_data+, without an argument:
+    #
+    #   unused_associations_data = Sequel::Model.update_unused_associations_data
+    #
+    # With no argument, +update_unused_associations_data+ will get
+    # the coverage data from the coverage file, and then use that
+    # to prepare the information.  You can then use the returned
+    # value the same as before to get the data on unused associations.
+    # To prevent stale coverage information, calling
+    # +update_unused_associations_data+ when using the :coverage_file
+    # plugin option will remove the coverage file by default (you can
+    # use the :keep_coverage option to prevent the deletion of the
+    # coverage file).
+    #
+    # = Automatic Usage of Unused Association Data
+    #
+    # Since it can be a pain to manually update all of your code
+    # to remove unused assocations or add options to prevent the
+    # definition of unused associations, the unused_associations
+    # plugin comes with support to take previously saved unused
+    # association data, and use it to not create unused associations,
+    # and to automatically use the appropriate options so that unused
+    # association methods are not created.
+    #
+    # To use this option, you first need to save the unused association
+    # data previously prepared.  You can do this by passing an
+    # :file option when loading the plugin.  
+    #
+    #   Sequel::Model.plugin :unused_associations,
+    #     file: 'unused_associations.json'
+    #
+    # With the :file option provided, you no longer need to use
+    # the return value of +update_unused_associations_data+, as
+    # the file will be updated with the information:
+    #
+    #   Sequel::Model.update_unused_associations_data(coverage_data: cov_data)
+    #
+    # Then, to use the saved unused associations data, add the
+    # :modify_associations plugin option:
+    #
+    #   Sequel::Model.plugin :unused_associations,
+    #     file: 'unused_associations.json',
+    #     modify_associations: true
+    #
+    # With the :modify_associations used, and the unused association
+    # data file is available, when subclasses attempt to create an
+    # unused association, the attempt will be ignored.  If the
+    # subclasses attempt to create an association where not
+    # all association methods are used, the plugin will automatically
+    # set the appropriate options so that the unused association
+    # methods are not defined.
+    #
+    # When you are testing which associations are used, make sure
+    # not to set the :modify_associations plugin option, or make sure
+    # that the unused associations data file does not exist.
+    #
+    # == Automatic Usage with Combined Coverage Results
+    #
+    # If you have multiple test suites and want to automatically
+    # use the unused association data, you should provide both
+    # :file and :coverage_file options when loading the plugin:
+    #
+    #   Sequel::Model.plugin :unused_associations,
+    #     file: 'unused_associations.json',
+    #     coverage_file: 'unused_associations_coverage.json'
+    #
+    # Then each test suite just needs to run
+    # +update_associations_coverage+ to update the coverage information:
+    #
+    #   Sequel::Model.update_associations_coverage
+    #
+    # After all test suites have been run, you can run
+    # +update_unused_associations_data+ to update the unused
+    # association data file (and remove the coverage file):
+    #
+    #   Sequel::Model.update_unused_associations_data
+    #
+    # Then you can add the :modify_associations plugin option to
+    # automatically use the unused association data.
+    #
+    # = Caveats
+    #
+    # Since this plugin is based on coverage information, if you do
+    # not have tests that cover all usage of associations in your
+    # application, you can end up with coverage that shows the
+    # association is not used, when it is used in code that is not
+    # covered.  The output of plugin can still be useful in such cases,
+    # as long as you are manually checking it.  However, you should
+    # avoid using the :modify_associations unless you have
+    # confidence that your tests cover all usage of associations
+    # in your application. You can specify the :is_used association
+    # option for any association that you know is used. If an
+    # association uses the :is_used association option, this plugin
+    # will not modify it if the :modify_associations option is used.
+    #
+    # This plugin does not handle anonymous classes. Any unused
+    # associations defined in anonymous classes will not be
+    # reported by this plugin.
+    #
+    # This plugin only considers the public instance methods the
+    # association defines to determine if it was used.  If an
+    # association is used in a way that does not call an instance
+    # method (such as only using the association with the
+    # dataset_associations plugin), then it would show up as unused
+    # by this plugin.
+    #
+    # As this relies on the method coverage added in Ruby 2.5, it does
+    # not work on older versions of Ruby.  It also does not work on
+    # JRuby, as JRuby does not implement method coverage.
+    module UnusedAssociations
+      # Load the subclasses plugin, as the unused associations plugin
+      # is designed to handle all subclasses of the class it is loaded
+      # into.
+      def self.apply(mod, opts=OPTS)
+        mod.plugin :subclasses
+      end
+
+      # Plugin options:
+      # :coverage_file :: The file to store the coverage information,
+      #                   when combining coverage information from
+      #                   multiple test suites.
+      # :file :: The file to store and/or load the unused associations data.
+      # :modify_associations :: Whether to use the unused associations data
+      #                         to skip defining associations or association
+      #                         methods.
+      # :unused_associations_data :: The unused associations data to use if the
+      #                              :modify_associations is used (by default, the
+      #                              :modify_associations option will use the data from
+      #                              the file specified by the :file option). This is
+      #                              same data returned by the
+      #                              +update_unused_associations_data+ method.
+      def self.configure(mod, opts=OPTS)
+        mod.instance_exec do
+          @unused_associations_coverage_file = opts[:coverage_file]
+          @unused_associations_file = opts[:file]
+          @unused_associations_data = if opts[:modify_associations]
+            if opts[:unused_associations_data]
+              opts[:unused_associations_data]
+            elsif File.file?(opts[:file])
+              Sequel.parse_json(File.binread(opts[:file]))
+            end
+          end
+        end
+      end
+
+      module ClassMethods
+        # Only the data is copied to subclasses, to allow the :modify_associations
+        # plugin option to affect them.  The :file and :coverage_file are not copied
+        # to subclasses, as users are expected ot call methods such as
+        # unused_associations only on the class that is loading the plugin.
+        Plugins.inherited_instance_variables(self, :@unused_associations_data=>nil)
+
+        # If modifying associations, and this association is marked as not used,
+        # and the association does not include the specific :is_used option,
+        # skip defining the association.
+        def associate(type, assoc_name, opts=OPTS)
+          if !opts[:is_used] && @unused_associations_data && (data = @unused_associations_data[name]) && data[assoc_name.to_s] == 'unused'
+            return
+          end
+          
+          super
+        end
+
+        # Parse the coverage result, and return the coverage data for the
+        # associations for descendants of this class. If the plugin
+        # uses the :coverage_file option, the existing coverage file will be loaded
+        # if present, and before the method returns, the coverage file will be updated.
+        #
+        # Options:
+        # :coverage_result :: The coverage result to use. This defaults to +Coverage.result+.
+        def update_associations_coverage(opts=OPTS)
+          coverage_result = opts[:coverage_result] || Coverage.result
+          module_mapping = {}
+          file = @unused_associations_coverage_file
+
+          coverage_data = if file && File.file?(file)
+            Sequel.parse_json(File.binread(file))
+          else
+            {}
+          end
+
+          ([self] + descendents).each do |sc|
+            next if sc.associations.empty? || !sc.name
+            module_mapping[sc.send(:overridable_methods_module)] = sc
+            coverage_data[sc.name] ||= {}
+          end
+
+          coverage_result.each do |file, coverage|
+            coverage[:methods].each do |(mod, meth), times|
+              next unless sc = module_mapping[mod]
+              coverage_data[sc.name][meth.to_s] ||= 0
+              coverage_data[sc.name][meth.to_s] += times
+            end
+          end
+
+          if file
+            File.binwrite(file, Sequel.object_to_json(coverage_data))
+          end
+
+          coverage_data
+        end
+
+        # Parse the coverage data returned by #update_associations_coverage,
+        # and return data on unused associations and unused association methods.
+        #
+        # Options:
+        # :coverage_data :: The coverage data to use. If not given, it is taken
+        #                   from the file specified by the :coverage_file plugin option.
+        # :keep_coverage :: Do not delete the file specified by the :coverage_file plugin
+        #                   option, even if it exists.
+        def update_unused_associations_data(options=OPTS)
+          coverage_data = options[:coverage_data] || Sequel.parse_json(File.binread(@unused_associations_coverage_file))
+
+          unused_associations_data = {}
+
+          ([self] + descendents).each do |sc|
+            next unless cov_data = coverage_data[sc.name]
+
+            sc.associations.each do |assoc|
+              ref = sc.association_reflection(assoc)
+
+              # Only report associations for the class they are defined in
+              next unless ref[:model] == sc
+
+              # Do not report associations using methods_module option, because this plugin only
+              # looks in the class's overridable_methods_module
+              next if ref[:methods_module]
+
+              info = {}
+
+              _update_association_coverage_info(info, cov_data, ref.dataset_method, :dataset_method)
+              _update_association_coverage_info(info, cov_data, ref.association_method, :association_method)
+
+              unless ref[:orig_opts][:read_only]
+                if ref.returns_array?
+                  _update_association_coverage_info(info, cov_data, ref[:add_method], :adder)
+                  _update_association_coverage_info(info, cov_data, ref[:remove_method], :remover)
+                  _update_association_coverage_info(info, cov_data, ref[:remove_all_method], :clearer)
+                else
+                  _update_association_coverage_info(info, cov_data, ref[:setter_method], :setter)
+                end
+              end
+
+              next if info.keys == [:missing]
+
+              if !info[:used]
+                (unused_associations_data[sc.name] ||= {})[assoc.to_s] = 'unused'
+              elsif unused = info[:unused]
+                if unused.include?(:setter) || [:adder, :remover, :clearer].all?{|k| unused.include?(k)}
+                  [:setter, :adder, :remover, :clearer].each do |k|
+                    unused.delete(k)
+                  end
+                  unused << :read_only
+                end
+                (unused_associations_data[sc.name] ||= {})[assoc.to_s] = unused.map(&:to_s)
+              end
+            end
+          end
+
+          if @unused_associations_file
+            File.binwrite(@unused_associations_file, Sequel.object_to_json(unused_associations_data))
+          end
+          unless options[:keep_coverage]
+            _delete_unused_associations_file(@unused_associations_coverage_file)
+          end
+
+          unused_associations_data
+        end
+
+        # Return an array of unused associations.  These are associations where none of the
+        # association methods are used, according to the coverage information.  Each entry
+        # in the array is an array of two strings, with the first string being the class name
+        # and the second string being the association name.
+        #
+        # Options:
+        # :unused_associations_data :: The data to use for determining which associations
+        #                              are unused, which is returned from
+        #                              +update_unused_associations_data+. If not given,
+        #                              loads the data from the file specified by the :file
+        #                              plugin option.
+        def unused_associations(opts=OPTS)
+          unused_associations_data = opts[:unused_associations_data] || Sequel.parse_json(File.binread(@unused_associations_file))
+
+          unused_associations = []
+          unused_associations_data.each do |sc, associations|
+            associations.each do |assoc, unused|
+              if unused == 'unused'
+                unused_associations << [sc, assoc]
+              end
+            end
+          end
+          unused_associations
+        end
+
+        # Return an array of unused association options.  These are associations some but not all
+        # of the association methods are used, according to the coverage information. Each entry
+        # in the array is an array of three elements.  The first element is the class name string,
+        # the second element is the association name string, and the third element is a hash of
+        # association options that can be used in the association so it does not define methods
+        # that are not used.
+        #
+        # Options:
+        # :unused_associations_data :: The data to use for determining which associations
+        #                              are unused, which is returned from
+        #                              +update_unused_associations_data+. If not given,
+        #                              loads the data from the file specified by the :file
+        #                              plugin option.
+        def unused_association_options(opts=OPTS)
+          unused_associations_data = opts[:unused_associations_data] || Sequel.parse_json(File.binread(@unused_associations_file))
+
+          unused_association_methods = []
+          unused_associations_data.each do |sc, associations|
+            associations.each do |assoc, unused|
+              unless unused == 'unused'
+                unused_association_methods << [sc, assoc, set_unused_options_for_association({}, unused)]
+              end
+            end
+          end
+          unused_association_methods
+        end
+
+        # Delete the unused associations coverage file and unused associations data file,
+        # if either exist.
+        def delete_unused_associations_files
+          _delete_unused_associations_file(@unused_associations_coverage_file)
+          _delete_unused_associations_file(@unused_associations_file)
+        end
+
+        private
+
+        # Delete the given file if it exists.
+        def _delete_unused_associations_file(file)
+          if file && File.file?(file)
+            File.unlink(file)
+          end
+        end
+
+        # Update the info hash with information on whether the given method was
+        # called, according to the coverage information.
+        def _update_association_coverage_info(info, coverage_data, meth, key)
+          type = case coverage_data[meth.to_s]
+          when 0
+            :unused
+          when Integer
+            :used
+          else
+            # Missing here means there is no coverage information for the
+            # the method, which indicates the expected method was never
+            # defined.  In that case, it can be ignored.
+            :missing
+          end
+
+          (info[type] ||= []) << key
+        end
+
+        # Based on the value of the unused, update the opts hash with association
+        # options that will prevent unused association methods from being
+        # defined.
+        def set_unused_options_for_association(opts, unused)
+          opts[:read_only] = true if unused.include?('read_only')
+          opts[:no_dataset_method] = true if unused.include?('dataset_method')
+          opts[:no_association_method] = true if unused.include?('association_method')
+          opts[:adder] = nil if unused.include?('adder')
+          opts[:remover] = nil if unused.include?('remover')
+          opts[:clearer] = nil if unused.include?('clearer')
+          opts
+        end
+
+        # If modifying associations, and this association has unused association
+        # methods, automatically set the appropriate options so the unused association
+        # methods are not defined, unless the association explicitly uses the :is_used
+        # options.
+        def def_association(opts)
+          if !opts[:is_used] && @unused_associations_data && (data = @unused_associations_data[name]) && (unused = data[opts[:name].to_s])
+            set_unused_options_for_association(opts, unused)
+          end
+          
+          super
+        end
+      end
+    end
+  end
+end
+# :nocov:

data/lib/sequel/version.rb

@@ -6,7 +6,7 @@ module Sequel
 
   # The minor version of Sequel.  Bumped for every non-patch level
   # release, generally around once a month.
-  MINOR = 45
+  MINOR = 46
 
   # The tiny version of Sequel.  Usually 0, only bumped for bugfix
   # releases that fix regressions from previous versions.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sequel
 version: !ruby/object:Gem::Version
-  version: 5.45.0
+  version: 5.46.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-01 00:00:00.000000000 Z
+date: 2021-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -189,6 +189,7 @@ extra_rdoc_files:
 - doc/release_notes/5.43.0.txt
 - doc/release_notes/5.44.0.txt
 - doc/release_notes/5.45.0.txt
+- doc/release_notes/5.46.0.txt
 - doc/release_notes/5.5.0.txt
 - doc/release_notes/5.6.0.txt
 - doc/release_notes/5.7.0.txt
@@ -262,6 +263,7 @@ files:
 - doc/release_notes/5.43.0.txt
 - doc/release_notes/5.44.0.txt
 - doc/release_notes/5.45.0.txt
+- doc/release_notes/5.46.0.txt
 - doc/release_notes/5.5.0.txt
 - doc/release_notes/5.6.0.txt
 - doc/release_notes/5.7.0.txt
@@ -528,6 +530,7 @@ files:
 - lib/sequel/plugins/tree.rb
 - lib/sequel/plugins/typecast_on_load.rb
 - lib/sequel/plugins/unlimited_update.rb
+- lib/sequel/plugins/unused_associations.rb
 - lib/sequel/plugins/update_or_create.rb
 - lib/sequel/plugins/update_primary_key.rb
 - lib/sequel/plugins/update_refresh.rb