dbi 0.4.0

data/lib/dbi/base_classes.rb

@@ -0,0 +1,12 @@
+#--
+# Fallback classes for default behavior of DBD driver
+# must be inherited by the DBD driver classes
+#++
+module DBI
+    class Base #:nodoc:
+    end
+end
+
+require 'dbi/base_classes/driver'
+require 'dbi/base_classes/database'
+require 'dbi/base_classes/statement'

data/lib/dbi/base_classes/database.rb

@@ -0,0 +1,135 @@
+module DBI
+    # Provides the core-level functionality for DatabaseHandles.
+    # 
+    # If the method description says "DBD Required", it's the DBD's
+    # responsibility to create this method. 
+    # 
+    # Required methods unimplemented by the DBD will raise
+    # DBD::NotImplementedError.
+    #
+    # "DBD Optional" methods are methods that do not have a default
+    # implementation but are optional due to the fact that many databases may
+    # not support these features (and emulating them would be prohibitive). 
+    #
+    # These methods raise DBI::NotSupportedError.
+    #
+    # Otherwise, DBI will provide a general alternative which should meet the
+    # expectations of the documentation. However, DBDs can override every
+    # method in this class.
+    #
+    class BaseDatabase < Base
+        def initialize(handle, attr)
+            @handle = handle
+            @attr   = {}
+            attr.each {|k,v| self[k] = v} 
+        end
+
+        # Disconnect from the database. DBD Required.
+        def disconnect
+            raise NotImplementedError
+        end
+
+        # Ping the database to ensure the connection is still alive. Boolean
+        # return, true for success. DBD Required.
+        def ping
+            raise NotImplementedError
+        end
+
+        # Prepare a cached statement, returning a StatementHandle. DBD
+        # Required.
+        def prepare(statement)
+            raise NotImplementedError
+        end
+
+        #
+        # Return a map of the columns that exist in the provided table name.
+        # DBD Required.
+        #
+        # The result should be an array of DBI::ColumnInfo objects which have,
+        # at minimum, the following fields: 
+        #
+        # * name:: the name of the column.
+        # * type:: This is not a field name in itself. You have two options:
+        #   * type_name:: The name of the type as returned by the database
+        #   * dbi_type:: A DBI::Type-conforming class that can be used to convert to a native type.
+        # * precision:: the precision (generally length) of the column
+        # * scale:: the scale (generally a secondary attribute to precision
+        #   that helps indicate length) of the column
+        #
+        def columns(table)
+            raise NotImplementedError
+        end
+        
+        #============================================
+        # OPTIONAL
+        #============================================
+
+        # Schedule a commit to the database immediately. DBD Optional.
+        def commit
+            raise NotSupportedError
+        end
+
+        # Schedule a rollback to the database immediately. DBD Optional.
+        def rollback
+            raise NotSupportedError
+        end
+
+        # Return the tables available to the database connection.
+        # 
+        # Note:: the basic implementation returns an empty array.
+        def tables
+            []
+        end
+
+        # 
+        # Execute a statement with the binds provided. Returns the statement
+        # handle unfinished.
+        #
+        # This is roughly equivalent to:
+        #
+        #   sth = dbh.prepare("my statement")
+        #   sth.execute(my, bind, vars)
+        #   
+        def execute(statement, *bindvars)
+            stmt = prepare(statement)
+            stmt.bind_params(*bindvars)
+            stmt.execute
+            stmt
+        end
+
+        #
+        # Execute and complete the statement with the binds provided. Returns
+        # the row modified count (via BaseStatement#rows). Finishes the
+        # statement handle for you.
+        #
+        # Roughly equivalent to:
+        #
+        #   sth = dbh.prepare("my statement)
+        #   sth.execute(my, bind, vars)
+        #   result = sth.rows
+        #   sth.finish
+        #
+        # Returning the value stored in `result`.
+        def do(statement, *bindvars)
+            stmt = execute(statement, *bindvars)
+            res = stmt.rows
+            stmt.finish
+            return res
+        end
+
+        #
+        # Get an attribute from the DatabaseHandle. These are DBD specific and
+        # embody things like Auto-Commit support for transactional databases.
+        #
+        # DBD Authors:: This messes with @attr directly.
+        #
+        def [](attr)
+            @attr[attr]
+        end
+
+        # Set an attribute on the DatabaseHandle. DBD Optional.
+        def []=(attr, value)
+            raise NotSupportedError
+        end
+    end # class BaseDatabase
+end

data/lib/dbi/base_classes/driver.rb

@@ -0,0 +1,47 @@
+module DBI
+
+    # Implements the basic functionality that constitutes a Driver
+    #
+    # Drivers do not have a direct interface exposed to the user; these methods
+    # are mostly for DBD authors.
+    #
+    # As with DBI::BaseDatabase, "DBD Required" and "DBD Optional" will be used
+    # to explain the same requirements.
+    #
+    class BaseDriver < Base
+        def initialize(dbi_version)
+            major, minor = dbi_version.split(".").collect { |x| x.to_i }
+            dbi_major, dbi_minor = DBI::VERSION.split(".").collect { |x| x.to_i }
+            unless major == dbi_major and minor == dbi_minor
+                raise InterfaceError, "Wrong DBD API version used"
+            end
+        end
+
+        # Connect to the database. DBD Required.
+        def connect(dbname, user, auth, attr)
+            raise NotImplementedError
+        end
+
+        # Default u/p information in an array.
+        def default_user
+            ['', '']
+        end
+
+        # Default attributes to set on the DatabaseHandle.
+        def default_attributes
+            {}
+        end
+
+        # Return the data sources available to this driver. Returns an empty
+        # array per default.
+        def data_sources
+            []
+        end
+
+        # Disconnect all DatabaseHandles. DBD Required.
+        def disconnect_all
+            raise NotImplementedError
+        end
+
+    end # class BaseDriver
+end

data/lib/dbi/base_classes/statement.rb

@@ -0,0 +1,167 @@
+module DBI
+    #
+    # StatementHandles are used to encapsulate the process of managing a
+    # statement (DDL or DML) and its parameters, sending it to the database,
+    # and gathering any results from the execution of that statement.
+    #
+    # As with the other `Base` classes, the terms "DBD Required" and "DBD
+    # Optional" are defined in DBI::BaseDatabase.
+    #
+    class BaseStatement < Base
+        def initialize(attr=nil)
+            @attr = attr || {}
+        end
+
+        #
+        # Bind a parameter to the statement. DBD Required.
+        #
+        # The parameter number is numeric and indexes starting at 1. This
+        # corresponds to the question marks (?) in the statement from the
+        # left-most part of the statement moving forward.
+        #
+        # The value may be any ruby type. How these are handled is
+        # DBD-dependent, but the vast majority of DBDs will convert these to
+        # string inside the query.
+        #
+        def bind_param(param, value, attribs)
+            raise NotImplementedError
+        end
+
+        #
+        # Execute the statement with the known binds. DBD Required.
+        #
+        def execute
+            raise NotImplementedError
+        end
+
+        #
+        # Close the statement and any result cursors. DBD Required.
+        #
+        # Note:: Most implementations will fail miserably if you forget to
+        #        finish your statement handles.
+        def finish
+            raise NotImplementedError
+        end
+
+        #
+        # Fetch the next row in the result set. DBD Required.
+        #
+        # DBI::Row is responsible for formatting the data the DBD provides it.
+        #
+        def fetch
+            raise NotImplementedError
+        end
+
+        ##
+        # returns result-set column information as array
+        # of hashs, where each hash represents one column. See
+        # BaseDatabase#columns. DBD Required.
+        #
+        def column_info
+            raise NotImplementedError
+        end
+
+        #============================================
+        # OPTIONAL
+        #============================================
+
+        #
+        # Take a list of bind variables and bind them successively using bind_param.
+        #
+        def bind_params(*bindvars)
+            bindvars.each_with_index {|val,i| bind_param(i+1, val, nil) }
+            self
+        end
+
+        #
+        # Cancel any result cursors. DBD Optional, but intentionally does not
+        # raise any exception as it's used internally to maintain consistency.
+        #
+        def cancel
+        end
+
+        #
+        # fetch_scroll is provided with a direction and offset and works
+        # similar to how seek() is used on files.
+        #
+        # The constants available for direction are as follows:
+        # 
+        # * SQL_FETCH_NEXT: fetch the next result.
+        # * SQL_FETCH_LAST: fetch the last result, period.
+        # * SQL_FETCH_RELATIVE: fetch the result at the offset. 
+        #
+        # Other constants can be used, but if this method is not supplied by
+        # the driver, they will result in a raise of DBI::NotSupportedError.
+        #
+
+        def fetch_scroll(direction, offset)
+            case direction
+            when SQL_FETCH_NEXT
+                return fetch
+            when SQL_FETCH_LAST
+                last_row = nil
+                while (row=fetch) != nil
+                    last_row = row
+                end
+                return last_row
+            when SQL_FETCH_RELATIVE
+                raise NotSupportedError if offset <= 0
+                row = nil
+                offset.times { row = fetch; break if row.nil? }
+                return row
+            else
+                raise NotSupportedError
+            end
+        end
+
+        #
+        # fetch x rows. The result is Array of DBI::Row.
+        #
+        def fetch_many(cnt)
+            rows = []
+            cnt.times do
+                row = fetch
+                break if row.nil?
+                rows << row.dup
+            end
+
+            if rows.empty?
+                nil
+            else
+                rows
+            end
+        end
+
+        #
+        # Fetch all available rows. Result is Array of DBI::Row.
+        #
+        def fetch_all
+            rows = []
+            loop do
+                row = fetch
+                break if row.nil?
+                rows << row.dup
+            end
+
+            if rows.empty?
+                nil
+            else
+                rows
+            end
+        end
+
+        #
+        # Get statement attributes.
+        #
+        def [](attr)
+            @attr[attr]
+        end
+
+        #
+        # Set statement attributes. DBD Optional.
+        #
+        def []=(attr, value)
+            raise NotSupportedError
+        end
+    end # class BaseStatement
+end

data/lib/dbi/binary.rb

@@ -0,0 +1,25 @@
+module DBI
+    #
+    # Encapsulates the concept of a CLOB/BLOB, which can then be passed as a
+    # bind via BaseStatement#bind_param.
+    #
+    # This is similar to a DBI::Type class and will eventually find its way
+    # there.
+    #
+    # See #new for usage.
+    class Binary
+        attr_accessor :data
+
+        # Construct a new DBI::Binary object with the data supplied as string.
+        # This object can then be used in bound variables to represent a CLOB
+        # or BLOB type.
+        def initialize(data)
+            @data = data
+        end
+
+        # Return the string representation of the DBI::Binary object.
+        def to_s
+            @data
+        end
+    end
+end

data/lib/dbi/columninfo.rb

@@ -0,0 +1,106 @@
+require 'delegate'
+require 'rubygems'
+begin
+    gem 'deprecated'
+rescue LoadError => e
+end
+
+require 'deprecated'
+
+module DBI
+    # This represents metadata for columns within a given table, such as the
+    # data type, whether or not the the column is a primary key, etc.
+    #
+    # ColumnInfo is a delegate of Hash, but represents its keys indifferently,
+    # coercing all strings to symbols. It also has ostruct-like features, f.e.:
+    #
+    #   h = ColumnInfo.new({ "foo" => "bar" })
+    #   h[:foo] => "bar"
+    #   h["foo"] => "bar"
+    #   h.foo => "bar"
+    #
+    # All of these forms have assignment forms as well.
+    #
+    class ColumnInfo < DelegateClass(Hash)
+
+        # Create a new ColumnInfo object.
+        #
+        # If no Hash is provided, one will be created for you. The hash will be
+        # shallow cloned for storage inside the object, and an attempt will be
+        # made to convert all string keys to symbols.
+        #
+        # In the event that both string and symbol keys are provided in the
+        # initial hash, we cannot safely route around collisions and therefore
+        # a TypeError is raised.
+        #
+        def initialize(hash=nil)
+            @hash = hash.dup rescue nil
+            @hash ||= Hash.new
+
+            # coerce all strings to symbols
+            @hash.each_key do |x|
+                if x.kind_of? String
+                    sym = x.to_sym
+                    if @hash.has_key? sym
+                        raise ::TypeError, 
+                            "#{self.class.name} may construct from a hash keyed with strings or symbols, but not both" 
+                    end
+                    @hash[sym] = @hash[x]
+                    @hash.delete(x)
+                end
+            end
+
+            super(@hash)
+        end
+
+        def [](key)
+            @hash[key.to_sym]
+        end
+
+        def []=(key, value)
+            @hash[key.to_sym] = value
+        end
+
+        def default() # :nodoc; XXX hack to get around Hash#default
+            method_missing(:default)
+        end
+
+        def method_missing(sym, value=nil)
+            if sym.to_s =~ /=$/
+                sym = sym.to_s.sub(/=$/, '').to_sym
+                @hash[sym] = value
+            elsif sym.to_s =~ /\?$/
+                sym = sym.to_s.sub(/\?$/, '').to_sym
+                @hash[sym]
+            else
+                @hash[sym]
+            end
+        end
+
+        # Aliases - XXX soon to be deprecated
+        def self.deprecated_alias(target, source) # :nodoc:
+            define_method(target) { |*args| method_missing(source, *args) }
+            deprecate target 
+        end
+
+        deprecated_alias :is_nullable?, :nullable
+        deprecated_alias :can_be_null?, :nullable
+
+        deprecated_alias :is_indexed?, :indexed
+
+        deprecated_alias :is_primary?, :primary
+
+        deprecated_alias :is_unique, :unique
+
+        deprecated_alias :size, :precision
+        deprecated_alias :size=, :precision=
+        deprecated_alias :length, :precision
+        deprecated_alias :length=, :precision=
+
+        deprecated_alias :decimal_digits, :scale
+        deprecated_alias :decimal_digits=, :scale=
+
+        deprecated_alias :default_value, :default
+        deprecated_alias :default_value=, :default=
+    end
+end