ironruby-dbi 0.1.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,229 @@
+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
+
+    attr_accessor :raise_error
+
+    # 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
+      sanity_check
+      @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)
+      sanity_check(stmt)
+      sth = StatementHandle.new(@handle.prepare(stmt), false, true, @convert_types)
+      # FIXME trace sth.trace(@trace_mode, @trace_output)
+      sth.dbh = self
+      sth.raise_error = raise_error
+
+      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={})
+      sanity_check(stmt)
+
+      if @convert_types
+        bindvars = DBI::Utils::ConvParam.conv_param(driver_name, bindvars)
+      end
+
+      sth = StatementHandle.new(@handle.execute(stmt, bindvars), true, true, @convert_types, true)
+      # FIXME trace sth.trace(@trace_mode, @trace_output)
+      sth.dbh = self
+      sth.raise_error = raise_error
+
+      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={})
+      sanity_check(stmt)
+      @handle.do(stmt, bindvars)
+      #@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={})
+      sanity_check(stmt)
+      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)
+      sanity_check(stmt)
+      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
+      sanity_check
+      @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 )
+      sanity_check
+      @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
+      sanity_check
+      @handle.ping
+    end
+
+    #
+    # Attempt to escape the value, rendering it suitable for inclusion in a SQL statement.
+    #
+    def quote(value)
+      sanity_check
+      @handle.quote(value)
+    end
+
+    #
+    # Force a commit to the database immediately.
+    #
+    def commit
+      sanity_check
+      @handle.commit
+    end
+
+    #
+    # Force a rollback to the database immediately.
+    #
+    def rollback
+      sanity_check
+      @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
+      sanity_check
+      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)
+      sanity_check
+      @handle[attr]
+    end
+
+    # Set an attribute on the DatabaseHandle.
+    def []= (attr, val)
+      sanity_check
+      @handle[attr] = val
+    end
+
+    protected
+
+    def sanity_check(stmt=nil)
+      raise InterfaceError, "Database connection was already closed!" if @handle.nil?
+      check_statement(stmt) if stmt
+    end
+
+    # basic sanity checks for statements
+    def check_statement(stmt)
+      raise InterfaceError, "Statement is empty, or contains nothing but whitespace" if stmt !~ /\S/
+    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,408 @@
+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
+    attr_accessor :raise_error
+
+    def initialize(handle, fetchable=false, prepared=true, convert_types=true, executed=false)
+      super(handle)
+      @fetchable = fetchable
+      @prepared  = prepared     # only false if immediate execute was used
+      @executed  = executed     # only true if the statement was already executed.
+      @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)
+      sanity_check({:prepared => true, :executed => true})
+
+      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)
+      sanity_check({ :prepared => true })
+
+      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
+      sanity_check({:prepared => true })
+
+      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
+      sanity_check
+      @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
+      sanity_check
+      @handle.cancel if @fetchable
+      @fetchable = false
+    end
+
+    #
+    # Obtains the column names for this query as an array.
+    #
+    def column_names
+      sanity_check
+      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
+      sanity_check
+      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
+      sanity_check
+      @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
+      sanity_check
+      @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)
+      sanity_check({ :fetchable => true, :prepared => true, :executed => true })
+
+      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)
+      sanity_check({:fetchable => true, :prepared => true, :executed => true})
+      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
+      sanity_check({:fetchable => true, :prepared => true, :executed => true})
+
+      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
+      sanity_check({:fetchable => true, :prepared => true, :executed => true})
+
+      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)
+      sanity_check({:fetchable => true, :prepared => true, :executed => true})
+
+      cols = column_names
+      rows = @handle.fetch_many(cnt)
+      if rows.nil? or rows.empty?
+        @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
+      sanity_check({:fetchable => true, :prepared => true, :executed => true})
+
+      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)
+      sanity_check({:fetchable => true, :prepared => true, :executed => true})
+
+      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)
+      sanity_check
+      @handle[attr]
+    end
+
+    # Set an attribute on the StatementHandle object.
+    def []= (attr, val)
+      sanity_check
+      @handle[attr] = val
+    end
+
+    protected
+
+    def sanity_check(params={})
+      raise InterfaceError, "Statement was already closed!" if @handle.nil?
+
+      params.each_key do |key|
+        case key
+          when :fetchable
+            check_fetchable
+          when :executed
+            check_executed
+          when :prepared
+            check_prepared
+          when :statement
+            check_statement(params[:statement])
+        end
+      end
+    end
+
+    def check_prepared
+      raise InterfaceError, "Statement wasn't prepared before." unless @prepared
+    end
+
+    def check_fetchable
+      if !@fetchable and @raise_error
+        raise InterfaceError, "Statement does not have any data for fetching."
+      end
+    end
+
+    def check_executed
+      raise InterfaceError, "Statement hasn't been executed yet." unless @executed
+    end
+
+    # basic sanity checks for statements
+    def check_statement(stmt)
+      raise InterfaceError, "Statement is empty, or contains nothing but whitespace" if stmt !~ /\S/
+    end
+
+  end # class StatementHandle
+end