This is a local copy of the specification. The online source copy is available at http://www.python.org/topics/database/DatabaseAPI-2.0.html

Python Database API Specification 2.0

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.

The interface specification consists of several sections:

Comments and questions about this specification may be directed to the SIG for Database Interfacing with Python.

For more information on database interfacing with Python and available packages see the Database Topics Guide on www.python.org.

This document describes the Python Database API Specification 2.0. The previous version 1.0 version is still available as reference. Package writers are encouraged to use this version of the specification as basis for new interfaces.


Module Interface

Connection Objects

Cursor Objects

Type Objects and Constructors

Implementation Hints

Major Changes from Version 1.0 to Version 2.0

Open Issues


Footnotes

  1. As a guideline the connection constructor parameters should be implemented as keyword parameters for more intuitive use and follow this order of parameters:

    dsn = Data source name as string
    user = User name as string (optional)
    password = Password as string (optional)
    host = Hostname (optional)
    database = Database name (optional)

    E.g. a connect could look like this:

    connect(dsn='myhost:MYDB',user='guido',password='234$?')

  2. Module implementors should prefer 'numeric', 'named' or 'pyformat' over the other formats because these offer more clarity and flexibility.

  3. If the database does not support the functionality required by the method, the interface should throw an exception in case the method is used.

    The preferred approach is to not implement the method and thus have Python generate an AttributeError in case the method is requested. This allows the programmer to check for database capabilities using the standard hasattr() function.

    For some dynamically configured interfaces it may not be appropriate to require dynamically making the method available. These interfaces should then raise a NotSupportedError to indicate the non-ability to perform the roll back when the method is invoked.

  4. A database interface may choose to support named cursors by allowing a string argument to the method. This feature is not part of the specification, since it complicates semantics of the .fetchXXX() methods.

  5. The module will use the __getitem__ method of the parameters object to map either positions (integers) or names (strings) to parameter values. This allows for both sequences and mappings to be used as input.

    The term "bound" refers to the process of binding an input value to a database execution buffer. In practical terms, this means that the input value is directly used as a value in the operation. The client should not be required to "escape" the value so that it can be used -- the value should be equal to the actual database value.

  6. Note that the interface may implement row fetching using arrays and other optimizations. It is not guaranteed that a call to this method will only move the associated cursor forward by one row.

  7. The rowcount attribute may be coded in a way that updates its value dynamically. This can be useful for databases that return useable rowcount values only after the first call to a .fetchXXX() method.