sequel 2.2.0 → 2.3.0

data/lib/sequel_core/deprecated.rb

@@ -0,0 +1,26 @@
+module Sequel
+  # This module makes it easy to add deprecation functionality to other classes.
+  module Deprecation # :nodoc:
+    # This sets the output stream for the deprecation messages.  Set it to an IO
+    # (or any object that responds to puts) and it will call puts on that
+    # object with the deprecation message.  Set to nil to ignore deprecation messages.
+    def self.deprecation_message_stream=(file)
+      @dms = file
+    end
+
+    # Set this to true to print tracebacks with every deprecation message,
+    # so you can see exactly where in your code the deprecated methods are
+    # being called.
+    def self.print_tracebacks=(pt)
+      @pt = pt
+    end
+
+    # Puts the messages unaltered to the deprecation message stream
+    def self.deprecate(message)
+      if @dms
+        @dms.puts(message)
+        caller.each{|c| @dms.puts(c)} if @pt 
+      end
+    end
+  end
+end

data/lib/sequel_core/exceptions.rb

@@ -0,0 +1,42 @@
+module Sequel
+  # Represents an error raised in Sequel code.
+  class Error < ::StandardError
+    
+    # Raised when Sequel is unable to load a specified adapter.
+    class AdapterNotFound < Error ; end
+    
+    # Raise when an invalid expression is encountered inside a block filter.
+    class InvalidExpression < Error; end
+                                       
+    # Represents an Invalid filter.    
+    class InvalidFilter < Error ; end
+    
+    # Represents an invalid join type.
+    class InvalidJoinType < Error ; end
+
+    # Raised on an invalid operation.
+    class InvalidOperation < Error; end
+                                       
+    # Error raised when an invalid statement is executed.
+    class InvalidStatement < Error; end
+
+    # Represents an Invalid transform.
+    class InvalidTransform < Error ; end
+    
+    # Represents an invalid value stored in the database.
+    class InvalidValue < Error ; end
+                                       
+    # Represents an attempt to performing filter operations when no filter has been specified yet.
+    class NoExistingFilter < Error ; end
+                                       
+    # There was an error while waiting on a connection from the connection pool
+    class PoolTimeoutError < Error ; end
+                                       
+    # Rollback is a special error used to rollback a transactions.
+    # A transaction block will catch this error and won't pass further up the stack.
+    class Rollback < Error ; end
+    
+    # Should be raised inside a worker loop to tell it to stop working.
+    class WorkerStop < RuntimeError ; end
+  end  
+end

data/lib/sequel_core/migration.rb

@@ -0,0 +1,187 @@
+module Sequel
+  # The Migration class describes a database migration that can be reversed.
+  # The migration looks very similar to ActiveRecord (Rails) migrations, e.g.:
+  #
+  #   class CreateSessions < Sequel::Migration
+  #     def up
+  #       create_table :sessions do
+  #         primary_key :id
+  #         varchar   :session_id, :size => 32, :unique => true
+  #         timestamp :created_at
+  #         text      :data
+  #       end
+  #     end
+  # 
+  #     def down
+  #       execute 'DROP TABLE sessions'
+  #     end
+  #   end
+  #
+  # To apply a migration to a database, you can invoke the #apply with
+  # the target database instance and the direction :up or :down, e.g.:
+  #
+  #   DB = Sequel.open ('sqlite://mydb')
+  #   CreateSessions.apply(DB, :up)
+  #
+  # See Sequel::Schema::Generator for the syntax to use for creating tables,
+  # and Sequel::Schema::AlterTableGenerator for the syntax to use when
+  # altering existing tables.
+  class Migration
+    # Creates a new instance of the migration and sets the @db attribute.
+    def initialize(db)
+      @db = db
+    end
+    
+    # Applies the migration to the supplied database in the specified
+    # direction.
+    def self.apply(db, direction)
+      obj = new(db)
+      case direction
+      when :up
+        obj.up
+      when :down
+        obj.down
+      else
+        raise ArgumentError, "Invalid migration direction specified (#{direction.inspect})"
+      end
+    end
+
+    # Returns the list of Migration descendants.
+    def self.descendants
+      @descendants ||= []
+    end
+    
+    # Adds the new migration class to the list of Migration descendants.
+    def self.inherited(base)
+      descendants << base
+    end
+    
+    # The default down action does nothing
+    def down
+    end
+    
+    # Intercepts method calls intended for the database and sends them along.
+    def method_missing(method_sym, *args, &block)
+      @db.send(method_sym, *args, &block)
+    end
+
+    # The default up action does nothing
+    def up
+    end
+  end
+
+  # The Migrator module performs migrations based on migration files in a 
+  # specified directory. The migration files should be named using the
+  # following pattern (in similar fashion to ActiveRecord migrations):
+  # 
+  #   <version>_<title>.rb
+  #
+  # For example, the following files are considered migration files:
+  #   
+  #   001_create_sessions.rb
+  #   002_add_data_column.rb
+  #   ...
+  #
+  # The migration files should contain one or more migration classes based
+  # on Sequel::Migration.
+  #
+  # To apply a migration, the #apply method must be invoked with the database
+  # instance, the directory of migration files and the target version. If
+  # no current version is supplied, it is read from the database. The migrator
+  # automatically creates a schema_info table in the database to keep track
+  # of the current migration version. If no migration version is stored in the
+  # database, the version is considered to be 0. If no target version is 
+  # specified, the database is migrated to the latest version available in the
+  # migration directory.
+  #
+  # For example, to migrate the database to the latest version:
+  #
+  #   Sequel::Migrator.apply(DB, '.')
+  #
+  # To migrate the database from version 1 to version 5:
+  #
+  #   Sequel::Migrator.apply(DB, '.', 5, 1)
+  module Migrator
+    MIGRATION_FILE_PATTERN = /\A\d+_.+\.rb\z/.freeze
+
+    # Migrates the supplied database in the specified directory from the
+    # current version to the target version. If no current version is
+    # supplied, it is extracted from a schema_info table. The schema_info
+    # table is automatically created and maintained by the apply function.
+    def self.apply(db, directory, target = nil, current = nil)
+      # determine current and target version and direction
+      current ||= get_current_migration_version(db)
+      target ||= latest_migration_version(directory)
+      raise Error, "No current version available" if current.nil?
+      raise Error, "No target version available" if target.nil?
+
+      direction = current < target ? :up : :down
+      
+      classes = migration_classes(directory, target, current, direction)
+      
+      db.transaction do
+        classes.each {|c| c.apply(db, direction)}
+        set_current_migration_version(db, target)
+      end
+      
+      target
+    end
+
+    # Gets the current migration version stored in the database. If no version
+    # number is stored, 0 is returned.
+    def self.get_current_migration_version(db)
+      r = schema_info_dataset(db).first
+      r ? r[:version] : 0
+    end
+
+    # Returns the latest version available in the specified directory.
+    def self.latest_migration_version(directory)
+      l = migration_files(directory).last
+      l ? File.basename(l).to_i : nil
+    end
+
+    # Returns a list of migration classes filtered for the migration range and
+    # ordered according to the migration direction.
+    def self.migration_classes(directory, target, current, direction)
+      range = direction == :up ?
+        (current + 1)..target : (target + 1)..current
+
+      # Remove class definitions
+      Migration.descendants.each do |c|
+        Object.send(:remove_const, c.to_s) rescue nil
+      end
+      Migration.descendants.clear # remove any defined migration classes
+
+      # load migration files
+      migration_files(directory, range).each {|fn| load(fn)}
+      
+      # get migration classes
+      classes = Migration.descendants
+      classes.reverse! if direction == :down
+      classes
+    end
+    
+    # Returns any found migration files in the supplied directory.
+    def self.migration_files(directory, range = nil)
+      files = []
+      Dir.new(directory).each do |file|
+        files[file.to_i] = File.join(directory, file) if MIGRATION_FILE_PATTERN.match(file)
+      end
+      filtered = range ? files[range] : files
+      filtered ? filtered.compact : []
+    end
+    
+    # Returns the dataset for the schema_info table. If no such table
+    # exists, it is automatically created.
+    def self.schema_info_dataset(db)
+      db.create_table(:schema_info) {integer :version} unless db.table_exists?(:schema_info)
+      db[:schema_info]
+    end
+    
+    # Sets the current migration  version stored in the database.
+    def self.set_current_migration_version(db, version)
+      dataset = schema_info_dataset(db)
+      dataset.send(dataset.first ? :update : :<<, :version => version)
+    end
+  end
+end

data/lib/sequel_core/object_graph.rb

@@ -0,0 +1,216 @@
+module Sequel
+  class Dataset
+    # Allows you to join multiple datasets/tables and have the result set
+    # split into component tables.
+    #
+    # This differs from the usual usage of join, which returns the result set
+    # as a single hash.  For example:
+    #
+    #   # CREATE TABLE artists (id INTEGER, name TEXT);
+    #   # CREATE TABLE albums (id INTEGER, name TEXT, artist_id INTEGER);
+    #   DB[:artists].left_outer_join(:albums, :artist_id=>:id).first
+    #   => {:id=>(albums.id||artists.id), :name=>(albums.name||artist.names), :artist_id=>albums.artist_id}
+    #   DB[:artists].graph(:albums, :artist_id=>:id).first
+    #   => {:artists=>{:id=>artists.id, :name=>artists.name}, :albums=>{:id=>albums.id, :name=>albums.name, :artist_id=>albums.artist_id}}
+    #
+    # Using a join such as left_outer_join, the attribute names that are shared between
+    # the tables are combined in the single return hash.  You can get around that by
+    # using .select with correct aliases for all of the columns, but it is simpler to
+    # use graph and have the result set split for you.  In addition, graph respects
+    # any row_proc or transform attributes of the current dataset and the datasets
+    # you use with graph.
+    #
+    # If you are graphing a table and all columns for that table are nil, this
+    # indicates that no matching rows existed in the table, so graph will return nil
+    # instead of a hash with all nil values:
+    #
+    #   # If the artist doesn't have any albums
+    #   DB[:artists].graph(:albums, :artist_id=>:id).first
+    #   => {:artists=>{:id=>artists.id, :name=>artists.name}, :albums=>nil}
+    #
+    # Arguments:
+    # * dataset -  Can be a symbol (specifying a table), another dataset,
+    #   or an object that responds to .dataset and yields a symbol or a dataset
+    # * join_conditions - Any condition(s) allowed by join_table.
+    # * options -  A hash of graph options.  The following options are currently used:
+    #   * :table_alias - The alias to use for the table.  If not specified, doesn't
+    #     alias the table.  You will get an error if the the alias (or table) name is
+    #     used more than once.
+    #   * :join_type - The type of join to use (passed to join_table).  Defaults to
+    #     :left_outer.
+    #   * :select - An array of columns to select.  When not used, selects
+    #     all columns in the given dataset.  When set to false, selects no
+    #     columns and is like simply joining the tables, though graph keeps
+    #     some metadata about join that makes it important to use graph instead
+    #     of join.
+    # * block - A block that is passed to join_table.
+    def graph(dataset, join_conditions = nil, options = {}, &block)
+      # Allow the use of a model, dataset, or symbol as the first argument
+      # Find the table name/dataset based on the argument
+      dataset = dataset.dataset if dataset.respond_to?(:dataset)
+      case dataset
+      when Symbol
+        table = dataset
+        dataset = @db[dataset]
+      when ::Sequel::Dataset
+        table = dataset.first_source
+      else
+        raise Error, "The dataset argument should be a symbol, dataset, or model"
+      end
+
+      # Raise Sequel::Error with explanation that the table alias has been used
+      raise_alias_error = lambda do
+        raise(Error, "this #{options[:table_alias] ? 'alias' : 'table'} has already been been used, please specify " \
+          "#{options[:table_alias] ? 'a different alias' : 'an alias via the :table_alias option'}") 
+      end
+
+      # Only allow table aliases that haven't been used
+      table_alias = options[:table_alias] || table
+      raise_alias_error.call if @opts[:graph] && @opts[:graph][:table_aliases] && @opts[:graph][:table_aliases].include?(table_alias)
+
+      # Join the table early in order to avoid cloning the dataset twice
+      ds = join_table(options[:join_type] || :left_outer, table, join_conditions, table_alias, &block)
+      opts = ds.opts
+
+      # Whether to include the table in the result set
+      add_table = options[:select] == false ? false : true
+      # Whether to add the columns to the list of column aliases
+      add_columns = !ds.opts.include?(:graph_aliases)
+
+      # Setup the initial graph data structure if it doesn't exist
+      unless graph = opts[:graph]
+        master = ds.first_source
+        raise_alias_error.call if master == table_alias
+        # Master hash storing all .graph related information
+        graph = opts[:graph] = {}
+        # Associates column aliases back to tables and columns
+        column_aliases = graph[:column_aliases] = {}
+        # Associates table alias (the master is never aliased)
+        table_aliases = graph[:table_aliases] = {master=>self}
+        # Keep track of the alias numbers used
+        ca_num = graph[:column_alias_num] = Hash.new(0)
+        # All columns in the master table are never
+        # aliased, but are not included if set_graph_aliases
+        # has been used.
+        if add_columns
+          select = opts[:select] = []
+          columns.each do |column|
+            column_aliases[column] = [master, column]
+            select.push(column.qualify(master))
+          end
+        end
+      end
+
+      # Add the table alias to the list of aliases
+      # Even if it isn't been used in the result set,
+      # we add a key for it with a nil value so we can check if it
+      # is used more than once
+      table_aliases = graph[:table_aliases]
+      table_aliases[table_alias] = add_table ? dataset : nil
+
+      # Add the columns to the selection unless we are ignoring them
+      if add_table && add_columns
+        select = opts[:select]
+        column_aliases = graph[:column_aliases]
+        ca_num = graph[:column_alias_num]
+        # Which columns to add to the result set
+        cols = options[:select] || dataset.columns
+        # If the column hasn't been used yet, don't alias it.
+        # If it has been used, try table_column.
+        # If that has been used, try table_column_N 
+        # using the next value of N that we know hasn't been
+        # used
+        cols.each do |column|
+          col_alias, identifier = if column_aliases[column]
+            column_alias = :"#{table_alias}_#{column}"
+            if column_aliases[column_alias]
+              column_alias_num = ca_num[column_alias]
+              column_alias = :"#{column_alias}_#{column_alias_num}" 
+              ca_num[column_alias] += 1
+            end
+            [column_alias, column.qualify(table_alias).as(column_alias)]
+          else
+            [column, column.qualify(table_alias)]
+          end
+          column_aliases[col_alias] = [table_alias, column]
+          select.push(identifier)
+        end
+      end
+      ds
+    end
+
+    # This allows you to manually specify the graph aliases to use
+    # when using graph.  You can use it to only select certain
+    # columns, and have those columns mapped to specific aliases
+    # in the result set.  This is the equivalent of .select for a
+    # graphed dataset, and must be used instead of .select whenever
+    # graphing is used. Example:
+    #
+    #   DB[:artists].graph(:albums, :artist_id=>:id).set_graph_aliases(:artist_name=>[:artists, :name], :album_name=>[:albums, :name]).first
+    #   => {:artists=>{:name=>artists.name}, :albums=>{:name=>albums.name}}
+    #
+    # Arguments:
+    # * graph_aliases - Should be a hash with keys being symbols of
+    #   column aliases, and values being arrays with two symbol elements.
+    #   The first element of the array should be the table alias,
+    #   and the second should be the actual column name.
+    def set_graph_aliases(graph_aliases)
+      cols = graph_aliases.collect do |col_alias, tc| 
+        identifier = tc[1].qualify(tc[0])
+        identifier = identifier.as(col_alias) unless tc[1] == col_alias
+        identifier
+      end
+      ds = select(*cols)
+      ds.opts[:graph_aliases] = graph_aliases
+      ds
+    end
+
+    private
+
+    # Fetch the rows, split them into component table parts,
+    # tranform and run the row_proc on each part (if applicable),
+    # and yield a hash of the parts.
+    def graph_each(opts, &block)
+      # Reject tables with nil datasets, as they are excluded from
+      # the result set
+      datasets = @opts[:graph][:table_aliases].to_a.reject{|ta,ds| ds.nil?}
+      # Get just the list of table aliases into a local variable, for speed
+      table_aliases = datasets.collect{|ta,ds| ta}
+      # Get an array of arrays, one for each dataset, with
+      # the necessary information about each dataset, for speed
+      datasets = datasets.collect do |ta, ds|
+        [ta, ds, ds.instance_variable_get(:@transform), ds.row_proc]
+      end
+      # Use the manually set graph aliases, if any, otherwise
+      # use the ones automatically created by .graph
+      column_aliases = @opts[:graph_aliases] || @opts[:graph][:column_aliases]
+      fetch_rows(select_sql(opts)) do |r|
+        graph = {}
+        # Create the sub hashes, one per table
+        table_aliases.each{|ta| graph[ta]={}}
+        # Split the result set based on the column aliases
+        # If there are columns in the result set that are
+        # not in column_aliases, they are ignored
+        column_aliases.each do |col_alias, tc|
+          ta, column = tc
+          graph[ta][column] = r[col_alias]
+        end
+        # For each dataset, transform and run the row
+        # row_proc if applicable
+        datasets.each do |ta,ds,tr,rp|
+          g = graph[ta]
+          graph[ta] = if g.values.any?
+            g = ds.transform_load(g) if tr
+            g = rp[g] if rp
+            g
+          else
+            nil
+          end
+        end
+
+        yield graph
+      end
+      self
+    end
+  end
+end