rdbi 0.9.0

data/lib/rdbi.rb

@@ -0,0 +1,189 @@
+require 'epoxy'
+require 'methlab'
+require 'thread'
+
+module RDBI
+  class << self
+    extend MethLab
+
+    # Every database handle allocated throughout the lifetime of the
+    # program. This functionality is subject to change and may be pruned
+    # during disconnection.
+    attr_reader :all_connections
+
+    #
+    # The last database handle allocated. This may come from pooled connections or regular ones.
+    #
+    attr_threaded_accessor :last_dbh
+  end
+
+  #
+  # connect() takes a class name, which may be represented as:
+  #
+  # * The full class name, such as RDBI::Driver::Mock
+  # * A symbol representing the significant portion, such as :Mock, which corresponds to RDBI::Driver::Mock
+  # * A string representing the same data as the symbol.
+  #
+  # Additionally, arguments that are passed on to the driver for consumption
+  # may be passed. Please refer to the driver documentation for more
+  # information.
+  #
+  # connect() returns an instance of RDBI::Database. In the instance a block
+  # is provided, it will be called upon connection success, with the
+  # RDBI::Database object provided in as the first argument.
+  def self.connect(klass, *args)
+
+    klass = RDBI::Util.class_from_class_or_symbol(klass, self::Driver)
+
+    driver = klass.new(*args)
+    dbh = self.last_dbh = driver.new_handle
+
+    @all_connections ||= []
+    @all_connections.push(dbh)
+
+    yield dbh if block_given?
+    return dbh
+  end
+
+  #
+  # connect_cached() works similarly to connect, but yields a database handle
+  # copied from a RDBI::Pool. The 'default' pool is the ... default, but this
+  # may be manipulated by providing :pool_name to the connection arguments.
+  #
+  # If a pool does not exist already, it will be created and a database
+  # handle instanced from your connection arguments.
+  #
+  # If a pool *already* exists, your connection arguments will be ignored and
+  # it will instance from the Pool's connection arguments.
+  def self.connect_cached(klass, *args)
+    args = args[0]
+    pool_name = args[:pool_name] || :default
+
+    dbh = nil
+
+    if RDBI::Pool[pool_name]
+      dbh = RDBI::Pool[pool_name].get_dbh
+    else
+      dbh = RDBI::Pool.new(pool_name, [klass, args]).get_dbh
+    end
+
+    self.last_dbh = dbh
+
+    yield dbh if block_given?
+    return dbh
+  end
+
+  #
+  # Retrieves a RDBI::Pool. See RDBI::Pool.[].
+  def self.pool(pool_name=:default)
+    RDBI::Pool[pool_name]
+  end
+
+  #
+  # Connects to and pings the database. Arguments are the same as for RDBI.connect.
+  def self.ping(klass, *args)
+    connect(klass, *args).ping
+  end
+
+  #
+  # Reconnects all known connections. See RDBI.all_connections.
+  def self.reconnect_all
+    @all_connections.each(&:reconnect)
+  end
+
+  #
+  # Disconnects all known connections. See RDBI.all_connections.
+  def self.disconnect_all
+    @all_connections.each(&:disconnect)
+  end
+
+  #
+  # Base Error class for RDBI. Rescue this to catch all RDBI-specific errors.
+  #
+  class Error < StandardError
+  end
+
+  #
+  # This error will be thrown if an operation is attempted while the database
+  # is disconnected.
+  #
+  class DisconnectedError < Error
+  end
+
+  #
+  # This error will be thrown if an operation is attempted that violated
+  # transaction semantics.
+  #
+  class TransactionError < Error
+  end
+end
+
+#
+# RDBI::Util is a set of utility methods used internally. It is not geared for
+# public consumption.
+#
+module RDBI::Util
+  #
+  # Requires with a LoadError check and emits a friendly "please install me"
+  # message.
+  #
+  def self.optional_require(lib)
+    require lib
+  rescue LoadError => e
+    raise LoadError, "The '#{lib}' gem is required to use this driver. Please install it."
+  end
+
+  #
+  # This is the loading logic we use to import drivers of various natures.
+  #
+  def self.class_from_class_or_symbol(klass, namespace)
+    klass.kind_of?(Class) ? klass : namespace.const_get(klass.to_s)
+  rescue
+    raise ArgumentError, "Invalid argument for driver name; must be Class, or a Symbol or String identifying the Class, and the driver Class must have been loaded"
+  end
+
+  #
+  # Rekey a string-keyed hash with equivalent symbols.
+  #
+  def self.key_hash_as_symbols(hash)
+    return nil unless hash
+
+    Hash[hash.map { |k,v| [k.to_sym, v] }]
+  end
+
+  #
+  # Copy an object and all of its descendants to form a new tree
+  #
+  def self.deep_copy(obj)
+    Marshal.load(Marshal.dump(obj))
+  end
+
+  #
+  # Takes an array and appropriate boxes/deboxes it based on what was
+  # requested.
+  #
+  #--
+  # FIXME this is a really poorly performing way of doing this.
+  #++
+  def self.format_results(row_count, ary)
+    case row_count
+    when :first, :last
+      ary = ary[0]
+      return nil if ary.empty?
+      return ary
+    else
+      return ary
+    end
+  end
+end
+
+require 'rdbi/pool'
+require 'rdbi/driver'
+require 'rdbi/database'
+require 'rdbi/statement'
+require 'rdbi/schema'
+require 'rdbi/result'
+require 'rdbi/cursor'
+require 'rdbi/types'
+
+# vim: syntax=ruby ts=2 et sw=2 sts=2

data/lib/rdbi/cursor.rb

@@ -0,0 +1,90 @@
+#
+# RDBI::Cursor is a method of abstractly encapsulating result handles that we
+# get back from databases. It has a consistent interface and therefore can be
+# used by RDBI::Result and its drivers.
+#
+# Drivers should make a whole-hearted attempt to do iterative fetching instead
+# of array fetching.. this will perform much better for larger results.
+#
+# RDBI::Cursor is largely an abstract class and will error if methods are not
+# implemented in an inheriting class. Please read the individual method
+# documentation for what each call should yield.
+#
+class RDBI::Cursor
+  #
+  # Exception which indicates that the inheriting class has not implemented
+  # these interface calls.
+  #
+  class NotImplementedError < Exception; end
+
+  extend MethLab
+  include Enumerable
+
+  # underlying handle.
+  
+  attr_reader :handle
+
+  # Default constructor. Feel free to override this.
+  #
+  def initialize(handle)
+    @handle = handle
+  end
+
+ 
+  # Returns the next row in the result.
+  def next_row; raise NotImplementedError, 'Subclasses must implement this method'; end
+
+  # Returns the count of rows that exist in this result.
+  def result_count; raise NotImplementedError, 'Subclasses must implement this method'; end
+
+  # Returns the number of affected rows (DML) in this result.
+  def affected_count; raise NotImplementedError, 'Subclasses must implement this method'; end
+
+  # Returns the first tuple in the result.
+  def first; raise NotImplementedError, 'Subclasses must implement this method'; end
+ 
+  # Returns the last tuple in the result.
+  def last; raise NotImplementedError, 'Subclasses must implement this method'; end
+ 
+  # Returns the items that have not been fetched yet in this result. Equivalent
+  # to all() if the fetched count is zero.
+  def rest; raise NotImplementedError, 'Subclasses must implement this method'; end
+
+  # Returns all the tuples.
+  def all; raise NotImplementedError, 'Subclasses must implement this method'; end
+
+  # Fetches +count+ tuples from the result and returns them.
+  def fetch(count=1); raise NotImplementedError, 'Subclasses must implement this method'; end
+
+  # Fetches the tuple at position +index+.
+  def [](index); raise NotImplementedError, 'Subclasses must implement this method'; end
+
+  # Are we on the last row?
+  def last_row?; raise NotImplementedError, 'Subclasses must implement this method'; end
+
+  # Is this result empty?
+  def empty?; raise NotImplementedError, 'Subclasses must implement this method'; end
+
+  # rewind the result to start again from the top.
+  def rewind; raise NotImplementedError, 'Subclasses must implement this method'; end
+
+  # See result_count().
+  def size
+    result_count
+  end
+
+  # Finish this cursor and schedule it for termination. 
+  def finish
+  end
+
+  # If your result handles cannot support operation disconnected from the
+  # statement, you will want to implement this method to fetch all values in
+  # certain situations.
+  def coerce_to_array
+  end
+
+  # Enumerable helper. Iterate over each item and yield it to a block.
+  def each
+    yield next_row until last_row? 
+  end
+end

data/lib/rdbi/database.rb

@@ -0,0 +1,262 @@
+#
+# RDBI::Database is the base class for database handles. This is the primary
+# method in which most users will access their database system.
+#
+# To execute statements, look at +prepare+ and +execute+.
+#
+# To retrieve schema information, look at +schema+ and +table_schema+.
+#
+# To deal with transactions, +transaction+, +commit+, and +rollback+.
+class RDBI::Database
+  extend MethLab
+
+  # the driver class that is responsible for creating this database handle.
+  attr_accessor :driver
+
+  # the name of the database we're connected to, if any.
+  attr_accessor :database_name
+
+  # the arguments used to create the connection.
+  attr_reader :connect_args
+
+  ##
+  # :attr_reader: last_statement
+  #
+  # the last statement handle allocated. affected by +prepare+ and +execute+.
+  attr_threaded_accessor :last_statement
+
+  ##
+  # :attr: last_query
+  # the last query sent, as a string.
+  attr_threaded_accessor :last_query
+
+  ##
+  # :attr: open_statements
+  # all the open statement handles.
+  attr_threaded_accessor :open_statements
+
+  ##
+  # :attr: in_transaction
+  # are we currently in a transaction?
+  
+  ##
+  # :attr: in_transaction?
+  # are we currently in a transaction?
+  inline(:in_transaction, :in_transaction?) { @in_transaction > 0 }
+
+  # the mutex for this database handle.
+  attr_reader :mutex
+
+  ##
+  # :attr: connected
+  # are we connected to the database?
+  
+  ##
+  # :attr_accessor: connected?
+  # are we connected to the database?
+  inline(:connected, :connected?) { @connected }
+
+  ##
+  # :method: ping
+  # ping the database. yield an integer result on success.
+  inline(:ping) { raise NoMethodError, "this method is not implemented in this driver" }
+
+  ##
+  # :method: table_schema
+  # query the schema for a specific table. Returns a RDBI::Schema object.
+  inline(:table_schema) { |*args| raise NoMethodError, "this method is not implemented in this driver" }
+
+  ##
+  # :method: schema
+  # query the schema for the entire database. Returns an array of RDBI::Schema objects.
+  inline(:schema) { |*args| raise NoMethodError, "this method is not implemented in this driver" }
+
+  ##
+  # :method: rollback
+  # ends the outstanding transaction and rolls the affected rows back.
+  inline(:rollback) { @in_transaction -= 1 unless @in_transaction == 0 }
+ 
+  ##
+  # :method: commit
+  # ends the outstanding transaction and commits the result.
+  inline(:commit)   { @in_transaction -= 1 unless @in_transaction == 0 }
+
+  #
+  # Create a new database handle. This is typically done by a driver and
+  # likely shouldn't be done directly.
+  #
+  # args is the connection arguments the user initially supplied to
+  # RDBI.connect.
+  def initialize(*args)
+    @connect_args   = RDBI::Util.key_hash_as_symbols(args[0])
+    @connected      = true
+    @mutex          = Mutex.new
+    @in_transaction = 0
+    self.open_statements = []
+  end
+
+  # reconnect to the database. Any outstanding connection will be terminated.
+  def reconnect
+    disconnect rescue nil
+    @connected = true
+  end
+
+  #
+  # disconnects from the database: will close (and complain, loudly) any
+  # statement handles left open.
+  #
+  def disconnect
+    unless self.open_statements.empty?
+      warn "[RDBI] Open statements during disconnection -- automatically finishing. You should fix this."
+      self.open_statements.each(&:finish)
+    end
+    self.open_statements = []
+    @connected = false
+  end
+
+  #
+  # Open a new transaction for processing. Accepts a block which will execute
+  # the portions during the transaction.
+  #
+  # Example:
+  #
+  #   dbh.transaction do |dbh|
+  #       dbh.execute("some query")
+  #       dbh.execute("some other query")
+  #       raise "oh crap!" # would rollback
+  #       dbh.commit # commits
+  #       dbh.rollback # rolls back
+  #   end
+  #
+  #   # at this point, if no raise or commit/rollback was triggered, it would
+  #   # commit.
+  #
+  # Any exception that isn't caught within this block will trigger a
+  # rollback. Additionally, you may use +commit+ and +rollback+ directly
+  # within the block to terminate the transaction early -- at which point
+  # *the transaction is over with and you may be in autocommit*. The
+  # RDBI::Database accessor +in_transaction+ exists to tell you if RDBI
+  # thinks its in a transaction or not.
+  #
+  # If you do not +commit+ or +rollback+ within the block and no exception is
+  # raised, RDBI presumes you wish this transaction to succeed and commits
+  # for you.
+  #
+  def transaction(&block)
+    @in_transaction += 1
+    begin
+      yield self
+      self.commit if @in_transaction > 0
+    rescue => e
+      self.rollback
+      raise e
+    ensure
+      @in_transaction -= 1 unless @in_transaction == 0
+    end
+  end
+
+  #
+  # Prepares a statement for execution. Takes a query as its only argument,
+  # returns a RDBI::Statement.
+  #
+  # ex:
+  #   sth = dbh.prepare("select * from foo where item = ?")
+  #   res = sth.execute("an item")
+  #   ary = res.to_a
+  #   sth.finish
+  #
+  # You can also use a block form which will auto-finish:
+  #   dbh.prepare("select * from foo where item = ?") do |sth|
+  #     sth.execute("an item")
+  #   end
+  #
+  def prepare(query)
+    sth = nil
+    mutex.synchronize do
+      self.last_query = query
+      sth = new_statement(query)
+      yield sth if block_given?
+      sth.finish if block_given?
+    end
+
+    return self.last_statement = sth
+  end
+
+  #
+  # Prepares and executes a statement. Takes a string query and an optional
+  # number of variable type binds.
+  #
+  # ex:
+  #   res = dbh.execute("select * from foo where item = ?", "an item")
+  #   ary = res.to_a
+  #
+  # You can also use a block form which will finish the statement and yield the
+  # result handle:
+  #   dbh.execute("select * from foo where item = ?", "an item") do |res|
+  #     res.as(:Struct).fetch(:all).each do |struct|
+  #       p struct.item
+  #     end
+  #   end
+  #
+  # Which will be considerably more performant under some database drivers.
+  #
+  def execute(query, *binds)
+    res = nil
+
+    mutex.synchronize do
+      self.last_query = query
+      self.last_statement = sth = new_statement(query)
+      res = sth.execute(*binds)
+
+      if block_given?
+        yield res
+      else
+        res.coerce_to_array
+      end
+
+      sth.finish
+    end
+
+    return res
+  end
+
+  #
+  # Process the query as your driver would normally, and return the result.
+  # Depending on the driver implementation and potentially connection
+  # settings, this may include interpolated data or client binding
+  # placeholders.
+  #
+  # <b>Driver Authors</b>: if the instance variable @preprocess_quoter is set
+  # to a proc that accepts an index/key, a map of named binds and an array of
+  # indexed binds, it will be called instead of the default quoter and there is
+  # no need to override this method. For example:
+  #
+  #   def initialize(...)
+  #     @preprocess_quoter = proc do |x, named, indexed|
+  #       @some_handle.quote((named[x] || indexed[x]).to_s)
+  #     end
+  #   end
+  #
+  # This will use RDBI's code to manage the binds before quoting, but use your
+  # quoter during bind processing.
+  #
+  def preprocess_query(query, *binds)
+    mutex.synchronize do
+      self.last_query = query
+    end
+   
+    ep = Epoxy.new(query)
+
+    hashes = binds.select { |x| x.kind_of?(Hash) }
+    binds.collect! { |x| x.kind_of?(Hash) ? nil : x } 
+    total_hash = hashes.inject({}) { |x, y| x.merge(y) }
+
+    if @preprocess_quoter.respond_to?(:call)
+      ep.quote(total_hash) { |x| @preprocess_quoter.call(x, total_hash, binds) }
+    else
+      ep.quote(total_hash) { |x| %Q{'#{(total_hash[x] || binds[x]).to_s.gsub(/'/, "''")}'} }
+    end
+  end
+end
+
+# vim: syntax=ruby ts=2 et sw=2 sts=2