sequel 4.36.0 → 5.61.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,9 +1,8 @@
 # frozen-string-literal: true
 
-if RUBY_VERSION >= '1.9.0'
 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
@@ -14,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
@@ -58,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
@@ -76,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

@@ -2,10 +2,10 @@
 
 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}
@@ -15,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)
@@ -41,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.
@@ -90,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)
@@ -103,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

@@ -7,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:
     #
@@ -25,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
@@ -42,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!
@@ -70,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

data/lib/sequel/plugins/insert_conflict.rb

@@ -0,0 +1,76 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The insert_conflict plugin allows handling conflicts due to unique
+    # constraints when saving new model instance, using the INSERT ON CONFLICT
+    # support in PostgreSQL 9.5+ and SQLite 3.24.0+. Example:
+    #
+    #   class Album < Sequel::Model
+    #     plugin :insert_conflict
+    #   end
+    #
+    #   Album.new(name: 'Foo', copies_sold: 1000).
+    #     insert_conflict(
+    #       target: :name,
+    #       update: {copies_sold: Sequel[:excluded][:b]}
+    #     ).
+    #     save
+    #
+    # This example will try to insert the album, but if there is an existing
+    # album with the name 'Foo', this will update the copies_sold attribute
+    # for that album.  See the PostgreSQL and SQLite adapter documention for
+    # the options you can pass to the insert_conflict method.
+    #
+    # You should not attempt to use this plugin to ignore conflicts when
+    # inserting, you should only use it to turn insert conflicts into updates.
+    # Any usage to ignore conflicts is not recommended or supported.
+    #
+    # Usage:
+    #
+    #   # Make all model subclasses support insert_conflict
+    #   Sequel::Model.plugin :insert_conflict
+    #
+    #   # Make the Album class support insert_conflict
+    #   Album.plugin :insert_conflict
+    module InsertConflict
+      def self.configure(model)
+        model.instance_exec do
+          if @dataset && !@dataset.respond_to?(:insert_conflict)
+            raise Error, "#{self}'s dataset does not support insert_conflict"
+          end
+        end
+      end
+
+      module InstanceMethods
+        # Set the insert_conflict options to pass to the dataset when inserting. 
+        def insert_conflict(opts=OPTS)
+          raise Error, "Model#insert_conflict is only supported on new model instances" unless new?
+          @insert_conflict_opts = opts
+          self
+        end
+
+        private
+
+        # Set the dataset used for inserting to use INSERT ON CONFLICT
+        # Model#insert_conflict has been called on the instance previously.
+        def _insert_dataset
+          ds = super
+
+          if @insert_conflict_opts
+            ds = ds.insert_conflict(@insert_conflict_opts)
+          end
+
+          ds
+        end
+
+        # Disable the use of prepared insert statements, as they are not compatible
+        # with this plugin.
+        def use_prepared_statements_for?(type)
+          return false if type == :insert || type == :insert_select
+          super if defined?(super)
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/insert_returning_select.rb

@@ -21,7 +21,7 @@ module Sequel
       # Modify the current model's dataset selection, if the model
       # has a dataset.
       def self.configure(model)
-        model.instance_eval do
+        model.instance_exec do
           self.dataset = dataset if @dataset && @dataset.opts[:select]
         end
       end
@@ -35,7 +35,7 @@ module Sequel
         # When reseting the instance dataset, also reset the instance_insert_dataset.
         def reset_instance_dataset
           ret = super
-          ds = @instance_dataset
+          return unless ds = @instance_dataset
 
           if columns = insert_returning_columns(ds)
             ds = ds.returning(*columns)

data/lib/sequel/plugins/instance_filters.rb

@@ -7,7 +7,9 @@ module Sequel
     # where you would normally have to drop down to the dataset level
     # to get the necessary control, because you only want to delete or
     # update the rows in certain cases based on the current status of
-    # the row in the database.
+    # the row in the database.  The main purpose of this plugin is to
+    # avoid race conditions by relying on the atomic properties of database
+    # transactions.
     # 
     #   class Item < Sequel::Model
     #     plugin :instance_filters
@@ -15,12 +17,12 @@ module Sequel
     #
     #   # These are two separate objects that represent the same
     #   # database row. 
-    #   i1 = Item.first(:id=>1, :delete_allowed=>false)
-    #   i2 = Item.first(:id=>1, :delete_allowed=>false)
+    #   i1 = Item.first(id: 1, delete_allowed: false)
+    #   i2 = Item.first(id: 1, delete_allowed: false)
     #
     #   # Add an instance filter to the object. This filter is in effect
     #   # until the object is successfully updated or deleted.
-    #   i1.instance_filter(:delete_allowed=>true)
+    #   i1.instance_filter(delete_allowed: true)
     #
     #   # Attempting to delete the object where the filter doesn't
     #   # match any rows raises an error.
@@ -28,7 +30,7 @@ module Sequel
     #
     #   # The other object that represents the same row has no
     #   # instance filters, and can be updated normally.
-    #   i2.update(:delete_allowed=>true)
+    #   i2.update(delete_allowed: true)
     #
     #   # Even though the filter is now still in effect, since the
     #   # database row has been updated to allow deleting,
@@ -100,7 +102,7 @@ module Sequel
         
         # Apply the instance filters to the given dataset
         def apply_instance_filters(ds)
-          instance_filters.inject(ds){|ds1, i| ds1.filter(*i[0], &i[1])}
+          instance_filters.inject(ds){|ds1, i| ds1.where(*i[0], &i[1])}
         end
         
         # Clear the instance filters.
@@ -121,10 +123,10 @@ module Sequel
         # Only use prepared statements for update and delete queries
         # if there are no instance filters.
         def use_prepared_statements_for?(type)
-          if (type == :update || type == :delete) && !instance_filters.empty?
+          if type == :update && !instance_filters.empty?
             false
           else
-            super
+            super if defined?(super)
           end
         end
       end