sequel 5.28.0 → 5.33.0

data/lib/sequel/model/base.rb

@@ -460,47 +460,6 @@ module Sequel
         super
       end
 
-      # If possible, set the dataset for the model subclass as soon as it
-      # is created.  Also, make sure the inherited class instance variables
-      # are copied into the subclass.
-      #
-      # Sequel queries the database to get schema information as soon as
-      # a model class is created:
-      #
-      #   class Artist < Sequel::Model # Causes schema query
-      #   end
-      def inherited(subclass)
-        super
-        ivs = subclass.instance_variables
-        inherited_instance_variables.each do |iv, dup|
-          next if ivs.include?(iv)
-          if (sup_class_value = instance_variable_get(iv)) && dup
-            sup_class_value = case dup
-            when :dup
-              sup_class_value.dup
-            when :hash_dup
-              h = {}
-              sup_class_value.each{|k,v| h[k] = v.dup}
-              h
-            when Proc
-              dup.call(sup_class_value)
-            else
-              raise Error, "bad inherited instance variable type: #{dup.inspect}"
-            end
-          end
-          subclass.instance_variable_set(iv, sup_class_value)
-        end
-
-        unless ivs.include?(:@dataset)
-          if @dataset && self != Model
-            subclass.set_dataset(@dataset.clone, :inherited=>true)
-          elsif (n = subclass.name) && !n.to_s.empty?
-            db
-            subclass.set_dataset(subclass.implicit_table_name)
-          end
-        end
-      end
-
       # Returns the implicit table name for the model class, which is the demodulized,
       # underscored, pluralized name of the class.
       #
@@ -515,12 +474,6 @@ module Sequel
         call(values)
       end
 
-      # Clear the setter_methods cache when a setter method is added.
-      def method_added(meth)
-        clear_setter_methods_cache if meth.to_s.end_with?('=')
-        super
-      end
-  
       # Mark the model as not having a primary key. Not having a primary key
       # can cause issues, among which is that you won't be able to update records.
       #
@@ -854,6 +807,47 @@ module Sequel
         meths
       end
   
+      # If possible, set the dataset for the model subclass as soon as it
+      # is created.  Also, make sure the inherited class instance variables
+      # are copied into the subclass.
+      #
+      # Sequel queries the database to get schema information as soon as
+      # a model class is created:
+      #
+      #   class Artist < Sequel::Model # Causes schema query
+      #   end
+      def inherited(subclass)
+        super
+        ivs = subclass.instance_variables
+        inherited_instance_variables.each do |iv, dup|
+          next if ivs.include?(iv)
+          if (sup_class_value = instance_variable_get(iv)) && dup
+            sup_class_value = case dup
+            when :dup
+              sup_class_value.dup
+            when :hash_dup
+              h = {}
+              sup_class_value.each{|k,v| h[k] = v.dup}
+              h
+            when Proc
+              dup.call(sup_class_value)
+            else
+              raise Error, "bad inherited instance variable type: #{dup.inspect}"
+            end
+          end
+          subclass.instance_variable_set(iv, sup_class_value)
+        end
+
+        unless ivs.include?(:@dataset)
+          if @dataset && self != Model
+            subclass.set_dataset(@dataset.clone, :inherited=>true)
+          elsif (n = subclass.name) && !n.to_s.empty?
+            db
+            subclass.set_dataset(subclass.implicit_table_name)
+          end
+        end
+      end
+
       # A hash of instance variables to automatically set up in subclasses.
       # Keys are instance variable symbols, values should be:
       # nil :: Assign directly from superclass to subclass (frozen objects)
@@ -908,6 +902,12 @@ module Sequel
         opts[:class_name] ||= '::' + ((name || '').split("::")[0..-2] + [camelize(default)]).join('::')
       end
   
+      # Clear the setter_methods cache when a setter method is added.
+      def method_added(meth)
+        clear_setter_methods_cache if meth.to_s.end_with?('=')
+        super
+      end
+  
       # Module that the class includes that holds methods the class adds for column accessors and
       # associations so that the methods can be overridden with +super+.
       def overridable_methods_module
@@ -1718,6 +1718,7 @@ module Sequel
 
       # The values hash to use when inserting a new record.
       alias _insert_values values
+      private :_insert_values
       
       # Refresh using a particular dataset, used inside save to make sure the same server
       # is used for reading newly inserted values from the database
@@ -1772,14 +1773,12 @@ module Sequel
               before_update
               columns = opts[:columns]
               if columns.nil?
-                if opts[:changed]
-                  cc = changed_columns
-                  columns_updated = @values.reject{|k,v| !cc.include?(k)}
-                  cc.clear
+                columns_updated = if opts[:changed]
+                  _save_update_changed_colums_hash
                 else
-                  columns_updated = _save_update_all_columns_hash
-                  _clear_changed_columns(:update)
+                  _save_update_all_columns_hash
                 end
+                _clear_changed_columns(:update)
               else # update only the specified columns
                 columns = Array(columns)
                 columns_updated = @values.reject{|k, v| !columns.include?(k)}
@@ -1827,6 +1826,14 @@ module Sequel
         v
       end
 
+      # Return a hash of values used when saving changed columns of an
+      # existing object.  Defaults to all of the objects current values
+      # that are recorded as modified.
+      def _save_update_changed_colums_hash
+        cc = changed_columns
+        @values.reject{|k,v| !cc.include?(k)}
+      end
+
       # Validate the object if validating on save. Skips validation
       # completely (including validation hooks) if
       # skip_validation_on_save! has been called on the object,

data/lib/sequel/model/plugins.rb

@@ -40,6 +40,7 @@ module Sequel
       mod.send(:define_method, :inherited_instance_variables) do ||
         super().merge!(hash)
       end
+      mod.send(:private, :inherited_instance_variables)
     end
 
     # Add method to +mod+ that overrides set_dataset to call the method afterward.

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

@@ -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_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/empty_failure_backtraces.rb

@@ -0,0 +1,38 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The empty_failure_backtraces plugin uses empty backtraces when raising HookFailed and ValidationFailed
+    # exceptions.  This can be significantly faster, and if you are using these exceptions for
+    # flow control, you do not need the backtraces.  This plugin is about 10% faster on CRuby
+    # and 10-15x faster on JRuby 9.2.7.0+.  This does not have an effect on JRuby <9.2.7.0.
+    #
+    # Usage:
+    #
+    #   # Make all model subclass instances use empty backtraces for HookFailed
+    #   # and ValidationFailed exceptions (called before loading subclasses)
+    #   Sequel::Model.plugin :empty_failure_backtraces
+    #
+    #   # Make the Album class use empty backtraces for HookFailed and ValidationFailed exceptions
+    #   Album.plugin :empty_failure_backtraces
+    module EmptyFailureBacktraces
+      module InstanceMethods
+        private
+
+        # Use empty backtrace for HookFailed exceptions.
+        def hook_failed_error(msg)
+          e = super
+          e.set_backtrace([])
+          e
+        end
+
+        # Use empty backtrace for ValidationFailed exceptions.
+        def validation_failed_error
+          e = super
+          e.set_backtrace([])
+          e
+        end
+      end
+    end
+  end
+end

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