rdbi 0.9.1 → 1.1.0

data/lib/rdbi/driver.rb

@@ -17,6 +17,9 @@ class RDBI::Driver
   # the constructor.
   def initialize(dbh_class, *args)
     @dbh_class = dbh_class
+    if args.empty? 
+      raise ArgumentError, "unable to connect without arguments"
+    end 
     @connect_args = [RDBI::Util.key_hash_as_symbols(args[0])]
   end
 
@@ -25,7 +28,7 @@ class RDBI::Driver
   # the RDBI::Database object, and sets the driver on the object to this
   # current object for duplication / multiple creation.
   #
-  def new_handle 
+  def new_handle
     dbh = @dbh_class.new(*@connect_args)
     dbh.driver = self
     return dbh

data/lib/rdbi/pool.rb

@@ -83,9 +83,11 @@ class RDBI::Pool
   # Usage:
   #
   # Pool.new(:fart, [:SQLite3, :database => "/tmp/foo.db"])
+  # Pool.new(:quux, { :database => :SQLite3, :database => ":memory:" })
   def initialize(name, connect_args, max=5)
     @handles      = []
     @connect_args = connect_args
+    munge_connect_args!
     @max          = max
     @last_index   = 0
     @mutex        = Mutex.new
@@ -225,6 +227,14 @@ class RDBI::Pool
   end
 
   protected 
+  
+  # reformat the connect arguments coming from certain external sources.
+  def munge_connect_args!
+    if @connect_args.kind_of?(Hash) and @connect_args.has_key?(:driver)
+      new_connect_args = [@connect_args.delete(:driver), @connect_args]
+      @connect_args = new_connect_args
+    end
+  end
 
   #
   # Add any ol' database handle. This is not for global consumption.

data/lib/rdbi/result.rb

@@ -46,12 +46,6 @@ class RDBI::Result
   # 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
 
@@ -84,18 +78,32 @@ class RDBI::Result
   def initialize(sth, binds, data, schema, type_hash)
     @schema         = schema
     @data           = data
-    @result_count   = data.size
-    @affected_count = data.affected_count
+    @affected_count = nil  # computed on demand
     @sth            = sth
     @binds          = binds
     @type_hash      = type_hash
     @driver         = RDBI::Result::Driver::Array
-    @fetch_handle   = nil
+    @result_driver  = nil
 
     configure_rewindable
     configure_driver(@driver)
+
+    RDBI::Util.upon_finalize!(self, @data, :finish)
   end
 
+  # The count of results (see RDBI::Result main documentation)
+  def result_count
+    # Non-rewindable cursors typically will give the number of rows
+    # fetched so far...
+    @data.size
+  end
+
+  # The count of affected rows by a DML statement (see RDBI::Result main documentation)
+  def affected_count
+    @affected_count ||= @data.affected_count
+  end
+
+
   #
   # Reload the result. This will:
   #
@@ -108,17 +116,17 @@ class RDBI::Result
     @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)
+    @affected_count = nil # recomputed on demand
 
     configure_rewindable
   end
 
   #
-  # Iterator for Enumerable methods. Yields a row at a time.
+  # Iterator for Enumerable methods.  Yields a row at a time as translated
+  # by the current +driver+.
   #
   def each
-    @data.each do |row|
+    while row = fetch(:next_row)
       yield(row)
     end
   end
@@ -154,6 +162,7 @@ class RDBI::Result
   #
   # Replace the Result Driver. See RDBI::Result's main docs and
   # RDBI::Result::Driver for more information on Result Drivers.
+  # Returns its receiver, permitting method chaining.
   #
   # You may pass:
   #
@@ -179,6 +188,7 @@ class RDBI::Result
     @data.rewindable_result = rr
     @driver       = driver_klass
     configure_driver(@driver, *args)
+    self
   end
 
   #
@@ -229,53 +239,51 @@ class RDBI::Result
       as(driver_klass, *args)
     end
 
-    @fetch_handle.fetch(row_count)
+    # fetch() has two significantly different return signatures:
+    #
+    # Returning a single row is nil upon EOF (:first, :last, inside #each)
+    # Returning a set of rows is [] upon EOF (all others)
+
+    raw, multiple_rows = case row_count
+                         when :first, :last, :next_row
+                           [@data.__send__(row_count), false]
+                         when :all, :rest
+                           [@data.__send__(row_count), true]
+                         else
+                           [@data.fetch(row_count), true]
+                         end
+
+    return @result_driver.format_multiple_rows(raw) if multiple_rows
+
+    @result_driver.format_single_row(raw) if raw
+
+    # else nil -- :first, :last or #each at EOF
   end
 
   #
-  # returns the first result in the set.
+  # Returns the first result in the set.  Note that this may force an
+  # advance of the underlying cursor for non-rewindable ResultSets.
   #
   def first
-    @data.first
+    fetch(:first)
   end
 
   #
-  # returns the last result in the set.
+  # Returns the last result in the set.  Note that this may exhaust the
+  # underlying cursor for non-rewindable ResultSets, as the driver advances
+  # to the end of the results to fetch the last row.
   #
   def last
-    @data.last
+    fetch(:last)
   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
-  end
-
-  #
-  # This call finishes the result and the RDBI::Statement handle, scheduling
-  # any unpreserved data for garbage collection.
+  # This call finishes the result, scheduling any unpreserved data for
+  # garbage collection.
   #
   def finish
-    @sth.finish
     @data.finish
     @data   = nil
     @sth    = nil
@@ -287,7 +295,7 @@ class RDBI::Result
   protected
 
   def configure_driver(driver_klass, *args)
-    @fetch_handle = driver_klass.new(self, *args)
+    @result_driver = driver_klass.new(self, *args)
   end
 
   def configure_rewindable
@@ -309,21 +317,21 @@ end
 # == Creating a Result Driver
 #
 # A result driver typically inherits from RDBI::Result::Driver and implements
-# at least one method: +fetch+.
+# at least two methods: +format_single_row+ and +format_multiple_rows+.
 #
-# 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.
+# +format_single_row+ is called with a single row fetched "raw" from the
+# underlying driver, that is, with an array of variously typed elements.  It
+# is never called with a nil argument.  +format_multiple_rows+ is called with
+# a possibly empty array of raw rows.
 #
-# 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>.
+# Note that +format_multiple_rows+ could be implemented in terms of
+# +format_single_row+.  However, for performance reasons it is not.
 #
-# If you wish to implement a constructor in your class, please see
-# RDBI::Result::Driver.new.
+# Base class RDBI::Result::Driver additionally provides the method
+# +convert_row+ to employ RDBI's type conversion facility (see RDBI::Type) for
+# converting "raw" data elements to convenient ruby types.  For performance
+# reasons, RDBI converts on request instead of preemptively, so <b>it is the
+# driver implementor's job to do any conversion</b>.
 #
 class RDBI::Result::Driver
 
@@ -336,48 +344,17 @@ class RDBI::Result::Driver
     @result = result
   end
 
-  #
-  # Fetch the result with any transformations. The default is to present the
-  # type converted array.
-  #
-  def fetch(row_count)
-    rows = RDBI::Util.format_results(row_count, (@result.raw_fetch(row_count) || []))
-
-    if rows.nil?
-      return rows 
-    elsif [:first, :last].include?(row_count)
-      return convert_row(rows)
-    else
-      result = []
-      rows.each do |row| 
-        result << convert_row(row)
-      end
-    end
-    return result
-  end
-
-  #
-  # Returns the first result in the set.
-  #
-  def first
-    return fetch(:first)
+  def format_single_row(raw)
+    convert_row(raw)
   end
 
-  #
-  # Returns the last result in the set.
-  #
-  # +Warning+: Depending on your database and drivers, calling this could have
-  # serious memory and performance implications!
-  #
-  def last
-    return fetch(:last)
+  def format_multiple_rows(raw_rows)
+    raw_rows.collect { |rr| convert_row(rr) }
   end
 
   protected
 
   def convert_row(row)
-    return [] if row.nil?
-    
     row.each_with_index do |x, i|
       row[i] = RDBI::Type::Out.convert(x, @result.schema.columns[i], @result.type_hash)
     end
@@ -418,12 +395,12 @@ class RDBI::Result::Driver::CSV < RDBI::Result::Driver
     # 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
+  def format_single_row(raw)
+    raw.to_csv
+  end
+
+  def format_multiple_rows(raw_rows)
+    raw_rows.inject("") do |accum, row| accum << row.to_csv end
   end
 end
 
@@ -444,28 +421,21 @@ class RDBI::Result::Driver::Struct < RDBI::Result::Driver
     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
+  def format_single_row(raw)
+    struct_klass.new(*super)
+  end
 
-    structs.collect! { |row| klass.new(*row) }
+  def format_multiple_rows(raw_rows)
+    super.collect { |row| struct_klass.new(*row) }
+  end
 
-    return RDBI::Util.format_results(row_count, structs)
+  private
+  def struct_klass
+    @struct_klass ||= ::Struct.new(*@result.schema.columns.map(&:name))
   end
 end
 
-# 
+#
 # Yields YAML representations of rows, each as an array keyed by the column
 # name (as symbol, not string).
 #
@@ -496,16 +466,17 @@ class RDBI::Result::Driver::YAML < RDBI::Result::Driver
     RDBI::Util.optional_require('yaml')
   end
 
-  def fetch(row_count)
-    column_names = @result.schema.columns.map(&:name)
+  def format_single_row(raw)
+    ::Hash[column_names.zip(raw)].to_yaml
+  end
 
-    if [:first, :last].include?(row_count)
-      Hash[column_names.zip(@result.raw_fetch(row_count)[0])].to_yaml
-    else
-      @result.raw_fetch(row_count).collect do |row|
-        Hash[column_names.zip(row)]
-      end.to_yaml
-    end
+  def format_multiple_rows(raw_rows)
+    raw_rows.collect { |row| ::Hash[column_names.zip(row)] }.to_yaml
+  end
+
+  private
+  def column_names
+    @column_names ||= @result.schema.columns.map(&:name)
   end
 end
 

data/lib/rdbi/schema.rb

@@ -13,7 +13,8 @@ RDBI::Column = Struct.new(
   :nullable,
   :metadata,
   :default,
-  :table
+  :table,
+  :primary_key
 )
 
 #
@@ -116,6 +117,12 @@ class RDBI::Column
   #
   # The table this column belongs to, if known, as symbol.
   #
+  
+  ##
+  # :attr_reader: primary_key
+  #
+  # Is this column a primary key?
+  #
 end
 
 # vim: syntax=ruby ts=2 et sw=2 sts=2

data/lib/rdbi/statement.rb

@@ -82,6 +82,9 @@
 # which itself is provided by the epoxy gem) is unkempt, SQL injection attacks
 # may be possible.
 #
+
+require 'weakref'
+
 class RDBI::Statement
   # the RDBI::Database handle that created this statement.
   attr_reader :dbh
@@ -140,9 +143,9 @@ class RDBI::Statement
     @dbh                   = dbh
     @finished              = false
     @input_type_map        = self.class.input_type_map
+    @finish_block          = nil
 
     self.rewindable_result = dbh.rewindable_result
-    @dbh.open_statements[self.object_id] = self
   end
 
   def prep_finalizer(&block)
@@ -162,9 +165,15 @@ class RDBI::Statement
 
     cursor, schema, type_map = new_execution(*binds)
     cursor.rewindable_result = self.rewindable_result
-    self.last_result = RDBI::Result.new(self, binds, cursor, schema, type_map)
+    r = RDBI::Result.new(self, binds, cursor, schema, type_map)
+    self.last_result = ::WeakRef.new(r)
+    r
   end
 
+  #
+  # Execute the statement with the supplied binds.  Intended for DDL and
+  # other statements which return no rows (e.g., INSERT, DELETE).
+  #
   def execute_modification(*binds)
     binds = pre_execute(*binds)
 
@@ -208,8 +217,18 @@ class RDBI::Statement
     raise NoMethodError, "this method is not implemented in this driver"
   end
 
+  ##
+  #
+  # Executes the statement, returning the number of rows affected.
+  #
+  # Database drivers may override this method in their +Statement+
+  # subclasses for efficiency.  This method is called when
+  # #execute_modification() is called for an RDBI::Statement or
+  # RDBI::Database object.
+  #
   def new_modification(*binds)
-    raise NoMethodError, "this method is not implemented in this driver"
+    cursor = new_execution(*binds)[0]
+    cursor.affected_count
   end
 
   protected