The psycopg2 module content — Psycopg v2.0.14 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Psycopg v2.0.14 documentation »

# The `psycopg2` module content

The module interface respects the standard defined in the DB API 2.0.

`psycopg2.` `connect`(dsn or params[, connection_factory])

  Create a new database session and return a new `connection` object.

  You can specify the connection parameters either as a string:

      conn = psycopg2.connect("dbname=test user=postgres password=secret")

  or using a set of keyword arguments:

      conn = psycopg2.connect(database="test", user="postgres", password="secret")

  The full list of available parameters is:

  - `dbname` – the database name (only in dsn string)
  - `database` – the database name (only as keyword argument)
  - `user` – user name used to authenticate
  - `password` – password used to authenticate
  - `host` – database host address (defaults to UNIX socket if not provided)
  - `port` – connection port number (defaults to 5432 if not provided)
  - `sslmode` – SSL TCP/IP negotiation mode

  Using the `connection_factory` parameter a different class or connections factory can be specified. It should be a callable object taking a `dsn` argument. See Connection and cursor factories for details.

  DB API extension

  The `connection_factory` parameter is a Psycopg extension to the DB API 2.0.

`psycopg2.` `apilevel`
  String constant stating the supported DB API level. For `psycopg2` is `2.0`.

`psycopg2.` `threadsafety`
  Integer constant stating the level of thread safety the interface supports. For `psycopg2` is `2`, i.e. threads can share the module and the connection. See Thread safety for details.

`psycopg2.` `paramstyle`
  String constant stating the type of parameter marker formatting expected by the interface. For `psycopg2` is `pyformat`. See also Passing parameters to SQL queries.

## Exceptions

In compliance with the DB API 2.0, the module makes informations about errors available through the following exceptions:

exception `psycopg2.` `Warning`
  Exception raised for important warnings like data truncations while inserting, etc. It is a subclass of the Python `StandardError`.

exception `psycopg2.` `Error`

  Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single `except` statement. Warnings are not considered errors and thus not use this class as base. It is a subclass of the Python `StandardError`.

  `pgerror`
    String representing the error message returned by the backend, `None` if not available.
  `pgcode`
    String representing the error code returned by the backend, `None` if not available. The `errorcodes` module contains symbolic constants representing PostgreSQL error codes.

  DB API extension

  The `pgerror` and `pgcode` attributes are Psycopg extensions.

      >>> try:
      ...     cur.execute("SELECT * FROM barf")
      ... except Exception, e:
      ...     pass

      >>> e.pgcode
      '42P01'
      >>> print e.pgerror
      ERROR:  relation "barf" does not exist
      LINE 1: SELECT * FROM barf
                            ^

  Changed in version 2.0.7: added `Error.pgerror` and `Error.pgcode` attributes.

exception `psycopg2.` `InterfaceError`
  Exception raised for errors that are related to the database interface rather than the database itself. It is a subclass of `Error`.

exception `psycopg2.` `DatabaseError`
  Exception raised for errors that are related to the database. It is a subclass of `Error`.

exception `psycopg2.` `DataError`
  Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc. It is a subclass of `DatabaseError`.

exception `psycopg2.` `OperationalError`
  Exception raised for errors that are related to the database’s operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc. It is a subclass of `DatabaseError`.

exception `psycopg2.` `IntegrityError`
  Exception raised when the relational integrity of the database is affected, e.g. a foreign key check fails. It is a subclass of `DatabaseError`.

exception `psycopg2.` `InternalError`
  Exception raised when the database encounters an internal error, e.g. the cursor is not valid anymore, the transaction is out of sync, etc. It is a subclass of `DatabaseError`.

exception `psycopg2.` `ProgrammingError`
  Exception raised for programming errors, e.g. table not found or already exists, syntax error in the SQL statement, wrong number of parameters specified, etc. It is a subclass of `DatabaseError`.

exception `psycopg2.` `NotSupportedError`
  Exception raised in case a method or database API was used which is not supported by the database, e.g. requesting a `rollback()` on a connection that does not support transaction or has transactions turned off. It is a subclass of `DatabaseError`.

DB API extension

Psycopg may raise a few other, more specialized, exceptions: currently `QueryCanceledError` and `TransactionRollbackError` are defined. These exceptions are not exposed by the main `psycopg2` module but are made available by the `extensions` module. All the additional exceptions are subclasses of standard DB API 2.0 exceptions, so trapping them specifically is not required.

This is the exception inheritance layout:

    StandardError
    |__ Warning
    |__ Error
        |__ InterfaceError
        |__ DatabaseError
            |__ DataError
            |__ OperationalError
            |   |__ psycopg2.extensions.QueryCanceledError
            |   |__ psycopg2.extensions.TransactionRollbackError
            |__ IntegrityError
            |__ InternalError
            |__ ProgrammingError
            |__ NotSupportedError

## Type Objects and Constructors

Note

This section is mostly copied verbatim from the DB API 2.0 specification. While these objects are exposed in compliance to the DB API, Psycopg offers very accurate tools to convert data between Python and PostgreSQL formats. See Adapting new Python types to SQL syntax and Type casting of SQL types into Python objects

Many databases need to have the input in a particular format for binding to an operation’s input parameters. For example, if an input is destined for a DATE column, then it must be bound to the database in a particular string format. Similar problems exist for “Row ID” columns or large binary items (e.g. blobs or RAW columns). This presents problems for Python since the parameters to the .execute*() method are untyped. When the database module sees a Python string object, it doesn’t know if it should be bound as a simple CHAR column, as a raw BINARY item, or as a DATE.

To overcome this problem, a module must provide the constructors defined below to create objects that can hold special values. When passed to the cursor methods, the module can then detect the proper type of the input parameter and bind it accordingly.

A Cursor Object’s description attribute returns information about each of the result columns of a query. The type_code must compare equal to one of Type Objects defined below. Type Objects may be equal to more than one type code (e.g. DATETIME could be equal to the type codes for date, time and timestamp columns; see the Implementation Hints below for details).

The module exports the following constructors and singletons:

`psycopg2.` `Date`(year, month, day)
  This function constructs an object holding a date value.

`psycopg2.` `Time`(hour, minute, second)
  This function constructs an object holding a time value.

`psycopg2.` `Timestamp`(year, month, day, hour, minute, second)
  This function constructs an object holding a time stamp value.

`psycopg2.` `DateFromTicks`(ticks)
  This function constructs an object holding a date value from the given ticks value (number of seconds since the epoch; see the documentation of the standard Python time module for details).

`psycopg2.` `TimeFromTicks`(ticks)
  This function constructs an object holding a time value from the given ticks value (number of seconds since the epoch; see the documentation of the standard Python time module for details).

`psycopg2.` `TimestampFromTicks`(ticks)
  This function constructs an object holding a time stamp value from the given ticks value (number of seconds since the epoch; see the documentation of the standard Python time module for details).

`psycopg2.` `Binary`(string)
  This function constructs an object capable of holding a binary (long) string value.

`psycopg2.` `STRING`
  This type object is used to describe columns in a database that are string-based (e.g. CHAR).

`psycopg2.` `BINARY`
  This type object is used to describe (long) binary columns in a database (e.g. LONG, RAW, BLOBs).

`psycopg2.` `NUMBER`
  This type object is used to describe numeric columns in a database.

`psycopg2.` `DATETIME`
  This type object is used to describe date/time columns in a database.

`psycopg2.` `ROWID`
  This type object is used to describe the “Row ID” column in a database.

### Navigation

- index
- modules |
- next |
- previous |
- Psycopg v2.0.14 documentation »