sequel 4.1.1 → 4.2.0

data/lib/sequel/extensions/pg_static_cache_updater.rb

@@ -0,0 +1,133 @@
+# The pg_static_cache_updater extension is designed to
+# automatically update the caches in the models using the
+# static_cache plugin when changes to the underlying tables
+# are detected.
+#
+# Before using the extension in production, you have to add
+# triggers to the tables for the classes where you want the
+# caches updated automatically.  You would generally do this
+# during a migration:
+#
+#   Sequel.migration do
+#     up do
+#       extension :pg_static_cache_updater
+#       create_static_cache_update_function
+#       create_static_cache_update_trigger(:table_1)
+#       create_static_cache_update_trigger(:table_2)
+#     end
+#     down do
+#       extension :pg_static_cache_updater
+#       drop_trigger(:table_2, default_static_cache_update_name)
+#       drop_trigger(:table_1, default_static_cache_update_name)
+#       drop_function(default_static_cache_update_name)
+#     end
+#   end
+#
+# After the triggers have been added, in your application process,
+# after setting up your models, you need to listen for changes to
+# the underlying tables:
+#
+#   class Model1 < Sequel::Model(:table_1)
+#     plugin :static_cache
+#   end
+#   class Model2 < Sequel::Model(:table_2)
+#     plugin :static_cache
+#   end
+#
+#   DB.extension :pg_static_cache_updater
+#   DB.listen_for_static_cache_updates([Model1, Model2])
+#
+# When an INSERT/UPDATE/DELETE happens on the underlying table,
+# the trigger will send a notification with the table's OID.
+# The application(s) listening on that channel will receive
+# the notification, check the oid to see if it matches one
+# for the model tables it is interested in, and tell that model
+# to reload the cache if there is a match.
+#
+# Note that listen_for_static_cache_updates spawns a new thread
+# which will reserve its own database connection.  This thread
+# runs until the application process is shutdown.
+#
+# Also note that PostgreSQL does not send notifications to
+# channels until after the transaction including the changes
+# is committed.  Also, because a separate thread is used to
+# listen for notifications, there may be a slight delay between
+# when the transaction is committed and when the cache is
+# reloaded.
+#
+# Requirements:
+# * PostgreSQL 9.0+
+# * Listening Database object must be using the postgres adapter
+#   with the pg driver (the model classes do not have to
+#   use the same Database).
+# * Must be using a thread-safe connection pool (the default).
+
+module Sequel
+  module Postgres
+    module StaticCacheUpdater
+      # Add the static cache update function to the PostgreSQL database.
+      # This must be added before any triggers using this function are
+      # added.
+      #
+      # Options:
+      # :channel_name :: Override the channel name to use.
+      # :function_name :: Override the function name to use.
+      def create_static_cache_update_function(opts=OPTS)
+        create_function(opts[:function_name]||default_static_cache_update_name, <<SQL, :returns=>:trigger, :language=>:plpgsql)
+BEGIN
+  PERFORM pg_notify(#{literal((opts[:channel_name]||default_static_cache_update_name).to_s)}, TG_RELID::text);
+  RETURN NULL;
+END
+SQL
+      end
+
+      # Add a trigger to the given table that calls the function
+      # which will notify about table changes.
+      #
+      # Options:
+      # :function_name :: Override the function name to use.
+      # :trigger_name :: Override the trigger name to use.
+      def create_static_cache_update_trigger(table, opts=OPTS)
+        create_trigger(table, opts[:trigger_name]||default_static_cache_update_name, opts[:function_name]||default_static_cache_update_name, :after=>true)
+      end
+
+      # The default name for the function, trigger, and notification channel
+      # for this extension.
+      def default_static_cache_update_name
+        :sequel_static_cache_update
+      end
+
+      # Listen on the notification channel for changes to any of tables for
+      # the models given. If notified about a change to one of the tables,
+      # reload the cache for the related model.  Options given are also
+      # passed to Database#listen.
+      #
+      # Note that this implementation does not currently support model
+      # models that use the same underlying table.
+      #
+      # Options:
+      # :channel_name :: Override the channel name to use.
+      def listen_for_static_cache_updates(models, opts=OPTS)
+        raise Error, "this database object does not respond to listen, use the postgres adapter with the pg driver" unless respond_to?(:listen)
+        models = [models] unless models.is_a?(Array)
+        raise Error, "array of models to listen for changes cannot be empty" if models.empty?
+
+        oid_map = {}
+        models.each do |model|
+          raise Error, "#{model.inspect} does not use the static_cache plugin" unless model.respond_to?(:load_cache, true)
+          oid_map[get(regclass_oid(model.dataset.first_source_table))] = model
+        end
+
+        Thread.new do
+          listen(opts[:channel_name]||default_static_cache_update_name, {:loop=>true}.merge(opts)) do |_, _, oid|
+            if model = oid_map[oid.to_i]
+              model.send(:load_cache)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  Database.register_extension(:pg_static_cache_updater, Postgres::StaticCacheUpdater)
+end

data/lib/sequel/extensions/pretty_table.rb

@@ -12,7 +12,7 @@
 # You can load this extension into specific datasets:
 #
 #   ds = DB[:table]
-#   ds.extension(:pretty_table)
+#   ds = ds.extension(:pretty_table)
 #
 # Or you can load it into all of a database's datasets, which
 # is probably the desired behavior if you are using this extension:

data/lib/sequel/extensions/query.rb

@@ -5,7 +5,7 @@
 # You can load this extension into specific datasets:
 #
 #   ds = DB[:table]
-#   ds.extension(:query)
+#   ds = ds.extension(:query)
 #
 # Or you can load it into all of a database's datasets, which
 # is probably the desired behavior if you are using this extension:
@@ -25,6 +25,8 @@ module Sequel
   end
 
   module DatasetQuery
+    Dataset.def_mutation_method(:query, :module=>self)
+
     # Translates a query block into a dataset. Query blocks are an
     # alternative to Sequel's usual method chaining, by using
     # instance_eval with a proxy object:

data/lib/sequel/extensions/query_literals.rb

@@ -24,7 +24,7 @@
 # You can load this extension into specific datasets:
 #
 #   ds = DB[:table]
-#   ds.extension(:query_literals)
+#   ds = ds.extension(:query_literals)
 #
 # Or you can load it into all of a database's datasets, which
 # is probably the desired behavior if you are using this extension:

data/lib/sequel/extensions/select_remove.rb

@@ -5,7 +5,7 @@
 # You can load this extension into specific datasets:
 #
 #   ds = DB[:table]
-#   ds.extension(:select_remove)
+#   ds = ds.extension(:select_remove)
 #
 # Or you can load it into all of a database's datasets, which
 # is probably the desired behavior if you are using this extension:

data/lib/sequel/extensions/sequel_3_dataset_methods.rb

@@ -12,7 +12,7 @@
 # You can load this extension into specific datasets:
 #
 #   ds = DB[:table]
-#   ds.extension(:sequel_3_dataset_methods)
+#   ds = ds.extension(:sequel_3_dataset_methods)
 #
 # Or you can load it into all of a database's datasets, which
 # is probably the desired behavior if you are using this extension:

data/lib/sequel/extensions/set_overrides.rb

@@ -7,7 +7,7 @@
 # You can load this extension into specific datasets:
 #
 #   ds = DB[:table]
-#   ds.extension(:set_overrides)
+#   ds = ds.extension(:set_overrides)
 #
 # Or you can load it into all of a database's datasets, which
 # is probably the desired behavior if you are using this extension:

data/lib/sequel/model.rb

@@ -80,7 +80,7 @@ module Sequel
 
     # Class methods added to model that call the method of the same name on the dataset
     DATASET_METHODS = (Dataset::ACTION_METHODS + Dataset::QUERY_METHODS +
-      [:each_server]) - [:and, :or, :[], :[]=, :columns, :columns!, :delete, :update, :add_graph_aliases]
+      [:each_server]) - [:and, :or, :[], :columns, :columns!, :delete, :update, :add_graph_aliases]
     
     # Boolean settings that can be modified at the global, class, or instance level.
     BOOLEAN_SETTINGS = [:typecast_empty_string_to_nil, :typecast_on_assignment, :strict_param_setting, \

data/lib/sequel/model/base.rb

@@ -1001,6 +1001,14 @@ module Sequel
         @changed_columns ||= []
       end
   
+      # Similar to Model#dup, but copies frozen status to returned object
+      # if current object is frozen.
+      def clone
+        o = dup
+        o.freeze if frozen?
+        o
+      end
+
       # Deletes and returns +self+.  Does not run destroy hooks.
       # Look into using +destroy+ instead.
       #
@@ -1026,6 +1034,18 @@ module Sequel
         checked_save_failure(opts){checked_transaction(opts){_destroy(opts)}}
       end
 
+      # Produce a shallow copy of the object, similar to Object#dup.
+      def dup
+        s = self
+        super.instance_eval do
+          @values = s.values.dup
+          @changed_columns = s.changed_columns.dup
+          @errors = s.errors.dup
+          @this = s.this.dup if !new? && model.primary_key
+          self
+        end
+      end
+  
       # Iterates through all of the current values using each.
       #
       #  Album[1].each{|k, v| puts "#{k} => #{v}"}
@@ -1396,12 +1416,6 @@ module Sequel
         self
       end
 
-      # REMOVE41
-      def set_values(hash)
-        Sequel::Deprecation.deprecate('Model#set_values is deprecreated and will be removed in Sequel 4.1.  Please use _refresh_set_values or _save_set_values or set the values directly.')
-        @values = hash
-      end
-      
       # Clear the setter_methods cache when a method is added
       def singleton_method_added(meth)
         @singleton_setter_added = true if meth.to_s =~ SETTER_METHOD_REGEXP

data/lib/sequel/model/exceptions.rb

@@ -11,7 +11,7 @@ module Sequel
     end
   end
 
-  # Deprecated alias for HookFailed, kept for backwards compatibility
+  # Alias for HookFailed, kept for backwards compatibility
   BeforeHookFailed = HookFailed
   
   # Exception class raised when +require_modification+ is set and an UPDATE or DELETE statement to modify the dataset doesn't

data/lib/sequel/plugins/composition.rb

@@ -161,6 +161,15 @@ module Sequel
           @compositions ||= {}
         end
 
+        # Duplicate compositions hash when duplicating model instance.
+        def dup
+          s = self
+          super.instance_eval do
+            @compositions = s.compositions.dup
+            self
+          end
+        end
+
         # Freeze compositions hash when freezing model instance.
         def freeze
           compositions.freeze

data/lib/sequel/plugins/dirty.rb

@@ -85,6 +85,25 @@ module Sequel
           initial_values.has_key?(column)
         end
 
+        # Duplicate internal data structures
+        def dup 
+          s = self
+          super.instance_eval do
+            @initial_values = s.initial_values.dup
+            @missing_initial_values = s.send(:missing_initial_values).dup
+            @previous_changes = s.previous_changes.dup if s.previous_changes
+            self
+          end
+        end
+
+        # Freeze internal data structures
+        def freeze
+          initial_values.freeze
+          missing_initial_values.freeze
+          @previous_changes.freeze if @previous_changes
+          super
+        end
+
         # The initial value of the given column.  If the column value has
         # not changed, this will be the same as the current value of the
         # column.
@@ -101,14 +120,6 @@ module Sequel
           @initial_values ||= {}
         end
 
-        # Freeze internal data structures
-        def freeze
-          initial_values.freeze
-          missing_initial_values.freeze
-          @previous_changes.freeze if @previous_changes
-          super
-        end
-
         # Reset the column to its initial value.  If the column was not set
         # initial, removes it from the values.
         #

data/lib/sequel/plugins/instance_filters.rb

@@ -59,6 +59,15 @@ module Sequel
           clear_instance_filters
         end
 
+        # Duplicate internal structures when duplicating model instance.
+        def dup
+          ifs = instance_filters.dup
+          super.instance_eval do
+            @instance_filters = ifs
+            self
+          end
+        end
+      
         # Freeze the instance filters when freezing the object
         def freeze
           instance_filters.freeze

data/lib/sequel/plugins/serialization.rb

@@ -172,6 +172,15 @@ module Sequel
           @deserialized_values ||= {}
         end
 
+        # Freeze the deserialized values
+        def dup
+          dv = deserialized_values.dup
+          super.instance_eval do
+            @deserialized_values = dv
+            self
+          end
+        end
+
         # Freeze the deserialized values
         def freeze
           deserialized_values.freeze

data/lib/sequel/plugins/serialization_modification_detection.rb

@@ -45,6 +45,15 @@ module Sequel
           cc
         end
 
+        # Duplicate the original deserialized values when duplicating instance.
+        def dup
+          o = @original_deserialized_values
+          super.instance_eval do
+            @original_deserialized_values = o.dup if o
+            self
+          end
+        end
+
         # Freeze the original deserialized values when freezing the instance.
         def freeze
           @original_deserialized_values ||= {}

data/lib/sequel/plugins/static_cache.rb

@@ -3,26 +3,45 @@ module Sequel
     # 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
+    # retrieves all rows in the database and statically 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.
+    # are frozen so they won't be modified unexpectedly, and before hooks disallow
+    # saving or destroying instances.
+    #
+    # You can use the :frozen=>false option to have this plugin return unfrozen
+    # instances.  This is slower as it requires creating new objects, but it allows
+    # you to make changes to the object and save them.  If you set the option to false,
+    # you are responsible for updating the cache manually (the pg_static_cache_updater
+    # extension can handle this automatically).
     #
     # 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
+    # * Model.all
+    # * Model.each
+    # * Model.count (without an argument or block)
+    # * Model.map
+    # * Model.to_hash
+    # * Model.to_hash_groups
     #
     # Usage:
     #
-    #   # Cache the AlbumType class staticly
+    #   # Cache the AlbumType class statically, disallowing any changes.
     #   AlbumType.plugin :static_cache
+    #
+    #   # Cache the AlbumType class statically, but return unfrozen instances
+    #   # that can be modified.
+    #   AlbumType.plugin :static_cache, :frozen=>false
     module StaticCache
-      # Populate the static caches when loading the plugin.
-      def self.configure(model)
-        model.send(:load_cache)
+      # Populate the static caches when loading the plugin. Options:
+      # :frozen :: Whether retrieved model objects are frozen.  The default is true,
+      #            for better performance as the shared frozen objects can be used
+      #            directly.  If set to false, new instances are created.
+      def self.configure(model, opts=OPTS)
+        model.instance_eval do
+          @static_cache_frozen = opts.fetch(:frozen, true)
+          load_cache
+        end
       end
 
       module ClassMethods
@@ -32,7 +51,11 @@ module Sequel
         # An array of all of the model's frozen instances, without issuing a database
         # query.
         def all
-          @all.dup
+          if @static_cache_frozen
+            @all.dup
+          else
+            map{|o| o}
+          end
         end
 
         # Get the number of records in the cache, without issuing a database query.
@@ -47,13 +70,17 @@ module Sequel
         # 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]
+          static_cache_object(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)
+          if @static_cache_frozen
+            @all.each(&block)
+          else
+            @all.each{|o| yield(static_cache_object(o))}
+          end
         end
 
         # Use the cache instead of a query to get the results.
@@ -65,36 +92,47 @@ module Sequel
             else
               @all.map{|r| r[column]}
             end
+          elsif @static_cache_frozen
+            @all.map(&block)
+          elsif block
+            @all.map{|o| yield(static_cache_object(o))}
           else
-            @all.map(&(Proc.new if block_given?))
+            all.map
           end
         end
 
         Plugins.after_set_dataset(self, :load_cache)
+        Plugins.inherited_instance_variables(self, :@static_cache_frozen=>nil)
 
         # Use the cache instead of a query to get the results.
         def to_hash(key_column = nil, value_column = nil)
-        return cache.dup if key_column.nil? && value_column.nil?
+        if key_column.nil? && value_column.nil?
+          if @static_cache_frozen
+            return cache.dup
+          else
+            key_column = primary_key
+          end
+        end
 
         h = {}
         if value_column
           if value_column.is_a?(Array)
             if key_column.is_a?(Array)
-              each{|r| h[r.values.values_at(*key_column)] = r.values.values_at(*value_column)}
+              @all.each{|r| h[r.values.values_at(*key_column)] = r.values.values_at(*value_column)}
             else
-              each{|r| h[r[key_column]] = r.values.values_at(*value_column)}
+              @all.each{|r| h[r[key_column]] = r.values.values_at(*value_column)}
             end
           else
             if key_column.is_a?(Array)
-              each{|r| h[r.values.values_at(*key_column)] = r[value_column]}
+              @all.each{|r| h[r.values.values_at(*key_column)] = r[value_column]}
             else
-              each{|r| h[r[key_column]] = r[value_column]}
+              @all.each{|r| h[r[key_column]] = r[value_column]}
             end
           end
         elsif key_column.is_a?(Array)
-          each{|r| h[r.values.values_at(*key_column)] = r}
+          @all.each{|r| h[r.values.values_at(*key_column)] = static_cache_object(r)}
         else
-          each{|r| h[r[key_column]] = r}
+          @all.each{|r| h[r[key_column]] = static_cache_object(r)}
         end
         h
         end
@@ -105,31 +143,36 @@ module Sequel
           if value_column
             if value_column.is_a?(Array)
               if key_column.is_a?(Array)
-                each{|r| (h[r.values.values_at(*key_column)] ||= []) << r.values.values_at(*value_column)}
+                @all.each{|r| (h[r.values.values_at(*key_column)] ||= []) << r.values.values_at(*value_column)}
               else
-                each{|r| (h[r[key_column]] ||= []) << r.values.values_at(*value_column)}
+                @all.each{|r| (h[r[key_column]] ||= []) << r.values.values_at(*value_column)}
               end
             else
               if key_column.is_a?(Array)
-                each{|r| (h[r.values.values_at(*key_column)] ||= []) << r[value_column]}
+                @all.each{|r| (h[r.values.values_at(*key_column)] ||= []) << r[value_column]}
               else
-                each{|r| (h[r[key_column]] ||= []) << r[value_column]}
+                @all.each{|r| (h[r[key_column]] ||= []) << r[value_column]}
               end
             end
           elsif key_column.is_a?(Array)
-            each{|r| (h[r.values.values_at(*key_column)] ||= []) << r}
+            @all.each{|r| (h[r.values.values_at(*key_column)] ||= []) << static_cache_object(r)}
           else
-            each{|r| (h[r[key_column]] ||= []) << r}
+            @all.each{|r| (h[r[key_column]] ||= []) << static_cache_object(r)}
           end
           h
         end
 
+        # Ask whether modifications to this class are allowed.
+        def static_cache_allow_modifications?
+          !@static_cache_frozen
+        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]
+          static_cache_object(cache[pk])
         end
 
         # Reload the cache for this model by retrieving all of the instances in the dataset
@@ -141,6 +184,31 @@ module Sequel
           @all = a.freeze
           @cache = h.freeze
         end
+
+        # If :frozen=>false is not used, just return the argument. Otherwise,
+        # create a new instance with the arguments values if the argument is
+        # not nil.
+        def static_cache_object(o)
+          if @static_cache_frozen
+            o
+          elsif o
+            call(o.values.dup)
+          end
+        end
+      end
+
+      module InstanceMethods
+        # Disallowing destroying the object unless the :frozen=>false option was used.
+        def before_destroy
+          return false unless model.static_cache_allow_modifications?
+          super
+        end
+
+        # Disallowing saving the object unless the :frozen=>false option was used.
+        def before_save
+          return false unless model.static_cache_allow_modifications?
+          super
+        end
       end
     end
   end