sequel 4.26.0 → 5.37.0

data/lib/sequel/plugins/tactical_eager_loading.rb

@@ -1,8 +1,10 @@
+# frozen-string-literal: true
+
 module Sequel
   module Plugins
     # The tactical_eager_loading plugin allows you to eagerly load
     # an association for all objects retrieved from the same dataset
-    # without calling eager on the dataset.  If you attempt to load
+    # without calling +eager+ on the dataset.  If you attempt to load
     # associated objects for a record and the association for that
     # object is currently not cached, it assumes you want to get
     # the associated objects for all objects retrieved with the dataset that
@@ -14,10 +16,99 @@ module Sequel
     #
     # Basically, this allows the following code to issue only two queries:
     #
-    #   Album.filter{id<100}.all do |a|
+    #   Album.where{id<100}.all do |a|
     #     a.artists
     #   end
+    #   # SELECT * FROM albums WHERE (id < 100)
+    #   # SELECT * FROM artists WHERE id IN (...)
+    #
+    # Note that if you are passing a callback to the association method via
+    # a block or :callback option, or using the :reload option to reload
+    # the association, eager loading will not be done.
+    #
+    # You can use the :eager_reload option to reload the association for all
+    # objects that the current object was retrieved with:
+    #
+    #   # SELECT * FROM albums WHERE (id < 100)
+    #   albums = Album.where{id<100}.all
+    #
+    #   # Eagerly load all artists for these albums
+    #   # SELECT * FROM artists WHERE id IN (...)
+    #   albums.first.artists
+    #
+    #   # Do something that may affect which artists are associated to the albums
+    #
+    #   # Eagerly reload all artists for these albums
+    #   # SELECT * FROM artists WHERE id IN (...)
+    #   albums.first.artists(eager_reload: true)
     # 
+    # You can also use the :eager option to specify dependent associations
+    # to eager load:
+    #
+    #  albums = Album.where{id<100}.all
+    #
+    #   # Eager load all artists for these albums, and all albums for those artists
+    #   # SELECT * FROM artists WHERE id IN (...)
+    #   # SELECT * FROM albums WHERE artist_id IN (...)
+    #   albums.first.artists(eager: :albums)
+    #
+    # You can also use :eager to specify an eager callback. For example:
+    #
+    #   albums = Album.where{id<100}.all
+    #
+    #   # Eagerly load all artists whose name starts with A-M for these albums
+    #   # SELECT * FROM artists WHERE name > 'N' AND id IN (...)
+    #   albums.first.artists(eager: lambda{|ds| ds.where(Sequel[:name] > 'N')})
+    #
+    # Note that the :eager option only takes effect if the association
+    # has not already been loaded for the model.
+    #
+    # The tactical_eager_loading plugin also allows transparent eager
+    # loading when calling association methods on associated objects
+    # eagerly loaded via Dataset#eager_graph.  This can reduce N queries
+    # to a single query when iterating over all associated objects.
+    # Consider the following code:
+    #
+    #   artists = Artist.eager_graph(:albums).all
+    #   artists.each do |artist|
+    #     artist.albums.each do |album|
+    #       album.tracks
+    #     end
+    #   end
+    #
+    # By default this will issue a single query to load the artists and
+    # albums, and then one query for each album to load the tracks for
+    # the album:
+    #
+    #   # SELECT artists.id, ...
+    #            albums.id, ...
+    #   # FROM artists
+    #   # LEFT OUTER JOIN albums ON (albums.artist_id = artists.id);
+    #   # SELECT * FROM tracks WHERE album_id = 1;
+    #   # SELECT * FROM tracks WHERE album_id = 2;
+    #   # SELECT * FROM tracks WHERE album_id = 10;
+    #   # ...
+    #
+    # With the tactical_eager_loading plugin, this uses the same
+    # query to load the artists and albums, but then issues a single query
+    # to load the tracks for all albums.
+    #
+    #   # SELECT artists.id, ...
+    #            albums.id, ...
+    #   # FROM artists
+    #   # LEFT OUTER JOIN albums ON (albums.artist_id = artists.id);
+    #   # SELECT * FROM tracks WHERE (tracks.album_id IN (1, 2, 10, ...));
+    #
+    # Note that transparent eager loading for associated objects
+    # loaded by eager_graph will only take place if the associated classes
+    # also use the tactical_eager_loading plugin.
+    #
+    # When using this plugin, calling association methods on separate
+    # instances of the same result set is not thread-safe, because this
+    # plugin attempts to modify all instances of the same result set
+    # to eagerly set the associated objects, and having separate threads
+    # modify the same model instance is not thread-safe.
+    #
     # Usage:
     #
     #   # Make all model subclass instances use tactical eager loading (called before loading subclasses)
@@ -49,11 +140,12 @@ module Sequel
         # If there the association is not in the associations cache and the object
         # was reteived via Dataset#all, eagerly load the association for all model
         # objects retrieved with the current object.
-        def load_associated_objects(opts, reload=false)
+        def load_associated_objects(opts, dynamic_opts=OPTS, &block)
+          dynamic_opts = load_association_objects_options(dynamic_opts, &block)
           name = opts[:name]
-          if !associations.include?(name) && retrieved_by && !frozen?
+          if (!associations.include?(name) || dynamic_opts[:eager_reload]) && opts[:allow_eager] != false && retrieved_by && !frozen? && !dynamic_opts[:callback] && !dynamic_opts[:reload]
             begin
-              retrieved_by.send(:eager_load, retrieved_with.reject(&:frozen?), name=>{})
+              retrieved_by.send(:eager_load, retrieved_with.reject(&:frozen?), name=>dynamic_opts[:eager] || OPTS)
             rescue Sequel::UndefinedAssociation
               # This can happen if class table inheritance is used and the association
               # is only defined in a subclass.  This particular instance can use the
@@ -69,7 +161,29 @@ module Sequel
       module DatasetMethods
         private
 
-        # Set the retrieved_with and retrieved_by attributes for the object
+        # Set the retrieved_with and retrieved_by attributes for each of the associated objects
+        # created by the eager graph loader with the appropriate class dataset and array of objects.
+        def _eager_graph_build_associations(_, egl)
+          objects = super
+
+          master = egl.master
+          egl.records_map.each do |k, v|
+            next if k == master || v.empty?
+
+            by = opts[:graph][:table_aliases][k]
+            values = v.values
+
+            values.each do |o|
+              next unless o.is_a?(TacticalEagerLoading::InstanceMethods) && !o.retrieved_by
+              o.retrieved_by = by
+              o.retrieved_with = values
+            end
+          end
+
+          objects
+        end
+
+        # Set the retrieved_with and retrieved_by attributes for each object
         # with the current dataset and array of all objects.
         def post_load(objects)
           super

data/lib/sequel/plugins/throw_failures.rb

@@ -0,0 +1,110 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The throw_failures plugin throws HookFailed and ValidationFailed exceptions instead
+    # of raising them.  If there is no matching catch block, the UncaughtThrowError will be rescued
+    # and the HookFailed or ValidationFailed exception will be raised normally.
+    #
+    # If you are setting up the catch blocks to handle these failures, in the failure case this
+    # plugin is about 10-15% faster on CRuby and 10x faster on JRuby.  If you are not
+    # setting up the catch blocks, in the failure case this plugin is about 30% slower on CRuby
+    # and 2x slower on JRuby.  So this plugin should only be used if you are setting up catch
+    # blocks manually.
+    #
+    # This plugin will setup catch blocks automatically for internally rescued HookFailed
+    # exceptions when the model is configured to not raise exceptions on failure (by default,
+    # the exceptions are internally rescued in that case.
+    #
+    # To set up the catch blocks, use the class of the exception:
+    #
+    #   ret = catch(Sequel::ValidationFailed) do
+    #     model_instance.save
+    #   end
+    #   if ret.is_a?(Sequel::ValidationFailed)
+    #     # handle failure
+    #   else
+    #     # handle success
+    #   end
+    #
+    # Usage:
+    #
+    #   # Make all model subclass instances throw HookFailed and ValidationFailed exceptions
+    #   # (called before loading subclasses)
+    #   Sequel::Model.plugin :throw_failures
+    #
+    #   # Make the Album class throw HookFailed and ValidationFailed exceptions
+    #   Album.plugin :throw_failures
+    module ThrowFailures
+      module InstanceMethods
+        # Catch any thrown HookFailed exceptions.
+        def valid?(opts = OPTS)
+          catch_hook_failures{super} || false
+        end
+
+        private
+
+        # Catch any HookFailed exceptions thrown inside the block, and return
+        # nil if there were any.
+        def catch_hook_failures
+          called = ret = nil
+          catch(HookFailed) do
+            ret = yield
+            called = true
+          end
+          ret if called
+        end
+
+        # Catch any thrown HookFailed exceptions if not raising on failure.
+        def checked_save_failure(opts)
+          if raise_on_failure?(opts)
+            super
+          else
+            catch_hook_failures{super}
+          end
+        end
+
+        if RUBY_VERSION >= '2.2' && (!defined?(JRUBY_VERSION) || JRUBY_VERSION > '9.1')
+          # Throw HookFailed with the generated error.  If the throw is not
+          # caught, just return the originally generated error.
+          def hook_failed_error(msg)
+            e = super
+            throw HookFailed, e
+          rescue UncaughtThrowError
+            e
+          end
+
+          # Throw ValidationFailed with the generated error.  If the throw is not
+          # caught, just return the originally generated error.
+          def validation_failed_error
+            e = super
+            throw ValidationFailed, e
+          rescue UncaughtThrowError
+            e
+          end
+        else
+          # UncaughtThrowError was added in Ruby 2.2.  Older Ruby versions
+          # used ArgumentError with "uncaught throw" at the start of the message
+
+          # :nocov:
+          def hook_failed_error(msg)
+            e = super
+            throw HookFailed, e
+          rescue ArgumentError => e2
+            raise e2 unless e2.message.start_with?('uncaught throw')
+            e
+          end
+
+          def validation_failed_error
+            e = super
+            throw ValidationFailed, e
+          rescue ArgumentError => e2
+            raise e2 unless e2.message.start_with?('uncaught throw')
+            e
+          end
+          # :nocov:
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/timestamps.rb

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 module Sequel
   module Plugins
     # The timestamps plugin creates hooks that automatically set create and
@@ -13,21 +15,23 @@ module Sequel
     #   Sequel::Model.plugin :timestamps
     #
     #   # Timestamp Album instances, with custom column names
-    #   Album.plugin :timestamps, :create=>:created_on, :update=>:updated_on
+    #   Album.plugin :timestamps, create: :created_on, update: :updated_on
     #
     #   # Timestamp Artist instances, forcing an overwrite of the create
     #   # timestamp, and setting the update timestamp when creating
-    #   Album.plugin :timestamps, :force=>true, :update_on_create=>true
+    #   Album.plugin :timestamps, force: true, update_on_create: true
     module Timestamps
       # Configure the plugin by setting the available options.  Note that
       # if this method is run more than once, previous settings are ignored,
       # and it will just use the settings given or the default settings.  Options:
+      # :allow_manual_update :: Whether to skip setting the update timestamp if it has been modified manually (default: false)
       # :create :: The field to hold the create timestamp (default: :created_at)
       # :force :: Whether to overwrite an existing create timestamp (default: false)
       # :update :: The field to hold the update timestamp (default: :updated_at)
       # :update_on_create :: Whether to set the update timestamp to the create timestamp when creating (default: false)
       def self.configure(model, opts=OPTS)
-        model.instance_eval do
+        model.instance_exec do
+          @allow_manual_timestamp_update = opts[:allow_manual_update]||false
           @create_timestamp_field = opts[:create]||:created_at
           @update_timestamp_field = opts[:update]||:updated_at
           @create_timestamp_overwrite = opts[:force]||false
@@ -47,9 +51,18 @@ module Sequel
           @create_timestamp_overwrite
         end
         
-        Plugins.inherited_instance_variables(self, :@create_timestamp_field=>nil, :@update_timestamp_field=>nil,
-          :@create_timestamp_overwrite=>nil, :@set_update_timestamp_on_create=>nil)
+        Plugins.inherited_instance_variables(self,
+          :@allow_manual_timestamp_update=>nil,
+          :@create_timestamp_field=>nil,
+          :@create_timestamp_overwrite=>nil,
+          :@set_update_timestamp_on_create=>nil,
+          :@update_timestamp_field=>nil)
         
+        # Whether to allow manual setting of the update timestamp when creating
+        def allow_manual_timestamp_update?
+          @allow_manual_timestamp_update
+        end
+
         # Whether to set the update timestamp to the create timestamp when creating
         def set_update_timestamp_on_create?
           @set_update_timestamp_on_create
@@ -63,14 +76,14 @@ module Sequel
           super
         end
         
-        private
-        
         # Set the create timestamp when creating
-        def _before_validation
+        def before_validation
           set_create_timestamp if new?
           super
         end
         
+        private
+
         # If the object has accessor methods for the create timestamp field, and
         # the create timestamp value is nil or overwriting it is allowed, set the
         # create timestamp field to the time given or the current time.  If setting
@@ -86,6 +99,7 @@ module Sequel
         # Set the update timestamp to the time given or the current time if the
         # object has a setter method for the update timestamp field.
         def set_update_timestamp(time=nil)
+          return if model.allow_manual_timestamp_update? && modified?(model.update_timestamp_field)
           meth = :"#{model.update_timestamp_field}="
           set_column_value(meth, time||model.dataset.current_datetime) if respond_to?(meth)
         end

data/lib/sequel/plugins/touch.rb

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 module Sequel
   module Plugins
     # The touch plugin adds a touch method to model instances, which saves
@@ -20,16 +22,13 @@ module Sequel
     #   Sequel::Model.plugin :touch
     #
     #   # Allow touching of Album instances, with a custom column
-    #   Album.plugin :touch, :column=>:updated_on
+    #   Album.plugin :touch, column: :updated_on
     #
     #   # Allow touching of Artist instances, updating the albums and tags
     #   # associations when touching, touching the +updated_on+ column for
     #   # albums and the +updated_at+ column for tags
-    #   Artist.plugin :touch, :associations=>[{:albums=>:updated_on}, :tags]
+    #   Artist.plugin :touch, associations: [{albums: :updated_on}, :tags]
     module Touch
-      # The default column to update when touching
-      TOUCH_COLUMN_DEFAULT = :updated_at
-
       def self.apply(model, opts=OPTS)
         model.instance_variable_set(:@touched_associations, {})
       end
@@ -44,7 +43,7 @@ module Sequel
       #                  If a hash is used, the value is used as the column to update.
       # :column :: The column to modify when touching a model instance.
       def self.configure(model, opts=OPTS)
-        model.touch_column = opts[:column] || TOUCH_COLUMN_DEFAULT if opts[:column] || !model.touch_column
+        model.touch_column = opts[:column] || :updated_at if opts[:column] || !model.touch_column
         model.touch_associations(opts[:associations]) if opts[:associations]
       end
 
@@ -61,6 +60,13 @@ module Sequel
 
         Plugins.inherited_instance_variables(self, :@touched_associations=>:dup, :@touch_column=>nil)
 
+        # Freeze the touched associations when freezing the model class.
+        def freeze
+          @touched_associations.freeze
+
+          super
+        end
+
         # Add additional associations to be touched.  See the :association option
         # of the Sequel::Plugin::Touch.configure method for the format of the associations
         # arguments.
@@ -76,6 +82,12 @@ module Sequel
       end
 
       module InstanceMethods
+        # Touch all of the model's touched_associations when creating the object.
+        def after_create
+          super
+          touch_associations
+        end
+
         # Touch all of the model's touched_associations when destroying the object.
         def after_destroy
           super
@@ -115,16 +127,17 @@ module Sequel
           model.touched_associations.each do |assoc, column|
             r = model.association_reflection(assoc)
             next unless r.can_have_associated_objects?(self)
-            ds = send(r.dataset_method)
+            ds = public_send(r[:dataset_method])
 
             if ds.send(:joined_dataset?)
               # Can't update all values at once, so update each instance individually.
               # Instead if doing a simple save, update via the instance's dataset,
               # to avoid going into an infinite loop in some cases.
-              send(r[:name]).each{|x| x.this.update(column=>touch_association_value)}
+              public_send(assoc).each{|x| x.this.update(column=>touch_association_value)}
             else
               # Update all values at once for performance reasons.
               ds.update(column=>touch_association_value)
+              associations.delete(assoc)
             end
           end
         end

data/lib/sequel/plugins/tree.rb

@@ -1,6 +1,8 @@
+# frozen-string-literal: true
+
 module Sequel
   module Plugins
-    # The Tree plugin adds additional associations and methods that allow you to 
+    # The tree plugin adds additional associations and methods that allow you to 
     # treat a Model as a tree.  
     #
     # A column for holding the parent key is required and is :parent_id by default.  
@@ -19,7 +21,7 @@ module Sequel
     #   end
     #  
     #   class Node < Sequel::Model
-    #     plugin :tree, :key=>:parentid, :order=>:position
+    #     plugin :tree, key: :parentid, order: :position
     #   end
     module Tree
       # Create parent and children associations.  Any options
@@ -30,25 +32,27 @@ module Sequel
       def self.apply(model, opts=OPTS)
         opts = opts.dup
         opts[:class] = model
+        opts[:key] ||= :parent_id
 
-        model.instance_eval do
-          @parent_column = (opts[:key] ||= :parent_id)
-          @tree_order = opts[:order]
-        end
-        
-        par = opts.merge(opts.fetch(:parent, {}))
+        par = opts.merge(opts.fetch(:parent, OPTS))
         parent = par.fetch(:name, :parent)
         
-        chi = opts.merge(opts.fetch(:children, {}))
+        chi = opts.merge(opts.fetch(:children, OPTS))
         children = chi.fetch(:name, :children)
 
         par[:reciprocal] = children
         chi[:reciprocal] = parent
 
-        model.many_to_one parent, par
-        model.one_to_many children, chi
+        model.instance_exec do
+          @parent_column = opts[:key]
+          @tree_order = opts[:order]
+          @parent_association_name = parent
+          @children_association_name = children
 
-        model.plugin SingleRoot if opts[:single_root]
+          many_to_one parent, par
+          one_to_many children, chi
+          plugin SingleRoot if opts[:single_root]
+        end
       end
       
       module ClassMethods
@@ -59,22 +63,20 @@ module Sequel
         # parent of the leaf.
         attr_accessor :parent_column
 
-        Plugins.inherited_instance_variables(self, :@parent_column=>nil, :@tree_order=>nil)
+        # The association name for the parent association
+        attr_reader :parent_association_name
 
-        # Returns list of all root nodes (those with no parent nodes).
-        #
-        #   TreeClass.roots # => [root1, root2]
-        def roots
-          roots_dataset.all
-        end
+        # The association name for the children association
+        attr_reader :children_association_name
+
+        Plugins.inherited_instance_variables(self, :@parent_column=>nil, :@tree_order=>nil, :@parent_association_name=>nil, :@children_association_name=>nil)
+        Plugins.def_dataset_methods(self, [:roots, :roots_dataset])
+
+        # Should freeze tree order if it is an array when freezing the model class.
+        def freeze
+          @tree_order.freeze if @tree_order.is_a?(Array)
         
-        # Returns the dataset for retrieval of all root nodes
-        #
-        #   TreeClass.roots_dataset # => Sequel::Dataset instance
-        def roots_dataset
-          ds = where(Sequel.or(Array(parent_column).zip([])))
-          ds = ds.order(*tree_order) if tree_order
-          ds
+          super
         end
       end
       
@@ -84,7 +86,10 @@ module Sequel
         #   subchild1.ancestors # => [child1, root]
         def ancestors
           node, nodes = self, []
-          nodes << node = node.parent while node.parent
+          meth = model.parent_association_name
+          while par = node.send(meth)
+            nodes << node = par
+          end
           nodes
         end
 
@@ -92,8 +97,8 @@ module Sequel
         #
         #   node.descendants # => [child1, child2, subchild1_1, subchild1_2, subchild2_1, subchild2_2]
         def descendants
-          nodes = children.dup
-          children.each{|child| nodes.concat(child.descendants)}
+          nodes = send(model.children_association_name).dup
+          send(model.children_association_name).each{|child| nodes.concat(child.descendants)}
           nodes 
         end
 
@@ -112,7 +117,11 @@ module Sequel
         #
         #   subchild1.self_and_siblings # => [subchild1, subchild2]
         def self_and_siblings
-          parent ? parent.children : model.roots
+          if parent = send(model.parent_association_name)
+            parent.send(model.children_association_name)
+          else
+            model.roots
+          end
         end
 
         # Returns all siblings of the current node.
@@ -130,6 +139,24 @@ module Sequel
         end
       end
 
+      module DatasetMethods
+        # Returns list of all root nodes (those with no parent nodes).
+        #
+        #   TreeClass.roots # => [root1, root2]
+        def roots
+          roots_dataset.all
+        end
+
+        # Returns the dataset for retrieval of all root nodes
+        #
+        #   TreeClass.roots_dataset # => Sequel::Dataset instance
+        def roots_dataset
+          ds = where(Sequel.or(Array(model.parent_column).zip([])))
+          ds = ds.order(*model.tree_order) if model.tree_order
+          ds
+        end
+      end
+
       # Plugin included when :single_root option is passed.
       module SingleRoot
         module ClassMethods