sequel 5.8.0 → 5.38.0

data/lib/sequel/plugins/defaults_setter.rb

@@ -95,7 +95,7 @@ module Sequel
               end
             end
           end
-          @default_values = h.merge!(@default_values || {})
+          @default_values = h.merge!(@default_values || OPTS)
         end
 
         # Handle the CURRENT_DATE and CURRENT_TIMESTAMP values specially by returning an appropriate Date or
@@ -116,7 +116,7 @@ module Sequel
         # Use default value for a new record if values doesn't already contain an entry for it.
         def [](k)
           if new? && !values.has_key?(k)
-            v = model.default_values[k]
+            v = model.default_values.fetch(k){return}
             v = v.call if v.respond_to?(:call)
             values[k] = v if model.cache_default_values?
             v

data/lib/sequel/plugins/dirty.rb

@@ -41,6 +41,15 @@ module Sequel
     #   artist.column_changes        # => {}
     #   artist.previous_changes      # => {:name=>['Foo', 'Bar']}
     #
+    #   artist.column_previously_was(:name)
+    #   # => 'Foo'
+    #   artist.column_previously_changed?(:name)
+    #   # => true
+    #   artist.column_previously_changed?(:name, from: 'Foo', to: 'Bar')
+    #   # => true
+    #   artist.column_previously_changed?(:name, from: 'Foo', to: 'Baz')
+    #   # => false
+    #
     # There is one caveat; when used with a column that also uses the
     # serialization plugin, setting the column back to its original value
     # after changing it is not correctly detected and will leave an entry
@@ -61,6 +70,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.
@@ -92,6 +114,41 @@ module Sequel
           initial_values.has_key?(column)
         end
 
+        # Whether the column was previously changed.
+        # Options:
+        # :from :: If given, the previous initial value of the column must match this
+        # :to :: If given, the previous changed value of the column must match this
+        #
+        #   update(name: 'Current')
+        #   previous_changes                  # => {:name=>['Initial', 'Current']}
+        #   column_previously_changed?(:name) # => true
+        #   column_previously_changed?(:id)   # => false
+        #   column_previously_changed?(:name, from: 'Initial', to: 'Current') # => true
+        #   column_previously_changed?(:name, from: 'Foo', to: 'Current')     # => false
+        def column_previously_changed?(column, opts=OPTS)
+          return false unless (pc = @previous_changes) && (val = pc[column])
+
+          if opts.has_key?(:from)
+            return false unless val[0] == opts[:from]
+          end
+
+          if opts.has_key?(:to)
+            return false unless val[1] == opts[:to]
+          end
+
+          true
+        end
+
+        # The previous value of the column, which is the initial value of
+        # the column before the object was previously saved.
+        #
+        #   initial_value(:name) # => 'Initial'
+        #   update(name: 'Current')
+        #   column_previously_was(:name) # => 'Initial'
+        def column_previously_was(column)
+          (pc = @previous_changes) && (val = pc[column]) && val[0]
+        end
+
         # Freeze internal data structures
         def freeze
           initial_values.freeze
@@ -159,23 +216,10 @@ module Sequel
 
         private
 
-        # Reset the initial values when setting values.
-        def _refresh_set_values(hash)
-          reset_initial_values
-          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
+        # Reset initial values when clearing changed columns
+        def _clear_changed_columns(reason)
+          reset_initial_values if reason == :initialize || reason == :refresh
           super
-          @previous_changes = column_changes
         end
 
         # When changing the column value, save the initial column value.  If the column
@@ -214,12 +258,6 @@ module Sequel
           self
         end
 
-        # Reset the initial values when initializing.
-        def initialize_set(h)
-          super
-          reset_initial_values
-        end
-
         # Array holding column symbols that were not present initially.  This is necessary
         # to differentiate between values that were not present and values that were
         # present but equal to nil.

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

@@ -35,8 +35,8 @@ module Sequel
     module Finder
       FINDER_TYPES = [:first, :all, :each, :get].freeze
 
-      def self.apply(mod)
-        mod.instance_exec do
+      def self.apply(model)
+        model.instance_exec do
           @finders ||= {}
           @finder_loaders ||= {}
         end

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