Other top-level objects
Allow access to information about the connection.
The object is usually returned by
Return the connection string to connect to the database.
The string contains all the parameters set to a non-default value, which might come either from the connection string and parameters passed to
connect() or from environment variables. The password is never returned (you can read it using the
get_parameters()method returns the same information as a dict.
The status of the connection. See
The status can be one of a number of values. However, only two of these are seen outside of an asynchronous connection procedure:
BAD. A good connection to the database has the status
OK. Ordinarily, an
OK status will remain so until
Connection.close(), but a communications failure might result in the status changing to
The current in-transaction status of the session. See
The status can be
IDLE (currently idle),
ACTIVE (a command is in progress),
INTRANS (idle, in a valid transaction block), or
INERROR (idle, in a failed transaction block).
UNKNOWN is reported if the connection is bad.
ACTIVE is reported only when a query has been sent to the server and not yet completed.
The current pipeline status of the client. See
The process ID (PID) of the backend process handling this connection. See
A string representing the database vendor connected to.
Normally it is
PostgreSQL; it may be different if connected to a different database.
New in version 3.1.
An integer representing the server version. See
The number is formed by converting the major, minor, and revision numbers into two-decimal-digit numbers and appending them together. Starting from PostgreSQL 10 the minor version was dropped, so the second group of digits is always 00. For example, version 9.3.5 is returned as 90305, version 10.2 as 100002.
The error message most recently generated by an operation on the connection. See
Return the connection parameters values.
Return all the parameters set to a non-default value, which might come either from the connection string and parameters passed to ~Connection.connect() or from environment variables. The password is never returned (you can read it using the password attribute).
The dsn attribute returns the same information in the form as a string.
The Python timezone info of the connection’s timezone.
>>> conn.info.timezone zoneinfo.ZoneInfo(key='Europe/Rome')
The server host name of the active connection. See
This can be a host name, an IP address, or a directory path if the connection is via Unix socket. (The path case can be distinguished because it will always be an absolute path, beginning with
The server IP address of the connection. See
Only available if the libpq used is at least from PostgreSQL 12. Raise ~psycopg.NotSupportedError otherwise.
The port of the active connection. See
The database name of the connection. See
The user name of the connection. See
The password of the connection. See
The command-line options passed in the connection request. See
Return a parameter setting of the connection.
Return None is the parameter is unknown.
Example of parameters are
PQparameterStatus() for all the available parameters.
The Python codec name of the connection’s client encoding.
The value returned is always normalized to the Python codec ~codecs.CodecInfo.name:
conn.execute("SET client_encoding TO LATIN9") conn.info.encoding 'iso8859-15'
A few PostgreSQL encodings are not available in Python and cannot be selected (currently
MULE_INTERNAL). The PostgreSQL
SQL_ASCII encoding has the special meaning of “no encoding”: see Strings adaptation for details.
class psycopg.Column(cursor, index)
An object describing a column of data from a database result, as described by the DBAPI, so it can also be unpacked as a 7-items tuple.
The object is returned by Cursor.description.
The name of the column.
The numeric OID of the column.
The field size, for
varchar(n), None otherwise.
The internal field size for fixed-size types, None otherwise.
The number of digits for fixed precision types.
The number of digits after the decimal point if available.
An asynchronous notification received from the database.
The object is usually returned by Connection.notifies().
The name of the channel on which the notification was received.
The message attached to the notification.
The PID of the backend process which sent the notification.
See Pipeline mode support for details.
Handler for connection in pipeline mode.
This objects is returned by Connection.pipeline().
Sync the pipeline, send any pending command and receive and process all available results.
Return !True if the psycopg libpq wrapper supports pipeline mode.
Handler for async connection in pipeline mode.
This objects is returned by AsyncConnection.pipeline().
See Transactions management for details about these objects.
Enum representing the isolation level for a transaction.
The value is usually used with the Connection.isolation_level property.
Check the PostgreSQL documentation for a description of the effects of the different levels of transaction isolation.
READ_UNCOMMITTED = 1
READ_COMMITTED = 2
REPEATABLE_READ = 3
SERIALIZABLE = 4
class psycopg.Transaction(connection, savepoint_name=None, force_rollback=False)
Returned by Connection.transaction() to handle a transaction block.
The name of the savepoint; !None if handling the main transaction.
The connection the object is managing.
class psycopg.AsyncTransaction(connection, savepoint_name=None, force_rollback=False)
Returned by AsyncConnection.transaction() to handle a transaction block.
Exit the current Transaction context immediately and rollback any changes made within this context.
If a transaction context is specified in the constructor, rollback enclosing transactions contexts up to and including the one specified.
It can be used as:
raise Rollback: roll back the operation that happened in the current transaction block and continue the program after the block.
raise Rollback(): same effect as above
raise Rollback(tx): roll back any operation that happened in the Transaction !tx (returned by a statement such as
with conn.transaction() as tx:and all the blocks nested within. The program will continue after the !tx block.
class psycopg.Xid(format_id, gtrid, bqual, prepared=None, owner=None, database=None)
A two-phase commit transaction identifier.
The object can also be unpacked as a 3-item tuple (format_id, gtrid, bqual).
See Two-Phase Commit protocol support for details.
Format Identifier of the two-phase transaction.
Global Transaction Identifier of the two-phase transaction.
If the Xid doesn’t follow the XA standard, it will be the PostgreSQL ID of the transaction (in which case format_id and bqual will be !None).
Branch Qualifier of the two-phase transaction.
prepared: Optional[datetime] = None
Timestamp at which the transaction was prepared for commit.
Only available on transactions recovered by ~Connection.tpc_recover().
owner: Optional[str] = None
Named of the user that executed the transaction.
Only available on recovered transactions.
database: Optional[str] = None
Named of the database in which the transaction was executed.
Only available on recovered transactions.