rdbi 0.9.0

data/lib/rdbi/driver.rb

@@ -0,0 +1,35 @@
+#
+# RDBI::Driver is the bootstrap handle to yield database connection
+# (RDBI::Database) handles. It preserves the connection parameters and the
+# desired database, and outside of yielding handles, does little else.
+#
+# As such, it is normally intended to be used by RDBI internally and (rarely
+# by) Database drivers.
+#
+class RDBI::Driver
+  # connection arguments requested during initialization
+  attr_reader :connect_args
+  # Database driver class requested for initialization
+  attr_reader :dbh_class
+
+  # Initialize a new driver object. This accepts an RDBI::Database subclass as a
+  # class name (shorthand does not work here) and the arguments to pass into
+  # the constructor.
+  def initialize(dbh_class, *args)
+    @dbh_class = dbh_class
+    @connect_args = [RDBI::Util.key_hash_as_symbols(args[0])]
+  end
+
+  #
+  # This is a proxy method to construct RDBI::Database handles. It constructs
+  # the RDBI::Database object, and sets the driver on the object to this
+  # current object for duplication / multiple creation.
+  #
+  def new_handle 
+    dbh = @dbh_class.new(*@connect_args)
+    dbh.driver = self
+    return dbh
+  end
+end
+
+# vim: syntax=ruby ts=2 et sw=2 sts=2

data/lib/rdbi/pool.rb

@@ -0,0 +1,236 @@
+#
+# RDBI::Pool - Connection Pooling.
+#
+# Pools are named resources that consist of N concurrent connections which all
+# have the same properties. Many group actions can be performed on them, such
+# as disconnecting the entire lot.
+#
+# RDBI::Pool itself has a global accessor, by way of +RDBI::Pool::[]+, that can
+# access these pools by name. Alternatively, you may access them through the
+# RDBI.pool interface.
+#
+# Pools are thread-safe and are capable of being resized without disconnecting
+# the culled database handles.
+#
+class RDBI::Pool
+
+  @mutex = Mutex.new
+
+  class << self
+    include Enumerable
+
+    # Iterate each pool and get the name of the pool (as a symbol) and the
+    # value as a Pool object.
+    def each
+      @pools.each do |key, value|
+        yield(key, value)
+      end
+    end
+
+    # obtain the names of each pool.
+    def keys
+      @pools.keys
+    end
+
+    # obtain the pool objects of each pool.
+    def values
+      @pools.values
+    end
+
+    #
+    # Retrieves a pool object for the name, or nothing if it does not exist.
+    # 
+    def [](name)
+      mutex.synchronize do
+        @pools ||= { }
+        @pools[name.to_sym]
+      end
+    end
+
+    #
+    # Sets the pool for the name. This is not recommended for end-user code.
+    #
+    def []=(name, value)
+      mutex.synchronize do
+        @pools ||= { }
+        @pools[name.to_sym] = value
+      end
+    end
+
+    def mutex
+      @mutex
+    end
+  end
+
+  include Enumerable
+
+  # a list of the pool handles for this object. Do not manipulate this directly.
+  attr_reader :handles
+  # the last index corresponding to the latest allocation request.
+  attr_reader :last_index
+  # the maximum number of items this pool can hold. should only be altered by resize.
+  attr_reader :max
+  # the Mutex for this pool.
+  attr_reader :mutex
+
+  #
+  # Creates a new pool.
+  #
+  # * name: the name of this pool, which will be used to find it in the global accessor.
+  # * connect_args: an array of arguments that would be passed to RDBI.connect, including the driver name.
+  # * max: the maximum number of connections to deal with.
+  #
+  # Usage:
+  #
+  # Pool.new(:fart, [:SQLite3, :database => "/tmp/foo.db"])
+  def initialize(name, connect_args, max=5)
+    @handles      = []
+    @connect_args = connect_args
+    @max          = max
+    @last_index   = 0
+    @mutex        = Mutex.new
+    self.class[name] = self
+  end
+
+  # Obtain each database handle in the pool.
+  def each
+    @handles.each { |dbh| yield dbh }
+  end
+
+  #
+  # Ping all database connections and average out the amount.
+  # 
+  # Any disconnected handles will be reconnected before this operation
+  # starts.
+  def ping
+    reconnect_if_disconnected
+    mutex.synchronize do 
+      @handles.inject(1) { |sum,dbh| sum + (dbh.ping || 1) } / @handles.size
+    end
+  end
+
+  #
+  # Unconditionally reconnect all database handles.
+  def reconnect
+    mutex.synchronize do 
+      @handles.each { |dbh| dbh.reconnect } 
+    end
+  end
+
+  #
+  # Only reconnect the database handles that have not been already connected.
+  def reconnect_if_disconnected
+    mutex.synchronize do 
+      @handles.each do |dbh|
+        dbh.reconnect unless dbh.connected?
+      end
+    end
+  end
+
+  # 
+  # Disconnect all database handles.
+  def disconnect
+    mutex.synchronize do
+      @handles.each(&:disconnect)
+    end
+  end
+
+  #
+  # Add a connection, connecting automatically with the connect arguments
+  # supplied to the constructor.
+  def add_connection
+    add(RDBI.connect(*@connect_args))
+  end
+
+  #
+  # Remove a specific connection. If this connection does not exist in the
+  # pool already, nothing will occur.
+  #
+  # This database object is *not* disconnected -- it is your responsibility
+  # to do so.
+  def remove(dbh)
+    mutex.synchronize do
+      @handles.reject! { |x| x.object_id == dbh.object_id }
+    end
+  end
+
+  #
+  # Resize the pool. If the new pool size is smaller, connections will be
+  # forcibly removed, preferring disconnected handles over connected ones.
+  #
+  # No database connections are disconnected.
+  #
+  # Returns the handles that were removed, if any.
+  #
+  def resize(max=5)
+    mutex.synchronize do
+      in_pool = @handles.select(&:connected?)
+
+      unless (in_pool.size >= max)
+        disconnected = @handles.select { |x| !x.connected? }
+        if disconnected.size > 0
+          in_pool += disconnected[0..(max - in_pool.size - 1)]
+        end
+      else
+        in_pool = in_pool[0..(max-1)]
+      end
+
+      rejected = @handles - in_pool
+
+      @max = max
+      @handles = in_pool
+      rejected
+    end
+  end
+
+  #
+  # Obtain a database handle from the pool. Ordering is round robin.
+  #
+  # A new connection may be created if it fills in the pool where a
+  # previously empty object existed. Additionally, if the current database
+  # handle is disconnected, it will be reconnected.
+  # 
+  def get_dbh
+    mutex.synchronize do
+      if @last_index >= @max
+        @last_index = 0
+      end
+
+      # XXX this is longhand for "make sure it's connected before we hand it
+      #     off"
+      if @handles[@last_index] and !@handles[@last_index].connected?
+        @handles[@last_index].reconnect
+      elsif !@handles[@last_index]
+        @handles[@last_index] = RDBI.connect(*@connect_args)
+      end
+
+      dbh = @handles[@last_index]
+      @last_index += 1
+      dbh
+    end
+  end
+
+  protected 
+
+  #
+  # Add any ol' database handle. This is not for global consumption.
+  #
+  def add(dbh)
+    dbh = *MethLab.validate_array_params([RDBI::Database], [dbh])
+    raise dbh if dbh.kind_of?(Exception)
+
+    dbh = dbh[0] if dbh.kind_of?(Array)
+
+    mutex.synchronize do
+      if @handles.size >= @max
+        raise ArgumentError, "too many handles in this pool (max: #{@max})"
+      end
+
+      @handles << dbh
+    end
+
+    return self
+  end
+end
+
+# vim: syntax=ruby ts=2 et sw=2 sts=2

data/lib/rdbi/result.rb

@@ -0,0 +1,402 @@
+#
+# RDBI::Result encapsulates results from a statement.
+#
+# Results in RDBI::Result are row-oriented and may be transformable by Result
+# Drivers (RDBI::Result::Driver). They are fetched as a unit or in order.
+#
+# The RDBI::Result API is deliberately architected to loosely resemble that of
+# IO or File.
+#
+# == Just give me the data!
+#
+# Have a peek at RDBI::Result#fetch.
+#
+# == Result Counts
+#
+# Multiple kinds of counts are represented in each result:
+#
+# * A count of the results provided
+# * A count of the affected rows.
+#
+# To elaborate, the "affected rows" is a count of rows that were altered by the
+# statement from a DML result such as +INSERT+ or +UPDATE+. In some cases,
+# statements will both alter rows and yield results, which is why this value is
+# not switched depending on the kind of statement.
+#
+# == Result Drivers
+#
+# Result drivers are subclasses of RDBI::Result::Driver that take the result as
+# input and yield a transformed input: data structures such a hashes, or even
+# wilder results such as CSV or JSON or YAML. Given the ability to sanely
+# transform row-oriented input, result drivers effectively have the power to do
+# anything.
+#
+# Accessing result drivers is as easy as using a secondary form of
+# RDBI::Result#fetch or more explicitly with the RDBI::Result#as call.
+#
+class RDBI::Result
+  extend MethLab
+  include Enumerable
+
+  # The RDBI::Schema structure associated with this result.
+  attr_reader :schema
+
+  # The RDBI::Statement that yielded this result.
+  attr_reader :sth
+
+  # The RDBI::Result::Driver currently associated with this Result.
+  attr_reader :driver
+
+  # The count of results (see RDBI::Result main documentation)
+  attr_reader :result_count
+
+  # The count of affected rows by a DML statement (see RDBI::Result main documentation)
+  attr_reader :affected_count
+
+  # The mapping of types for each positional argument in the Result.
+  attr_reader :type_hash
+
+  # The binds used in the statement that yielded this Result.
+  attr_reader :binds
+
+  # FIXME async
+  inline(:complete, :complete?) { true }
+
+  ##
+  # :attr_reader: has_data
+  #
+  # Does this result have data?
+
+  ##
+  # :attr_reader: has_data?
+  #
+  # Does this result have data?
+  inline(:has_data, :has_data?) { @data.size > 0 }
+
+  #
+  # Creates a new RDBI::Result. Please refer to RDBI::Statement#new_execution
+  # for instructions on how this is typically used and how the contents are
+  # passed to the constructor.
+  #
+  def initialize(sth, binds, data, schema, type_hash)
+    @schema         = schema
+    @data           = data
+    @result_count   = data.size
+    @affected_count = data.affected_count
+    @sth            = sth
+    @binds          = binds
+    @type_hash      = type_hash
+    @mutex          = Mutex.new
+    @driver         = RDBI::Result::Driver::Array
+    @fetch_handle   = nil
+    as(@driver)
+  end
+
+  #
+  # Reload the result. This will:
+  #
+  # * Execute the statement that yielded this result again, with the original binds
+  # * Replace the results and other attributes with the new results.
+  #
+  def reload
+    @data.finish
+    res = @sth.execute(*@binds)
+    @data           = res.instance_variable_get(:@data)
+    @type_hash      = res.instance_variable_get(:@type_hash)
+    @schema         = res.instance_variable_get(:@schema)
+    @result_count   = res.instance_variable_get(:@result_count)
+    @affected_count = res.instance_variable_get(:@affected_count)
+  end
+
+  #
+  # Iterator for Enumerable methods. Yields a row at a time.
+  #
+  def each
+    @data.each do |row|
+      yield(row)
+    end
+  end
+
+  #
+  # Reset the index.
+  #
+  def rewind
+    @data.rewind
+  end
+
+  #
+  # Coerce the underlying result to an array, fetching all values.
+  #
+  def coerce_to_array
+    @data.coerce_to_array
+  end
+
+  #
+  # :call-seq:
+  #   as(String)
+  #   as(Symbol)
+  #   as(Class)
+  #   as([Class, String, or Symbol], *driver_arguments)
+  #
+  # Replace the Result Driver. See RDBI::Result's main docs and
+  # RDBI::Result::Driver for more information on Result Drivers.
+  #
+  # You may pass:
+  #
+  # * A Symbol or String which is shorthand for loading from the
+  #   RDBI::Result::Driver namespace -- for example: "CSV" will result in the
+  #   class RDBI::Result::Driver::CSV.
+  # * A full class name.
+  #
+  # There are no naming requirements; the String/Symbol form is just shorthand
+  # for convention.
+  #
+  # Any additional arguments will be passed to the driver's constructor.
+  #
+  def as(driver_klass, *args)
+
+    driver_klass  = RDBI::Util.class_from_class_or_symbol(driver_klass, RDBI::Result::Driver)
+
+    @data.rewind
+    @driver       = driver_klass
+    @fetch_handle = driver_klass.new(self, *args)
+  end
+
+  #
+  # :call-seq:
+  #   fetch()
+  #   fetch(Integer)
+  #   fetch(:first)
+  #   fetch(:last)
+  #   fetch(:all)
+  #   fetch(:rest)
+  #   fetch(amount, [Class, String, or Symbol], *driver_arguments)
+  #
+  # fetch is the way people will typically interact with this class. It yields
+  # some or all of the results depending on the arguments given. Additionally,
+  # it can be supplemented with the arguments passed to RDBI::Result#as to
+  # one-off select a result driver.
+  #
+  # The initial argument can be none or one of many options:
+  #
+  # * An Integer n requests n rows from the result and increments the index.
+  # * No argument uses an Integer count of 1.
+  # * :first yields the first row of the result, regardless of the index.
+  # * :last yields the last row of the result, regardless of the index.
+  # * :all yields the whole set of rows, regardless of the index.
+  # * :rest yields all the items that have not been fetched, determined by the index.
+  # * :first and :last return nil if there are no results. All others will
+  #   return an empty array.
+  #
+  # == The index
+  #
+  # I bet you're wondering what that is now, right? Well, the index is
+  # essentially a running row count that is altered by certain fetch
+  # operations. This makes sequential fetches much simpler.
+  #
+  # The index is largely implemented by RDBI::Cursor (and Database Driver
+  # subclasses)
+  #
+  # Items that do not use the index do not affect it.
+  #
+  # Result Drivers will always rewind the index, as this implicates a "point of
+  # no return" state change. You may always return to the original driver you
+  # were using, but the index position will be lost.
+  #
+  # The default result driver is RDBI::Result::Driver::Array.
+  #
+  def fetch(row_count=1, driver_klass=nil, *args)
+    if driver_klass
+      as(driver_klass, *args)
+    end
+
+    @fetch_handle.fetch(row_count)
+  end
+
+  alias read fetch
+
+  #
+  # raw_fetch is a straight array fetch without driver interaction. If you
+  # think you need this, please still read the fetch documentation as there is
+  # a considerable amount of overlap.
+  #
+  # This is generally used by Result Drivers to transform results.
+  #
+  def raw_fetch(row_count)
+    final_res = case row_count
+                when :all
+                  @data.all
+                when :rest
+                  @data.rest
+                when :first
+                  [@data.first]
+                when :last
+                  [@data.last]
+                else
+                  @data.fetch(row_count)
+                end
+    RDBI::Util.deep_copy(final_res)
+  end
+
+  #
+  # This call finishes the result and the RDBI::Statement handle, scheduling
+  # any unpreserved data for garbage collection.
+  #
+  def finish
+    @sth.finish
+    @data.finish
+    @data   = nil
+    @sth    = nil
+    @driver = nil
+    @binds  = nil
+    @schema = nil
+  end
+end
+
+#
+# A result driver is a transformative element for RDBI::Result. Its design
+# could be loosely described as a "fancy decorator".
+#
+# Usage and purpose is covered in the main RDBI::Result documentation. This
+# section will largely serve the purpose of helping those who wish to implement
+# result drivers themselves.
+#
+# == Creating a Result Driver
+#
+# A result driver typically inherits from RDBI::Result::Driver and implements
+# at least one method: +fetch+.
+#
+# This fetch is not RDBI::Result#fetch, and doesn't have the same call
+# semantics. Instead, it takes a single argument, the +row_count+, and
+# typically passes that to RDBI::Result#raw_fetch to get results to process. It
+# then returns the data transformed.
+#
+# RDBI::Result::Driver additionally provides two methods, convert_row and
+# convert_item, which leverage RDBI's type conversion facility (see RDBI::Type)
+# to assist in type conversion. For performance reasons, RDBI chooses to
+# convert on request instead of preemptively, so <b>it is the driver implementor's
+# job to do any conversion</b>.
+#
+# If you wish to implement a constructor in your class, please see
+# RDBI::Result::Driver.new.
+#
+class RDBI::Result::Driver
+
+  #
+  # Result driver constructor. This is the logic that associates the result
+  # driver for decoration over the result; if you wish to override this method,
+  # please call +super+ before performing your own operations.
+  #
+  def initialize(result, *args)
+    @result = result
+    @result.rewind
+  end
+
+  #
+  # Fetch the result with any transformations. The default is to present the
+  # type converted array.
+  #
+  def fetch(row_count)
+    ary = (@result.raw_fetch(row_count) || []).enum_for.with_index.map do |item, i|
+      convert_row(item)
+    end
+
+    RDBI::Util.format_results(row_count, ary)
+  end
+
+  # convert an entire row of data with the specified result map (see
+  # RDBI::Type)
+  def convert_row(row)
+    newrow = []
+    (row || []).each_with_index do |x, i|
+      newrow.push(convert_item(x, @result.schema.columns[i]))
+    end
+    return newrow
+  end
+
+  # convert a single item (row element) with the specified result map.
+  def convert_item(item, column)
+    RDBI::Type::Out.convert(item, column, @result.type_hash)
+  end
+end
+
+#
+# This is the standard Array driver. If you are familiar with the typical
+# results of a database layer similar to RDBI, these results should be very
+# familiar.
+#
+# If you wish for named accessors, please see RDBI::Result::Driver::Struct.
+#
+class RDBI::Result::Driver::Array < RDBI::Result::Driver
+end
+
+#
+# This driver yields CSV:
+#
+#   dbh.execute("select foo, bar from my_table").fetch(:first, :CSV)
+#
+# Yields the contents of columns foo and bar in CSV format (a String).
+#
+# The +fastercsv+ gem on 1.8 is used, which is the canonical +csv+ library on
+# 1.9. If you are using Ruby 1.8 and do not have this gem available and try to
+# use this driver, the code will abort during driver construction.
+#
+class RDBI::Result::Driver::CSV < RDBI::Result::Driver
+  def initialize(result, *args)
+    super
+    if RUBY_VERSION =~ /^1.8/
+      RDBI::Util.optional_require('fastercsv')
+    else
+      require 'csv'
+    end
+    # FIXME columns from schema deal maybe?
+  end
+
+  def fetch(row_count)
+    csv_string = ""
+    @result.raw_fetch(row_count).each do |row|
+      csv_string << row.to_csv
+    end
+    return csv_string
+  end
+end
+
+#
+# Yields Struct objects instead of arrays for the rows. What this means is that
+# you will recieve a single array of Structs, each struct representing a row of
+# the database.
+#
+# example:
+#
+#   results = dbh.execute("select foo, bar from my_table").fetch(:all, :Struct)
+#
+#   results[0].foo        # first row, foo column
+#   results[10].bar       # 11th row, bar column
+#
+class RDBI::Result::Driver::Struct < RDBI::Result::Driver
+  def initialize(result, *args)
+    super
+  end
+
+  def fetch(row_count)
+    column_names = @result.schema.columns.map(&:name)
+
+    klass = ::Struct.new(*column_names)
+
+    structs = super
+
+    if [:first, :last].include?(row_count) 
+      if structs
+        return klass.new(*structs)
+      else
+        return structs
+      end
+    end
+
+    structs.collect! { |row| klass.new(*row) }
+
+    return RDBI::Util.format_results(row_count, structs)
+  end
+end
+
+# vim: syntax=ruby ts=2 et sw=2 sts=2