sequel 5.33.0 → 5.58.0

data/lib/sequel/plugins/composition.rb

@@ -143,10 +143,14 @@ module Sequel
                 compositions[name] = send(composer_meth)
               end
             end
-            define_method("#{name}=") do |v|
+            alias_method(name, name)
+
+            meth = :"#{name}="
+            define_method(meth) do |v|
               modified!
               compositions[name] = v
             end
+            alias_method(meth, meth)
           end
         end
 
@@ -167,8 +171,10 @@ module Sequel
 
         # Freeze compositions hash when freezing model instance.
         def freeze
-          compositions.freeze
+          compositions
           super
+          compositions.freeze
+          self
         end
 
         # For each composition, set the columns in the model class based

data/lib/sequel/plugins/concurrent_eager_loading.rb

@@ -0,0 +1,174 @@
+# frozen-string-literal: true
+
+module Sequel
+  extension 'async_thread_pool'
+
+  module Plugins
+    # The concurrent_eager_loading plugin allows for eager loading multiple associations
+    # concurrently in separate threads.  You must load the async_thread_pool Database
+    # extension into the Database object the model class uses in order for this plugin
+    # to work.
+    # 
+    # By default in Sequel, eager loading happens in a serial manner.  If you have code
+    # such as:
+    #
+    #   Album.eager(:artist, :genre, :tracks)
+    #
+    # Sequel will load the albums, then the artists for the albums, then
+    # the genres for the albums, then the tracks for the albums.
+    #
+    # With the concurrent_eager_loading plugin, you can use the +eager_load_concurrently+
+    # method to allow for concurrent eager loading:
+    #
+    #   Album.eager_load_concurrently.eager(:artist, :genre, :tracks)
+    #
+    # This will load the albums, first, since it needs to load the albums to know
+    # which artists, genres, and tracks to eagerly load. However, it will load the
+    # artists, genres, and tracks for the albums concurrently in separate threads.
+    # This can significantly improve performance, especially if there is significant
+    # latency between the application and the database. Note that using separate threads
+    # is only used in the case where there are multiple associations to eagerly load.
+    # With only a single association to eagerly load, there is no reason to use a
+    # separate thread, since it would not improve performance.
+    #
+    # If you want to make concurrent eager loading the default, you can load the
+    # plugin with the +:always+ option. In this case, all eager loads will be
+    # concurrent.  If you want to force a non-concurrent eager load, you can use
+    # +eager_load_serially+:
+    #
+    #   Album.eager_load_serially.eager(:artist, :genre, :tracks)
+    #
+    # Note that making concurrent eager loading the default is probably a bad idea
+    # if you are eager loading inside transactions and want the eager load to
+    # reflect changes made inside the transaction, unless you plan to use
+    # +eager_load_serially+ for such cases.  See the async_thread_pool
+    # Database extension documentation for more general caveats regarding its use.
+    #
+    # The default eager loaders for all of the association types that ship with Sequel
+    # support safe concurrent eager loading.  However, if you are specifying a custom
+    # +:eager_loader+ for an association, it may not work safely unless it it modified to
+    # support concurrent eager loading.  Taking this example from the
+    # {Advanced Associations guide}[rdoc-ref:doc/advanced_associations.rdoc]
+    #
+    #   Album.many_to_one :artist, :eager_loader=>(proc do |eo_opts|
+    #     eo_opts[:rows].each{|album| album.associations[:artist] = nil}
+    #     id_map = eo_opts[:id_map]
+    #     Artist.where(:id=>id_map.keys).all do |artist|
+    #       if albums = id_map[artist.id]
+    #         albums.each do |album|
+    #           album.associations[:artist] = artist
+    #         end
+    #       end
+    #     end
+    #   end)
+    #
+    # This would not support concurrent eager loading safely.  To support safe
+    # concurrent eager loading, you need to make sure you are not modifying
+    # the associations for objects concurrently by separate threads.  This is
+    # implemented using a mutex, which you can access via <tt>eo_opts[:mutex]</tt>.
+    # To keep things simple, you can use +Sequel.synchronize_with+ to only
+    # use this mutex if it is available.  You want to use the mutex around the
+    # code that initializes the associations (usually to +nil+ or <tt>[]</tt>),
+    # and also around the code that sets the associatied objects appropriately
+    # after they have been retreived.  You do not want to use the mutex around
+    # the code that loads the objects, since that will prevent concurrent loading.
+    # So after the changes, the custom eager loader would look like this:
+    #
+    #   Album.many_to_one :artist, :eager_loader=>(proc do |eo_opts|
+    #     Sequel.synchronize_with(eo[:mutex]) do
+    #       eo_opts[:rows].each{|album| album.associations[:artist] = nil}
+    #     end
+    #     id_map = eo_opts[:id_map]
+    #     rows = Artist.where(:id=>id_map.keys).all
+    #     Sequel.synchronize_with(eo[:mutex]) do
+    #       rows.each do |artist|
+    #         if albums = id_map[artist.id]
+    #           albums.each do |album|
+    #             album.associations[:artist] = artist
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end)
+    #
+    # Usage:
+    #
+    #   # Make all model subclass datasets support concurrent eager loading
+    #   Sequel::Model.plugin :concurrent_eager_loading
+    #
+    #   # Make the Album class datasets support concurrent eager loading
+    #   Album.plugin :concurrent_eager_loading
+    #
+    #   # Make all model subclass datasets concurrently eager load by default
+    #   Sequel::Model.plugin :concurrent_eager_loading, always: true
+    module ConcurrentEagerLoading
+      def self.configure(mod, opts=OPTS)
+        if opts.has_key?(:always)
+          mod.instance_variable_set(:@always_eager_load_concurrently, opts[:always])
+        end
+      end
+
+      module ClassMethods
+        Plugins.inherited_instance_variables(self, :@always_eager_load_concurrently => nil)
+        Plugins.def_dataset_methods(self, [:eager_load_concurrently, :eager_load_serially])
+
+        # Whether datasets for this class should eager load concurrently by default.
+        def always_eager_load_concurrently?
+          @always_eager_load_concurrently
+        end
+      end
+
+      module DatasetMethods
+        # Return a cloned dataset that will eager load associated results concurrently
+        # using the async thread pool.
+        def eager_load_concurrently
+          cached_dataset(:_eager_load_concurrently) do
+            clone(:eager_load_concurrently=>true)
+          end
+        end
+
+        # Return a cloned dataset that will noteager load associated results concurrently
+        # using the async thread pool. Only useful if the current dataset has been marked
+        # as loading concurrently, or loading concurrently is the model's default behavior.
+        def eager_load_serially
+          cached_dataset(:_eager_load_serially) do
+            clone(:eager_load_concurrently=>false)
+          end
+        end
+
+        private
+
+        # Whether this particular dataset will eager load results concurrently.
+        def eager_load_concurrently?
+          v = @opts[:eager_load_concurrently]
+          v.nil? ? model.always_eager_load_concurrently? : v
+        end
+
+        # If performing eager loads concurrently, and at least 2 associations are being
+        # eagerly loaded, create a single mutex used for all eager loads.  After the
+        # eager loads have been performed, force loading of any async results, so that
+        # all eager loads will have been completed before this method returns.
+        def perform_eager_loads(eager_load_data)
+          return super if !eager_load_concurrently? || eager_load_data.length < 2
+
+          mutex = Mutex.new
+          eager_load_data.each_value do |eo|
+            eo[:mutex] = mutex
+          end
+
+          super.each do |v|
+            if Sequel::Database::AsyncThreadPool::BaseProxy === v
+              v.__value
+            end
+          end
+        end
+
+        # If performing eager loads concurrently, perform this eager load using the
+        # async thread pool.
+        def perform_eager_load(loader, eo)
+          eo[:mutex] ? db.send(:async_run){super} : super
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/constraint_validations.rb

@@ -220,7 +220,8 @@ module Sequel
               '%'
             when '%'
               '.*'
-            when '_'
+            else
+            #when '_'
               '.'
             end
           end

data/lib/sequel/plugins/csv_serializer.rb

@@ -82,11 +82,13 @@ module Sequel
           end
         END
       else
+        # :nocov:
         # :nodoc:
         def self.csv_call(*args, opts, &block)
           CSV.send(*args, opts, &block)
         end
         # :nodoc:
+        # :nocov:
       end
 
       module ClassMethods

data/lib/sequel/plugins/dataset_associations.rb

@@ -62,7 +62,10 @@ module Sequel
           ret = super
           r = association_reflection(name)
           meth = r.returns_array? ? name : pluralize(name).to_sym
-          dataset_module{define_method(meth){associated(name)}}
+          dataset_module do
+            define_method(meth){associated(name)}
+            alias_method(meth, meth)
+          end
           ret
         end
 

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

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

@@ -111,7 +111,9 @@ module Sequel
         # 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

data/lib/sequel/plugins/insert_conflict.rb

@@ -22,6 +22,10 @@ module Sequel
     # for that album.  See the PostgreSQL and SQLite adapter documention for
     # the options you can pass to the insert_conflict method.
     #
+    # You should not attempt to use this plugin to ignore conflicts when
+    # inserting, you should only use it to turn insert conflicts into updates.
+    # Any usage to ignore conflicts is not recommended or supported.
+    #
     # Usage:
     #
     #   # Make all model subclasses support insert_conflict

data/lib/sequel/plugins/instance_specific_default.rb

@@ -0,0 +1,113 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The instance_specific_default plugin exists to make it easier to use a
+    # global :instance_specific association option, or to warn or raise when Sequel
+    # has to guess which value to use :instance_specific option (Sequel defaults to
+    # guessing true as that is the conservative setting).  It is helpful to
+    # use this plugin, particularly with the :warn or :raise settings, to determine
+    # which associations should have :instance_specific set.  Setting the
+    # :instance_specific to false for associations that are not instance specific
+    # can improve performance.
+    #
+    # Associations are instance-specific if their block calls
+    # a model instance method, or where the value of the block varies
+    # based on runtime state, and the variance is outside of a delayed evaluation.
+    # For example, with the following three associations:
+    #
+    #   Album.one_to_one :first_track, class: :Track do |ds|
+    #     ds.where(number: 1)
+    #   end
+    #
+    #   Album.one_to_one :last_track, class: :Track do |ds|
+    #     ds.where(number: num_tracks)
+    #   end
+    #
+    #   Album.one_to_many :recent_tracks, class: :Track do |ds|
+    #     ds.where{date_updated > Date.today - 10}
+    #   end
+    #
+    # +first_track+ is not instance specific, but +last_track+ and +recent_tracks+ are.
+    # +last_track+ is because the +num_tracks+ call in the block is calling
+    # <tt>Album#num_tracks</tt>.  +recent_tracks+ is because the value will change over
+    # time. This plugin allows you to find these cases, and set the :instance_specific
+    # option appropriately for them:
+    #
+    #   Album.one_to_one :first_track, class: :Track, instance_specific: false do |ds|
+    #     ds.where(number: 1)
+    #   end
+    #
+    #   Album.one_to_one :last_track, class: :Track, instance_specific: true do |ds|
+    #     ds.where(number: num_tracks)
+    #   end
+    #
+    #   Album.one_to_many :recent_tracks, class: :Track, instance_specific: true do |ds|
+    #     ds.where{date_updated > Date.today - 10}
+    #   end
+    #
+    # For the +recent_tracks+ association, instead of marking it instance_specific, you
+    # could also use a delayed evaluation, since it doesn't actually contain
+    # instance-specific code:
+    #
+    #   Album.one_to_many :recent_tracks, class: :Track, instance_specific: false do |ds|
+    #     ds.where{date_updated > Sequel.delay{Date.today - 10}}
+    #   end
+    #
+    # Possible arguments to provide when loading the plugin:
+    #
+    # true :: Set the :instance_specific option to true
+    # false :: Set the :instance_specific option to false
+    # :default :: Call super to set the :instance_specific option
+    # :warn :: Emit a warning before calling super to set the :instance_specific option
+    # :raise :: Raise a Sequel::Error if an :instance_specific option is not provided and
+    #           an association could be instance-specific.
+    #
+    # Note that this plugin only affects associations which could be instance
+    # specific (those with blocks), where the :instance_specific option was not
+    # specified when the association was created.
+    #
+    # Usage:
+    #
+    #   # Set how to handle associations that could be instance specific
+    #   # but did not specify an :instance_specific option, for all subclasses
+    #   # (set before creating subclasses).
+    #   Sequel::Model.plugin :instance_specific_default, :warn
+    #
+    #   # Set how to handle associations that could be instance specific
+    #   # but did not specify an :instance_specific option, for the Album class
+    #   Album.plugin :instance_specific_default, :warn
+    module InstanceSpecificDefault
+      # Set how to handle associations that could be instance specific but did
+      # not specify an :instance_specific value.
+      def self.configure(model, default)
+        model.instance_variable_set(:@instance_specific_default, default)
+      end
+
+      module ClassMethods
+        Plugins.inherited_instance_variables(self, :@instance_specific_default=>nil)
+
+        private
+
+        # Return the appropriate :instance_specific value, or warn or raise if
+        # configured.
+        def _association_instance_specific_default(name)
+          case @instance_specific_default
+          when true, false
+            return @instance_specific_default
+          when :default
+            # nothing
+          when :warn
+            warn("possibly instance-specific association without :instance_specific option (class: #{self}, association: #{name})", :uplevel => 3)
+          when :raise
+            raise Sequel::Error, "possibly instance-specific association without :instance_specific option (class: #{self}, association: #{name})"
+          else
+            raise Sequel::Error, "invalid value passed to instance_specific_default plugin: #{@instance_specific_default.inspect}"
+          end
+
+          super
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/json_serializer.rb

@@ -133,21 +133,39 @@ module Sequel
         end
       end
       
-      # Helper class used for making sure that cascading options
-      # for model associations works correctly.  Cascaded options
-      # work by creating instances of this class, which take a
-      # literal JSON string and have +to_json+ return it.
+      # SEQUEL6: Remove
+      # :nocov:
       class Literal
-        # Store the literal JSON to use
         def initialize(json)
           @json = json
         end
         
-        # Return the literal JSON to use
         def to_json(*a)
           @json
         end
       end
+      # :nocov:
+      Sequel::Deprecation.deprecate_constant(self, :Literal)
+
+      # Convert the given object to a JSON data structure using the given arguments.
+      def self.object_to_json_data(obj, *args, &block)
+        if obj.is_a?(Array)
+          obj.map{|x| object_to_json_data(x, *args, &block)}
+        else
+          if obj.respond_to?(:to_json_data)
+            obj.to_json_data(*args, &block)
+          else
+            begin
+              Sequel.parse_json(Sequel.object_to_json(obj, *args, &block))
+            # :nocov:
+            rescue Sequel.json_parser_error_class
+              # Support for old Ruby code that only supports parsing JSON object/array
+              Sequel.parse_json(Sequel.object_to_json([obj], *args, &block))[0]
+            # :nocov:
+            end
+          end
+        end
+      end
 
       module ClassMethods
         # The default opts to use when serializing model objects to JSON.
@@ -324,20 +342,7 @@ module Sequel
                 end
 
                 v = v.empty? ? [] : [v]
-
-                objs = public_send(k)
-
-                is_array = if r = model.association_reflection(k)
-                  r.returns_array?
-                else
-                  objs.is_a?(Array)
-                end
-                
-                h[key_name] = if is_array
-                  objs.map{|obj| Literal.new(Sequel.object_to_json(obj, *v))}
-                else
-                  Literal.new(Sequel.object_to_json(objs, *v))
-                end
+                h[key_name] = JsonSerializer.object_to_json_data(public_send(k), *v)
               end
             else
               Array(inc).each do |c|
@@ -347,7 +352,8 @@ module Sequel
                 else
                   key_name = c.to_s
                 end
-                h[key_name] = public_send(c)
+
+                h[key_name] = JsonSerializer.object_to_json_data(public_send(c))
               end
             end
           end
@@ -359,9 +365,18 @@ module Sequel
             h = {root => h}
           end
 
-          h = yield h if block_given?
+          h = yield h if defined?(yield)
           Sequel.object_to_json(h, *a)
         end
+
+        # Convert the receiver to a JSON data structure using the given arguments.
+        def to_json_data(*args, &block)
+          if block
+            to_json(*args){|x| return block.call(x)}
+          else
+            to_json(*args){|x| return x}
+          end
+        end
       end
 
       module DatasetMethods
@@ -420,13 +435,13 @@ module Sequel
             else
               all
             end
-            array.map{|obj| Literal.new(Sequel.object_to_json(obj, opts, &opts[:instance_block]))}
+            JsonSerializer.object_to_json_data(array, opts, &opts[:instance_block])
           else
             all
           end
 
           res = {collection_root => res} if collection_root
-          res = yield res if block_given?
+          res = yield res if defined?(yield)
 
           Sequel.object_to_json(res, *a)
         end