sequel 4.36.0 → 5.61.0

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

@@ -0,0 +1,124 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The enum plugin allows for easily adding methods to modify the value of
+    # a column.  It allows treating the column itself as an enum, returning a
+    # symbol for the related enum value.  It also allows for setting up dataset
+    # methods to easily find records having or not having each enum value.
+    #
+    # After loading the plugin, you can call the +enum+ method to define the
+    # methods.  The +enum+ method accepts a symbol for the underlying
+    # database column, and a hash with symbol keys for the enum values.
+    # For example, the following call:
+    #
+    #   Album.enum :status_id, good: 1, bad: 2
+    #
+    # Will define the following instance methods:
+    #
+    # Album#good! :: Change +status_id+ to +1+ (does not save the receiver)
+    # Album#bad! :: Change +status_id+ to +2+ (does not save the receiver)
+    # Album#good? :: Return whether +status_id+ is +1+
+    # Album#bad? :: Return whether +status_id+ is +2+
+    #
+    # It will override the following instance methods:
+    #
+    # Album#status_id :: Return +:good+/+:bad+ instead of +1+/+2+ (other values returned as-is)
+    # Album#status_id= :: Allow calling with +:good+/+:bad+ to set +status_id+ to +1+/+2+ (other values,
+    #                     such as <tt>'good'</tt>/<tt>'bad'</tt> set as-is)
+    #
+    # If will define the following dataset methods:
+    #
+    # Album.dataset.good :: Return a dataset filtered to rows where +status_id+ is +1+
+    # Album.dataset.not_good :: Return a dataset filtered to rows where +status_id+ is not +1+
+    # Album.dataset.bad:: Return a dataset filtered to rows where +status_id+ is +2+
+    # Album.dataset.not_bad:: Return a dataset filtered to rows where +status_id+ is not +2+
+    #
+    # When calling +enum+, you can also provide the following options:
+    #
+    # :prefix :: Use a prefix for methods defined for each enum value. If +true+ is provided at the value, use the column name as the prefix.
+    #            For example, with <tt>prefix: 'status'</tt>, the instance methods defined above would be +status_good?+, +status_bad?+,
+    #            +status_good!+, and +status_bad!+, and the dataset methods defined would be +status_good+, +status_not_good+, +status_bad+,
+    #            and +status_not_bad+.
+    # :suffix :: Use a suffix for methods defined for each enum value. If +true+ is provided at the value, use the column name as the suffix.
+    #            For example, with <tt>suffix: 'status'</tt>, the instance methods defined above would be +good_status?+, +bad_status?+,
+    #            +good_status!+, and +bad_status!+, and the dataset methods defined would be +good_status+, +not_good_status+, +bad_status+,
+    #            and +not_bad_status+.
+    # :override_accessors :: Set to +false+ to not override the column accessor methods.
+    # :dataset_methods :: Set to +false+ to not define dataset methods.
+    #
+    # Note that this does not use a true enum column in the database.  If you are
+    # looking for enum support in the database, and your are using PostgreSQL,
+    # Sequel supports that via the pg_enum Database extension.
+    #
+    # Usage:
+    #
+    #   # Make all model subclasses handle enums
+    #   Sequel::Model.plugin :enum
+    #
+    #   # Make the Album class handle enums
+    #   Album.plugin :enum
+    module Enum
+      module ClassMethods
+        # Define instance and dataset methods in this class to treat column
+        # as a enum.  See Enum documentation for usage.
+        def enum(column, values, opts=OPTS)
+          raise Sequel::Error, "enum column must be a symbol" unless column.is_a?(Symbol)
+          raise Sequel::Error, "enum values must be provided as a hash with symbol keys" unless values.is_a?(Hash) && values.all?{|k,| k.is_a?(Symbol)}
+
+          if prefix = opts[:prefix]
+            prefix = column if prefix == true
+            prefix = "#{prefix}_"
+          end
+
+          if suffix = opts[:suffix]
+            suffix = column if suffix == true
+            suffix = "_#{suffix}"
+          end
+          
+          values = Hash[values].freeze
+          inverted = values.invert.freeze
+
+          unless @enum_methods
+            @enum_methods = Module.new
+            include @enum_methods
+          end
+
+          @enum_methods.module_eval do
+            unless opts[:override_accessors] == false
+              define_method(column) do
+                v = super()
+                inverted.fetch(v, v)
+              end
+
+              define_method(:"#{column}=") do |v|
+                super(values.fetch(v, v))
+              end
+            end
+
+            values.each do |key, value|
+              define_method(:"#{prefix}#{key}#{suffix}!") do
+                self[column] = value
+                nil
+              end
+
+              define_method(:"#{prefix}#{key}#{suffix}?") do
+                self[column] == value
+              end
+            end
+          end
+
+          unless opts[:dataset_methods] == false
+            dataset_module do
+              values.each do |key, value|
+                cond = Sequel[column=>value]
+                where :"#{prefix}#{key}#{suffix}", cond
+                where :"#{prefix}not_#{key}#{suffix}", ~cond
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/error_splitter.rb

@@ -32,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