sequel 3.10.0 → 3.11.0

data/lib/sequel/model.rb

@@ -51,7 +51,7 @@ module Sequel
        last left_join left_outer_join limit lock_style map max min multi_insert naked
        natural_full_join natural_join natural_left_join natural_right_join order order_by
        order_more paginate print qualify query range reverse reverse_order right_join right_outer_join
-       select select_all select_hash select_map select_more select_order_map
+       select select_all select_append select_hash select_map select_more select_order_map
        server set set_defaults set_graph_aliases set_overrides
        single_value sum to_csv to_hash truncate unfiltered ungraphed ungrouped union unlimited unordered 
        update where with with_recursive with_sql'.map{|x| x.to_sym}
@@ -72,7 +72,8 @@ module Sequel
     # If the value is nil, the superclass's instance variable is used directly in the subclass.
     INHERITED_INSTANCE_VARIABLES = {:@allowed_columns=>:dup, :@dataset_methods=>:dup, 
       :@dataset_method_modules=>:dup, :@primary_key=>nil, :@use_transactions=>nil,
-      :@raise_on_save_failure=>nil, :@restricted_columns=>:dup, :@restrict_primary_key=>nil,
+      :@raise_on_save_failure=>nil, :@require_modification=>nil, 
+      :@restricted_columns=>:dup, :@restrict_primary_key=>nil,
       :@simple_pk=>nil, :@simple_table=>nil, :@strict_param_setting=>nil,
       :@typecast_empty_string_to_nil=>nil, :@typecast_on_assignment=>nil,
       :@raise_on_typecast_failure=>nil, :@plugins=>:dup}
@@ -100,6 +101,7 @@ module Sequel
     @primary_key = :id
     @raise_on_save_failure = true
     @raise_on_typecast_failure = true
+    @require_modification = nil
     @restrict_primary_key = true
     @restricted_columns = nil
     @simple_pk = nil

data/lib/sequel/model/associations.rb

@@ -410,17 +410,17 @@ module Sequel
       #   end
       # 
       # The project class now has the following instance methods:
-      # * portfolio - Returns the associated portfolio.
-      # * portfolio=(obj) - Sets the associated portfolio to the object,
-      #   but the change is not persisted until you save the record (for many_to_one associations).
-      # * portfolio_dataset - Returns a dataset that would return the associated
-      #   portfolio, only useful in fairly specific circumstances.
-      # * milestones - Returns an array of associated milestones
-      # * add_milestone(obj) - Associates the passed milestone with this object.
-      # * remove_milestone(obj) - Removes the association with the passed milestone.
-      # * remove_all_milestones - Removes associations with all associated milestones.
-      # * milestones_dataset - Returns a dataset that would return the associated
-      #   milestones, allowing for further filtering/limiting/etc.
+      # portfolio :: Returns the associated portfolio.
+      # portfolio=(obj) :: Sets the associated portfolio to the object,
+      #                    but the change is not persisted until you save the record (for many_to_one associations).
+      # portfolio_dataset :: Returns a dataset that would return the associated
+      #                      portfolio, only useful in fairly specific circumstances.
+      # milestones :: Returns an array of associated milestones
+      # add_milestone(obj) :: Associates the passed milestone with this object.
+      # remove_milestone(obj) :: Removes the association with the passed milestone.
+      # remove_all_milestones :: Removes associations with all associated milestones.
+      # milestones_dataset :: Returns a dataset that would return the associated
+      #                       milestones, allowing for further filtering/limiting/etc.
       #
       # If you want to override the behavior of the add_/remove_/remove_all_/ methods
       # or the association setter method, there are private instance methods created that are prepended
@@ -439,6 +439,10 @@ module Sequel
       #   => [:portfolio, :milestones]
       #   Project.association_reflection(:portfolio)
       #   => {:type => :many_to_one, :name => :portfolio, :class_name => "Portfolio"}
+      #
+      # For a more in depth general overview, as well as a reference guide,
+      # see the {Association Basics page}[link:files/doc/association_basics_rdoc.html].
+      # For examples of advanced usage, see the {Advanced Associations page}[link:files/doc/advanced_associations_rdoc.html].
       module ClassMethods
         # All association reflections defined for this model (default: none).
         attr_reader :association_reflections
@@ -564,7 +568,7 @@ module Sequel
         #   - :primary_key - column in the associated table that :key option references, as a symbol.
         #     Defaults to the primary key of the associated table. Can use an
         #     array of symbols for a composite key association.
-        # * :one_to_many:
+        # * :one_to_many and :one_to_one:
         #   - :key - foreign key in associated model's table that references
         #     current model's primary key, as a symbol.  Defaults to
         #     :"#{self.name.underscore}_id".  Can use an
@@ -618,7 +622,7 @@ module Sequel
           opts[:order_eager_graph] = true unless opts.include?(:order_eager_graph)
           conds = opts[:conditions]
           opts[:graph_conditions] = conds if !opts.include?(:graph_conditions) and Sequel.condition_specifier?(conds)
-          opts[:graph_conditions] = opts[:graph_conditions] ? opts[:graph_conditions].to_a : []
+          opts[:graph_conditions] = opts.fetch(:graph_conditions, []).to_a
           opts[:graph_select] = Array(opts[:graph_select]) if opts[:graph_select]
           [:before_add, :before_remove, :after_add, :after_remove, :after_load, :before_set, :after_set, :extend].each do |cb_type|
             opts[cb_type] = Array(opts[cb_type])
@@ -747,7 +751,7 @@ module Sequel
           opts[:cartesian_product_number] ||= 1
           join_table = (opts[:join_table] ||= opts.default_join_table)
           left_key_alias = opts[:left_key_alias] ||= opts.default_associated_key_alias
-          graph_jt_conds = opts[:graph_join_table_conditions] = opts[:graph_join_table_conditions] ? opts[:graph_join_table_conditions].to_a : []
+          graph_jt_conds = opts[:graph_join_table_conditions] = opts.fetch(:graph_join_table_conditions, []).to_a
           opts[:graph_join_table_join_type] ||= opts[:graph_join_type]
           opts[:after_load].unshift(:array_uniq!) if opts[:uniq]
           opts[:dataset] ||= proc{opts.associated_class.inner_join(join_table, rcks.zip(opts.right_primary_keys) + lcks.zip(lcpks.map{|k| send(k)}))}
@@ -960,6 +964,13 @@ module Sequel
 
       # Private instance methods used to implement the associations support.
       module InstanceMethods
+        # The currently cached associations.  A hash with the keys being the
+        # association name symbols and the values being the associated object
+        # or nil (many_to_one), or the array of associated objects (*_to_many).
+        def associations
+          @associations ||= {}
+        end
+      
         # Used internally by the associations code, like pk but doesn't raise
         # an Error if the model has no primary key.
         def pk_or_nil
@@ -1004,6 +1015,12 @@ module Sequel
             end
           end
         end
+        
+        # Clear the associations cache when refreshing
+        def _refresh(dataset)
+          associations.clear
+          super
+        end
 
         # Add the given associated object to the given association
         def add_associated_object(opts, o, *args)

data/lib/sequel/model/base.rb

@@ -42,6 +42,11 @@ module Sequel
       # plugins) in connection with option to check for typecast failures for
       # columns that aren't blobs or strings.
       attr_accessor :raise_on_typecast_failure
+      
+      # Whether to raise an error if an UPDATE or DELETE query related to
+      # a model instance does not modify exactly 1 row.  If set to false,
+      # Sequel will not check the number of rows modified (default: true).
+      attr_accessor :require_modification
   
       # Which columns are specifically restricted in a call to set/update/new/etc.
       # (default: not set).  Some columns are restricted regardless of
@@ -282,6 +287,7 @@ module Sequel
           raise(Error, "Model.set_dataset takes a Symbol or a Sequel::Dataset")
         end
         @dataset.row_proc = Proc.new{|r| load(r)}
+        @require_modification = Sequel::Model.require_modification.nil? ? @dataset.provides_accurate_rows_matched? : Sequel::Model.require_modification
         if inherited
           @simple_table = superclass.simple_table
           @columns = @dataset.columns rescue nil
@@ -493,7 +499,7 @@ module Sequel
     # * The following instance_methods all call the class method of the same
     #   name: columns, dataset, db, primary_key, db_schema.
     # * The following instance methods allow boolean flags to be set on a per-object
-    #   basis: raise_on_save_failure, raise_on_typecast_failure, strict_param_setting, 
+    #   basis: raise_on_save_failure, raise_on_typecast_failure, require_modification, strict_param_setting, 
     #   typecast_empty_string_to_nil, typecast_on_assignment, use_transactions.
     #   If they are not used, the object will default to whatever the model setting is.
     module InstanceMethods
@@ -518,7 +524,7 @@ module Sequel
       private_class_method :class_attr_overridable, :class_attr_reader
 
       class_attr_reader :columns, :db, :primary_key, :db_schema
-      class_attr_overridable :raise_on_save_failure, :raise_on_typecast_failure, :strict_param_setting, :typecast_empty_string_to_nil, :typecast_on_assignment, :use_transactions
+      class_attr_overridable :raise_on_save_failure, :raise_on_typecast_failure, :require_modification, :strict_param_setting, :typecast_empty_string_to_nil, :typecast_on_assignment, :use_transactions
 
       # The hash of attribute values.  Keys are symbols with the names of the
       # underlying database columns.
@@ -587,13 +593,6 @@ module Sequel
       # this alias makes it so you can use model instead of
       # self.class.
       alias_method :model, :class
-  
-      # The currently cached associations.  A hash with the keys being the
-      # association name symbols and the values being the associated object
-      # or nil (many_to_one), or the array of associated objects (*_to_many).
-      def associations
-        @associations ||= {}
-      end
 
       # The autoincrementing primary key for this model object. Should be
       # overridden if you have a composite primary key with one part of it
@@ -611,7 +610,7 @@ module Sequel
       # Deletes and returns self.  Does not run destroy hooks.
       # Look into using destroy instead.
       def delete
-        this.delete
+        _delete
         self
       end
       
@@ -826,6 +825,19 @@ module Sequel
       end
 
       private
+      
+      # Actually do the deletion of the object's dataset.
+      def _delete
+        n = _delete_dataset.delete
+        raise(NoExistingObject, "Attempt to delete object did not result in a single row modification (Rows Deleted: #{n}, SQL: #{_delete_dataset.delete_sql})") if require_modification && n != 1
+        n
+      end
+      
+      # The dataset to use when deleting the object.   The same as the object's
+      # dataset by default.
+      def _delete_dataset
+        this
+      end
   
       # Internal destroy method, separted from destroy to
       # allow running inside a transaction
@@ -864,7 +876,6 @@ module Sequel
       def _refresh(dataset)
         set_values(dataset.first || raise(Error, "Record not found"))
         changed_columns.clear
-        associations.clear
         self
       end
       
@@ -909,7 +920,15 @@ module Sequel
       
       # Update this instance's dataset with the supplied column hash.
       def _update(columns)
-        this.update(columns)
+        n = _update_dataset.update(columns)
+        raise(NoExistingObject, "Attempt to update object did not result in a single row modification (SQL: #{_update_dataset.update_sql(columns)})") if require_modification && n != 1
+        n
+      end
+      
+      # The dataset to use when updating an object.  The same as the object's
+      # dataset by default.
+      def _update_dataset
+        this
       end
 
       # If raise_on_save_failure is false, check for BeforeHookFailed
@@ -1014,7 +1033,7 @@ module Sequel
       # option is present in the hash, use that, otherwise, fallback to the
       # object's default (if set), or class's default (if not).
       def use_transaction?(opts = {})
-        opts.include?(:transaction) ? opts[:transaction] : use_transactions
+        opts.fetch(:transaction, use_transactions)
       end
     end
 

data/lib/sequel/model/exceptions.rb

@@ -1,5 +1,12 @@
 module Sequel
-  # This exception will be raised when raise_on_save_failure is set and validation fails
+  # Exception class raised when raise_on_save_failure is set and a before hook returns false
+  class BeforeHookFailed < Error; end
+  
+  # Exception class raised when require_modification is set and an UPDATE or DELETE statement to modify the dataset doesn't
+  # modify a single row.
+  class NoExistingObject < Error; end
+  
+  # Exception class raised when raise_on_save_failure is set and validation fails
   class ValidationFailed < Error
     def initialize(errors)
       if errors.respond_to?(:full_messages)
@@ -11,7 +18,4 @@ module Sequel
     end
     attr_reader :errors
   end
-
-  # This exception will be raised when raise_on_save_failure is set and a before hook returns false
-  class BeforeHookFailed < Error; end
 end

data/lib/sequel/model/plugins.rb

@@ -28,24 +28,14 @@ module Sequel
     # the camelized plugin name under Sequel::Plugins.
     def self.plugin(plugin, *args, &blk)
       arg = args.first
-      block = args.length > 1 ? lambda{args} : lambda{arg}
       m = plugin.is_a?(Module) ? plugin : plugin_module(plugin)
       unless @plugins.include?(m)
         @plugins << m
         m.apply(self, *args, &blk) if m.respond_to?(:apply)
-        if m.const_defined?("InstanceMethods")
-          define_method(:"#{plugin}_opts", &block)
-          include(m::InstanceMethods)
-        end
-        if m.const_defined?("ClassMethods")
-          meta_def(:"#{plugin}_opts", &block)
-          extend(m::ClassMethods)
-        end
+        include(m::InstanceMethods) if m.const_defined?("InstanceMethods")
+        extend(m::ClassMethods)if m.const_defined?("ClassMethods")
         if m.const_defined?("DatasetMethods")
-          if @dataset
-            dataset.meta_def(:"#{plugin}_opts", &block)
-            dataset.extend(m::DatasetMethods)
-          end
+          dataset.extend(m::DatasetMethods) if @dataset
           dataset_method_modules << m::DatasetMethods
           meths = m::DatasetMethods.public_instance_methods.reject{|x| NORMAL_METHOD_NAME_REGEXP !~ x.to_s}
           def_dataset_method(*meths) unless meths.empty?

data/lib/sequel/plugins/active_model.rb

@@ -11,6 +11,9 @@ module Sequel
       ClassMethods = ::ActiveModel::Naming
 
       module InstanceMethods
+        # The default string to join composite primary keys with in to_param.
+        DEFAULT_TO_PARAM_JOINER = '-'.freeze
+      
         # Record that an object was destroyed, for later use by
         # destroyed?
         def after_destroy
@@ -18,15 +21,16 @@ module Sequel
           @destroyed = true
         end
         
-        # Whether the object was destroyed by destroy.  Not true
-        # for objects that were deleted.
-        def destroyed?
-          @destroyed == true
+        # False if the object is new? or has been destroyed, true otherwise.
+        def persisted?
+          !new? && @destroyed != true
         end
         
-        # An alias for new?
-        def new_record?
-          new?
+        # An array of primary key values, or nil if the object is not persisted.
+        def to_key
+          if persisted?
+            primary_key.is_a?(Symbol) ? [pk] : pk
+          end
         end
 
         # With the ActiveModel plugin, Sequel model objects are already
@@ -34,6 +38,21 @@ module Sequel
         def to_model
           self
         end
+        
+        # An string representing the object's primary key.  For composite
+        # primary keys, joins them with to_param_joiner.
+        def to_param
+          if k = to_key
+            k.join(to_param_joiner)
+          end
+        end
+        
+        private
+        
+        # The string to use to join composite primary key param strings.
+        def to_param_joiner
+          DEFAULT_TO_PARAM_JOINER
+        end
       end
     end
   end

data/lib/sequel/plugins/instance_filters.rb

@@ -0,0 +1,98 @@
+module Sequel
+  module Plugins
+    # This plugin allows you to add filters on a per object basis that
+    # restrict updating or deleting the object.  It's designed for cases
+    # where you would normally have to drop down to the dataset level
+    # to get the necessary control, because you only want to delete or
+    # update the rows in certain cases based on the current status of
+    # the row in the database.
+    # 
+    #   class Item < Sequel::Model
+    #     plugin :instance_filters
+    #   end
+    #
+    #   # These are two separate objects that represent the same
+    #   # database row. 
+    #   i1 = Item.first(:id=>1, :delete_allowed=>false)
+    #   i2 = Item.first(:id=>1, :delete_allowed=>false)
+    #
+    #   # Add an instance filter to the object. This filter is in effect
+    #   # until the object is successfully updated or deleted.
+    #   i1.instance_filter(:delete_allowed=>true)
+    #
+    #   # Attempting to delete the object where the filter doesn't
+    #   # match any rows raises an error.
+    #   i1.delete # raises Sequel::Error
+    #
+    #   # The other object that represents the same row has no
+    #   # instance filters, and can be updated normally.
+    #   i2.update(:delete_allowed=>true)
+    #
+    #   # Even though the filter is now still in effect, since the
+    #   # database row has been updated to allow deleting,
+    #   # delete now works.
+    #   i1.delete
+    #
+    # This plugin sets the require_modification flag on the model,
+    # so if the model's dataset doesn't provide an accurate number
+    # of matched rows, this could result in invalid exceptions being raised.
+    module InstanceFilters
+      # Exception class raised when updating or deleting an object does
+      # not affect exactly one row.
+      Error = Sequel::NoExistingObject
+      
+      # Set the require_modification flag to true for the model.
+      def self.configure(model)
+        model.require_modification = true
+      end
+
+      module InstanceMethods
+        # Clear the instance filters after successfully destroying the object.
+        def after_destroy
+          super
+          clear_instance_filters
+        end
+        
+        # Clear the instance filters after successfully updating the object.
+        def after_update
+          super
+          clear_instance_filters
+        end
+      
+        # Add an instance filter to the array of instance filters
+        # Both the arguments given and the block are passed to the
+        # dataset's filter method.
+        def instance_filter(*args, &block)
+          instance_filters << [args, block]
+        end
+      
+        private
+        
+        # Lazily initialize the instance filter array.
+        def instance_filters
+          @instance_filters ||= []
+        end
+        
+        # Apply the instance filters to the given dataset
+        def apply_instance_filters(ds)
+          instance_filters.inject(ds){|ds, i| ds.filter(*i[0], &i[1])}
+        end
+        
+        # Clear the instance filters.
+        def clear_instance_filters
+          instance_filters.clear
+        end
+        
+        # Apply the instance filters to the dataset returned by super.
+        def _delete_dataset
+          apply_instance_filters(super)
+        end
+        
+        # Apply the instance filters to the dataset returned by super.
+        def _update_dataset
+          apply_instance_filters(super)
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/many_through_many.rb

@@ -193,7 +193,7 @@ module Sequel
           opts[:eager_grapher] ||= proc do |ds, assoc_alias, table_alias|
             iq = table_alias
             opts.edges.each do |t|
-              ds = ds.graph(t[:table], t.include?(:only_conditions) ? t[:only_conditions] : (Array(t[:right]).zip(Array(t[:left])) + t[:conditions]), :select=>false, :table_alias=>ds.unused_table_alias(t[:table]), :join_type=>t[:join_type], :implicit_qualifier=>iq, &t[:block])
+              ds = ds.graph(t[:table], t.fetch(:only_conditions, (Array(t[:right]).zip(Array(t[:left])) + t[:conditions])), :select=>false, :table_alias=>ds.unused_table_alias(t[:table]), :join_type=>t[:join_type], :implicit_qualifier=>iq, &t[:block])
               iq = nil
             end
             fe = opts[:final_edge]

data/lib/sequel/plugins/optimistic_locking.rb

@@ -1,4 +1,6 @@
 module Sequel
+  require 'plugins/instance_filters'
+  
   module Plugins
     # This plugin implements a simple database-independent locking mechanism
     # to ensure that concurrent updates do not override changes. This is
@@ -16,10 +18,14 @@ module Sequel
     # table has a lock_version column (or other column you name via the lock_column
     # class level accessor) that defaults to 0.
     #
-    # This plugin does not work with the class_table_inheritance plugin.
+    # This plugin relies on the instance_filters plugin.
     module OptimisticLocking
       # Exception class raised when trying to update or destroy a stale object.
-      class Error < Sequel::Error
+      Error = InstanceFilters::Error
+      
+      # Load the instance_filters plugin into the model.
+      def self.apply(model, opts={})
+        model.plugin :instance_filters
       end
 
       # Set the lock_column to the :lock_column option, or :lock_version if
@@ -40,23 +46,33 @@ module Sequel
       end
     
       module InstanceMethods
+        # Add the lock column instance filter to the object before destroying it.
+        def before_destroy
+          lock_column_instance_filter
+          super
+        end
+        
+        # Add the lock column instance filter to the object before updating it.
+        def before_update
+          lock_column_instance_filter
+          super
+        end
+        
         private
         
-        # Only delete the object when destroying if it has the same lock version.  If the row
-        # doesn't have the same lock version, raise an error.
-        def _destroy_delete
+        # Add the lock column instance filter to the object.
+        def lock_column_instance_filter
           lc = model.lock_column
-          raise(Error, "Attempt to destroy a stale object") if this.filter(lc=>send(lc)).delete != 1
+          instance_filter(lc=>send(lc))
         end
         
         # Only update the row if it has the same lock version, and increment the
-        # lock version.  If the row doesn't have the same lock version, raise
-        # an Error.
+        # lock version.
         def _update(columns)
           lc = model.lock_column
           lcv = send(lc)
           columns[lc] = lcv + 1
-          raise(Error, "Attempt to update a stale object") if this.filter(lc=>lcv).update(columns) != 1
+          super
           send("#{lc}=", lcv + 1)
         end
       end