sequel 4.26.0 → 5.37.0

data/lib/sequel/plugins/eager_each.rb

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 module Sequel
   module Plugins
     # The eager_each plugin makes calling each on an eager loaded dataset do eager loading.
@@ -13,6 +15,11 @@ module Sequel
     # and setting a new flag in the cloned dataset, so that each can check with the flag to
     # determine whether it should call all.
     #
+    # This plugin also makes #first and related methods that load single records work with
+    # eager loading.  Note that when using eager_graph, calling #first or a similar method
+    # will result in two queries, one to load the main object, and one to eagerly load all associated
+    # objects to that main object.
+    #
     # Usage:
     #
     #   # Make all model subclass instances eagerly load for each (called before loading subclasses)
@@ -23,16 +30,16 @@ module Sequel
     module EagerEach 
       module DatasetMethods
         # Don't call #all when attempting to load the columns.
-        def columns
+        def columns!
           if use_eager_all?
-            clone(:all_called=>true).columns
+            clone(:all_called=>true).columns!
           else
             super
           end
         end
 
         # Call #all instead of #each if eager loading,
-        # uless #each is being called by #all.
+        # unless #each is being called by #all.
         def each(&block)
           if use_eager_all?
             all(&block)
@@ -51,6 +58,23 @@ module Sequel
           end
         end
 
+        # Handle eager loading when calling first and related methods.  For eager_graph,
+        # this does an additional query after retrieving a single record, because otherwise
+        # the associated records won't get eager loaded correctly.
+        def single_record!
+          if use_eager_all?
+            obj = clone(:all_called=>true).all.first
+
+            if opts[:eager_graph]
+              obj = clone(:all_called=>true).where(obj.qualified_pk_hash).unlimited.all.first
+            end
+
+            obj
+          else
+            super
+          end
+        end
+
         private
 
         # Wether to use all when each is called, true when eager loading

data/lib/sequel/plugins/eager_graph_eager.rb

@@ -0,0 +1,139 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The eager_graph_eager plugin allows for chaining eager loads after eager_graph
+    # loads.  Given the following model associations:
+    #
+    #   Band.one_to_many :albums
+    #   Album.one_to_many :tracks
+    #
+    # Let's say you wanted to return bands ordered by album name, and eagerly load
+    # those albums, you can do that using:
+    #
+    #   Band.eager_graph(:albums).order{albums[:name]}
+    #
+    # Let's say you also wanted to eagerly load the tracks for each album. You could
+    # just add them to the eager_graph call:
+    #  
+    #   Band.eager_graph(albums: :tracks).order{albums[:name]}
+    #
+    # However, the bloats the result set, and you aren't ordering by the track
+    # information, so a join is not required.  The eager_graph_eager plugin allows
+    # you to specify that the tracks be eagerly loaded in a separate query after
+    # the eager_graph load of albums:
+    # 
+    #   Band.eager_graph(:albums).eager_graph_eager([:albums], :tracks).order{albums[:name]}
+    #
+    # <tt>Dataset#eager_graph_eager</tt>'s first argument is a dependency chain, specified
+    # as an array of symbols.  This specifies the point at which to perform the eager load.
+    # The remaining arguments are arguments that could be passed to Dataset#eager to specify
+    # what dependent associations should be loaded at that point.
+    #
+    # If you also have the following model association:
+    #
+    #   Track.one_to_many :lyrics
+    #
+    # Here's some different ways of performing eager loading:
+    #
+    #   # 4 Queries: bands, albums, tracks, lyrics
+    #   Band.eager(albums: {tracks: :lyrics})
+    #
+    #   # 1 Query: bands+albums+tracks+lyrics
+    #   Band.eager_graph(albums: {tracks: :lyrics})
+    #
+    #   # 3 Queries: bands+albums, tracks, lyrics
+    #   Band.eager_graph(:albums).eager_graph_eager([:albums], tracks: :lyrics)
+    #
+    #   # 2 Queries: bands+albums+tracks, lyrics
+    #   Band.eager_graph(albums: :tracks).eager_graph_eager([:albums, :tracks], :lyrics)
+    #
+    #   # 2 Queries: bands+albums, tracks+lyrics
+    #   Band.eager_graph(:albums).eager_graph_eager([:albums], tracks: proc{|ds| ds.eager_graph(:lyrics)})
+    #
+    # Usage:
+    #
+    #   # Support eager_graph_eager in all subclass datasets (called before loading subclasses)
+    #   Sequel::Model.plugin :eager_graph_eager
+    #
+    #   # Support eager_graph_eager in Album class datasets
+    #   Album.plugin :eager_graph_eager
+    module EagerGraphEager
+      module DatasetMethods
+        # Specify for the given dependency chain, after loading objects for the
+        # current dataset via eager_graph, eagerly load the given associations at that point in the
+        # dependency chain.
+        #
+        # dependency_chain :: Array of association symbols, with the first association symbol
+        #                     specifying an association in the dataset's model, the next
+        #                     association specifying an association in the previous association's
+        #                     associated model, and so on.
+        # assocs :: Symbols or hashes specifying associations to eagerly load at the point
+        #           specified by the dependency chain.
+        def eager_graph_eager(dependency_chain, *assocs)
+          unless dependency_chain.is_a?(Array) && dependency_chain.all?{|s| s.is_a?(Symbol)} && !dependency_chain.empty?
+            raise Error, "eager_graph_eager first argument must be array of symbols"
+          end
+
+          current = model
+          deps = dependency_chain.map do |dep|
+            unless ref = current.association_reflection(dep)
+              raise Error, "invalid association #{dep.inspect} for #{current.inspect}"
+            end
+            current = ref.associated_class
+            [dep, ref.returns_array?]
+          end
+          assocs = current.dataset.send(:eager_options_for_associations, assocs)
+
+          deps.each(&:freeze)
+          deps.unshift(current)
+          deps.freeze
+
+          assocs.freeze
+
+          if h = @opts[:eager_graph_eager]
+            h = Hash[h]
+            h[deps] = assocs
+          else
+            h = {deps => assocs}
+          end
+
+          clone(:eager_graph_eager=>h.freeze)
+        end
+
+        protected
+
+        # After building objects from the rows, if eager_graph_eager has been
+        # called on the datasets, for each dependency chain specified, eagerly
+        # load the appropriate associations.
+        def eager_graph_build_associations(rows)
+          objects = super
+
+          if eager_data = @opts[:eager_graph_eager]
+            eager_data.each do |deps, assocs|
+              current = objects
+
+              last_class, *deps = deps
+              deps.each do |dep, is_multiple|
+                current_assocs = current.map(&:associations)
+
+                if is_multiple
+                  current = current_assocs.flat_map{|a| a[dep]}
+                else
+                  current = current_assocs.map{|a| a[dep]}
+                  current.compact!
+                end
+
+                current.uniq!(&:object_id)
+              end
+
+              last_class.dataset.send(:eager_load, current, assocs)
+            end
+          end
+
+          objects
+        end
+      end
+    end
+  end
+end

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/error_splitter.rb

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 module Sequel
   module Plugins
     # The error_splitter plugin automatically splits errors entries related to
@@ -30,25 +32,30 @@ module Sequel
     #   Album.plugin :error_splitter
     module ErrorSplitter
       module InstanceMethods
-        # If the model instance is not valid, go through all of the errors entries.  For
-        # any that apply to multiple columns, remove them and add separate error entries,
-        # one per column.
-        def _valid?(*)
+        private
+
+        # If the model instance is not valid, split the errors before returning.
+        def _valid?(opts)
           v = super
           unless v
-            errors.keys.select{|k| k.is_a?(Array)}.each do |ks|
-              msgs = errors.delete(ks)
-              ks.each do |k|
-                msgs.each do |msg|
-                  errors.add(k, msg)
-                end
+            split_validation_errors(errors)
+          end
+          v
+        end
+
+        # Go through all of the errors entries.  For any that apply to multiple columns,
+        # remove them and add separate error entries, one per column.
+        def split_validation_errors(errors)
+          errors.keys.select{|k| k.is_a?(Array)}.each do |ks|
+            msgs = errors.delete(ks)
+            ks.each do |k|
+              msgs.each do |msg|
+                errors.add(k, msg)
               end
             end
           end
-          v
         end
       end
     end
   end
 end
-

data/lib/sequel/plugins/finder.rb

@@ -0,0 +1,246 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The finder plugin adds Model.finder for defining optimized finder methods.
+    # There are two ways to use this.  The recommended way is to pass a symbol
+    # that represents a model class method that returns a dataset:
+    #
+    #   def Artist.by_name(name)
+    #     where(name: name)
+    #   end
+    #
+    #   Artist.finder :by_name
+    #
+    # This creates an optimized first_by_name method, which you can call normally:
+    #
+    #   Artist.first_by_name("Joe")
+    #
+    # The alternative way to use this to pass your own block:
+    #
+    #   Artist.finder(name: :first_by_name){|pl, ds| ds.where(name: pl.arg).limit(1)}
+    #
+    # Additionally, there is a Model.prepared_finder method.  This works similarly
+    # to Model.finder, but uses a prepared statement.  This limits the types of
+    # arguments that will be accepted, but can perform better in the database.
+    # 
+    # Usage:
+    #
+    #   # Make all model subclasses support Model.finder
+    #   # (called before loading subclasses)
+    #   Sequel::Model.plugin :finder
+    #
+    #   # Make the Album class support Model.finder
+    #   Album.plugin :finder
+    module Finder
+      FINDER_TYPES = [:first, :all, :each, :get].freeze
+
+      def self.apply(model)
+        model.instance_exec do
+          @finders ||= {}
+          @finder_loaders ||= {}
+        end
+      end
+
+      module ClassMethods
+        # Create an optimized finder method using a dataset placeholder literalizer.
+        # This pre-computes the SQL to use for the query, except for given arguments.
+        #
+        # There are two ways to use this.  The recommended way is to pass a symbol
+        # that represents a model class method that returns a dataset:
+        #
+        #   def Artist.by_name(name)
+        #     where(name: name)
+        #   end
+        #
+        #   Artist.finder :by_name
+        #
+        # This creates an optimized first_by_name method, which you can call normally:
+        #
+        #   Artist.first_by_name("Joe")
+        #
+        # The alternative way to use this to pass your own block:
+        #
+        #   Artist.finder(name: :first_by_name){|pl, ds| ds.where(name: pl.arg).limit(1)}
+        #
+        # Note that if you pass your own block, you are responsible for manually setting
+        # limits if necessary (as shown above).
+        #
+        # Options:
+        # :arity :: When using a symbol method name, this specifies the arity of the method.
+        #           This should be used if if the method accepts an arbitrary number of arguments,
+        #           or the method has default argument values.  Note that if the method is defined
+        #           as a dataset method, the class method Sequel creates accepts an arbitrary number
+        #           of arguments, so you should use this option in that case.  If you want to handle
+        #           multiple possible arities, you need to call the finder method multiple times with
+        #           unique :arity and :name methods each time.
+        # :name :: The name of the method to create.  This must be given if you pass a block.
+        #          If you use a symbol, this defaults to the symbol prefixed by the type.
+        # :mod :: The module in which to create the finder method.  Defaults to the singleton
+        #         class of the model.
+        # :type :: The type of query to run.  Can be :first, :each, :all, or :get, defaults to
+        #          :first.
+        #
+        # Caveats:
+        #
+        # This doesn't handle all possible cases.  For example, if you have a method such as:
+        #
+        #   def Artist.by_name(name)
+        #     name ? where(name: name) : exclude(name: nil)
+        #   end
+        #
+        # Then calling a finder without an argument will not work as you expect.
+        #
+        #   Artist.finder :by_name
+        #   Artist.by_name(nil).first
+        #   # WHERE (name IS NOT NULL)
+        #   Artist.first_by_name(nil)
+        #   # WHERE (name IS NULL)
+        #
+        # See Dataset::PlaceholderLiteralizer for additional caveats.
+        def finder(meth=OPTS, opts=OPTS, &block)
+          if block
+            raise Error, "cannot pass both a method name argument and a block of Model.finder" unless meth.is_a?(Hash)
+            raise Error, "cannot pass two option hashes to Model.finder" unless opts.equal?(OPTS)
+            opts = meth
+            raise Error, "must provide method name via :name option when passing block to Model.finder" unless meth_name = opts[:name]
+          end
+
+          type = opts.fetch(:type, :first)
+          unless prepare = opts[:prepare]
+            raise Error, ":type option to Model.finder must be :first, :all, :each, or :get" unless FINDER_TYPES.include?(type)
+          end
+          limit1 = type == :first || type == :get
+          meth_name ||= opts[:name] || :"#{type}_#{meth}"
+
+          argn = lambda do |model|
+            if arity = opts[:arity]
+              arity
+            else
+              method = block || model.method(meth)
+              (method.arity < 0 ? method.arity.abs - 1 : method.arity)
+            end
+          end
+
+          loader_proc = if prepare
+            proc do |model|
+              args = prepare_method_args('$a', argn.call(model))
+              ds = if block
+                model.instance_exec(*args, &block)
+              else
+                model.public_send(meth, *args)
+              end
+              ds = ds.limit(1) if limit1
+              model_name = model.name
+              if model_name.to_s.empty?
+                model_name = model.object_id
+              else
+                model_name = model_name.gsub(/\W/, '_')
+              end
+              ds.prepare(type, :"#{model_name}_#{meth_name}")
+            end
+          else
+            proc do |model|
+              n = argn.call(model)
+              block ||= lambda do |pl, model2|
+                args = (0...n).map{pl.arg}
+                ds = model2.public_send(meth, *args)
+                ds = ds.limit(1) if limit1
+                ds
+              end
+
+              Sequel::Dataset::PlaceholderLiteralizer.loader(model, &block) 
+            end
+          end
+
+          @finder_loaders[meth_name] = loader_proc
+          mod = opts[:mod] || singleton_class
+          if prepare
+            def_prepare_method(mod, meth_name)
+          else
+            def_finder_method(mod, meth_name, type)
+          end
+        end
+
+        def freeze
+          @finder_loaders.freeze
+          @finder_loaders.each_key{|k| finder_for(k)} if @dataset
+          @finders.freeze
+          super
+        end
+
+        # Similar to finder, but uses a prepared statement instead of a placeholder
+        # literalizer. This makes the SQL used static (cannot vary per call), but
+        # allows binding argument values instead of literalizing them into the SQL
+        # query string.
+        #
+        # If a block is used with this method, it is instance_execed by the model,
+        # and should accept the desired number of placeholder arguments.
+        #
+        # The options are the same as the options for finder, with the following
+        # exception:
+        # :type :: Specifies the type of prepared statement to create
+        def prepared_finder(meth=OPTS, opts=OPTS, &block)
+          if block
+            raise Error, "cannot pass both a method name argument and a block of Model.finder" unless meth.is_a?(Hash)
+            meth = meth.merge(:prepare=>true)
+          else
+            opts = opts.merge(:prepare=>true)
+          end
+          finder(meth, opts, &block)
+        end
+
+        Plugins.inherited_instance_variables(self, :@finders=>:dup, :@finder_loaders=>:dup)
+
+        private
+
+        # Define a finder method in the given module with the given method name that
+        # load rows using the finder with the given name.
+        def def_finder_method(mod, meth, type)
+          mod.send(:define_method, meth){|*args, &block| finder_for(meth).public_send(type, *args, &block)}
+        end
+
+        # Define a prepared_finder method in the given module that will call the associated prepared
+        # statement.
+        def def_prepare_method(mod, meth)
+          mod.send(:define_method, meth){|*args, &block| finder_for(meth).call(prepare_method_arg_hash(args), &block)}
+        end
+
+        # Find the finder to use for the give method.  If a finder has not been loaded
+        # for the method, load the finder and set correctly in the finders hash, then
+        # return the finder.
+        def finder_for(meth)
+          unless finder = (frozen? ? @finders[meth] : Sequel.synchronize{@finders[meth]})
+            finder_loader = @finder_loaders.fetch(meth)
+            finder = finder_loader.call(self)
+            Sequel.synchronize{@finders[meth] = finder}
+          end
+          finder
+        end
+
+        # An hash of prepared argument values for the given arguments, with keys
+        # starting at a.  Used by the methods created by prepared_finder.
+        def prepare_method_arg_hash(args)
+          h = {}
+          prepare_method_args('a', args.length).zip(args).each{|k, v| h[k] = v}
+          h
+        end
+
+        # An array of prepared statement argument names, of length n and starting with base.
+        def prepare_method_args(base, n)
+          (0...n).map do
+            s = base.to_sym
+            base = base.next
+            s
+          end
+        end
+
+        # Clear any finders when reseting the instance dataset
+        def reset_instance_dataset
+          Sequel.synchronize{@finders.clear} if @finders && !@finders.frozen?
+          super
+        end
+      end
+    end
+  end
+end