sequel 4.26.0 → 5.37.0

data/lib/sequel/plugins/association_dependencies.rb

@@ -1,12 +1,14 @@
+# frozen-string-literal: true
+
 module Sequel
   module Plugins
-    # The AssociationDependencies plugin allows you do easily set up before and/or after destroy hooks
+    # The association_dependencies plugin allows you do easily set up before and/or after destroy hooks
     # for destroying, deleting, or nullifying associated model objects.  The following
     # association types support the following dependency actions:
     # 
-    # * :many_to_many - :nullify (removes all related entries in join table)
-    # * :many_to_one - :delete, :destroy
-    # * :one_to_many, one_to_one - :delete, :destroy, :nullify (sets foreign key to NULL for all associated objects)
+    # :many_to_many :: :nullify (removes all related entries in join table)
+    # :many_to_one :: :delete, :destroy
+    # :one_to_many, one_to_one :: :delete, :destroy, :nullify (sets foreign key to NULL for all associated objects)
     #
     # This plugin works directly with the association datasets and does not use any cached association values.
     # The :delete action will delete all associated objects from the database in a single SQL call.
@@ -16,21 +18,21 @@ module Sequel
     # and dependency action values.  You can provide the hash to the plugin call itself or
     # to the add_association_dependencies method:
     #
-    #   Business.plugin :association_dependencies, :address=>:delete
+    #   Business.plugin :association_dependencies, address: :delete
     #   # or:
     #   Artist.plugin :association_dependencies
-    #   Artist.add_association_dependencies :albums=>:destroy, :reviews=>:delete, :tags=>:nullify
+    #   Artist.add_association_dependencies albums: :destroy, reviews: :delete, tags: :nullify
     module AssociationDependencies
       # Mapping of association types to when the dependency calls should be made (either
       # :before for in before_destroy or :after for in after_destroy)
-      ASSOCIATION_MAPPING = {:one_to_many=>:before, :many_to_one=>:after, :many_to_many=>:before, :one_to_one=>:before}
+      ASSOCIATION_MAPPING = {:one_to_many=>:before, :many_to_one=>:after, :many_to_many=>:before, :one_to_one=>:before}.freeze
 
       # The valid dependence actions
-      DEPENDENCE_ACTIONS = [:delete, :destroy, :nullify]
+      DEPENDENCE_ACTIONS = [:delete, :destroy, :nullify].freeze
 
       # Initialize the association_dependencies hash for this model.
       def self.apply(model, hash=OPTS)
-        model.instance_eval{@association_dependencies = {:before_delete=>[], :before_destroy=>[], :before_nullify=>[], :after_delete=>[], :after_destroy=>[]}}
+        model.instance_exec{@association_dependencies = {:before_delete=>[], :before_destroy=>[], :before_nullify=>[], :after_delete=>[], :after_destroy=>[]}}
       end
 
       # Call add_association_dependencies with any dependencies given in the plugin call.
@@ -48,7 +50,7 @@ module Sequel
         attr_reader :association_dependencies
 
         # Add association dependencies to this model.  The hash should have association name
-        # symbol keys and dependency action symbol values (e.g. :albums=>:destroy).
+        # symbol keys and dependency action symbol values (e.g. albums: :destroy).
         def add_association_dependencies(hash)
           hash.each do |association, action|
             raise(Error, "Nonexistent association: #{association}") unless r = association_reflection(association)
@@ -58,19 +60,26 @@ module Sequel
             association_dependencies[:"#{time}_#{action}"] << if action == :nullify
               case type
               when :one_to_many , :many_to_many
-                proc{send(r.remove_all_method)}
+                [r[:remove_all_method]]
               when :one_to_one
-                proc{send(r.setter_method, nil)}
+                [r[:setter_method], nil]
               else
                 raise(Error, "Can't nullify many_to_one associated objects: association: #{association}")
               end
             else
               raise(Error, "Can only nullify many_to_many associations: association: #{association}") if type == :many_to_many
-              r.dataset_method
+              r[:dataset_method]
             end
           end
         end
 
+        # Freeze association dependencies when freezing model class.
+        def freeze
+          @association_dependencies.freeze.each_value(&:freeze)
+
+          super
+        end
+
         Plugins.inherited_instance_variables(self, :@association_dependencies=>:hash_dup)
       end
 
@@ -79,16 +88,16 @@ module Sequel
         # many_to_one associations.
         def after_destroy
           super
-          model.association_dependencies[:after_delete].each{|m| send(m).delete}
-          model.association_dependencies[:after_destroy].each{|m| send(m).destroy}
+          model.association_dependencies[:after_delete].each{|m| public_send(m).delete}
+          model.association_dependencies[:after_destroy].each{|m| public_send(m).destroy}
         end
 
         # Run the delete, destroy, and nullify association dependency actions for
         # *_to_many associations.
         def before_destroy
-          model.association_dependencies[:before_delete].each{|m| send(m).delete}
-          model.association_dependencies[:before_destroy].each{|m| send(m).destroy}
-          model.association_dependencies[:before_nullify].each{|p| instance_eval(&p)}
+          model.association_dependencies[:before_delete].each{|m| public_send(m).delete}
+          model.association_dependencies[:before_destroy].each{|m| public_send(m).destroy}
+          model.association_dependencies[:before_nullify].each{|args| public_send(*args)}
           super
         end
       end

data/lib/sequel/plugins/association_lazy_eager_option.rb

@@ -0,0 +1,66 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The association_lazy_eager_option plugin supports passing
+    # an +:eager+ option to an association method.  If the related
+    # association is already cached, the cached version will be
+    # returned.  If the association is not already cached, it will
+    # be loaded, and the value of the +:eager+ option will be used
+    # to perform an eager load of the given associations.
+    # the plural versions.
+    #
+    # With Sequel's default behavior, you can already perform an
+    # eager load when lazy loading using a block:
+    #
+    #   obj.association{|ds| ds.eager(:nested_association)}
+    #
+    # However, this will ignore any cached version.  In more
+    # complex software, the association may already be cached
+    # and have the nested association cached inside of it, and
+    # using this callback approach then requires 2 unnecessary
+    # queries. This plugin will not perform any queries if the
+    # association is already cached, preventing duplicate work.
+    # However, you should make sure that an already loaded
+    # association has the nested association already eagerly
+    # loaded.
+    # 
+    # Usage:
+    #
+    #   # Make all model subclasses support the :eager association
+    #   # method option (called before loading subclasses)
+    #   Sequel::Model.plugin :association_lazy_eager_option
+    #
+    #   # Make the Album class support the :eager association
+    #   # method option
+    #   Album.plugin :association_lazy_eager_option
+    module AssociationLazyEagerOption
+      module InstanceMethods
+        private
+
+        # Return a dataset for the association after applying any dynamic callback.
+        def _associated_dataset(opts, dynamic_opts)
+          ds = super
+
+          if eager = dynamic_opts[:eager]
+            ds = ds.eager(eager)
+          end
+
+          ds
+        end
+        
+        # A placeholder literalizer that can be used to load the association, or nil to not use one.
+        def _associated_object_loader(opts, dynamic_opts)
+          return if dynamic_opts[:eager]
+          super
+        end
+
+        # Whether to use a simple primary key lookup on the associated class when loading.
+        def load_with_primary_key_lookup?(opts, dynamic_opts)
+          return false if dynamic_opts[:eager]
+          super
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/association_multi_add_remove.rb

@@ -0,0 +1,85 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The association_multi_add_remove plugin allows adding, removing and setting
+    # multiple associated objects in a single method call.
+    # By default Sequel::Model defines singular <tt>add_*</tt> and <tt>remove_*</tt>
+    # methods that operate on a single associated object, this adds plural forms
+    # that operate on multiple associated objects. Example:
+    #
+    #   artist.albums # => [album1]
+    #   artist.add_albums([album2, album3])
+    #   artist.albums # => [album1, album2, album3]
+    #   artist.remove_albums([album3, album1])
+    #   artist.albums # => [album2]
+    #   artist.albums = [album2, album3]
+    #   artist.albums # => [album2, album3]
+    #
+    # It can handle all situations that the normal singular methods handle, but there is
+    # no attempt to optimize behavior, so using these methods will not improve performance.
+    #
+    # The add/remove/set methods defined by this plugin use a transaction,
+    # so if one add/remove/set fails and raises an exception, all adds/removes/set
+    # will be rolled back. If you are using database sharding and want to save
+    # to a specific shard, call Model#set_server to set the server for this instance,
+    # as the transaction will be opened on that server.
+    #
+    # You can customize the method names used for adding/removing multiple associated
+    # objects using the :multi_add_method and :multi_remove_method association options.
+    #
+    # Usage:
+    #
+    #   # Allow adding/removing/setting multiple associated objects in a single call
+    #   # for all model subclass instances (called before loading subclasses):
+    #   Sequel::Model.plugin :association_multi_add_remove
+    #
+    #   # Allow adding/removing/setting multiple associated objects in a single call
+    #   # for Album instances (called before defining associations in the class):
+    #   Album.plugin :association_multi_add_remove
+    module AssociationMultiAddRemove
+      module ClassMethods
+        private
+
+        # Define the methods use to add/remove/set multiple associated objects
+        # in a single method call.
+        def def_association_instance_methods(opts)
+          super
+
+          if opts[:adder]
+            add_method = opts[:add_method]
+            multi_add_method = opts[:multi_add_method] || :"add_#{opts[:name]}"
+            multi_add_method = nil if add_method == multi_add_method
+            if multi_add_method
+              association_module_def(multi_add_method, opts) do |objs, *args|
+                db.transaction(:server=>@server){objs.map{|obj| send(add_method, obj, *args)}.compact}
+              end
+            end
+          end
+
+          if opts[:remover]
+            remove_method = opts[:remove_method]
+            multi_remove_method = opts[:multi_remove_method] || :"remove_#{opts[:name]}"
+            multi_remove_method = nil if remove_method == multi_remove_method
+            if multi_remove_method
+              association_module_def(multi_remove_method, opts) do |objs, *args|
+                db.transaction(:server=>@server){objs.map{|obj| send(remove_method, obj, *args)}.compact}
+              end
+            end
+          end
+
+          if multi_add_method && multi_remove_method
+            association_module_def(:"#{opts[:name]}=", opts) do |objs, *args|
+              db.transaction(:server=>@server) do
+                existing_objs = send(opts.association_method)
+                send(multi_remove_method, (existing_objs - objs), *args)
+                send(multi_add_method, (objs - existing_objs), *args)
+                nil
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/association_pks.rb

@@ -1,15 +1,23 @@
+# frozen-string-literal: true
+
 module Sequel
   module Plugins
-    # The association_pks plugin adds association_pks and association_pks=
-    # instance methods to the model class for each association added.  These
-    # methods allow for easily returning the primary keys of the associated
-    # objects, and easily modifying which objects are associated:
+    # The association_pks plugin adds association_pks, association_pks=, and
+    # association_pks_dataset instance methods to the model class for each
+    # one_to_many and many_to_many association added.  These methods allow for
+    # easily returning the primary keys of the associated objects, and easily
+    # modifying which objects are associated:
     #
     #   Artist.one_to_many :albums
     #   artist = Artist[1]
+    #   artist.album_pks_dataset
+    #   # SELECT id FROM albums WHERE (albums.artist_id = 1)
+    #
     #   artist.album_pks # [1, 2, 3]
     #   artist.album_pks = [2, 4]
     #   artist.album_pks # [2, 4]
+    #   artist.save
+    #   # Persist changes
     #
     # Note that it uses the singular form of the association name. Also note
     # that the setter both associates to new primary keys not in the assocation
@@ -18,14 +26,35 @@ module Sequel
     # This plugin makes modifications directly to the underlying tables,
     # it does not create or return any model objects, and therefore does
     # not call any callbacks.  If you have any association callbacks,
-    # you probably should not use the setter methods.
+    # you probably should not use the setter methods this plugin adds.
+    #
+    # By default, changes to the association will not happen until the object
+    # is saved.  However, using the delay_pks: false association option, you can have
+    # the changes made immediately when the association_pks setter method is called.
     #
-    # If an association uses the :delay_pks option, you can set the associated
-    # pks for new objects, and the setting will not be persisted until after the
-    # object has been created in the database.  Additionally, if an association
-    # uses the :delay_pks=>:all option, you can set the associated pks for existing
-    # objects, and the setting will not be persisted until after the object has
-    # been saved.
+    # By default, repeated calls to the association_pks getter method will not be
+    # cached, unless the setter method has been used and the delay_pks: false
+    # association option is not used.  You can set caching of repeated calls to the
+    # association_pks getter method using the :cache_pks association option.  You can
+    # pass the :refresh option when calling the getter method to ignore any existing
+    # cached values, similar to how the :refresh option works with associations.
+    #
+    # By default, if you pass a nil value to the setter, an exception will be raised.
+    # You can change this behavior by using the :association_pks_nil association option.
+    # If set to :ignore, the setter will take no action if nil is given.
+    # If set to :remove, the setter will treat the nil as an empty array, removing
+    # the association all currently associated values.
+    #
+    # For many_to_many associations, association_pks assumes the related pks can be
+    # accessed directly from the join table.  This works in most cases, but in cases
+    # where the :right_primary_key association option is used to specify a different
+    # primary key in the associated table, association_pks will return the value of
+    # the association primary keys (foreign key values to associated table in the join
+    # table), not the associated model primary keys.  If you would like to use the
+    # associated model primary keys, you need to use the
+    # :association_pks_use_associated_table association option. If the
+    # :association_pks_use_associated_table association option is used, no setter
+    # method will be added.
     #
     # Usage:
     #
@@ -42,8 +71,17 @@ module Sequel
 
         # Define a association_pks method using the block for the association reflection 
         def def_association_pks_methods(opts)
-          association_module_def(:"#{singularize(opts[:name])}_pks", opts){_association_pks_getter(opts)}
-          association_module_def(:"#{singularize(opts[:name])}_pks=", opts){|pks| _association_pks_setter(opts, pks)} unless opts[:read_only]
+          association_module_def(opts[:pks_dataset_method], &opts[:pks_dataset])
+
+          opts[:pks_getter_method] = :"#{singularize(opts[:name])}_pks_getter"
+          association_module_def(opts[:pks_getter_method], &opts[:pks_getter])
+          association_module_def(:"#{singularize(opts[:name])}_pks", opts){|dynamic_opts=OPTS| _association_pks_getter(opts, dynamic_opts)}
+
+          if opts[:pks_setter]
+            opts[:pks_setter_method] = :"#{singularize(opts[:name])}_pks_setter"
+            association_module_def(opts[:pks_setter_method], &opts[:pks_setter])
+            association_module_def(:"#{singularize(opts[:name])}_pks=", opts){|pks| _association_pks_setter(opts, pks)}
+          end
         end
 
         # Add a getter that checks the join table for matching records and
@@ -59,35 +97,64 @@ module Sequel
           clpk = lpk.is_a?(Array)
           crk = rk.is_a?(Array)
 
-          opts[:pks_getter] = if clpk
+          dataset_method = opts[:pks_dataset_method] = :"#{singularize(opts[:name])}_pks_dataset"
+
+          opts[:pks_dataset] = if join_associated_table = opts[:association_pks_use_associated_table]
+            tname = opts[:join_table]
+            lambda do
+              cond = if clpk
+                lk.zip(lpk).map{|k, pk| [Sequel.qualify(tname, k), get_column_value(pk)]}
+              else
+                {Sequel.qualify(tname, lk) => get_column_value(lpk)}
+              end
+              rpk = opts.associated_class.primary_key
+              opts.associated_dataset.
+                naked.where(cond).
+                select(*Sequel.public_send(rpk.is_a?(Array) ? :deep_qualify : :qualify, opts.associated_class.table_name, rpk))
+            end
+          elsif clpk
+            lambda do
+              cond = lk.zip(lpk).map{|k, pk| [k, get_column_value(pk)]}
+              _join_table_dataset(opts).where(cond).select(*rk)
+            end
+          else
+            lambda do
+              _join_table_dataset(opts).where(lk=>get_column_value(lpk)).select(*rk)
+            end
+          end
+
+          opts[:pks_getter] = if join_associated_table = opts[:association_pks_use_associated_table]
             lambda do
-              h = {}
-              lk.zip(lpk).each{|k, pk| h[k] = get_column_value(pk)}
-              _join_table_dataset(opts).filter(h).select_map(rk)
+              public_send(dataset_method).map(opts.associated_class.primary_key)
             end
           else
             lambda do
-              _join_table_dataset(opts).filter(lk=>get_column_value(lpk)).select_map(rk)
+              public_send(dataset_method).map(rk)
             end
           end
 
-          opts[:pks_setter] = lambda do |pks|
-            pks = send(crk ? :convert_cpk_array : :convert_pk_array, opts, pks)
-            checked_transaction do
-              if clpk
-                lpkv = lpk.map{|k| get_column_value(k)}
-                cond = lk.zip(lpkv)
+          if !opts[:read_only] && !join_associated_table
+            opts[:pks_setter] = lambda do |pks|
+              if pks.empty?
+                public_send(opts[:remove_all_method])
               else
-                lpkv = get_column_value(lpk)
-                cond = {lk=>lpkv}
+                checked_transaction do
+                  if clpk
+                    lpkv = lpk.map{|k| get_column_value(k)}
+                    cond = lk.zip(lpkv)
+                  else
+                    lpkv = get_column_value(lpk)
+                    cond = {lk=>lpkv}
+                  end
+                  ds = _join_table_dataset(opts).where(cond)
+                  ds.exclude(rk=>pks).delete
+                  pks -= ds.select_map(rk)
+                  lpkv = Array(lpkv)
+                  key_array = crk ? pks.map{|pk| lpkv + pk} : pks.map{|pk| lpkv + [pk]}
+                  key_columns = Array(lk) + Array(rk)
+                  ds.import(key_columns, key_array)
+                end
               end
-              ds = _join_table_dataset(opts).filter(cond)
-              ds.exclude(rk=>pks).delete
-              pks -= ds.select_map(rk)
-              lpkv = Array(lpkv)
-              key_array = crk ? pks.map{|pk| lpkv + pk} : pks.map{|pk| lpkv + [pk]}
-              key_columns = Array(lk) + Array(rk)
-              ds.import(key_columns, key_array)
             end
           end
 
@@ -103,37 +170,42 @@ module Sequel
 
           key = opts[:key]
 
-          opts[:pks_getter] = lambda do
-            send(opts.dataset_method).select_map(opts.associated_class.primary_key)
+          dataset_method = opts[:pks_dataset_method] = :"#{singularize(opts[:name])}_pks_dataset"
+
+          opts[:pks_dataset] = lambda do
+            public_send(opts[:dataset_method]).select(*opts.associated_class.primary_key)
           end
 
-          opts[:pks_setter] = lambda do |pks|
-            primary_key = opts.associated_class.primary_key
+          opts[:pks_getter] = lambda do
+            public_send(dataset_method).map(opts.associated_class.primary_key)
+          end
 
-            pks = if primary_key.is_a?(Array)
-              convert_cpk_array(opts, pks)
-            else
-              convert_pk_array(opts, pks)
-            end
+          unless opts[:read_only]
+            opts[:pks_setter] = lambda do |pks|
+              if pks.empty?
+                public_send(opts[:remove_all_method])
+              else
+                primary_key = opts.associated_class.primary_key
+                pkh = {primary_key=>pks}
 
-            pkh = {primary_key=>pks}
+                if key.is_a?(Array)
+                  h = {}
+                  nh = {}
+                  key.zip(pk).each do|k, v|
+                    h[k] = v
+                    nh[k] = nil
+                  end
+                else
+                  h = {key=>pk}
+                  nh = {key=>nil}
+                end
 
-            if key.is_a?(Array)
-              h = {}
-              nh = {}
-              key.zip(pk).each do|k, v|
-                h[k] = v
-                nh[k] = nil
+                checked_transaction do
+                  ds = public_send(opts.dataset_method)
+                  ds.unfiltered.where(pkh).update(h)
+                  ds.exclude(pkh).update(nh)
+                end
               end
-            else
-              h = {key=>pk}
-              nh = {key=>nil}
-            end
-
-            checked_transaction do
-              ds = send(opts.dataset_method)
-              ds.unfiltered.filter(pkh).update(h)
-              ds.exclude(pkh).update(nh)
             end
           end
 
@@ -147,7 +219,8 @@ module Sequel
         def after_save
           if assoc_pks = @_association_pks
             assoc_pks.each do |name, pks|
-              instance_exec(pks, &model.association_reflection(name)[:pks_setter]) unless pks.empty?
+             # pks_setter_method is private
+              send(model.association_reflection(name)[:pks_setter_method], pks)
             end
             @_association_pks = nil
           end
@@ -165,48 +238,73 @@ module Sequel
         # Return the primary keys of the associated objects.
         # If the receiver is a new object, return any saved
         # pks, or an empty array if no pks have been saved.
-        def _association_pks_getter(opts)
-          delay = opts[:delay_pks]
-          if new? && delay
+        def _association_pks_getter(opts, dynamic_opts=OPTS)
+          do_cache = opts[:cache_pks]
+          delay = opts.fetch(:delay_pks, true)
+          cache_or_delay = do_cache || delay
+
+          if dynamic_opts[:refresh] && @_association_pks
+            @_association_pks.delete(opts[:name])
+          end
+
+          if new? && cache_or_delay
             (@_association_pks ||= {})[opts[:name]] ||= []
-          elsif delay == :always && @_association_pks && (objs = @_association_pks[opts[:name]])
+          elsif cache_or_delay && @_association_pks && (objs = @_association_pks[opts[:name]])
             objs
+          elsif do_cache
+           # pks_getter_method is private
+            (@_association_pks ||= {})[opts[:name]] = send(opts[:pks_getter_method])
           else
-            instance_exec(&opts[:pks_getter])
+           # pks_getter_method is private
+            send(opts[:pks_getter_method])
           end
         end
 
         # Update which objects are associated to the receiver.
         # If the receiver is a new object, save the pks
-        # so the update can happen after the received has been saved.
+        # so the update can happen after the receiver has been saved.
         def _association_pks_setter(opts, pks)
-          delay = opts[:delay_pks]
-          if (new? && delay) || (delay == :always)
-            modified!
-            (@_association_pks ||= {})[opts[:name]] = pks
-          else
-            instance_exec(pks, &opts[:pks_setter])
+          if pks.nil?
+            case opts[:association_pks_nil]
+            when :remove
+              pks = []
+            when :ignore
+              return
+            else
+              raise Error, "nil value given to association_pks setter"
+            end
           end
-        end
 
-        # If any of associated class's composite primary key column types is integer,
-        # typecast the appropriate values to integer before using them.
-        def convert_cpk_array(opts, cpks)
-          if klass = opts.associated_class and sch = klass.db_schema and (cols = sch.values_at(*klass.primary_key)).all? and (convs = cols.map{|c| c[:type] == :integer}).any?
-            cpks.map do |cpk|
-              cpk.zip(convs).map do |pk, conv|
-                conv ? model.db.typecast_value(:integer, pk) : pk
-              end
-            end
+          pks = convert_pk_array(opts, pks)
+
+          if opts.fetch(:delay_pks, true)
+            modified!
+            (@_association_pks ||= {})[opts[:name]] = pks
           else
-            cpks
+            # pks_setter_method is private
+            send(opts[:pks_setter_method], pks)
           end
         end
 
         # If the associated class's primary key column type is integer,
         # typecast all provided values to integer before using them.
         def convert_pk_array(opts, pks)
-          if klass = opts.associated_class and sch = klass.db_schema and col = sch[klass.primary_key] and col[:type] == :integer
+          klass = opts.associated_class
+          primary_key = klass.primary_key
+          sch = klass.db_schema
+
+          if primary_key.is_a?(Array)
+            if (cols = sch.values_at(*klass.primary_key)).all? && (convs = cols.map{|c| c[:type] == :integer}).all?
+              db = model.db
+              pks.map do |cpk|
+                cpk.map do |pk|
+                  db.typecast_value(:integer, pk)
+                end
+              end
+            else
+              pks
+            end
+          elsif (col = sch[klass.primary_key]) && (col[:type] == :integer)
             pks.map{|pk| model.db.typecast_value(:integer, pk)}
           else
             pks