sequel 5.39.0 → 5.64.0

data/lib/sequel/plugins/composition.rb

@@ -39,8 +39,8 @@ module Sequel
     # also be implemented as:
     #
     #   Album.composition :date,
-    #     :composer=>proc{Date.new(year, month, day) if year || month || day},
-    #     :decomposer=>(proc do
+    #     composer: proc{Date.new(year, month, day) if year || month || day},
+    #     decomposer: (proc do
     #       if d = compositions[:date]
     #         self.year = d.year
     #         self.month = d.month
@@ -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/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

@@ -37,7 +37,7 @@ module Sequel
     #
     # It also saves the previously changed values after an update:
     #
-    #   artist.update(:name=>'Bar')
+    #   artist.update(name: 'Bar')
     #   artist.column_changes        # => {}
     #   artist.previous_changes      # => {:name=>['Foo', 'Bar']}
     #

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

@@ -97,7 +97,9 @@ module Sequel
         #   Artist.first_by_name(nil)
         #   # WHERE (name IS NULL)
         #
-        # See Dataset::PlaceholderLiteralizer for additional caveats.
+        # See Dataset::PlaceholderLiteralizer for additional caveats. Note that if the model's
+        # dataset does not support placeholder literalizers, you will not be able to use this
+        # method.
         def finder(meth=OPTS, opts=OPTS, &block)
           if block
             raise Error, "cannot pass both a method name argument and a block of Model.finder" unless meth.is_a?(Hash)

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

@@ -29,7 +29,7 @@ module Sequel
     #   end
     #
     # +first_track+ is not instance specific, but +last_track+ and +recent_tracks+ are.
-    # +last_trac+ is because the +num_tracks+ call in the block is calling
+    # +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:

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

data/lib/sequel/plugins/lazy_attributes.rb

@@ -52,7 +52,9 @@ module Sequel
           unless select = dataset.opts[:select]
             select = dataset.columns.map{|c| Sequel.qualify(dataset.first_source, c)}
           end
+          db_schema = @db_schema
           set_dataset(dataset.select(*select.reject{|c| attrs.include?(dataset.send(:_hash_key_symbol, c))}))
+          @db_schema = db_schema
           attrs.each{|a| define_lazy_attribute_getter(a)}
         end
         
@@ -71,6 +73,7 @@ module Sequel
                 super()
               end
             end
+            alias_method(a, a)
           end
         end
       end

data/lib/sequel/plugins/list.rb

@@ -33,7 +33,9 @@ module Sequel
     # You can provide a <tt>:scope</tt> option to scope the list.  This option
     # can be a symbol or array of symbols specifying column name(s), or a proc
     # that accepts a model instance and returns a dataset representing the list
-    # the object is in.
+    # the object is in.  You will need to provide a <tt>:scope</tt> option if
+    # the model's dataset uses a subquery (such as when using the class_table_inheritance
+    # plugin).
     # 
     # For example, if each item has a +user_id+ field, and you want every user
     # to have their own list: