sequel 5.29.0 → 5.34.0

data/lib/sequel/plugins/association_multi_add_remove.rb

@@ -39,6 +39,8 @@ module Sequel
     #   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)

data/lib/sequel/plugins/association_pks.rb

@@ -2,13 +2,17 @@
 
 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]
@@ -22,11 +26,18 @@ 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 option, you can have the
-    # changes made immediately when the association_pks setter method is called.
+    # 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.
+    #
+    # 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.
@@ -60,9 +71,11 @@ module Sequel
 
         # Define a association_pks method using the block for the association reflection 
         def def_association_pks_methods(opts)
+          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){_association_pks_getter(opts)}
+          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"
@@ -84,7 +97,9 @@ module Sequel
           clpk = lpk.is_a?(Array)
           crk = rk.is_a?(Array)
 
-          opts[:pks_getter] = if join_associated_table = opts[:association_pks_use_associated_table]
+          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
@@ -95,16 +110,26 @@ module Sequel
               rpk = opts.associated_class.primary_key
               opts.associated_dataset.
                 naked.where(cond).
-                select_map(Sequel.public_send(rpk.is_a?(Array) ? :deep_qualify : :qualify, opts.associated_class.table_name, rpk))
+                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_map(rk)
+              _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
+              public_send(dataset_method).map(opts.associated_class.primary_key)
             end
           else
             lambda do
-              _join_table_dataset(opts).where(lk=>get_column_value(lpk)).select_map(rk)
+              public_send(dataset_method).map(rk)
             end
           end
 
@@ -145,8 +170,14 @@ module Sequel
 
           key = opts[: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_getter] = lambda do
-            public_send(opts[:dataset_method]).select_map(opts.associated_class.primary_key)
+            public_send(dataset_method).map(opts.associated_class.primary_key)
           end
 
           unless opts[:read_only]
@@ -207,12 +238,22 @@ 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)
+        def _association_pks_getter(opts, dynamic_opts=OPTS)
+          do_cache = opts[:cache_pks]
           delay = opts.fetch(:delay_pks, true)
-          if new? && delay
+          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 && @_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
            # pks_getter_method is private
             send(opts[:pks_getter_method])

data/lib/sequel/plugins/association_proxies.rb

@@ -109,6 +109,8 @@ module Sequel
 
         Plugins.inherited_instance_variables(self, :@association_proxy_to_dataset=>nil)
 
+        private
+
         # Changes the association method to return a proxy instead of the associated objects
         # directly.
         def def_association_method(opts)

data/lib/sequel/plugins/boolean_subsets.rb

@@ -31,7 +31,10 @@ module Sequel
       # Create boolean subset methods for each boolean column.
       def self.configure(model, &block)
         model.instance_exec do
-          define_singleton_method(:boolean_subset_args, &block) if block
+          if block
+            define_singleton_method(:boolean_subset_args, &block)
+            singleton_class.send(:private, :boolean_subset_args)
+          end
           create_boolean_subsets if @dataset
         end
       end

data/lib/sequel/plugins/class_table_inheritance.rb

@@ -278,6 +278,27 @@ module Sequel
 
         Plugins.inherited_instance_variables(self, :@cti_models=>nil, :@cti_tables=>nil, :@cti_table_columns=>nil, :@cti_instance_dataset=>nil, :@cti_table_map=>nil, :@cti_alias=>nil, :@cti_ignore_subclass_columns=>nil, :@cti_qualify_tables=>nil)
 
+        # The table name for the current model class's main table.
+        def table_name
+          if cti_tables && cti_tables.length > 1
+            @cti_alias
+          else
+            super
+          end
+        end
+
+        # The name of the most recently joined table.
+        def cti_table_name
+          cti_tables ? cti_tables.last : dataset.first_source_alias
+        end
+
+        # The model class for the given key value.
+        def sti_class_from_key(key)
+          sti_class(sti_model_map[key])
+        end
+
+        private
+
         def inherited(subclass)
           ds = sti_dataset
 
@@ -340,27 +361,6 @@ module Sequel
           end
         end
 
-        # The table name for the current model class's main table.
-        def table_name
-          if cti_tables && cti_tables.length > 1
-            @cti_alias
-          else
-            super
-          end
-        end
-
-        # The name of the most recently joined table.
-        def cti_table_name
-          cti_tables ? cti_tables.last : dataset.first_source_alias
-        end
-
-        # The model class for the given key value.
-        def sti_class_from_key(key)
-          sti_class(sti_model_map[key])
-        end
-
-        private
-
         # If using a subquery for class table inheritance, also use a subquery
         # when setting subclass dataset.
         def sti_subclass_dataset(key)
@@ -383,11 +383,6 @@ module Sequel
           self
         end
 
-        # Don't allow use of prepared statements.
-        def use_prepared_statements_for?(type)
-          false
-        end
-
         # Set the sti_key column based on the sti_key_map.
         def before_validation
           if new? && (set = self[model.sti_key])
@@ -438,6 +433,11 @@ module Sequel
             end
           end
         end
+
+        # Don't allow use of prepared statements.
+        def use_prepared_statements_for?(type)
+          false
+        end
       end
     end
   end

data/lib/sequel/plugins/dirty.rb

@@ -61,6 +61,19 @@ module Sequel
         # that were used in the update statement.
         attr_reader :previous_changes
 
+        # Reset the initial values after saving.
+        def after_save
+          super
+          reset_initial_values
+        end
+
+        # Save the current changes so they are available after updating.  This happens
+        # before after_save resets them.
+        def after_update
+          super
+          @previous_changes = column_changes
+        end
+
         # An array with the initial value and the current value
         # of the column, if the column has been changed.  If the
         # column has not been changed, returns nil.
@@ -165,19 +178,6 @@ module Sequel
           super
         end
 
-        # Reset the initial values after saving.
-        def after_save
-          super
-          reset_initial_values
-        end
-
-        # Save the current changes so they are available after updating.  This happens
-        # before after_save resets them.
-        def after_update
-          super
-          @previous_changes = column_changes
-        end
-
         # When changing the column value, save the initial column value.  If the column
         # value is changed back to the initial value, update changed columns to remove
         # the column.

data/lib/sequel/plugins/forbid_lazy_load.rb

@@ -0,0 +1,214 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The forbid_lazy_load plugin forbids lazy loading of associations
+    # for objects in cases where the object wasn't loaded with a
+    # method that only returns a single object.
+    #
+    # The main reason for doing this is it makes it easier to detect
+    # N+1 query issues. Note that Sequel also offers a
+    # tactical_eager_loading plugin which will automatically eagerly
+    # load associations for all objects retrived in the same query
+    # if any object would attempt to lazily load an association. That
+    # approach may be simpler if you are trying to prevent N+1 issues,
+    # though it does retain more objects in memory.
+    #
+    # This plugin offers multiple different ways to forbid lazy
+    # loading.  You can forbid lazy loading associations for individual
+    # model instances:
+    #
+    #   obj = Album[1]
+    #   obj.forbid_lazy_load
+    #   obj.artist # raises Sequel::Plugins::ForbidLazyLoad::Error
+    #
+    # +forbid_lazy_load+ is automatically called on instances if the
+    # instances are loaded via a method such as Dataset#all,
+    # Dataset#each, and other methods that load multiple instances
+    # at once.  These are the cases where lazily loading associations
+    # for such instances can cause N+1 issues.
+    #
+    #   Album.all.first.artist
+    #   objs.first.artist # raises Sequel::Plugins::ForbidLazyLoad::Error
+    #
+    #   Album.each do |obj|
+    #     obj.artist # raises Sequel::Plugins::ForbidLazyLoad::Error
+    #   end
+    #
+    #   Album[1].artist # no error
+    #
+    #   Album.first.artist # no error
+    #
+    # You can allow lazy loading associations for an instance that it
+    # was previously forbidden for:
+    # 
+    #   obj = Album.all.first
+    #   obj.allow_lazy_load
+    #   obj.artist # no error
+    #
+    # You can forbid lazy loading associations on a per-call basis,
+    # even if lazy loading of associations is allowed for the instance:
+    #
+    #   obj = Album[1]
+    #   obj.artist(forbid_lazy_load: true)
+    #   # raises Sequel::Plugins::ForbidLazyLoad::Error
+    #
+    # This also works for allowing lazy loading associations for a
+    # specific association load even if it is forbidden for the instance:
+    #  
+    #   obj = Album.all.first
+    #   obj.artist(forbid_lazy_load: false)
+    #   # nothing raised
+    #
+    # You can also forbid lazy loading on a per-association basis using the
+    # +:forbid_lazy_load+ association option with a +true+ value:
+    #
+    #   Album.many_to_one :artist, forbid_lazy_load: true
+    #   Album[1].artist # raises Sequel::Plugins::ForbidLazyLoad::Error
+    #
+    # However, you probably don't want to do this as it will forbid any
+    # lazy loading of the association, even if the loading could not
+    # result in an N+1 issue.
+    #
+    # On the flip side, you can allow lazy loading using the 
+    # +:forbid_lazy_load+ association option with a +false+ value:
+    #
+    #   Album.many_to_one :artist, forbid_lazy_load: false
+    #   Album.all.first.artist # no error
+    #
+    # One reason to do this is when using a plugin like static_cache
+    # on the associated model, where a query is not actually issued
+    # when doing a lazy association load.  To make that particular
+    # case easier, this plugin makes Model.finalize_associations
+    # automatically set the association option if the associated
+    # class uses the static_cache plugin.
+    #
+    # Note that even with this plugin, there can still be N+1 issues,
+    # such as:
+    #
+    #   Album.each do |obj| # 1 query for all albums
+    #     Artist[obj.artist_id] # 1 query per album for each artist
+    #   end
+    # 
+    # Usage:
+    #
+    #   # Make all model subclasses support forbidding lazy load
+    #   # (called before loading subclasses)
+    #   Sequel::Model.plugin :forbid_lazy_load
+    #
+    #   # Make the Album class support forbidding lazy load
+    #   Album.plugin :forbid_lazy_load
+    module ForbidLazyLoad
+      # Error raised when attempting to lazy load an association when
+      # lazy loading has been forbidden.
+      class Error < StandardError
+      end
+
+      module ClassMethods
+        Plugins.def_dataset_methods(self, :forbid_lazy_load)
+
+        # If the static_cache plugin is used by the associated class for
+        # an association, allow lazy loading that association, since the
+        # lazy association load will use a hash table lookup and not a query.
+        def allow_lazy_load_for_static_cache_associations
+          if defined?(::Sequel::Plugins::StaticCache::ClassMethods)
+            @association_reflections.each_value do |ref|
+              if ref.associated_class.is_a?(::Sequel::Plugins::StaticCache::ClassMethods)
+                ref[:forbid_lazy_load] = false
+              end
+            end
+          end
+        end
+
+        # Allow lazy loading for static cache associations before finalizing.
+        def finalize_associations
+          allow_lazy_load_for_static_cache_associations
+          super
+        end
+      end
+
+      module InstanceMethods
+        # Set this model instance to allow lazy loading of associations.
+        def allow_lazy_load
+          @forbid_lazy_load = false
+          self
+        end
+
+        # Set this model instance to not allow lazy loading of associations.
+        def forbid_lazy_load
+          @forbid_lazy_load = true
+          self
+        end
+
+        private
+
+        # Allow lazy loading for objects returned by singular associations.
+        def _load_associated_object(opts, dynamic_opts)
+          # The implementation that loads these associations does
+          # .all.first, which would result in the object returned being
+          # marked as forbidding lazy load.
+          obj = super
+          obj.allow_lazy_load if obj.is_a?(InstanceMethods)
+          obj
+        end
+
+        # Raise an Error if lazy loading has been forbidden for
+        # the instance, association, or call.
+        def _load_associated_objects(opts, dynamic_opts=OPTS)
+          case dynamic_opts[:forbid_lazy_load]
+          when false
+            # nothing
+          when nil
+            unless dynamic_opts[:reload]
+              case opts[:forbid_lazy_load]
+              when nil
+                raise Error, "lazy loading forbidden for this object (association: #{opts.inspect}, object: #{inspect})" if @forbid_lazy_load
+              when false
+                # nothing
+              else
+                raise Error, "lazy loading forbidden for this association (#{opts.inspect})"
+              end
+            end
+          else
+            raise Error, "lazy loading forbidden for this association method call (association: #{opts.inspect})"
+          end
+
+          super
+        end
+      end
+
+      module DatasetMethods
+        # Mark model instances retrieved in this call as forbidding lazy loading.
+        def each
+          if row_proc
+            super do |obj|
+              obj.forbid_lazy_load if obj.is_a?(InstanceMethods)
+              yield obj
+            end
+          else
+            super
+          end
+        end
+
+        # Mark model instances retrieved in this call as forbidding lazy loading.
+        def with_sql_each(sql)
+          if row_proc
+            super(sql) do |obj|
+              obj.forbid_lazy_load if obj.is_a?(InstanceMethods)
+              yield obj
+            end
+          else
+            super
+          end
+        end
+
+        # Mark model instances retrieved in this call as allowing lazy loading.
+        def with_sql_first(sql)
+          obj = super
+          obj.allow_lazy_load if obj.is_a?(InstanceMethods)
+          obj
+        end
+      end
+    end
+  end
+end