sequel 4.45.0 → 4.46.0

data/lib/sequel/plugins/class_table_inheritance.rb

@@ -119,6 +119,10 @@ module Sequel
     #
     #   # Some examples of using these options:
     #
+    #   # Use a subquery for all subclass datasets, fixing issues with ambiguous
+    #   # column names.
+    #   Employee.plugin :class_table_inheritance, :key=>:kind, :alias=>:employees
+    #
     #   # Specifying the tables with a :table_map hash
     #   Employee.plugin :class_table_inheritance,
     #     :table_map=>{:Employee  => :employees,
@@ -179,6 +183,8 @@ module Sequel
       end
 
       # Initialize the plugin using the following options:
+      # :alias :: Use a subquery for each subclass dataset that joins to another table,
+      #           using this as the alias.
       # :key :: Column symbol that holds the key that identifies the class to use.
       #         Necessary if you want to call model methods on a superclass
       #         that return subclass instances
@@ -197,6 +203,7 @@ module Sequel
           @cti_instance_dataset = @instance_dataset
           @cti_table_columns = columns
           @cti_table_map = opts[:table_map] || {}
+          @cti_alias = opts[:alias]
         end
       end
 
@@ -235,7 +242,7 @@ module Sequel
         # For backwards compatibility.
         def cti_columns
           h = {}
-          cti_models.each { |m| h[m.table_name] = m.cti_table_columns }
+          cti_models.each { |m| h[m.cti_table_name] = m.cti_table_columns }
           h
         end
 
@@ -256,7 +263,7 @@ module Sequel
           super
         end
 
-        Plugins.inherited_instance_variables(self, :@cti_models=>nil, :@cti_tables=>nil, :@cti_table_columns=>nil, :@cti_instance_dataset=>nil, :@cti_table_map=>nil)
+        Plugins.inherited_instance_variables(self, :@cti_models=>nil, :@cti_tables=>nil, :@cti_table_columns=>nil, :@cti_instance_dataset=>nil, :@cti_table_map=>nil, :@cti_alias=>nil)
 
         def inherited(subclass)
           ds = sti_dataset
@@ -278,25 +285,30 @@ module Sequel
               table = nil if !columns || columns.empty?
             end
           end
-          table = nil if table && (table == table_name)
+          table = nil if table && (table == cti_table_name)
 
           return unless table
 
           pk = primary_key
           subclass.instance_eval do
             if cti_tables.length == 1
-              ds = ds.select(*self.columns.map{|cc| Sequel.qualify(table_name, Sequel.identifier(cc))})
+              ds = ds.select(*self.columns.map{|cc| Sequel.qualify(cti_table_name, Sequel.identifier(cc))})
             end
             cols = columns - [pk]
             unless (cols & ds.columns).empty?
               Sequel::Deprecation.deprecate('Using class_table_inheritance with duplicate column names in subclass tables (other than the primary key column)', 'Make sure all tables used have unique column names, or implement support for handling duplicate column names in the class_table_inheritance plugin')
             end
             sel_app = cols.map{|cc| Sequel.qualify(table, Sequel.identifier(cc))}
-            @sti_dataset = ds.join(table, pk=>pk).select_append(*sel_app)
-            set_dataset(@sti_dataset)
+            @sti_dataset = ds = ds.join(table, pk=>pk).select_append(*sel_app)
+
+            if @cti_alias
+              ds = ds.from_self(:alias=>@cti_alias)
+            end
+
+            set_dataset(ds)
             set_columns(self.columns)
             @dataset = @dataset.with_row_proc(lambda{|r| subclass.sti_load(r)})
-            cols.each{|a| define_lazy_attribute_getter(a, :dataset=>dataset, :table=>table)}
+            cols.each{|a| define_lazy_attribute_getter(a, :dataset=>dataset, :table=>@cti_alias||table)}
 
             @cti_models += [self]
             @cti_tables += [table]
@@ -311,12 +323,37 @@ module Sequel
 
         # The table name for the current model class's main table.
         def table_name
-          cti_tables ? cti_tables.last : super
+          if cti_tables
+            if @cti_alias
+              @cti_alias
+            else
+              cti_tables.last
+            end
+          else
+            super
+          end
+        end
+
+        # The name of the most recently joined table.
+        def cti_table_name
+          cti_tables ? cti_tables.last : dataset.first_source_alias
         end
 
         def sti_class_from_key(key)
           sti_class(sti_model_map[key])
         end
+
+        private
+
+        # If using a subquery for class table inheritance, also use a subquery
+        # when setting subclass dataset.
+        def sti_subclass_dataset(key)
+          ds = super
+          if @cti_alias
+            ds = ds.from_self(:alias=>@cti_alias)
+          end
+          ds
+        end
       end
 
       module InstanceMethods
@@ -346,8 +383,8 @@ module Sequel
           if new? && (set = self[model.sti_key])
             exp = model.sti_key_chooser.call(self)
             if set != exp
-              set_table = model.sti_class_from_key(set).table_name
-              exp_table = model.sti_class_from_key(exp).table_name
+              set_table = model.sti_class_from_key(set).cti_table_name
+              exp_table = model.sti_class_from_key(exp).cti_table_name
               set_column_value("#{model.sti_key}=", exp) if set_table != exp_table
             end
           end

data/lib/sequel/plugins/dataset_associations.rb

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

data/lib/sequel/plugins/def_dataset_method.rb

@@ -0,0 +1,90 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The def_dataset_method plugin adds Model.def_dataset_method
+    # for defining dataset methods:
+    #
+    #   Album.def_dataset_method(:by_name) do |name|
+    #     where(:name=>name)
+    #   end
+    #
+    # Additionally, this adds support for Model.subset, which can also
+    # be used to define dataset methods that add specific filters:
+    #
+    #   Album.subset(:gold){copies_sold >= 500000}
+    #
+    # This exists for backwards compatibility with previous Sequel versions.
+    # 
+    # Usage:
+    #
+    #   # Make all model subclasses support Model.def_dataset_method
+    #   # (called before loading subclasses)
+    #   Sequel::Model.plugin :def_dataset_method
+    #
+    #   # Make the Album class support Model.def_dataset_method
+    #   Album.plugin :def_dataset_method
+    module DefDatasetMethod
+      module ClassMethods
+        # If a block is given, define a method on the dataset (if the model currently has an dataset)  with the given argument name using
+        # the given block.  Also define a class method on the model that calls the
+        # dataset method.  Stores the method name and block so that it can be reapplied if the model's
+        # dataset changes.
+        #
+        # If a block is not given, just define a class method on the model for each argument
+        # that calls the dataset method of the same argument name.
+        #
+        # Using dataset_module is recommended over using this method.  In addition to allowing
+        # more natural ruby syntax for defining methods manually, it also offers numerous
+        # helper methods that make defining common dataset methods more easily, as well as
+        # supporting dataset caching (assuming the arguments allow it).
+        #
+        #   # Add new dataset method and class method that calls it
+        #   Artist.def_dataset_method(:by_name){order(:name)}
+        #   Artist.where(:name.like('A%')).by_name
+        #   Artist.by_name.where(:name.like('A%'))
+        #
+        #   # Just add a class method that calls an existing dataset method
+        #   Artist.def_dataset_method(:paginate)
+        #   Artist.paginate(2, 10)
+        def def_dataset_method(*args, &block)
+          raise(Error, "No arguments given") if args.empty?
+
+          if block
+            raise(Error, "Defining a dataset method using a block requires only one argument") if args.length > 1
+            dataset_module{define_method(args.first, &block)}
+          else
+            args.each{|arg| def_model_dataset_method(arg)}
+          end
+        end
+
+        # Sets up a dataset method that returns a filtered dataset.
+        # Sometimes thought of as a scope, and like most dataset methods,
+        # they can be chained.
+        # For example:
+        #
+        #   Topic.subset(:joes, :username.like('%joe%'))
+        #   Topic.subset(:popular){num_posts > 100}
+        #   Topic.subset(:recent){created_on > Date.today - 7}
+        #
+        # Allows you to do:
+        #
+        #   Topic.joes.recent.popular
+        #
+        # to get topics with a username that includes joe that
+        # have more than 100 posts and were created less than
+        # 7 days ago.
+        #
+        # Both the args given and the block are passed to <tt>Dataset#filter</tt>.
+        #
+        # This method creates dataset methods that do not accept arguments.  To create
+        # dataset methods that accept arguments, you should use define a
+        # method directly inside a #dataset_module block.
+        def subset(*args, &block)
+          dataset_module{subset(*args, &block)}
+        end
+      end
+    end
+  end
+end
+

data/lib/sequel/plugins/finder.rb

@@ -0,0 +1,240 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The finder plugin adds Model.finder for defining optimized finder methods.
+    # There are two ways to use this.  The recommended way is to pass a symbol
+    # that represents a model class method that returns a dataset:
+    #
+    #   def Artist.by_name(name)
+    #     where(:name=>name)
+    #   end
+    #
+    #   Artist.finder :by_name
+    #
+    # This creates an optimized first_by_name method, which you can call normally:
+    #
+    #   Artist.first_by_name("Joe")
+    #
+    # The alternative way to use this to pass your own block:
+    #
+    #   Artist.finder(:name=>:first_by_name){|pl, ds| ds.where(:name=>pl.arg).limit(1)}
+    #
+    # Additionally, there is a Model.prepared_finder method.  This works similarly
+    # to Model.finder, but uses a prepared statement.  This limits the types of
+    # arguments that will be accepted, but can perform better in the database.
+    # 
+    # Usage:
+    #
+    #   # Make all model subclasses support Model.finder
+    #   # (called before loading subclasses)
+    #   Sequel::Model.plugin :finder
+    #
+    #   # Make the Album class support Model.finder
+    #   Album.plugin :finder
+    module Finder
+      FINDER_TYPES = [:first, :all, :each, :get].freeze
+
+      def self.apply(mod)
+        mod.instance_exec do
+          @finders ||= {}
+          @finder_loaders ||= {}
+        end
+      end
+
+      module ClassMethods
+        # Create an optimized finder method using a dataset placeholder literalizer.
+        # This pre-computes the SQL to use for the query, except for given arguments.
+        #
+        # There are two ways to use this.  The recommended way is to pass a symbol
+        # that represents a model class method that returns a dataset:
+        #
+        #   def Artist.by_name(name)
+        #     where(:name=>name)
+        #   end
+        #
+        #   Artist.finder :by_name
+        #
+        # This creates an optimized first_by_name method, which you can call normally:
+        #
+        #   Artist.first_by_name("Joe")
+        #
+        # The alternative way to use this to pass your own block:
+        #
+        #   Artist.finder(:name=>:first_by_name){|pl, ds| ds.where(:name=>pl.arg).limit(1)}
+        #
+        # Note that if you pass your own block, you are responsible for manually setting
+        # limits if necessary (as shown above).
+        #
+        # Options:
+        # :arity :: When using a symbol method name, this specifies the arity of the method.
+        #           This should be used if if the method accepts an arbitrary number of arguments,
+        #           or the method has default argument values.  Note that if the method is defined
+        #           as a dataset method, the class method Sequel creates accepts an arbitrary number
+        #           of arguments, so you should use this option in that case.  If you want to handle
+        #           multiple possible arities, you need to call the finder method multiple times with
+        #           unique :arity and :name methods each time.
+        # :name :: The name of the method to create.  This must be given if you pass a block.
+        #          If you use a symbol, this defaults to the symbol prefixed by the type.
+        # :mod :: The module in which to create the finder method.  Defaults to the singleton
+        #         class of the model.
+        # :type :: The type of query to run.  Can be :first, :each, :all, or :get, defaults to
+        #          :first.
+        #
+        # Caveats:
+        #
+        # This doesn't handle all possible cases.  For example, if you have a method such as:
+        #
+        #   def Artist.by_name(name)
+        #     name ? where(:name=>name) : exclude(:name=>nil)
+        #   end
+        #
+        # Then calling a finder without an argument will not work as you expect.
+        #
+        #   Artist.finder :by_name
+        #   Artist.by_name(nil).first
+        #   # WHERE (name IS NOT NULL)
+        #   Artist.first_by_name(nil)
+        #   # WHERE (name IS NULL)
+        #
+        # See Dataset::PlaceholderLiteralizer for additional caveats.
+        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)
+            raise Error, "cannot pass two option hashes to Model.finder" unless opts.equal?(OPTS)
+            opts = meth
+            raise Error, "must provide method name via :name option when passing block to Model.finder" unless meth_name = opts[:name]
+          end
+
+          type = opts.fetch(:type, :first)
+          unless prepare = opts[:prepare]
+            raise Error, ":type option to Model.finder must be :first, :all, :each, or :get" unless FINDER_TYPES.include?(type)
+          end
+          limit1 = type == :first || type == :get
+          meth_name ||= opts[:name] || :"#{type}_#{meth}"
+
+          argn = lambda do |model|
+            if arity = opts[:arity]
+              arity
+            else
+              method = block || model.method(meth)
+              (method.arity < 0 ? method.arity.abs - 1 : method.arity)
+            end
+          end
+
+          loader_proc = if prepare
+            proc do |model|
+              args = prepare_method_args('$a', argn.call(model))
+              ds = if block
+                model.instance_exec(*args, &block)
+              else
+                model.send(meth, *args)
+              end
+              ds = ds.limit(1) if limit1
+              model_name = model.name
+              if model_name.to_s.empty?
+                model_name = model.object_id
+              else
+                model_name = model_name.gsub(/\W/, '_')
+              end
+              ds.prepare(type, :"#{model_name}_#{meth_name}")
+            end
+          else
+            proc do |model|
+              n = argn.call(model)
+              block ||= lambda do |pl, model2|
+                args = (0...n).map{pl.arg}
+                ds = model2.send(meth, *args)
+                ds = ds.limit(1) if limit1
+                ds
+              end
+
+              Sequel::Dataset::PlaceholderLiteralizer.loader(model, &block) 
+            end
+          end
+
+          @finder_loaders[meth_name] = loader_proc
+          mod = opts[:mod] || (class << self; self; end)
+          if prepare
+            def_prepare_method(mod, meth_name)
+          else
+            def_finder_method(mod, meth_name, type)
+          end
+        end
+
+        def freeze
+          @finder_loaders.freeze
+          @finder_loaders.each_key{|k| finder_for(k)} if @dataset
+          @finders.freeze
+          super
+        end
+
+        # Similar to finder, but uses a prepared statement instead of a placeholder
+        # literalizer. This makes the SQL used static (cannot vary per call), but
+        # allows binding argument values instead of literalizing them into the SQL
+        # query string.
+        #
+        # If a block is used with this method, it is instance_execed by the model,
+        # and should accept the desired number of placeholder arguments.
+        #
+        # The options are the same as the options for finder, with the following
+        # exception:
+        # :type :: Specifies the type of prepared statement to create
+        def prepared_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)
+            meth = meth.merge(:prepare=>true)
+          else
+            opts = opts.merge(:prepare=>true)
+          end
+          finder(meth, opts, &block)
+        end
+
+        Plugins.inherited_instance_variables(self, :@finders=>:dup, :@autoreloading_associations=>:hash_dup, :@default_association_options=>:dup, :@cache_associations=>nil, :@default_eager_limit_strategy=>nil)
+
+        private
+
+        # Define a finder method in the given module with the given method name that
+        # load rows using the finder with the given name.
+        def def_finder_method(mod, meth, type)
+          mod.send(:define_method, meth){|*args, &block| finder_for(meth).send(type, *args, &block)}
+        end
+
+        # Define a prepared_finder method in the given module that will call the associated prepared
+        # statement.
+        def def_prepare_method(mod, meth)
+          mod.send(:define_method, meth){|*args, &block| finder_for(meth).call(prepare_method_arg_hash(args), &block)}
+        end
+
+        # Find the finder to use for the give method.  If a finder has not been loaded
+        # for the method, load the finder and set correctly in the finders hash, then
+        # return the finder.
+        def finder_for(meth)
+          unless finder = (frozen? ? @finders[meth] : Sequel.synchronize{@finders[meth]})
+            finder_loader = @finder_loaders.fetch(meth)
+            finder = finder_loader.call(self)
+            Sequel.synchronize{@finders[meth] = finder}
+          end
+          finder
+        end
+
+        # An hash of prepared argument values for the given arguments, with keys
+        # starting at a.  Used by the methods created by prepared_finder.
+        def prepare_method_arg_hash(args)
+          h = {}
+          prepare_method_args('a', args.length).zip(args).each{|k, v| h[k] = v}
+          h
+        end
+
+        # An array of prepared statement argument names, of length n and starting with base.
+        def prepare_method_args(base, n)
+          (0...n).map do
+            s = base.to_sym
+            base = base.next
+            s
+          end
+        end
+      end
+    end
+  end
+end