sequel 4.26.0 → 5.37.0

data/lib/sequel/plugins/forbid_lazy_load.rb

@@ -0,0 +1,216 @@
+# 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
+          # :nocov:
+          if defined?(::Sequel::Plugins::StaticCache::ClassMethods)
+          # :nocov:
+            @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

data/lib/sequel/plugins/force_encoding.rb

@@ -1,7 +1,8 @@
-if RUBY_VERSION >= '1.9.0'
+# frozen-string-literal: true
+
 module Sequel
   module Plugins
-    # The ForceEncoding plugin allows you force specific encodings for all
+    # The force_encoding plugin allows you force specific encodings for all
     # strings that are used by the model.  When model instances are loaded
     # from the database, all values in the hash that are strings are
     # forced to the given encoding.  Whenever you update a model column
@@ -12,11 +13,11 @@ module Sequel
     #
     # Usage:
     #
-    #   # Force all strings to be UTF8 encoded in a all model subclasses
+    #   # Force all strings to be UTF-8 encoded in a all model subclasses
     #   # (called before loading subclasses)
     #   Sequel::Model.plugin :force_encoding, 'UTF-8'
     #
-    #   # Force the encoding for the Album model to UTF8
+    #   # Force the encoding for the Album model to UTF-8
     #   Album.plugin :force_encoding
     #   Album.forced_encoding = 'UTF-8'
     module ForceEncoding
@@ -56,15 +57,16 @@ module Sequel
         
         # Force the encoding for all string values in the given row hash.
         def force_hash_encoding(row)
-          fe = model.forced_encoding
-          row.values.each{|v| v.force_encoding(fe) if v.is_a?(String)} if fe
+          if fe = model.forced_encoding
+            row.each_value{|v| v.force_encoding(fe) if v.is_a?(String) && !v.is_a?(Sequel::SQL::Blob)}
+          end
           row
         end
         
         # Force the encoding of all returned strings to the model's forced_encoding.
         def typecast_value(column, value)
           s = super
-          if s.is_a?(String) && (fe = model.forced_encoding)
+          if s.is_a?(String) && !s.is_a?(Sequel::SQL::Blob) && (fe = model.forced_encoding)
             s = s.dup if s.frozen?
             s.force_encoding(fe)
           end
@@ -74,8 +76,3 @@ module Sequel
     end
   end
 end
-else
-# :nocov:
-  raise LoadError, 'ForceEncoding plugin only works on Ruby 1.9+'
-# :nocov:
-end

data/lib/sequel/plugins/hook_class_methods.rb

@@ -1,9 +1,11 @@
+# frozen-string-literal: true
+
 module Sequel
   module Plugins
-    # Sequel's built-in hook class methods plugin is designed for backwards
+    # Sequel's built-in hook_class_methods plugin is designed for backwards
     # compatibility.  Its use is not encouraged, it is recommended to use
-    # instance methods and super instead of this plugin.  What this plugin
-    # allows you to do is, for example:
+    # instance methods and super instead of this plugin.  This plugin allows
+    # calling class methods with blocks to define hooks:
     #
     #   # Block only, can cause duplicate hooks if code is reloaded
     #   before_save{self.created_at = Time.now}
@@ -13,17 +15,14 @@ module Sequel
     #   before_save(:set_created_at)
     #
     # Pretty much anything you can do with a hook class method, you can also
-    # do with an instance method instead:
+    # do with an instance method instead (making sure to call super), which is
+    # the recommended way to add hooks in Sequel:
     #
     #    def before_save
-    #      return false if super == false
+    #      super
     #      self.created_at = Time.now
     #    end
     #
-    # Note that returning false in any before hook block will skip further
-    # before hooks and abort the action.  So if a before_save hook block returns
-    # false, future before_save hook blocks are not called, and the save is aborted.
-    # 
     # Usage:
     #
     #   # Allow use of hook class methods in all model subclasses (called before loading subclasses)
@@ -39,46 +38,18 @@ module Sequel
       end
 
       module ClassMethods
-        Model::HOOKS.each{|h| class_eval("def #{h}(method = nil, &block); add_hook(:#{h}, method, &block) end", __FILE__, __LINE__)}
+        Model::HOOKS.each do |h|
+          class_eval(<<-END, __FILE__, __LINE__ + 1)
+            def #{h}(method = nil, &block)
+              add_hook(:#{h}, method, &block)
+            end
+          END
+        end
 
-        # This adds a new hook type. It will define both a class
-        # method that you can use to add hooks, as well as an instance method
-        # that you can use to call all hooks of that type.  The class method
-        # can be called with a symbol or a block or both.  If a block is given and
-        # and symbol is not, it adds the hook block to the hook type.  If a block
-        # and symbol are both given, it replaces the hook block associated with
-        # that symbol for a given hook type, or adds it if there is no hook block
-        # with that symbol for that hook type.  If no block is given, it assumes
-        # the symbol specifies an instance method to call and adds it to the hook
-        # type.
-        #
-        # If any before hook block returns false, the instance method will return false
-        # immediately without running the rest of the hooks of that type.
-        #
-        # It is recommended that you always provide a symbol to this method,
-        # for descriptive purposes.  It's only necessary to do so when you 
-        # are using a system that reloads code.
-        # 
-        # Example of usage:
-        #
-        #  class MyModel
-        #   add_hook_type :before_move_to
-        #   before_move_to(:check_move_allowed, &:allow_move?)
-        #   def move_to(there)
-        #     return if before_move_to == false
-        #     # move MyModel object to there
-        #   end
-        #  end
-        #
-        # Do not call this method with untrusted input, as that can result in
-        # arbitrary code execution.
-        def add_hook_type(*hooks)
-          Model::HOOKS.concat(hooks)
-          hooks.each do |hook|
-            @hooks[hook] = []
-            instance_eval("def #{hook}(method = nil, &block); add_hook(:#{hook}, method, &block) end", __FILE__, __LINE__)
-            class_eval("def #{hook}; model.hook_blocks(:#{hook}){|b| return false if instance_eval(&b) == false}; end", __FILE__, __LINE__)
-          end
+        # Freeze hooks when freezing model class.
+        def freeze
+          @hooks.freeze.each_value(&:freeze)
+          super
         end
     
         # Returns true if there are any hook blocks for the given hook.
@@ -88,7 +59,14 @@ module Sequel
     
         # Yield every block related to the given hook.
         def hook_blocks(hook)
-          @hooks[hook].each{|k,v| yield v}
+          # SEQUEL6: Remove
+          Sequel::Deprecation.deprecate("The hook_blocks class method in the hook_class_methods plugin is deprecated and will be removed in Sequel 6.")
+          @hooks[hook].each{|_,v,_| yield v}
+        end
+
+        # Yield every method related to the given hook.
+        def hook_methods_for(hook)
+          @hooks[hook].each{|_,_,m| yield m}
         end
 
         Plugins.inherited_instance_variables(self, :@hooks=>:hash_dup)
@@ -101,24 +79,31 @@ module Sequel
         def add_hook(hook, tag, &block)
           unless block
             (raise Error, 'No hook method specified') unless tag
-            block = proc {send tag}
+            # Allow calling private hook methods
+            block = proc {send(tag)}
           end
+
           h = @hooks[hook]
+
           if tag && (old = h.find{|x| x[0] == tag})
             old[1] = block
+            Plugins.def_sequel_method(self, old[2], 0, &block)
           else
+            meth = Plugins.def_sequel_method(self, "validation_class_methods_#{hook}", 0, &block)
             if hook.to_s =~ /^before/
-              h.unshift([tag,block])
+              h.unshift([tag, block, meth])
             else
-              h << [tag, block]
+              h << [tag, block, meth]
             end
           end
         end
       end
 
       module InstanceMethods
-        Model::BEFORE_HOOKS.each{|h| class_eval("def #{h}; model.hook_blocks(:#{h}){|b| return false if instance_eval(&b) == false}; super; end", __FILE__, __LINE__)}
-        Model::AFTER_HOOKS.each{|h| class_eval("def #{h}; super; model.hook_blocks(:#{h}){|b| instance_eval(&b)}; end", __FILE__, __LINE__)}
+        # hook methods are private
+        [:before_create, :before_update, :before_validation, :before_save, :before_destroy].each{|h| class_eval("def #{h}; model.hook_methods_for(:#{h}){|m| send(m)}; super end", __FILE__, __LINE__)}
+
+        [:after_create, :after_update, :after_validation, :after_save, :after_destroy].each{|h| class_eval("def #{h}; super; model.hook_methods_for(:#{h}){|m| send(m)}; end", __FILE__, __LINE__)}
       end
     end
   end

data/lib/sequel/plugins/input_transformer.rb

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 module Sequel
   module Plugins
     # InputTransformer is a plugin that allows generic transformations
@@ -5,14 +7,14 @@ module Sequel
     #
     #   Album.plugin :input_transformer
     #   Album.add_input_transformer(:reverser){|v| v.is_a?(String) ? v.reverse : v}
-    #   album = Album.new(:name=>'foo')
+    #   album = Album.new(name: 'foo')
     #   album.name # => 'oof'
     #
     # You can specifically set some columns to skip some input
     # input transformers:
     #
     #   Album.skip_input_transformer(:reverser, :foo)
-    #   Album.new(:foo=>'bar').foo # => 'bar'
+    #   Album.new(foo: 'bar').foo # => 'bar'
     # 
     # Usage:
     #
@@ -23,9 +25,8 @@ module Sequel
     #   Album.plugin :input_transformer
     module InputTransformer
       def self.apply(model, *)
-        model.instance_eval do
+        model.instance_exec do
           @input_transformers = {}
-          @input_transformer_order = []
           @skip_input_transformer_columns = {}
         end
       end
@@ -40,19 +41,28 @@ module Sequel
         # Hash of input transformer name symbols to transformer callables.
         attr_reader :input_transformers
 
-        # The order in which to call the input transformers.
-        attr_reader :input_transformer_order
+        # The order in which to call the input transformers. For backwards compatibility only.
+        def input_transformer_order
+          input_transformers.keys.reverse
+        end
 
-        Plugins.inherited_instance_variables(self, :@skip_input_transformer_columns=>:hash_dup, :@input_transformers=>:dup, :@input_transformer_order=>:dup)
+        Plugins.inherited_instance_variables(self, :@skip_input_transformer_columns=>:hash_dup, :@input_transformers=>:dup)
 
         # Add an input transformer to this model.
         def add_input_transformer(transformer_name, &block)
           raise(Error, 'must provide both transformer name and block when adding input transformer') unless transformer_name && block
           @input_transformers[transformer_name] = block
-          @input_transformer_order.unshift(transformer_name)
           @skip_input_transformer_columns[transformer_name] = []
         end
 
+        # Freeze input transformers when freezing model class
+        def freeze
+          @input_transformers.freeze
+          @skip_input_transformer_columns.freeze.each_value(&:freeze)
+
+          super
+        end
+
         # Set columns that the transformer should skip.
         def skip_input_transformer(transformer_name, *columns)
           @skip_input_transformer_columns[transformer_name].concat(columns).uniq!
@@ -68,8 +78,8 @@ module Sequel
         # Transform the input using all of the transformers, except those explicitly
         # skipped, before setting the value in the model object.
         def []=(k, v)
-          model.input_transformer_order.each do |transformer_name|
-            v = model.input_transformers[transformer_name].call(v) unless model.skip_input_transformer?(transformer_name, k)
+          model.input_transformers.reverse_each do |name, transformer|
+            v = transformer.call(v) unless model.skip_input_transformer?(name, k)
           end
           super
         end