sequel 4.36.0 → 5.61.0

data/lib/sequel/plugins/static_cache.rb

@@ -10,12 +10,12 @@ module Sequel
     # are frozen so they won't be modified unexpectedly, and before hooks disallow
     # saving or destroying instances.
     #
-    # You can use the :frozen=>false option to have this plugin return unfrozen
+    # You can use the frozen: false option to have this plugin return unfrozen
     # instances.  This is slower as it requires creating new objects, but it allows
     # you to make changes to the object and save them.  If you set the option to false,
     # you are responsible for updating the cache manually (the pg_static_cache_updater
     # extension can handle this automatically).  Note that it is not safe to use the
-    # :frozen=>false option if you are mutating column values directly.  If you are
+    # frozen: false option if you are mutating column values directly.  If you are
     # mutating column values, you should also override Model.call to dup each mutable
     # column value to ensure it is not shared by other instances.
     #
@@ -24,8 +24,10 @@ module Sequel
     # * Primary key lookups (e.g. Model[1])
     # * Model.all
     # * Model.each
+    # * Model.first (without block, only supporting no arguments or single integer argument)
     # * Model.count (without an argument or block)
     # * Model.map
+    # * Model.as_hash
     # * Model.to_hash
     # * Model.to_hash_groups
     #
@@ -36,9 +38,9 @@ module Sequel
     #
     #   # Cache the AlbumType class statically, but return unfrozen instances
     #   # that can be modified.
-    #   AlbumType.plugin :static_cache, :frozen=>false
+    #   AlbumType.plugin :static_cache, frozen: false
     #
-    # If you would like the speed benefits of keeping :frozen=>true but still need
+    # If you would like the speed benefits of keeping frozen: true but still need
     # to occasionally update objects, you can side-step the before_ hooks by
     # overriding the class method +static_cache_allow_modifications?+ to return true:
     #
@@ -53,14 +55,14 @@ module Sequel
     # Now if you +#dup+ a Model object (the resulting object is not frozen), you
     # will be able to update and save the duplicate.
     # Note the caveats around your responsibility to update the cache still applies.
-    #
+    # You can update the cache via `.load_cache` method.
     module StaticCache
       # Populate the static caches when loading the plugin. Options:
       # :frozen :: Whether retrieved model objects are frozen.  The default is true,
       #            for better performance as the shared frozen objects can be used
       #            directly.  If set to false, new instances are created.
       def self.configure(model, opts=OPTS)
-        model.instance_eval do
+        model.instance_exec do
           @static_cache_frozen = opts.fetch(:frozen, true)
           load_cache
         end
@@ -70,13 +72,25 @@ module Sequel
         # A frozen ruby hash holding all of the model's frozen instances, keyed by frozen primary key.
         attr_reader :cache
 
-        # An array of all of the model's frozen instances, without issuing a database
-        # query.
-        def all
-          if @static_cache_frozen
-            @all.dup
+        # An array of all of the model's instances, without issuing a database
+        # query. If a block is given, yields each instance to the block.
+        def all(&block)
+          array = @static_cache_frozen ? @all.dup : to_a
+          array.each(&block) if block
+          array
+        end
+
+        # If a block is given, multiple arguments are given, or a single
+        # non-Integer argument is given, performs the default behavior of
+        # issuing a database query.  Otherwise, uses the cached values
+        # to return either the first cached instance (no arguments) or an
+        # array containing the number of instances specified (single integer
+        # argument).
+        def first(*args)
+          if defined?(yield) || args.length > 1 || (args.length == 1 && !args[0].is_a?(Integer))
+            super
           else
-            map{|o| o}
+            @all.first(*args)
           end
         end
 
@@ -127,41 +141,46 @@ module Sequel
         Plugins.inherited_instance_variables(self, :@static_cache_frozen=>nil)
 
         # Use the cache instead of a query to get the results.
-        def to_hash(key_column = nil, value_column = nil)
-        if key_column.nil? && value_column.nil?
-          if @static_cache_frozen
-            return Hash[cache]
-          else
-            key_column = primary_key
+        def as_hash(key_column = nil, value_column = nil, opts = OPTS)
+          if key_column.nil? && value_column.nil?
+            if @static_cache_frozen && !opts[:hash]
+              return Hash[cache]
+            else
+              key_column = primary_key
+            end
           end
-        end
 
-        h = {}
-        if value_column
-          if value_column.is_a?(Array)
-            if key_column.is_a?(Array)
-              @all.each{|r| h[r.values.values_at(*key_column)] = r.values.values_at(*value_column)}
+          h = opts[:hash] || {}
+          if value_column
+            if value_column.is_a?(Array)
+              if key_column.is_a?(Array)
+                @all.each{|r| h[r.values.values_at(*key_column)] = r.values.values_at(*value_column)}
+              else
+                @all.each{|r| h[r[key_column]] = r.values.values_at(*value_column)}
+              end
             else
-              @all.each{|r| h[r[key_column]] = r.values.values_at(*value_column)}
+              if key_column.is_a?(Array)
+                @all.each{|r| h[r.values.values_at(*key_column)] = r[value_column]}
+              else
+                @all.each{|r| h[r[key_column]] = r[value_column]}
+              end
             end
+          elsif key_column.is_a?(Array)
+            @all.each{|r| h[r.values.values_at(*key_column)] = static_cache_object(r)}
           else
-            if key_column.is_a?(Array)
-              @all.each{|r| h[r.values.values_at(*key_column)] = r[value_column]}
-            else
-              @all.each{|r| h[r[key_column]] = r[value_column]}
-            end
+            @all.each{|r| h[r[key_column]] = static_cache_object(r)}
           end
-        elsif key_column.is_a?(Array)
-          @all.each{|r| h[r.values.values_at(*key_column)] = static_cache_object(r)}
-        else
-          @all.each{|r| h[r[key_column]] = static_cache_object(r)}
+          h
         end
-        h
+
+        # Alias of as_hash for backwards compatibility.
+        def to_hash(*a)
+          as_hash(*a)
         end
 
         # Use the cache instead of a query to get the results
-        def to_hash_groups(key_column, value_column = nil)
-          h = {}
+        def to_hash_groups(key_column, value_column = nil, opts = OPTS)
+          h = opts[:hash] || {}
           if value_column
             if value_column.is_a?(Array)
               if key_column.is_a?(Array)
@@ -189,28 +208,33 @@ module Sequel
           !@static_cache_frozen
         end
 
-        private
-
-        # Return the frozen object with the given pk, or nil if no such object exists
-        # in the cache, without issuing a database query.
-        def primary_key_lookup(pk)
-          static_cache_object(cache[pk])
-        end
-
         # Reload the cache for this model by retrieving all of the instances in the dataset
         # freezing them, and populating the cached array and hash.
         def load_cache
-          a = dataset.all
+          @all = load_static_cache_rows
           h = {}
-          a.each do |o|
+          @all.each do |o|
             o.errors.freeze
             h[o.pk.freeze] = o.freeze
           end
-          @all = a.freeze
           @cache = h.freeze
         end
 
-        # If :frozen=>false is not used, just return the argument. Otherwise,
+        private
+
+        # Load the static cache rows from the database.
+        def load_static_cache_rows
+          ret = super if defined?(super)
+          ret || dataset.all.freeze
+        end
+
+        # Return the frozen object with the given pk, or nil if no such object exists
+        # in the cache, without issuing a database query.
+        def primary_key_lookup(pk)
+          static_cache_object(cache[pk])
+        end
+
+        # If frozen: false is not used, just return the argument. Otherwise,
         # create a new instance with the arguments values if the argument is
         # not nil.
         def static_cache_object(o)
@@ -223,15 +247,15 @@ module Sequel
       end
 
       module InstanceMethods
-        # Disallowing destroying the object unless the :frozen=>false option was used.
+        # Disallowing destroying the object unless the frozen: false option was used.
         def before_destroy
-          return false unless model.static_cache_allow_modifications?
+          cancel_action("modifying model objects that use the static_cache plugin is not allowed") unless model.static_cache_allow_modifications?
           super
         end
 
-        # Disallowing saving the object unless the :frozen=>false option was used.
+        # Disallowing saving the object unless the frozen: false option was used.
         def before_save
-          return false unless model.static_cache_allow_modifications?
+          cancel_action("modifying model objects that use the static_cache plugin is not allowed") unless model.static_cache_allow_modifications?
           super
         end
       end

data/lib/sequel/plugins/static_cache_cache.rb

@@ -0,0 +1,53 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The static_cache_cache plugin allows for caching the row content for subclasses
+    # that use the static cache plugin (or just the current class).  Using this plugin
+    # can avoid the need to query the database every time loading the plugin into a
+    # model, which can save time when you have a lot of models using the static_cache
+    # plugin.
+    #
+    # Usage:
+    #
+    #   # Make all model subclasses that use the static_cache plugin use
+    #   # the cached values in the given file
+    #   Sequel::Model.plugin :static_cache_cache, "static_cache.cache"
+    #
+    #   # Make the AlbumType model the cached values in the given file,
+    #   # should be loaded before the static_cache plugin
+    #   AlbumType.plugin :static_cache_cache, "static_cache.cache"
+    module StaticCacheCache
+      def self.configure(model, file)
+        model.instance_variable_set(:@static_cache_cache_file, file)
+        model.instance_variable_set(:@static_cache_cache, File.exist?(file) ? Marshal.load(File.read(file)) : {})
+      end
+
+      module ClassMethods
+        # Dump the in-memory cached rows to the cache file.
+        def dump_static_cache_cache
+          File.open(@static_cache_cache_file, 'wb'){|f| f.write(Marshal.dump(@static_cache_cache))}
+          nil
+        end
+
+        Plugins.inherited_instance_variables(self, :@static_cache_cache_file=>nil, :@static_cache_cache=>nil)
+
+        private
+
+        # Load the rows for the model from the cache if available.
+        # If not available, load the rows from the database, and
+        # then update the cache with the raw rows.
+        def load_static_cache_rows
+          if rows = Sequel.synchronize{@static_cache_cache[name]}
+            rows.map{|row| call(row)}.freeze
+          else
+            rows = dataset.all.freeze
+            raw_rows = rows.map(&:values)
+            Sequel.synchronize{@static_cache_cache[name] = raw_rows}
+            rows
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/string_stripper.rb

@@ -5,7 +5,7 @@ module Sequel
     # StringStripper is a plugin that strips all input strings
     # when assigning to the model's values. Example:
     #
-    #   album = Album.new(:name=>' A ')
+    #   album = Album.new(name: ' A ')
     #   album.name # => 'A'
     #
     # SQL::Blob instances and all non-strings are not modified by
@@ -14,7 +14,7 @@ module Sequel
     # other columns to skip the stripping:
     #
     #   Album.skip_string_stripping :foo
-    #   Album.new(:foo=>' A ').foo # => ' A '
+    #   Album.new(foo: ' A ').foo # => ' A '
     # 
     # Usage:
     #
@@ -28,7 +28,7 @@ module Sequel
         model.plugin(:input_transformer, :string_stripper){|v| (v.is_a?(String) && !v.is_a?(SQL::Blob)) ? v.strip : v}
       end
       def self.configure(model)
-        model.instance_eval{set_skipped_string_stripping_columns if @dataset}
+        model.send(:set_skipped_string_stripping_columns)
       end
 
       module ClassMethods

data/lib/sequel/plugins/subclasses.rb

@@ -2,10 +2,10 @@
 
 module Sequel
   module Plugins
-    # The Subclasses plugin keeps track of all subclasses of the
+    # The subclasses plugin keeps track of all subclasses of the
     # current model class.  Direct subclasses are available via the
     # subclasses method, and all descendent classes are available via the
-    # descendents method.
+    # descendants method:
     #
     #   c = Class.new(Sequel::Model)
     #   c.plugin :subclasses
@@ -16,7 +16,15 @@ module Sequel
     #   sc1.subclasses  # [ssc1]
     #   sc2.subclasses  # []
     #   ssc1.subclasses # []
-    #   c.descendents   # [sc1, ssc1, sc2]
+    #   c.descendants   # [sc1, ssc1, sc2]
+    #
+    # You can also finalize the associations and then freeze the classes
+    # in all descendent classes.  Doing so is a recommended practice after
+    # all models have been defined in production and testing, and this makes
+    # it easier than keeping track of the classes to finalize and freeze
+    # manually:
+    #
+    #   c.freeze_descendants
     #
     # You can provide a block when loading the plugin, and it will be called
     # with each subclass created:
@@ -27,9 +35,14 @@ module Sequel
     #   class B < Sequel::Model; end
     #   a # => [A, B]
     module Subclasses
+      NEED_SUBCLASSES = !Object.respond_to?(:subclasses) || Object.method(:subclasses).source_location
+      private_constant :NEED_SUBCLASSES
+
       # Initialize the subclasses instance variable for the model.
       def self.apply(model, &block)
-        model.instance_variable_set(:@subclasses, [])
+        # :nocov:
+        model.instance_variable_set(:@subclasses, [])  if NEED_SUBCLASSES
+        # :nocov:
         model.instance_variable_set(:@on_subclass, block)
       end
 
@@ -38,23 +51,43 @@ module Sequel
         # class created.
         attr_reader :on_subclass
 
-        # All subclasses for the current model.  Does not
-        # include the model itself.
-        attr_reader :subclasses
+        # :nocov:
+        if NEED_SUBCLASSES
+          # All subclasses for the current model.  Does not
+          # include the model itself.
+          attr_reader :subclasses
+        end
+        # :nocov:
 
         # All descendent classes of this model.
-        def descendents
-          Sequel.synchronize{subclasses.dup}.map{|x| [x] + x.send(:descendents)}.flatten
+        def descendants
+          Sequel.synchronize{subclasses.dup}.map{|x| [x] + x.send(:descendants)}.flatten
         end
 
+        # SEQUEL6: Remove
+        alias descendents descendants
+
+        # Freeze all descendent classes.  This also finalizes the associations for those
+        # classes before freezing.
+        def freeze_descendants
+          descendants.each(&:finalize_associations).each(&:freeze)
+        end
+
+        # SEQUEL6: Remove
+        alias freeze_descendents freeze_descendants
+
         Plugins.inherited_instance_variables(self, :@subclasses=>lambda{|v| []}, :@on_subclass=>nil)
 
+        private
+
         # Add the subclass to this model's current subclasses,
         # and initialize a new subclasses instance variable
         # in the subclass.
         def inherited(subclass)
           super
-          Sequel.synchronize{subclasses << subclass}
+          # :nocov:
+          Sequel.synchronize{subclasses << subclass} if NEED_SUBCLASSES
+          # :nocov:
           on_subclass.call(subclass) if on_subclass
         end
       end

data/lib/sequel/plugins/subset_conditions.rb

@@ -13,7 +13,9 @@ module Sequel
     #   Album.plugin :subset_conditions
     #
     #   # This will now create a published_conditions method
-    #   Album.subset :published, :published => true
+    #   Album.dataset_module do
+    #     subset :published, published: true
+    #   end
     #
     #   Album.where(Album.published_conditions).sql
     #   # SELECT * FROM albums WHERE (published IS TRUE)
@@ -21,16 +23,24 @@ module Sequel
     #   Album.exclude(Album.published_conditions).sql
     #   # SELECT * FROM albums WHERE (published IS NOT TRUE)
     #
-    #   Album.where(Sequel.|(Album.published_conditions, :ready=>true)).sql
+    #   Album.where(Album.published_conditions | {ready: true}).sql
     #   # SELECT * FROM albums WHERE ((published IS TRUE) OR (ready IS TRUE))
     module SubsetConditions
-      module ClassMethods
+      def self.apply(model, &block)
+        model.instance_exec do
+          @dataset_module_class = Class.new(@dataset_module_class) do
+            include DatasetModuleMethods
+          end
+        end
+      end
+
+      module DatasetModuleMethods
         # Also create a method that returns the conditions the filter uses.
-        def subset(name, *args, &block)
+        def where(name, *args, &block)
           super
           cond = args
           cond = cond.first if cond.size == 1
-          def_dataset_method(:"#{name}_conditions"){filter_expr(cond, &block)}
+          define_method(:"#{name}_conditions"){filter_expr(cond, &block)}
         end
       end
     end

data/lib/sequel/plugins/table_select.rb

@@ -20,7 +20,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
         end
       end
@@ -32,7 +32,7 @@ module Sequel
         # has no explicit selection, select table.* from that table.
         def convert_input_dataset(ds)
           ds = super
-          if !ds.opts[:select] && (from = ds.opts[:from]) && from.length == 1 && !ds.opts[:join]
+          unless ds.opts[:select]
             ds = ds.select_all(ds.first_source)
           end
           ds

data/lib/sequel/plugins/tactical_eager_loading.rb

@@ -4,7 +4,7 @@ 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
@@ -16,7 +16,7 @@ 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)
@@ -30,7 +30,7 @@ module Sequel
     # objects that the current object was retrieved with:
     #
     #   # SELECT * FROM albums WHERE (id < 100)
-    #   albums = Album.filter{id<100}.all
+    #   albums = Album.where{id<100}.all
     #
     #   # Eagerly load all artists for these albums
     #   # SELECT * FROM artists WHERE id IN (...)
@@ -40,25 +40,81 @@ module Sequel
     #
     #   # Eagerly reload all artists for these albums
     #   # SELECT * FROM artists WHERE id IN (...)
-    #   albums.first.artists(:eager_reload=>true)
+    #   albums.first.artists(eager_reload: true)
     # 
     # You can also use the :eager option to specify dependent associations
     # to eager load:
     #
-    #  albums = Album.filter{id<100}.all
+    #  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)
+    #   albums.first.artists(eager: :albums)
     #
     # You can also use :eager to specify an eager callback. For example:
     #
-    #   albums = Album.filter{id<100}.all
+    #   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=>proc{|ds| ds.where(:name > 'N')})
+    #   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.
+    #
+    # Because this plugin will automatically use eager loading for
+    # performance, it can break code that defines associations that
+    # do not support eager loading, without marking that they do not
+    # support eager loading via the <tt>allow_eager: false</tt> option.
+    # Make sure to set <tt>allow_eager: false</tt> on any association
+    # used with this plugin if the association doesn't support eager loading.
     #
     # Usage:
     #
@@ -91,12 +147,18 @@ 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, dynamic_opts=nil, &block)
+        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) || dynamic_opts[:eager_reload]) && retrieved_by && !frozen? && !dynamic_opts[:callback] && !dynamic_opts[:reload]
+          eager_reload = dynamic_opts[:eager_reload]
+          if (!associations.include?(name) || 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=>dynamic_opts[:eager] || {})
+              objects = if eager_reload
+                retrieved_with.reject(&:frozen?)
+              else
+                retrieved_with.reject{|x| x.frozen? || x.associations.include?(name)}
+              end
+              retrieved_by.send(:eager_load, objects, 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
@@ -112,7 +174,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