sequel 3.21.0 → 3.39.0

data/lib/sequel/plugins/serialization_modification_detection.rb

@@ -0,0 +1,63 @@
+module Sequel
+  module Plugins
+    # This plugin extends the serialization plugin and enables it to detect
+    # changes in serialized values by checking whether the current
+    # deserialized value is the same as the original deserialized value.
+    # The serialization plugin does not do such checks by default, as they
+    # often aren't needed and can hurt performance.
+    #
+    # Note that for this plugin to work correctly, the values you are
+    # serializing must roundtrip correctly (i.e. deserialize(serialize(value))
+    # should equal value).  This is true in most cases, but not in all.  For
+    # example, ruby symbols round trip through yaml, but not json (as they get
+    # turned into strings in json).
+    #
+    # == Example
+    #
+    #   require 'sequel'
+    #   require 'json'
+    #   class User < Sequel::Model
+    #     plugin :serialization, :json, :permissions
+    #     plugin :serialization_modification_detection
+    #   end
+    #   user = User.create(:permissions => {})
+    #   user.permissions[:global] = 'read-only'
+    #   user.save_changes
+    module SerializationModificationDetection
+      # Load the serialization plugin automatically.
+      def self.apply(model)
+        model.plugin :serialization
+      end
+      
+      module InstanceMethods
+        # Clear the cache of original deserialized values after saving so that it doesn't
+        # show the column is modified after saving.
+        def after_save
+          super
+          @original_deserialized_values = {}
+        end
+
+        # Detect which serialized columns have changed.
+        def changed_columns
+          cc = super
+          deserialized_values.each{|c, v| cc << c if !cc.include?(c) && original_deserialized_value(c) != v} 
+          cc
+        end
+
+        private
+
+        # For new objects, serialize any existing deserialized values so that changes can
+        # be detected.
+        def initialize_set(values)
+          super
+          serialize_deserialized_values
+        end
+
+        # Return the original deserialized value of the column, caching it to improve performance.
+        def original_deserialized_value(column)
+          (@original_deserialized_values ||= {})[column] ||= deserialize_value(column, self[column])
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/sharding.rb

@@ -1,13 +1,14 @@
 module Sequel
   module Plugins
-    # The sharding plugin makes it easy to use Sequel's sharding features
-    # with models.  It lets you create model objects on specific shards,
-    # and any models retrieved from specific shards are automatically
-    # saved back to those shards.  It also works with associations,
-    # so that model objects retrieved from specific shards will only
-    # return associated objects from that shard, and using the
-    # add/remove/remove_all association methods will only affect
-    # that shard.
+    # The sharding plugin augments Sequel's default model sharding support
+    # in the following ways:
+    #
+    # 1) It automatically sets model instances to be saved back to the
+    #    shard they were retreived from.
+    # 2) It makes model associations use the same shard as the model
+    #    object.
+    # 3) It adds a slightly nicer API for creating model instances on
+    #    specific shards.
     # 
     # Usage:
     #
@@ -40,15 +41,21 @@ module Sequel
         def new_using_server(s, values={}, &block)
           new(values, &block).set_server(s)
         end
-      end
 
-      module InstanceMethods
-        # Set the shard that this object is tied to.  Returns self.
-        def set_server(s)
-          @server = s
-          self
+        private
+
+        # Set the server for each graphed dataset to the current server
+        # unless the graphed dataset already has a server set.
+        def eager_graph_dataset(opts, eager_options)
+          ds = super
+          if s = eager_options[:self].opts[:server]
+            ds = ds.server(s) unless ds.opts[:server]
+          end
+          ds
         end
+      end
 
+      module InstanceMethods
         # Set the server that this object is tied to, unless it has
         # already been set.  Returns self.
         def set_server?(s)
@@ -56,11 +63,6 @@ module Sequel
           self
         end
 
-        # Ensure that the instance dataset is tied to the correct shard.
-        def this
-          use_server(super)
-        end
-
         private
 
         # Ensure that association datasets are tied to the correct shard.
@@ -68,21 +70,11 @@ module Sequel
           use_server(super)
         end
 
-        # Ensure that the object is inserted into the correct shard.
-        def _insert_dataset
-          use_server(super)
-        end
-
         # Ensure that the join table for many_to_many associations uses the correct shard.
         def _join_table_dataset(opts)
           use_server(super)
         end
 
-        # Make sure to use the correct shard when using a transaction
-        def checked_transaction(opts={}, &block)
-          super(@server ? {:server=>@server}.merge(opts) : opts, &block)
-        end
-
         # If creating the object by doing <tt>add_association</tt> for a
         # +many_to_many+ association, make sure the associated object is created on the
         # current object's shard, unless the passed object already has an assigned shard.
@@ -90,11 +82,6 @@ module Sequel
           o.set_server?(@server) if o.respond_to?(:set_server?)
           super
         end
-
-        # Set the given dataset to use the current object's shard.
-        def use_server(ds)
-          @server ? ds.server(@server) : ds
-        end
       end
 
       module DatasetMethods
@@ -109,26 +96,6 @@ module Sequel
           end
           ds
         end
-
-        private
-
-        # Set the shard of all retrieved objects to the shard of
-        # the table's dataset, or the current shard if the table's
-        # dataset does not have a shard.
-        def graph_each
-          ta = @opts[:graph][:table_aliases]
-          s = @opts[:server]
-          super do |r|
-            r.each do |k, v|
-              if ds = ta[k]
-                dss = ds.opts[:server]
-              end
-              vs = dss || s
-              v.set_server(vs) if vs && v.respond_to?(:set_server)
-            end
-            yield r
-          end
-        end
       end
     end
   end

data/lib/sequel/plugins/single_table_inheritance.rb

@@ -108,28 +108,30 @@ module Sequel
           key = skm[subclass] 
           sti_subclass_added(key)
           ska = [key]
+          rp = dataset.row_proc
           subclass.set_dataset(sd.filter(SQL::QualifiedIdentifier.new(table_name, sk)=>ska), :inherited=>true)
           subclass.instance_eval do
+            dataset.row_proc = rp
             @sti_key = sk
             @sti_key_array = ska
             @sti_dataset = sd
             @sti_key_map = skm
             @sti_model_map = smm
-            @simple_table = nil
+            self.simple_table = nil
           end
         end
 
         # Return an instance of the class specified by sti_key,
         # used by the row_proc.
         def sti_load(r)
-          sti_class(sti_model_map[r[sti_key]]).load(r)
+          sti_class(sti_model_map[r[sti_key]]).call(r)
         end
 
         # Make sure that all subclasses of the parent class correctly include 
         # keys for all of their descendant classes.
         def sti_subclass_added(key)
           if sti_key_array
-            sti_key_array << key
+            Sequel.synchronize{sti_key_array << key}
             superclass.sti_subclass_added(key)
           end
         end

data/lib/sequel/plugins/static_cache.rb

@@ -0,0 +1,99 @@
+module Sequel
+  module Plugins
+    # The static_cache plugin is designed for models that are not modified at all
+    # in production use cases, or at least where modifications to them would usually
+    # coincide with an application restart.  When loaded into a model class, it 
+    # retrieves all rows in the database and staticly caches a ruby array and hash
+    # keyed on primary key containing all of the model instances.  All of these instances
+    # are frozen so they won't be modified unexpectedly.
+    #
+    # The caches this plugin creates are used for the following things:
+    #
+    # * Primary key lookups (e.g. Model[1])
+    # * Model.all calls
+    # * Model.each calls
+    # * Model.map calls without an argument
+    # * Model.to_hash calls without an argument
+    #
+    # Usage:
+    #
+    #   # Cache the AlbumType class staticly
+    #   AlbumType.plugin :static_cache
+    module StaticCache
+      # Populate the static caches when loading the plugin.
+      def self.configure(model)
+        model.send(:load_cache)
+      end
+
+      module ClassMethods
+        # A frozen ruby hash holding all of the model's frozen instances, keyed by frozen primary key.
+        attr_reader :cache
+
+        # An array of all of the model's frozen instances, without issuing a database
+        # query.
+        def all
+          @all.dup
+        end
+
+        # Return the frozen object with the given pk, or nil if no such object exists
+        # in the cache, without issuing a database query.
+        def cache_get_pk(pk)
+          cache[pk]
+        end
+
+        # Yield each of the model's frozen instances to the block, without issuing a database
+        # query.
+        def each(&block)
+          @all.each(&block)
+        end
+
+        # If no arguments are given, yield each of the model's frozen instances to the block.
+        # and return a new array, without issuing a database query.  If any arguments are
+        # given, use the default Sequel behavior.
+        def map(*a)
+          if a.empty?
+            @all.map(&(Proc.new if block_given?))
+          else
+            super
+          end
+        end
+
+        # Reload the cache when the dataset changes.
+        def set_dataset(*)
+          s = super
+          load_cache
+          s
+        end
+
+        # If no arguments are given, yield an identity map for the model with frozen primary keys
+        # and instances, without issuing a database query. If any arguments are
+        # given, use the default Sequel behavior.
+        def to_hash(*a)
+          if a.empty?
+            cache.dup
+          else
+            super
+          end
+        end
+
+        private
+
+        # Return the frozen object with the given pk, or nil if no such object exists
+        # in the cache, without issuing a database query.
+        def primary_key_lookup(pk)
+          cache[pk]
+        end
+
+        # Reload the cache for this model by retrieving all of the instances in the dataset
+        # freezing them, and populating the cached array and hash.
+        def load_cache
+          a = dataset.all
+          h = {}
+          a.each{|o| h[o.pk.freeze] = o.freeze}
+          @all = a.freeze
+          @cache = h.freeze
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/subclasses.rb

@@ -15,20 +15,34 @@ module Sequel
     #   sc2.subclasses  # []
     #   ssc1.subclasses # []
     #   c.descendents   # [sc1, ssc1, sc2]
+    #
+    # You can provide a block when loading the plugin, and it will be called
+    # with each subclass created:
+    #
+    #   a = []
+    #   Sequel::Model.plugin(:subclasses){|sc| a << sc}
+    #   class A < Sequel::Model; end
+    #   class B < Sequel::Model; end
+    #   a # => [A, B]
     module Subclasses
       # Initialize the subclasses instance variable for the model.
-      def self.apply(model)
+      def self.apply(model, &block)
         model.instance_variable_set(:@subclasses, [])
+        model.instance_variable_set(:@on_subclass, block)
       end
 
       module ClassMethods
+        # Callable object that should be called with every descendent
+        # class created.
+        attr_reader :on_subclass
+
         # All subclasses for the current model.  Does not
         # include the model itself.
         attr_reader :subclasses
 
         # All descendent classes of this model.
         def descendents
-          subclasses.map{|x| [x] + x.descendents}.flatten
+          Sequel.synchronize{_descendents}
         end
 
         # Add the subclass to this model's current subclasses,
@@ -36,8 +50,20 @@ module Sequel
         # in the subclass.
         def inherited(subclass)
           super
-          subclasses << subclass
+          Sequel.synchronize{subclasses << subclass}
           subclass.instance_variable_set(:@subclasses, [])
+          if on_subclass
+            subclass.instance_variable_set(:@on_subclass, on_subclass)
+            on_subclass.call(subclass)
+          end
+        end
+
+        private
+
+        # Recursive, non-thread safe version of descendents, since
+        # the mutex Sequel uses isn't reentrant.
+        def _descendents
+          subclasses.map{|x| [x] + x.send(:_descendents)}.flatten
         end
       end
     end

data/lib/sequel/plugins/tactical_eager_loading.rb

@@ -28,19 +28,18 @@ module Sequel
     module TacticalEagerLoading
       module InstanceMethods
         # The dataset that retrieved this object, set if the object was
-        # reteived via Dataset#all with an active identity map.
+        # reteived via Dataset#all.
         attr_accessor :retrieved_by
 
         # All model objects retrieved with this object, set if the object was
-        # reteived via Dataset#all with an active identity map.
+        # reteived via Dataset#all.
         attr_accessor :retrieved_with
 
         private
 
-        # If there is an active identity map and the association is not in the
-        # associations cache and the object was reteived via Dataset#all,
-        # eagerly load the association for all model objects retrieved with the
-        # current object.
+        # If there the association is not in the associations cache and the object
+        # was reteived via Dataset#all, eagerly load the association for all model
+        # objects retrieved with the current object.
         def load_associated_objects(opts, reload=false)
           name = opts[:name]
           if !associations.include?(name) && retrieved_by
@@ -51,6 +50,7 @@ module Sequel
               # is only defined in a subclass.  This particular instance can use the
               # association, but it can't be eagerly loaded as the parent class doesn't
               # have access to the association, and that's the class doing the eager loading.
+              nil
             end
           end
           super
@@ -60,7 +60,7 @@ module Sequel
       module DatasetMethods
         private
 
-        # If there is an active identity map, set the reteived_with attribute for the object
+        # Set the reteived_with and retrieved_by attributes for the object
         # with the current dataset and array of all objects.
         def post_load(objects)
           super

data/lib/sequel/plugins/timestamps.rb

@@ -19,7 +19,7 @@ module Sequel
     #   # timestamp, and setting the update timestamp when creating
     #   Album.plugin :timestamps, :force=>true, :update_on_create=>true
     module Timestamps
-      # Configure the plugin by setting the avialable options.  Note that
+      # Configure the plugin by setting the available options.  Note that
       # if this method is run more than once, previous settings are ignored,
       # and it will just use the settings given or the default settings.  Options:
       # * :create - The field to hold the create timestamp (default: :created_at)

data/lib/sequel/plugins/tree.rb

@@ -4,7 +4,7 @@ module Sequel
     # treat a Model as a tree.  
     #
     # A column for holding the parent key is required and is :parent_id by default.  
-    # This may be overridden by passing column name via :key
+    # This may be overridden by passing column name via :key.
     #
     # Optionally, a column to control order of nodes returned can be specified
     # by passing column name via :order.
@@ -98,7 +98,7 @@ module Sequel
           nodes 
         end
 
-        # Returns the root node of the tree that this node descends from
+        # Returns the root node of the tree that this node descends from.
         # This node is returned if it is a root node itself.
         def root
           ancestors.last || self
@@ -124,7 +124,7 @@ module Sequel
         end
       end
 
-      # Plugin included when :single_root option is passed
+      # Plugin included when :single_root option is passed.
       module SingleRoot
         module ClassMethods
           # Returns the single root node.

data/lib/sequel/plugins/typecast_on_load.rb

@@ -5,7 +5,7 @@ module Sequel
     # typecast correctly (with correct being defined as how the model object
     # would typecast the same column values).
     #
-    # This plugin modifies Model.load to call the setter methods (which typecast
+    # This plugin modifies Model#set_values to call the setter methods (which typecast
     # by default) for all columns given.  You can either specify the columns to
     # typecast on load in the plugin call itself, or afterwards using 
     # add_typecast_on_load_columns:
@@ -41,16 +41,11 @@ module Sequel
           super
           subclass.instance_variable_set(:@typecast_on_load_columns, typecast_on_load_columns.dup)
         end
-
-        # Call the setter method for each of the typecast on load columns,
-        # ensuring the model object will have the correct typecasting even
-        # if the database doesn't typecast the columns correctly.
-        def load(values)
-          super.load_typecast
-        end
       end
 
       module InstanceMethods
+        # Call the setter method for each of the model's typecast_on_load_columns
+        # with the current value, so it can be typecasted correctly.
         def load_typecast
           model.typecast_on_load_columns.each do |c|
             if v = values[c]
@@ -61,10 +56,12 @@ module Sequel
           self
         end
 
-        private
-
-        def _refresh(dataset)
-          super.load_typecast
+        # Typecast values using #load_typecast when the values are retrieved from
+        # the database.
+        def set_values(values)
+          ret = super
+          load_typecast
+          ret
         end
       end
     end

data/lib/sequel/plugins/update_primary_key.rb

@@ -1,6 +1,6 @@
 module Sequel
   module Plugins
-    # The update_primary_key plugin allows you to modify an objects
+    # The update_primary_key plugin allows you to modify an object's
     # primary key and then save the record.  Sequel does not work
     # correctly with primary key modifications by default.  Sequel
     # is designed to work with surrogate primary keys that never need to be
@@ -22,7 +22,7 @@ module Sequel
     module UpdatePrimaryKey
       module ClassMethods
         # Cache the pk_hash when loading records
-        def load(h)
+        def call(h)
           r = super(h)
           r.pk_hash
           r

data/lib/sequel/plugins/validation_class_methods.rb

@@ -60,7 +60,6 @@ module Sequel
 
         # Setup the validations and validation_reflections hash in the subclass.
         def inherited(subclass)
-          super
           vr = @validation_reflections
           subclass.class_eval do
             @validation_mutex = Mutex.new
@@ -69,6 +68,7 @@ module Sequel
             vr.each{|k,v| h[k] = v.dup}
             @validation_reflections = h
           end
+          super
         end
     
         # Instructs the model to skip validations defined in superclasses

data/lib/sequel/plugins/validation_helpers.rb

@@ -40,6 +40,37 @@ module Sequel
     # changing the values of the Sequel::Plugins::ValidationHelpers::DEFAULT_OPTIONS hash.  You
     # change change the default options on a per model basis
     # by overriding a private instance method default_validation_helpers_options.
+    #
+    # By changing the default options, you can setup internationalization of the
+    # error messages.  For example, you would modify the default options:
+    #
+    #   Sequel::Plugins::ValidationHelpers::DEFAULT_OPTIONS.merge!(
+    #     :exact_length=>{:message=>lambda{|exact| I18n.t("errors.exact_length", :exact => exact)}},
+    #     :integer=>{:message=>lambda{I18n.t("errors.integer")}},
+    #     ...
+    #   )
+    #
+    # and then use something like this in your yaml translation file:
+    #
+    #   en:
+    #     errors:
+    #       exact_length: "is not %{exact} characters"
+    #       integer: "is not a number"
+    #
+    # Note that if you want to support internationalization of Errors#full_messages,
+    # you need to override the method.  Here's an example:
+    #   
+    #   class Sequel::Model::Errors
+    #     ATTRIBUTE_JOINER = I18n.t('errors.joiner').freeze
+    #     def full_messages
+    #       inject([]) do |m, kv|
+    #         att, errors = *kv
+    #         att.is_a?(Array) ? Array(att).map!{|v| I18n.t("attributes.#{v}")} : att = I18n.t("attributes.#{att}")
+    #         errors.each {|e| m << (e.is_a?(LiteralString) ? e : "#{Array(att).join(ATTRIBUTE_JOINER)} #{e}")}
+    #         m
+    #       end
+    #     end
+    #   end
     module ValidationHelpers
       # Default validation options used by Sequel.  Can be modified to change the error
       # messages for all models (e.g. for internationalization), or to set certain
@@ -162,19 +193,39 @@ module Sequel
         # since it can deal with a grouping of multiple attributes.
         #
         # Possible Options:
-        # * :message - The message to use (default: 'is already taken')
-        # * :only_if_modified - Only check the uniqueness if the object is new or
-        #   one of the columns has been modified.
+        # :message :: The message to use (default: 'is already taken')
+        # :only_if_modified :: Only check the uniqueness if the object is new or
+        #                      one of the columns has been modified.
+        # :where :: A callable object where call takes three arguments, a dataset,
+        #           the current object, and an array of columns, and should return
+        #           a modified dataset that is filtered to include only rows with
+        #           the same values as the current object for each column in the array.
+        #
+        # If you want to to a case insensitive uniqueness validation on a database that
+        # is case sensitive by default, you can use:
+        #
+        #   :where=>(proc do |ds, obj, cols|
+        #     ds.where(cols.map do |c|
+        #       v = obj.send(c)
+        #       v = v.downcase if v
+        #       [Sequel.function(:lower, c), v]
+        #     end)
+        #   end)
         def validates_unique(*atts)
           opts = default_validation_helpers_options(:unique)
           if atts.last.is_a?(Hash)
             opts = opts.merge(atts.pop)
           end
           message = validation_error_message(opts[:message])
+          where = opts[:where]
           atts.each do |a|
             arr = Array(a)
             next if opts[:only_if_modified] && !new? && !arr.any?{|x| changed_columns.include?(x)}
-            ds = model.filter(arr.map{|x| [x, send(x)]})
+            ds = if where
+              where.call(model.dataset, self, arr)
+            else
+              model.where(arr.map{|x| [x, send(x)]})
+            end
             ds = yield(ds) if block_given?
             ds = ds.exclude(pk_hash) unless new?
             errors.add(a, message) unless ds.count == 0

data/lib/sequel/plugins/xml_serializer.rb

@@ -79,6 +79,11 @@ module Sequel
     #
     #   Album.array_from_xml(Album.to_xml) # same as Album.all
     #
+    # If you have an existing array of model instances you want to convert to
+    # XML, you can call the class to_xml method with the :array option:
+    #
+    #   Album.to_xml(:array=>[Album[1], Album[2]])
+    #
     # Usage:
     #
     #   # Add XML output capability to all model subclass instances (called before loading subclasses)
@@ -205,9 +210,9 @@ module Sequel
                 klass.from_xml_node(node)
               end
             elsif cols.include?(k)
-              self[k.to_sym] = node[:nil] ? nil : node.children.first.to_s
+              self[k.to_sym] = node.key?('nil') ? nil : node.children.first.to_s
             elsif meths.include?("#{k}=")
-              send("#{k}=", node[:nil] ? nil : node.children.first.to_s)
+              send("#{k}=", node.key?('nil') ? nil : node.children.first.to_s)
             else
               raise Error, "Entry in XML not an association or column and no setter method exists: #{k}"
             end
@@ -266,7 +271,7 @@ module Sequel
 
           name_proc = model.xml_serialize_name_proc(opts)
           x = model.xml_builder(opts)
-          x.send(name_proc[opts.fetch(:root_name, model.send(:underscore, model.name)).to_s]) do |x1|
+          x.send(name_proc[opts.fetch(:root_name, model.send(:underscore, model.name).gsub('/', '__')).to_s]) do |x1|
             cols.each do |c|
               attrs = {}
               if types
@@ -316,8 +321,14 @@ module Sequel
           raise(Sequel::Error, "Dataset#to_xml") unless row_proc
           x = model.xml_builder(opts)
           name_proc = model.xml_serialize_name_proc(opts)
+          array = if opts[:array]
+            opts = opts.dup
+            opts.delete(:array)
+          else
+            all
+          end
           x.send(name_proc[opts.fetch(:array_root_name, model.send(:pluralize, model.send(:underscore, model.name))).to_s]) do |x1|
-            all.each do |obj|
+            array.each do |obj|
               obj.to_xml(opts.merge(:builder=>x1))
             end
           end