Introduction

    This API has been defined to encourage similarity between the
    Python modules that are used to access databases.  By doing this,
    we hope to achieve a consistency leading to more easily understood
    modules, code that is generally more portable across databases,
    and a broader reach of database connectivity from Python.
 
    This interface specification consists of several items:

        * Module Interface
        * Connection Objects
        * Cursor Objects
        * DBI Helper Objects
 
    Comments and questions about this specification may be directed to
    the SIG on Tabular Databases in Python
    (http://www.python.org/sigs/db-sig).

    This specification document was last updated on: April 9, 1996.
    It will be known as Version 1.0 of this specification.

Module Interface

    The database interface modules should typically be named with
    something terminated by 'db'.  Existing examples are: 'oracledb',
    'informixdb', and 'pg95db'.  These modules should export several
    names:
 
        modulename(connection_string)

            Constructor for creating a connection to the database.
            Returns a Connection Object.
 
        error
        
            Exception raised for errors from the database module.

Connection Objects

    Connection Objects should respond to the following methods:
 
        close()

            Close the connection now (rather than whenever __del__ is
            called).  The connection will be unusable from this point
            forward; an exception will be raised if any operation is
            attempted with the connection.
 
        commit()

            Commit any pending transaction to the database.
 
        rollback()

            Roll the database back to the start of any pending
            transaction.
 
        cursor()

            Return a new Cursor Object.  An exception may be thrown if
            the database does not support a cursor concept.
 
        callproc([params])

            (Note: this method is not well-defined yet.)  Call a
            stored database procedure with the given (optional)
            parameters.  Returns the result of the stored procedure.
 
        (all Cursor Object attributes and methods)

            For databases that do not have cursors and for simple
            applications that do not require the complexity of a
            cursor, a Connection Object should respond to each of the
            attributes and methods of the Cursor Object.  Databases
            that have cursor can implement this by using an implicit,
            internal cursor.

 

Cursor Objects

    These objects represent a database cursor, which is used to manage
    the context of a fetch operation.
 
    Cursor Objects should respond to the following methods and
    attributes:
 
        arraysize

            This read/write attribute specifies the number of rows to
            fetch at a time with fetchmany().  This value is also used
            when inserting multiple rows at a time (passing a
            tuple/list of tuples/lists as the params value to
            execute()).  This attribute will default to a single row.
 
            Note that the arraysize is optional and is merely provided
            for higher performance database interactions.
            Implementations should observe it with respect to the
            fetchmany() method, but are free to interact with the
            database a single row at a time.
 
        description

            This read-only attribute is a tuple of 7-tuples.  Each
            7-tuple contains information describing each result