sequel 3.9.0 → 3.10.0

data/lib/sequel/model/base.rb

@@ -301,7 +301,7 @@ module Sequel
       # Example:
       #   class Tagging < Sequel::Model
       #     # composite key
-      #     set_primary_key :taggable_id, :tag_id
+      #     set_primary_key [:taggable_id, :tag_id]
       #   end
       #
       #   class Person < Sequel::Model
@@ -437,6 +437,21 @@ module Sequel
         end
         schema_hash
       end
+      
+      # For the given opts hash and default name or :class option, add a
+      # :class_name option unless already present which contains the name
+      # of the class to use as a string.  The purpose is to allow late
+      # binding to the class later using constantize.
+      def late_binding_class_option(opts, default)
+        case opts[:class]
+          when String, Symbol
+            # Delete :class to allow late binding
+            opts[:class_name] ||= opts.delete(:class).to_s
+          when Class
+            opts[:class_name] ||= opts[:class].name
+        end
+        opts[:class_name] ||= ((name || '').split("::")[0..-2] + [camelize(default)]).join('::')
+      end
   
       # Module that the class includes that holds methods the class adds for column accessors and
       # associations so that the methods can be overridden with super
@@ -653,6 +668,11 @@ module Sequel
         @values.keys
       end
       
+      # Refresh this record using for_update unless this is a new record.  Returns self.
+      def lock!
+        new? ? self : _refresh(this.for_update)
+      end
+      
       # Remove elements of the model object that make marshalling fail. Returns self.
       def marshallable!
         @this = nil

data/lib/sequel/model/plugins.rb

@@ -64,7 +64,9 @@ module Sequel
       # defined, the corresponding plugin gem is automatically loaded.
       def plugin_module(plugin)
         module_name = plugin.to_s.gsub(/(^|_)(.)/){|x| x[-1..-1].upcase}
-        if not Sequel::Plugins.const_defined?(module_name)
+        if !Sequel::Plugins.const_defined?(module_name) ||
+           (Sequel.const_defined?(module_name) &&
+            Sequel::Plugins.const_get(module_name) == Sequel.const_get(module_name))
           begin
             Sequel.tsk_require "sequel/plugins/#{plugin}"
           rescue LoadError

data/lib/sequel/plugins/association_dependencies.rb

@@ -6,7 +6,7 @@ module Sequel
     # 
     # * :many_to_many - :nullify (removes all related entries in join table)
     # * :many_to_one - :delete, :destroy
-    # * :one_to_many - :delete, :destroy, :nullify (sets foreign key to NULL for all associated objects)
+    # * :one_to_many, one_to_one - :delete, :destroy, :nullify (sets foreign key to NULL for all associated objects)
     #
     # This plugin works directly with the association datasets and does not use any cached association values.
     # The :delete action will delete all associated objects from the database in a single SQL call.
@@ -23,7 +23,7 @@ module Sequel
     module AssociationDependencies
       # Mapping of association types to when the dependency calls should be made (either
       # :before for in before_destroy or :after for in after_destroy)
-      ASSOCIATION_MAPPING = {:one_to_many=>:before, :many_to_one=>:after, :many_to_many=>:before}
+      ASSOCIATION_MAPPING = {:one_to_many=>:before, :many_to_one=>:after, :many_to_many=>:before, :one_to_one=>:before}
 
       # The valid dependence actions
       DEPENDENCE_ACTIONS = [:delete, :destroy, :nullify]
@@ -52,13 +52,20 @@ module Sequel
         def add_association_dependencies(hash)
           hash.each do |association, action|
             raise(Error, "Nonexistent association: #{association}") unless r = association_reflection(association)
+            type = r[:type]
             raise(Error, "Invalid dependence action type: association: #{association}, dependence action: #{action}") unless DEPENDENCE_ACTIONS.include?(action)
-            raise(Error, "Invalid association type: association: #{association}, type: #{r[:type]}") unless time = ASSOCIATION_MAPPING[r[:type]]
+            raise(Error, "Invalid association type: association: #{association}, type: #{type}") unless time = ASSOCIATION_MAPPING[type]
             association_dependencies[:"#{time}_#{action}"] << if action == :nullify
-              raise(Error, "Can't nullify many_to_one associated objects: association: #{association}") if r[:type] == :many_to_one
-              r.remove_all_method
+              case type
+              when :one_to_many , :many_to_many
+                proc{send(r.remove_all_method)}
+              when :one_to_one
+                proc{send(r.setter_method, nil)}
+              else
+                raise(Error, "Can't nullify many_to_one associated objects: association: #{association}")
+              end
             else
-              raise(Error, "Can only nullify many_to_many associations: association: #{association}") if r[:type] == :many_to_many
+              raise(Error, "Can only nullify many_to_many associations: association: #{association}") if type == :many_to_many
               r.dataset_method
             end
           end
@@ -87,7 +94,7 @@ module Sequel
         def before_destroy
           model.association_dependencies[:before_delete].each{|m| send(m).delete}
           model.association_dependencies[:before_destroy].each{|m| send(m).destroy}
-          model.association_dependencies[:before_nullify].each{|m| send(m)}
+          model.association_dependencies[:before_nullify].each{|p| instance_eval(&p)}
           super
         end
       end

data/lib/sequel/plugins/caching.rb

@@ -15,11 +15,15 @@ module Sequel
     #    cache_store.get(key) => obj     # Returns object set with same key.
     #    cache_store.get(key2) => nil    # nil returned if there isn't an object
     #                                    # currently in the cache with that key.
+    #    cache_store.delete(key)         # Remove key from cache
     #
     # If the :ignore_exceptions option is true, exceptions raised by cache_store.get
     # are ignored and nil is returned instead.  The memcached API is to
     # raise an exception for a missing record, so if you use memcached, you will
     # want to use this option.
+    #
+    # Note that only Model.[] method calls with a primary key argument are cached
+    # using this plugin.
     module Caching
       # Set the cache_store and cache_ttl attributes for the given model.
       # If the :ttl option is not given, 3600 seconds is the default.

data/lib/sequel/plugins/composition.rb

@@ -0,0 +1,138 @@
+module Sequel
+  module Plugins
+    # The composition plugin allows you to easily define getter and
+    # setter instance methods for a class where the backing data
+    # is composed of other getters and decomposed to other setters.
+    #
+    # A simple example of this is when you have a database table with
+    # separate columns for year, month, and day, but where you want
+    # to deal with Date objects in your ruby code.  This can be handled
+    # with:
+    #
+    #   Model.composition :date, :mapping=>[:year, :month, :day]
+    #
+    # The :mapping option is optional, but you can define custom
+    # composition and decomposition procs via the :composer and
+    # :decomposer options.
+    #
+    # Note that when using the composition object, you should not
+    # modify the underlying columns if you are also instantiating
+    # the composition, as otherwise the composition object values
+    # will override any underlying columns when the object is saved.
+    module Composition
+      # Define the necessary class instance variables.
+      def self.apply(model)
+        model.instance_eval{@compositions = {}}
+      end
+
+      module ClassMethods
+        # A hash with composition name keys and composition reflection
+        # hash values.
+        attr_reader :compositions
+        
+        # A module included in the class holding the composition
+        # getter and setter methods.
+        attr_reader :composition_module
+        
+        # Define a composition for this model, with name being the name of the composition.
+        # You must provide either a :mapping option or both the :composer and :decomposer options. 
+        #
+        # Options:
+        # * :class - if using the :mapping option, the class to use, as a Class, String or Symbol.
+        # * :composer - A proc that is instance evaled when the composition getter method is called
+        #   to create the composition.
+        # * :decomposer - A proc that is instance evaled before saving the model object,
+        #   if the composition object exists, which sets the columns in the model object
+        #   based on the value of the composition object.
+        # * :mapping - An array where each element is either a symbol or an array of two symbols.
+        #   A symbol is treated like an array of two symbols where both symbols are the same.
+        #   The first symbol represents the getter method in the model, and the second symbol
+        #   represents the getter method in the composition object. Example:
+        #     # Uses columns year, month, and day in the current model
+        #     # Uses year, month, and day methods in the composition object
+        #     :mapping=>[:year, :month, :day]
+        #     # Uses columns year, month, and day in the current model
+        #     # Uses y, m, and d methods in the composition object where
+        #     # for example y in the composition object represents year
+        #     # in the model object.
+        #     :mapping=>[[:year, :y], [:month, :m], [:day, :d]]
+        def composition(name, opts={})
+          opts = opts.dup
+          compositions[name] = opts
+          if mapping = opts[:mapping]
+            keys = mapping.map{|k| k.is_a?(Array) ? k.first : k}
+            if !opts[:composer]              
+              late_binding_class_option(opts, name)
+              klass = opts[:class]
+              class_proc = proc{klass || constantize(opts[:class_name])}
+              opts[:composer] = proc do
+                if values = keys.map{|k| send(k)} and values.any?{|v| !v.nil?}
+                  class_proc.call.new(*values)
+                else
+                  nil
+                end
+              end
+            end
+            if !opts[:decomposer]
+              setter_meths = keys.map{|k| :"#{k}="}
+              cov_methods = mapping.map{|k| k.is_a?(Array) ? k.last : k}
+              setters = setter_meths.zip(cov_methods)
+              opts[:decomposer] = proc do
+                if (o = compositions[name]).nil?
+                  setter_meths.each{|sm| send(sm, nil)}
+                else
+                  setters.each{|sm, cm| send(sm, o.send(cm))}
+                end
+              end
+            end
+          end
+          raise(Error, "Must provide :composer and :decomposer options, or :mapping option") unless opts[:composer] && opts[:decomposer]
+          define_composition_accessor(name, opts)
+        end
+        
+        # Copy the necessary class instance variables to the subclass.
+        def inherited(subclass)
+          super
+          c = compositions.dup
+          subclass.instance_eval{@compositions = c}
+        end
+        
+        # Define getter and setter methods for the composition object.
+        def define_composition_accessor(name, opts={})
+          include(@composition_module ||= Module.new) unless composition_module
+          composer = opts[:composer]
+          composition_module.class_eval do
+            define_method(name) do 
+              compositions.include?(name) ? compositions[name] : (compositions[name] = instance_eval(&composer))
+            end
+            define_method("#{name}=") do |v|
+              modified!
+              compositions[name] = v
+            end
+          end
+        end
+      end
+
+      module InstanceMethods
+        # Clear the cached compositions when refreshing.
+        def _refresh(ds)
+          v = super
+          compositions.clear
+          v
+        end
+
+        # For each composition, set the columns in the model class based
+        # on the composition object.
+        def before_save
+          @compositions.keys.each{|n| instance_eval(&model.compositions[n][:decomposer])} if @compositions
+          super
+        end
+        
+        # Cache of composition objects for this class.
+        def compositions
+          @compositions ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/identity_map.rb

@@ -103,8 +103,8 @@ module Sequel
         # map for the associated object and return it if present.
         def _load_associated_objects(opts)
           klass = opts.associated_class
-          if idm = model.identity_map and !opts.returns_array? and opts[:key] and pk = send(opts[:key]) and
-           opts[:primary_key] == klass.primary_key and o = idm[klass.identity_map_key(pk)]
+          if idm = model.identity_map and opts[:type] == :many_to_one and opts[:primary_key] == klass.primary_key and
+           opts[:key] and pk = send(opts[:key]) and o = idm[klass.identity_map_key(pk)]
             o
           else
             super

data/lib/sequel/plugins/lazy_attributes.rb

@@ -17,7 +17,7 @@ module Sequel
     #     end
     #   end
     module LazyAttributes
-      # Tactical eager loading requires the tactical_eager_loading plugin
+      # Lazy attributes requires the identity map and tactical eager loading plugins
       def self.apply(model, *attrs)
         model.plugin :identity_map
         model.plugin :tactical_eager_loading  

data/lib/sequel/plugins/nested_attributes.rb

@@ -91,9 +91,10 @@ module Sequel
             send(reflection[:name]) << obj
             after_save_hook{send(reflection.add_method, obj)}
           else
+            associations[reflection[:name]] = obj
             # Don't need to validate the object twice if :validate association option is not false
             # and don't want to validate it at all if it is false.
-            before_save_hook{send(reflection.setter_method, obj.save(:validate=>false))}
+            send(reflection[:type] == :many_to_one ? :before_save_hook : :after_save_hook){send(reflection.setter_method, obj.save(:validate=>false))}
           end
           obj
         end
@@ -103,7 +104,7 @@ module Sequel
         def nested_attributes_find(reflection, pk)
           pk = pk.to_s
           unless obj = Array(associated_objects = send(reflection[:name])).find{|x| x.pk.to_s == pk}
-            raise(Error, 'no associated object with that primary key does not exist') unless reflection[:nested_attributes][:strict] == false
+            raise(Error, "no matching associated object with given primary key (association: #{reflection[:name]}, pk: #{pk})") unless reflection[:nested_attributes][:strict] == false
           end
           obj
         end

data/lib/sequel/plugins/rcte_tree.rb

@@ -0,0 +1,281 @@
+module Sequel
+  module Plugins
+    # = Overview
+    #
+    # The rcte_tree plugin deals with tree structured data stored
+    # in the database using the adjacency list model (where child rows
+    # have a foreign key pointing to the parent rows), using recursive
+    # common table expressions to load all ancestors in a single query,
+    # all descendants in a single query, and all descendants to a given
+    # level (where level 1 is children, level 2 is children and grandchildren
+    # etc.) in a single query.
+    #
+    # = Background
+    # 
+    # There are two types of common models for storing tree structured data
+    # in an SQL database, the adjacency list model and the nested set model.
+    # Before recursive common table expressions (or similar capabilities such
+    # as CONNECT BY for Oracle), the nested set model was the only easy way
+    # to retrieve all ancestors and descendants in a single query.  However,
+    # it has significant performance corner cases.
+    #
+    # On PostgreSQL 8.4, with a significant number of rows, the nested set
+    # model is almost 500 times slower than using a recursive common table
+    # expression with the adjacency list model to get all descendants, and
+    # almost 24,000 times slower to get all descendants to a given level.
+    #
+    # Considering that the nested set model requires more difficult management
+    # than the adjacency list model, it's almost always better to use the
+    # adjacency list model if your database supports common table expressions.
+    # See http://explainextended.com/2009/09/24/adjacency-list-vs-nested-sets-postgresql/
+    # for detailed analysis.
+    #
+    # = Usage
+    #
+    # The rcte_tree plugin is unlike most plugins in that it doesn't add any class,
+    # instance, or dataset modules.  It only has a single apply method, which
+    # adds four associations to the model: parent, children, ancestors, and
+    # descendants.  Both the parent and children are fairly standard many_to_one
+    # and one_to_many associations, respectively.  However, the ancestors and
+    # descendants associations are special.  Both the ancestors and descendants
+    # associations will automatically set the parent and children associations,
+    # respectively, for current object and all of the ancestor or descendant
+    # objects, whenever they are loaded (either eagerly or lazily).  Additionally,
+    # the descendants association can take a level argument when called eagerly,
+    # which limits the returned objects to only that many levels in the tree (see
+    # the Overview).
+    #
+    #   Model.plugin :rcte_tree
+    #   
+    #   # Lazy loading
+    #   model = Model.first
+    #   model.parent
+    #   model.children
+    #   model.ancestors # Populates :parent association for all ancestors
+    #   model.descendants # Populates :children association for all descendants
+    #   
+    #   # Eager loading - also populates the :parent and children associations
+    #   # for all ancestors and descendants
+    #   Model.filter(:id=>[1, 2]).eager(:ancestors, :descendants).all
+    #   
+    #   # Eager loading children and grand children
+    #   Model.filter(:id=>[1, 2]).eager(:descendants=>2).all
+    #   # Eager loading children, grand children, and great grand children
+    #   Model.filter(:id=>[1, 2]).eager(:descendants=>3).all
+    #
+    # = Options
+    #
+    # You can override the options for any specific association by making
+    # sure the plugin options contain one of the following keys:
+    #
+    # * :parent - hash of options for the parent association
+    # * :children - hash of options for the children association
+    # * :ancestors - hash of options for the ancestors association
+    # * :descendants - hash of options for the descendants association
+    #
+    # Note that you can change the name of the above associations by specifying
+    # a :name key in the appropriate hash of options above.  For example:
+    #
+    #   Model.plugin :rcte_tree, :parent=>{:name=>:mother},
+    #    :children=>{:name=>:daughters}, :descendants=>{:name=>:offspring}
+    #
+    # Any other keys in the main options hash are treated as options shared by
+    # all of the associations.  Here's a few options that affect the plugin:
+    #
+    # * :key - The foreign key in the table that points to the primary key
+    #   of the parent (default: :parent_id)
+    # * :primary_key - The primary key to use (default: the model's primary key)
+    # * :key_alias - The symbol identifier to use for aliasing when eager
+    #   loading (default: :x_root_x)
+    # * :cte_name - The symbol identifier to use for the common table expression
+    #   (default: :t)
+    # * :level_alias - The symbol identifier to use when eagerly loading descendants
+    #   up to a given level (default: :x_level_x)
+    module RcteTree
+      # Create the appropriate parent, children, ancestors, and descendants
+      # associations for the model.
+      def self.apply(model, opts={})
+        opts = opts.dup
+        opts[:class] = model
+        
+        key = opts[:key] ||= :parent_id
+        prkey = opts[:primary_key] ||= model.primary_key
+        
+        par = opts.merge(opts.fetch(:parent, {}))
+        parent = par.fetch(:name, :parent)
+        model.many_to_one parent, par
+        
+        chi = opts.merge(opts.fetch(:children, {}))
+        childrena = chi.fetch(:name, :children)
+        model.one_to_many childrena, chi
+        
+        ka = opts[:key_alias] ||= :x_root_x
+        t = opts[:cte_name] ||= :t
+        opts[:reciprocal] = nil
+        c_all = SQL::ColumnAll.new(model.table_name)
+        
+        a = opts.merge(opts.fetch(:ancestors, {}))
+        ancestors = a.fetch(:name, :ancestors)
+        a[:read_only] = true unless a.has_key?(:read_only)
+        a[:eager_loader_key] = key
+        a[:dataset] ||= proc do
+          model.from(t).
+           with_recursive(t, model.filter(prkey=>send(key)),
+            model.join(t, key=>prkey).
+            select(c_all))
+        end
+        aal = Array(a[:after_load])
+        aal << proc do |m, ancs|
+          unless m.associations.has_key?(parent)
+            parent_map = {m[prkey]=>m}
+            child_map = {}
+            child_map[m[key]] = m if m[key]
+            m.associations[parent] = nil
+            ancs.each do |obj|
+              obj.associations[parent] = nil
+              parent_map[obj[prkey]] = obj
+              if ok = obj[key]
+                child_map[ok] = obj
+              end
+            end
+            parent_map.each do |parent_id, obj|
+              if child = child_map[parent_id]
+                child.associations[parent] = obj
+              end
+            end
+          end
+        end
+        a[:after_load] ||= aal
+        a[:eager_loader] ||= proc do |key_hash, objects, associations|
+          id_map = key_hash[key]
+          parent_map = {}
+          children_map = {}
+          objects.each do |obj|
+            parent_map[obj[prkey]] = obj
+            (children_map[obj[key]] ||= []) << obj
+            obj.associations[ancestors] = []
+            obj.associations[parent] = nil
+          end
+          r = model.association_reflection(ancestors)
+          model.eager_loading_dataset(r,
+           model.from(t).
+            with_recursive(t, model.filter(prkey=>id_map.keys).
+              select(SQL::AliasedExpression.new(prkey, ka), c_all),
+             model.join(t, key=>prkey).
+             select(SQL::QualifiedIdentifier.new(t, ka), c_all)),
+           r.select,
+           associations).all do |obj|
+            opk = obj[prkey]
+            if in_pm = parent_map.has_key?(opk)
+              if idm_obj = parent_map[opk]
+                idm_obj.values[ka] = obj.values[ka]
+                obj = idm_obj
+              end
+            else
+              obj.associations[parent] = nil
+              parent_map[opk] = obj
+              (children_map[obj[key]] ||= []) << obj
+            end
+            
+            if roots = id_map[obj.values.delete(ka)]
+              roots.each do |root|
+                root.associations[ancestors] << obj
+              end
+            end
+          end
+          parent_map.each do |parent_id, obj|
+            if children = children_map[parent_id]
+              children.each do |child|
+                child.associations[parent] = obj
+              end
+            end
+          end
+        end
+        model.one_to_many ancestors, a
+        
+        d = opts.merge(opts.fetch(:descendants, {}))
+        descendants = d.fetch(:name, :descendants)
+        d[:read_only] = true unless d.has_key?(:read_only)
+        la = d[:level_alias] ||= :x_level_x
+        d[:dataset] ||= proc do
+          model.from(t).
+           with_recursive(t, model.filter(key=>send(prkey)),
+            model.join(t, prkey=>key).
+            select(SQL::ColumnAll.new(model.table_name)))
+          end
+        dal = Array(d[:after_load])
+        dal << proc do |m, descs|
+          unless m.associations.has_key?(childrena)
+            parent_map = {m[prkey]=>m}
+            children_map = {}
+            m.associations[childrena] = []
+            descs.each do |obj|
+              obj.associations[childrena] = []
+              if opk = obj[prkey]
+                parent_map[opk] = obj
+              end
+              if ok = obj[key]
+                (children_map[ok] ||= []) << obj
+              end
+            end
+            children_map.each do |parent_id, objs|
+              parent_map[parent_id].associations[childrena] = objs
+            end
+          end
+        end
+        d[:after_load] = dal
+        d[:eager_loader] ||= proc do |key_hash, objects, associations|
+          id_map = key_hash[prkey]
+          parent_map = {}
+          children_map = {}
+          objects.each do |obj|
+            parent_map[obj[prkey]] = obj
+            obj.associations[descendants] = []
+            obj.associations[childrena] = []
+          end
+          r = model.association_reflection(descendants)
+          base_case = model.filter(key=>id_map.keys).
+           select(SQL::AliasedExpression.new(key, ka), c_all)
+          recursive_case = model.join(t, prkey=>key).
+           select(SQL::QualifiedIdentifier.new(t, ka), c_all)
+          if associations.is_a?(Integer)
+            level = associations
+            no_cache_level = level - 1
+            associations = {}
+            base_case = base_case.select_more(SQL::AliasedExpression.new(0, la))
+            recursive_case = recursive_case.select_more(SQL::AliasedExpression.new(SQL::QualifiedIdentifier.new(t, la) + 1, la)).filter(SQL::QualifiedIdentifier.new(t, la) < level - 1)
+          end
+          model.eager_loading_dataset(r,
+           model.from(t).with_recursive(t, base_case, recursive_case),
+           r.select,
+           associations).all do |obj|
+            if level
+              no_cache = no_cache_level == obj.values.delete(la)
+            end
+            
+            opk = obj[prkey]
+            if in_pm = parent_map.has_key?(opk)
+              if idm_obj = parent_map[opk]
+                idm_obj.values[ka] = obj.values[ka]
+                obj = idm_obj
+              end
+            else
+              obj.associations[childrena] = [] unless no_cache
+              parent_map[opk] = obj
+            end
+            
+            if root = id_map[obj.values.delete(ka)].first
+              root.associations[descendants] << obj
+            end
+            
+            (children_map[obj[key]] ||= []) << obj
+          end
+          children_map.each do |parent_id, objs|
+            parent_map[parent_id].associations[childrena] = objs.uniq
+          end
+        end
+        model.one_to_many descendants, d
+      end
+    end
+  end
+end