Other top-level objects

Connection information

class psycopg.ConnectionInfo(pgconn)

Allow access to information about the connection.

The object is usually returned by Connection.info.

dsn

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 password attribute).

Note

The get_parameters() method returns the same information as a dict.

status

The status of the connection. See :pq:`PQstatus()`.

The status can be one of a number of values. However, only two of these are seen outside of an asynchronous connection procedure: OK and 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 BAD prematurely.

transaction_status

The current in-transaction status of the session. See :pq:`PQtransactionStatus()`.

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.

pipeline_status

The current pipeline status of the client. See :pq:`PQpipelineStatus()`.

backend_pid

The process ID (PID) of the backend process handling this connection. See :pq:`PQbackendPID()`.

vendor

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.

server_version

An integer representing the server version. See :pq:`PQserverVersion()`.

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.

error_message

The error message most recently generated by an operation on the connection. See :pq:`PQerrorMessage()`.

get_parameters()

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 connect() or from environment variables. The password is never returned (you can read it using the password attribute).

Return type:

dict[str, str]

Note

The dsn attribute returns the same information in the form as a string.

timezone

The Python timezone info of the connection’s timezone.

>>> conn.info.timezone
zoneinfo.ZoneInfo(key='Europe/Rome')
host

The server host name of the active connection. See :pq:`PQhost()`.

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 /.)

hostaddr

The server IP address of the connection. See :pq:`PQhostaddr()`.

Only available if the libpq used is at least from PostgreSQL 12. Raise NotSupportedError otherwise.

port

The port of the active connection. See :pq:`PQport()`.

dbname

The database name of the connection. See :pq:`PQdb()`.

user

The user name of the connection. See :pq:`PQuser()`.

password

The password of the connection. See :pq:`PQpass()`.

options

The command-line options passed in the connection request. See :pq:`PQoptions`.

parameter_status(param_name)

Return a parameter setting of the connection.

Return None is the parameter is unknown.

Return type:

Optional[str]

Example of parameters are server_version, standard_conforming_strings… See :pq:`PQparameterStatus()` for all the available parameters.

encoding

The Python codec name of the connection’s client encoding.

The value returned is always normalized to the Python codec 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 EUC_TW, MULE_INTERNAL). The PostgreSQL SQL_ASCII encoding has the special meaning of “no encoding”: see Strings adaptation for details.

The description Column object

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.

name

The name of the column.

type_code

The numeric OID of the column.

display_size

The field size, for varchar(n), None otherwise.

internal_size

The internal field size for fixed-size types, None otherwise.

precision

The number of digits for fixed precision types.

scale

The number of digits after the decimal point if available.

Notifications

class psycopg.Notify

An asynchronous notification received from the database.

The object is usually returned by Connection.notifies().

channel: str

The name of the channel on which the notification was received.

payload: str

The message attached to the notification.

pid: int

The PID of the backend process which sent the notification.