viking-sequel 3.10.0

data/lib/sequel/plugins/optimistic_locking.rb

@@ -0,0 +1,81 @@
+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
+    # best implemented by a code example:
+    # 
+    #   class Person < Sequel::Model
+    #     plugin :optimistic_locking
+    #   end
+    #   p1 = Person[1]
+    #   p2 = Person[1]
+    #   p1.update(:name=>'Jim') # works
+    #   p2.update(:name=>'Bob') # raises Sequel::Plugins::OptimisticLocking::Error
+    #
+    # In order for this plugin to work, you need to make sure that the database
+    # table has a lock_version column (or other column you name via the lock_column
+    # class level accessor) that defaults to 0.
+    #
+    # This plugin relies on the instance_filters plugin.
+    module OptimisticLocking
+      # Exception class raised when trying to update or destroy a stale object.
+      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
+      # that option is not given.
+      def self.configure(model, opts={})
+        model.lock_column = opts[:lock_column] || :lock_version
+      end
+      
+      module ClassMethods
+        # The column holding the version of the lock
+        attr_accessor :lock_column
+        
+        # Copy the lock_column value into the subclass
+        def inherited(subclass)
+          super
+          subclass.lock_column = lock_column
+        end
+      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
+        
+        # Add the lock column instance filter to the object.
+        def lock_column_instance_filter
+          lc = model.lock_column
+          instance_filter(lc=>send(lc))
+        end
+        
+        # Only update the row if it has the same lock version, and increment the
+        # lock version.
+        def _update(columns)
+          lc = model.lock_column
+          lcv = send(lc)
+          columns[lc] = lcv + 1
+          super
+          send("#{lc}=", lcv + 1)
+        end
+      end
+    end
+  end
+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

data/lib/sequel/plugins/schema.rb

@@ -0,0 +1,66 @@
+module Sequel
+  module Plugins
+    # Sequel's built in schema plugin allows you to define your schema
+    # directly in the model using Model.set_schema (which takes a block
+    # similar to Database#create_table), and use Model.create_table to
+    # create a table using the schema information.
+    #
+    # This plugin is mostly suited to test code.  If there is any
+    # chance that your application's schema could change, you should
+    # be using the migration extension instead.
+    module Schema
+      module ClassMethods
+        # Creates table, using the column information from set_schema.
+        def create_table
+          db.create_table(table_name, :generator=>@schema)
+          @db_schema = get_db_schema(true)
+          columns
+        end
+        
+        # Drops the table if it exists and then runs create_table.  Should probably
+        # not be used except in testing.
+        def create_table!
+          drop_table rescue nil
+          create_table
+        end
+
+        # Creates the table unless the table already exists
+        def create_table?
+          create_table unless table_exists?
+        end
+        
+        # Drops table.
+        def drop_table
+          db.drop_table(table_name)
+        end
+    
+        # Returns table schema created with set_schema for direct descendant of Model.
+        # Does not retreive schema information from the database, see db_schema if you
+        # want that.
+        def schema
+          @schema || (superclass.schema unless superclass == Model)
+        end
+    
+        # Defines a table schema (see Schema::Generator for more information).
+        #
+        # This is only needed if you want to use the create_table/create_table! methods.
+        # Will also set the dataset if you provide a name, as well as setting
+        # the primary key if you defined one in the passed block.
+        #
+        # In general, it is a better idea to use migrations for production code, as
+        # migrations allow changes to existing schema.  set_schema is mostly useful for
+        # test code or simple examples.
+        def set_schema(name = nil, &block)
+          set_dataset(db[name]) if name
+          @schema = Sequel::Schema::Generator.new(db, &block)
+          set_primary_key(@schema.primary_key_name) if @schema.primary_key_name
+        end
+        
+        # Returns true if table exists, false otherwise.
+        def table_exists?
+          db.table_exists?(table_name)
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/serialization.rb

@@ -0,0 +1,166 @@
+module Sequel
+  module Plugins
+    # Sequel's built in Serialization plugin allows you to keep serialized
+    # ruby objects in the database, while giving you deserialized objects
+    # when you call an accessor.
+    #
+    # This plugin works by keeping the serialized value in the values, and
+    # adding a @deserialized_values hash.  The reader method for serialized columns
+    # will check the @deserialized_values for the value, return it if present,
+    # or deserialized the entry in @values and return it.  The writer method will
+    # set the @deserialized_values entry.  This plugin adds a before_save hook
+    # that serializes all @deserialized_values to @values.
+    #
+    # You can use either marshal, yaml, or json as the serialization format.
+    # If you use yaml or json, you should require them by yourself.
+    #
+    # Because of how this plugin works, it must be used inside each model class
+    # that needs serialization, after any set_dataset method calls in that class.
+    # Otherwise, it is possible that the default column accessors will take
+    # precedence.
+    #
+    # == Example
+    #
+    #   require 'sequel'
+    #   require 'json'
+    #   class User < Sequel::Model
+    #     plugin :serialization, :json, :permissions
+    #     # or
+    #     plugin :serialization
+    #     serialize_attributes :marshal, :permissions, :attributes
+    #   end
+    #   user = User.create
+    #   user.permissions = { :global => 'read-only' }
+    #   user.save
+    module Serialization
+      # Set up the column readers to do deserialization and the column writers
+      # to save the value in deserialized_values.
+      def self.apply(model, *args)
+        model.instance_eval{@serialization_map = {}}
+      end
+      
+      def self.configure(model, format=nil, *columns)
+        model.serialize_attributes(format, *columns) unless columns.empty?
+      end
+
+      module ClassMethods
+        # A map of the serialized columns for this model.  Keys are column
+        # symbols, values are serialization formats (:marshal, :yaml, or :json).
+        attr_reader :serialization_map
+
+        # Module to store the serialized column accessor methods, so they can
+        # call be overridden and call super to get the serialization behavior
+        attr_accessor :serialization_module
+
+        # Copy the serialization format and columns to serialize into the subclass.
+        def inherited(subclass)
+          super
+          sm = serialization_map.dup
+          subclass.instance_eval{@serialization_map = sm}
+        end
+        
+        # The first value in the serialization map.  This is only for
+        # backwards compatibility, use serialization_map in new code.
+        def serialization_format
+          serialization_map.values.first
+        end
+        
+        # Create instance level reader that deserializes column values on request,
+        # and instance level writer that stores new deserialized value in deserialized
+        # columns
+        def serialize_attributes(format, *columns)
+          raise(Error, "Unsupported serialization format (#{format}), should be :marshal, :yaml, or :json") unless [:marshal, :yaml, :json].include?(format)
+          raise(Error, "No columns given.  The serialization plugin requires you specify which columns to serialize") if columns.empty?
+          define_serialized_attribute_accessor(format, *columns)
+        end
+        
+        # The columns that will be serialized.  This is only for
+        # backwards compatibility, use serialization_map in new code.
+        def serialized_columns
+          serialization_map.keys
+        end
+
+        private
+
+        # Add serializated attribute acessor methods to the serialization_module
+        def define_serialized_attribute_accessor(format, *columns)
+          m = self
+          include(self.serialization_module ||= Module.new) unless serialization_module
+          serialization_module.class_eval do
+            columns.each do |column|
+              m.serialization_map[column] = format
+              define_method(column) do 
+                if deserialized_values.has_key?(column)
+                  deserialized_values[column]
+                else
+                  deserialized_values[column] = deserialize_value(column, super())
+                end
+              end
+              define_method("#{column}=") do |v| 
+                changed_columns << column unless changed_columns.include?(column)
+                deserialized_values[column] = v
+              end
+            end
+          end
+        end
+      end
+
+      module InstanceMethods
+        # Hash of deserialized values, used as a cache.
+        attr_reader :deserialized_values
+
+        # Set @deserialized_values to the empty hash
+        def initialize(*args, &block)
+          @deserialized_values = {}
+          super
+        end
+
+        # Serialize all deserialized values
+        def before_save
+          super
+          deserialized_values.each do |k,v|
+            @values[k] = serialize_value(k, v)
+          end
+        end
+        
+        # Empty the deserialized values when refreshing.
+        def refresh
+          @deserialized_values = {}
+          super
+        end
+
+        private
+
+        # Deserialize the column from either marshal or yaml format
+        def deserialize_value(column, v)
+          return v if v.nil?
+          case model.serialization_map[column] 
+          when :marshal
+            Marshal.load(v.unpack('m')[0]) rescue Marshal.load(v)
+          when :yaml
+            YAML.load v if v
+          when :json
+            JSON.parse v if v
+          else
+            raise Error, "Bad serialization format (#{model.serialization_map[column].inspect}) for column #{column.inspect}"
+          end
+        end
+
+        # Serialize the column to either marshal or yaml format
+        def serialize_value(column, v)
+          return v if v.nil?
+          case model.serialization_map[column] 
+          when :marshal
+            [Marshal.dump(v)].pack('m')
+          when :yaml
+            v.to_yaml
+          when :json
+            JSON.generate v
+          else
+            raise Error, "Bad serialization format (#{model.serialization_map[column].inspect}) for column #{column.inspect}"
+          end
+        end
+      end
+    end
+  end
+end