dbi 0.4.0

data/lib/dbi/exceptions.rb

@@ -0,0 +1,65 @@
+module DBI
+    #  Exceptions (borrowed by Python API 2.0)
+
+    # Base class of all other error exceptions.  Use this to catch all DBI
+    # errors.
+    class Error < RuntimeError
+    end
+
+    # For important warnings like data truncation, etc.
+    class Warning < RuntimeError
+    end
+
+    # Exception for errors related to the DBI interface rather than the
+    # database itself.
+    class InterfaceError < Error
+    end
+
+    # Exception raised if the DBD driver has not specified a mandatory method.
+    class NotImplementedError < InterfaceError
+    end
+
+    # Exception for errors related to the database.
+    class DatabaseError < Error
+        attr_reader :err, :errstr, :state
+
+        def initialize(errstr="", err=nil, state=nil)
+            super(errstr)
+            @err, @errstr, @state = err, errstr, state
+        end
+    end
+
+    # Exception for errors due to problems with the processed 
+    # data such as division by zero, numeric value out of range, etc.
+    class DataError < DatabaseError
+    end
+
+    # Exception for errors related to the database's operation which are not
+    # necessarily under the control of the programmer.  This includes such
+    # things as unexpected disconnect, datasource name not found, transaction
+    # could not be processed, a memory allocation error occured during
+    # processing, etc.
+    class OperationalError < DatabaseError
+    end
+
+    # Exception raised when the relational integrity of the database
+    # is affected, e.g. a foreign key check fails.
+    class IntegrityError < DatabaseError
+    end
+
+    # Exception raised when the database encounters an internal error, 
+    # e.g. the cursor is not valid anymore, the transaction is out of sync.
+    class InternalError < DatabaseError
+    end
+
+    # Exception raised for programming errors, e.g. table not found
+    # or already exists, syntax error in SQL statement, wrong number
+    # of parameters specified, etc.
+    class ProgrammingError < DatabaseError
+    end
+
+    # Exception raised if e.g. commit() is called for a database which do not
+    # support transactions.
+    class NotSupportedError < DatabaseError
+    end
+end

data/lib/dbi/handles.rb

@@ -0,0 +1,49 @@
+#
+# Dispatch classes (Handle, DriverHandle, DatabaseHandle and StatementHandle)
+#
+
+module DBI
+    #
+    # Base class for all handles.
+    #
+    class Handle
+        attr_reader :trace_mode, :trace_output
+        attr_reader :handle 
+        attr :convert_types, true
+
+        def initialize(handle, convert_types=true)
+            @handle = handle
+            @trace_mode = @trace_output = nil
+            @convert_types = convert_types
+        end
+
+        # Please seee DBI.trace.
+        def trace(mode=nil, output=nil)
+            # FIXME trace
+            raise InterfaceError, "the trace module has been removed until it actually works."
+            @trace_mode   = mode   || @trace_mode   || DBI::DEFAULT_TRACE_MODE
+            @trace_output = output || @trace_output || DBI::DEFAULT_TRACE_OUTPUT
+        end
+
+        #
+        # Leverage a driver-specific method. The method name will have "__"
+        # prepended to them before calling, and the DBD must define them as
+        # such for them to work.
+        #
+        def func(function, *values)
+            if @handle.respond_to?("__" + function.to_s) then
+                @handle.send("__" + function.to_s, *values)  
+            else
+                raise InterfaceError, "Driver specific function <#{function}> not available."
+            end
+        rescue ArgumentError
+            raise InterfaceError, "Wrong # of arguments for driver specific function"
+        end
+
+        # error functions?
+    end
+end
+
+require 'dbi/handles/driver'
+require 'dbi/handles/database'
+require 'dbi/handles/statement'

data/lib/dbi/handles/database.rb

@@ -0,0 +1,211 @@
+module DBI
+    # DatabaseHandle is the interface the consumer sees after connecting to the
+    # database via DBI.connect.
+    #
+    # It is strongly discouraged that DBDs inherit from this class directly;
+    # please inherit from the DBI::BaseDatabase instead.
+    #
+    # Note: almost all methods in this class will raise InterfaceError if the
+    # database is not connected.
+    class DatabaseHandle < Handle
+        # This is the driver name as supplied by the DBD's driver_name method.
+        # Its primary utility is in DBI::TypeUtil#convert.
+        def driver_name
+            return @driver_name.dup if @driver_name
+            return nil
+        end
+
+        # Assign the driver name. This can be leveraged to create custom type
+        # management via DBI::TypeUtil#convert.
+        def driver_name=(name)
+            @driver_name = name
+            @driver_name.freeze
+        end
+
+        #
+        # Boolean if we are still connected to the database. See #ping.
+        #
+        def connected?
+            not @handle.nil?
+        end
+
+        #
+        # Disconnect from the database. Will raise InterfaceError if this was
+        # already done prior.
+        #
+        def disconnect
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            @handle.disconnect
+            @handle = nil
+        end
+
+        #
+        # Prepare a StatementHandle and return it. If given a block, it will
+        # supply that StatementHandle as the first argument to the block, and
+        # BaseStatement#finish it when the block is done executing.
+        #
+        def prepare(stmt)
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            sth = StatementHandle.new(@handle.prepare(stmt), false, true, @convert_types)
+            # FIXME trace sth.trace(@trace_mode, @trace_output)
+            sth.dbh = self
+
+            if block_given?
+                begin
+                    yield sth
+                ensure
+                    sth.finish unless sth.finished?
+                end
+            else
+                return sth
+            end 
+        end
+
+        #
+        # Prepare and execute a statement. It has block semantics equivalent to #prepare.
+        #
+        def execute(stmt, *bindvars)
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+
+            if @convert_types
+                bindvars = DBI::Utils::ConvParam.conv_param(driver_name, *bindvars)
+            end
+
+            sth = StatementHandle.new(@handle.execute(stmt, *bindvars), true, false, @convert_types)
+            # FIXME trace sth.trace(@trace_mode, @trace_output)
+            sth.dbh = self
+
+            if block_given?
+                begin
+                    yield sth
+                ensure
+                    sth.finish unless sth.finished?
+                end
+            else
+                return sth
+            end 
+        end
+
+        #
+        # Perform a statement. This goes straight to the DBD's implementation
+        # of #do (and consequently, BaseDatabase#do), and does not work like
+        # #execute and #prepare. Should return a row modified count.
+        #
+        def do(stmt, *bindvars)
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            @handle.do(stmt, *DBI::Utils::ConvParam.conv_param(driver_name, *bindvars))
+        end
+
+        #
+        # Executes a statement and returns the first row from the result.
+        #
+        def select_one(stmt, *bindvars)
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            row = nil
+            execute(stmt, *bindvars) do |sth|
+                row = sth.fetch 
+            end
+            row
+        end
+
+        #
+        # Executes a statement and returns all rows from the result. If a block
+        # is given, it is executed for each row.
+        # 
+        def select_all(stmt, *bindvars, &p)
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            rows = nil
+            execute(stmt, *bindvars) do |sth|
+                if block_given?
+                    sth.each(&p)
+                else
+                    rows = sth.fetch_all 
+                end
+            end
+            return rows
+        end
+
+        #
+        # Return the tables available to this DatabaseHandle as an array of strings.
+        #
+        def tables
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            @handle.tables
+        end
+
+        #
+        # Returns the columns of the provided table as an array of ColumnInfo
+        # objects. See BaseDatabase#columns for the minimum parameters that
+        # this method must provide.
+        #
+        def columns( table )
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            @handle.columns( table ).collect {|col| ColumnInfo.new(col) }
+        end
+
+        #
+        # Attempt to establish if the database is still connected. While
+        # #connected? returns the state the DatabaseHandle thinks is true, this
+        # is an active operation that will contact the database.
+        #
+        def ping
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            @handle.ping
+        end
+
+        #
+        # Attempt to escape the value, rendering it suitable for inclusion in a SQL statement.
+        #
+        def quote(value)
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            @handle.quote(value)
+        end
+
+        #
+        # Force a commit to the database immediately.
+        #
+        def commit
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            @handle.commit
+        end
+
+        #
+        # Force a rollback to the database immediately.
+        #
+        def rollback
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            @handle.rollback
+        end
+
+        #
+        # Commits, runs the block provided, yielding the DatabaseHandle as it's
+        # argument. If an exception is raised through the block, rollback occurs.
+        # Otherwise, commit occurs.
+        #
+        def transaction
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            raise InterfaceError, "No block given" unless block_given?
+
+            commit
+            begin
+                yield self
+                commit
+            rescue Exception
+                rollback
+                raise
+            end
+        end
+
+        # Get an attribute from the DatabaseHandle.
+        def [] (attr)
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            @handle[attr]
+        end
+
+        # Set an attribute on the DatabaseHandle.
+        def []= (attr, val)
+            raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+            @handle[attr] = val
+        end
+    end
+end

data/lib/dbi/handles/driver.rb

@@ -0,0 +1,60 @@
+module DBI
+    # DriverHandles, while not directly exposed, are essentially the backend
+    # for the facade that many DBI root-level methods communicate with.
+    class DriverHandle < Handle
+
+        attr_writer :driver_name
+
+        # Connect to the database. The DSN will have been parsed at this point
+        # and the named parameters should need no explanation.
+        #
+        # If a block is provided to DBI.connect, the connected DatabaseHandle
+        # will be provided as the first argument to the block, and the
+        # DatabaseHandle will be disconnected upon block exit.
+        #
+        def connect(db_args, user, auth, params)
+
+            user = @handle.default_user[0] if user.nil?
+            auth = @handle.default_user[1] if auth.nil?
+
+            # TODO: what if only one of them is nil?
+            #if user.nil? and auth.nil? then
+            #  user, auth = @handle.default_user
+            #end
+
+            params ||= {}
+            new_params = @handle.default_attributes
+            params.each {|k,v| new_params[k] = v} 
+
+            if params.has_key?(:_convert_types)
+                @convert_types = params[:_convert_types]
+            end
+
+            db = @handle.connect(db_args, user, auth, new_params)
+            dbh = DatabaseHandle.new(db, @convert_types)
+            # FIXME trace
+            # dbh.trace(@trace_mode, @trace_output)
+            dbh.driver_name = @driver_name
+
+            if block_given?
+                begin
+                    yield dbh
+                ensure  
+                    dbh.disconnect if dbh.connected?
+                end  
+            else
+                return dbh
+            end
+        end
+
+        # See BaseDriver#data_sources.
+        def data_sources
+            @handle.data_sources
+        end
+
+        # See BaseDriver#disconnect_all.
+        def disconnect_all
+            @handle.disconnect_all
+        end
+    end
+end

data/lib/dbi/handles/statement.rb

@@ -0,0 +1,375 @@
+module DBI
+    #
+    # StatementHandle is the interface the consumer sees after successfully
+    # issuing a DatabaseHandle#prepare. They may also be exposed through other
+    # methods that send statements to the database.
+    #
+    # Almost all methods in this class will raise InterfaceError if the
+    # statement is already finished.
+    #
+    class StatementHandle < Handle
+
+        include Enumerable
+
+        attr_accessor :dbh
+
+        def initialize(handle, fetchable=false, prepared=true, convert_types=true)
+            super(handle)
+            @fetchable = fetchable
+            @prepared  = prepared     # only false if immediate execute was used
+            @cols = nil
+            @coltypes = nil
+            @convert_types = convert_types
+
+            if @fetchable
+                @row = DBI::Row.new(column_names, column_types, nil, @convert_types)
+            else
+                @row = nil
+            end
+        end
+
+        # Returns true if the StatementHandle has had #finish called on it,
+        # explicitly or otherwise.
+        def finished?
+            @handle.nil?
+        end
+
+        # Returns true if the statement is believed to return data upon #fetch.
+        #
+        # The current reliability of this (and the concept in general) is
+        # suspect.
+        def fetchable?
+            @fetchable
+        end
+
+        #
+        # Instruct successive calls to #fetch to cast the type returned into
+        # `type`, for row position `pos`. Like all bind_* calls, `pos` indexes
+        # starting at 1.
+        #
+        # `type` is an object with the DBI::Type calling convention.
+        #
+        # This call must be called after #execute has successfully ran,
+        # otherwise it will raise InterfaceError.
+        #
+        # Example:
+        #  # `foo` is an integer and this statement will return two rows. 
+        #  sth = dbh.prepare("select foo from bar") 
+        #  # would raise InterfaceError if called here
+        #  sth.execute
+        #
+        #  sth.bind_coltype(1, DBI::Type::Varchar) 
+        #  # would normally use DBI::Type::Integer and return a Fixnum. We'll make it a string.
+        #  sth.fetch => ["1"]
+        #
+        #  # Here we coerce it to Float.
+        #  sth.bind_coltype(1, DBI::Type::Float)
+        #  sth.fetch => [1.0]
+        #  sth.finish
+        #
+        def bind_coltype(pos, type)
+            raise InterfaceError, "statement must be executed before using this command" unless @executed
+
+            coltypes = column_types
+
+            if (pos - 1) < 1
+                raise InterfaceError, "bind positions index starting at 1"
+            end
+
+            coltypes[pos-1] = type
+            @row = DBI::Row.new(column_names, coltypes, nil, @convert_types)
+        end
+
+        #
+        # Just like BaseStatement#bind_param, but will attempt to convert the
+        # type if it's supposed to, adhering to the DBD's current ruleset.
+        #
+        def bind_param(param, value, attribs=nil)
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            raise InterfaceError, "Statement wasn't prepared before." unless @prepared
+
+            if @convert_types
+                value = DBI::Utils::ConvParam.conv_param(dbh.driver_name, value)[0]
+            end
+
+            @handle.bind_param(param, value, attribs)
+        end
+
+
+        # Execute the statement.
+        #
+        # This generally means that the statement will be sent to the database
+        # and some form of result cursor will be obtained, but is ultimately
+        # driver-dependent.
+        #
+        # If arguments are supplied, these are fed to #bind_param.
+        def execute(*bindvars)
+            cancel     # cancel before 
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            raise InterfaceError, "Statement wasn't prepared before." unless @prepared
+
+            if @convert_types
+                bindvars = DBI::Utils::ConvParam.conv_param(dbh.driver_name, *bindvars)
+            end
+
+            @handle.bind_params(*bindvars)
+            @handle.execute
+            @fetchable = true
+            @executed = true
+
+            # TODO:?
+            #if @row.nil?
+            @row = DBI::Row.new(column_names, column_types, nil, @convert_types)
+            #end
+            return nil
+        end
+
+        #
+        # Finish the statement, causing the database to release all assets
+        # related to it (any result cursors, normally).
+        #
+        # StatementHandles that have already been finished will normally be
+        # inoperable and unavailable for further use.
+        #
+        def finish
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            @handle.finish
+            @handle = nil
+        end
+
+        #
+        # Cancel the query, closing any open result cursors and truncating any result sets.
+        #
+        # The difference between this and #finish is that cancelled statements
+        # may be re-executed.
+        #
+        def cancel
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            @handle.cancel if @fetchable
+            @fetchable = false
+        end
+
+        #
+        # Obtains the column names for this query as an array.
+        #
+        def column_names
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            return @cols unless @cols.nil?
+            @cols = @handle.column_info.collect {|col| col['name'] }
+        end
+
+        #
+        # Obtain the type mappings for the columns in this query based on
+        # ColumnInfo data on the query.
+        #
+        # The result will be a position-dependent array of objects that conform
+        # to the DBI::Type calling syntax.
+        #
+        def column_types
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            return @coltypes unless @coltypes.nil?
+            @coltypes = @handle.column_info.collect do |col| 
+                if col['dbi_type']
+                    col['dbi_type']
+                else
+                    DBI::TypeUtil.type_name_to_module(col['type_name'])
+                end
+            end
+        end
+
+        #
+        # See BaseStatement#column_info.
+        #
+        def column_info
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            @handle.column_info.collect {|col| ColumnInfo.new(col) }
+        end
+
+        #
+        # Should return the row modified count as the result of statement execution.
+        #
+        # However, some low-level drivers do not supply this information or
+        # supply misleading information (> 0 rows for read-only select
+        # statements, f.e.)
+        #
+        def rows
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            @handle.rows
+        end
+
+
+        #
+        # See BaseStatement#fetch.
+        #
+        # fetch can also take a block which will be applied to each row in a
+        # similar fashion to Enumerable#collect. See #each.
+        #
+        def fetch(&p)
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+
+            if block_given? 
+                while (res = @handle.fetch) != nil
+                    @row = @row.dup
+                    @row.set_values(res)
+                    yield @row
+                end
+                @handle.cancel
+                @fetchable = false
+                return nil
+            else
+                res = @handle.fetch
+                if res.nil?
+                    @handle.cancel
+                    @fetchable = false
+                else
+                    @row = @row.dup
+                    @row.set_values(res)
+                    res = @row
+                end
+                return res
+            end
+        end
+
+        #
+        # Synonym for #fetch with a block.
+        #
+        def each(&p)
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            raise InterfaceError, "Statement must first be executed" unless @fetchable
+            raise InterfaceError, "No block given" unless block_given?
+
+            fetch(&p)
+        end
+
+        #
+        # Similar to #fetch, but returns Array of Array instead of Array of
+        # DBI::Row objects (and therefore does not perform type mapping). This
+        # is basically a way to get the raw data from the DBD.
+        #
+        def fetch_array
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            raise InterfaceError, "Statement must first be executed" unless @fetchable
+
+            if block_given? 
+                while (res = @handle.fetch) != nil
+                    yield res
+                end
+                @handle.cancel
+                @fetchable = false
+                return nil
+            else
+                res = @handle.fetch
+                if res.nil?
+                    @handle.cancel
+                    @fetchable = false
+                end
+                return res
+            end
+        end
+
+        #
+        # Map the columns and results into an Array of Hash resultset.
+        #
+        # No type conversion is performed here. Expect this to change in 0.6.0.
+        #
+        def fetch_hash
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            raise InterfaceError, "Statement must first be executed" unless @fetchable
+
+            cols = column_names
+
+            if block_given? 
+                while (row = @handle.fetch) != nil
+                    hash = {}
+                    row.each_with_index {|v,i| hash[cols[i]] = v} 
+                    yield hash
+                end
+                @handle.cancel
+                @fetchable = false
+                return nil
+            else
+                row = @handle.fetch
+                if row.nil?
+                    @handle.cancel
+                    @fetchable = false
+                    return nil
+                else
+                    hash = {}
+                    row.each_with_index {|v,i| hash[cols[i]] = v} 
+                    return hash
+                end
+            end
+        end
+
+        #
+        # Fetch `cnt` rows. Result is array of DBI::Row
+        #
+        def fetch_many(cnt)
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            raise InterfaceError, "Statement must first be executed" unless @fetchable
+
+            cols = column_names
+            rows = @handle.fetch_many(cnt)
+            if rows.nil?
+                @handle.cancel
+                @fetchable = false
+                return []
+            else
+                return rows.collect{|r| tmp = @row.dup; tmp.set_values(r); tmp }
+            end
+        end
+
+        # 
+        # Fetch the entire result set. Result is array of DBI::Row.
+        #
+        def fetch_all
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            raise InterfaceError, "Statement must first be executed" unless @fetchable
+
+            cols = column_names
+            fetched_rows = []
+
+            begin
+                while row = fetch do
+                    fetched_rows.push(row)
+                end
+            rescue Exception
+            end
+
+            @handle.cancel
+            @fetchable = false
+
+            return fetched_rows
+        end
+
+        #
+        # See BaseStatement#fetch_scroll.
+        #
+        def fetch_scroll(direction, offset=1)
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            raise InterfaceError, "Statement must first be executed" unless @fetchable
+
+            row = @handle.fetch_scroll(direction, offset)
+            if row.nil?
+                #@handle.cancel
+                #@fetchable = false
+                return nil
+            else
+                @row.set_values(row)
+                return @row
+            end
+        end
+
+        # Get an attribute from the StatementHandle object.
+        def [] (attr)
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            @handle[attr]
+        end
+
+        # Set an attribute on the StatementHandle object.
+        def []= (attr, val)
+            raise InterfaceError, "Statement was already closed!" if @handle.nil?
+            @handle[attr] = val
+        end
+    end # class StatementHandle
+end