pq – libpq wrapper module

psycopg3 is built around the libpq, the PostgreSQL client library, which performs most of the network communications and returns query results in C structures.

The low-level functions of the library are exposed by the objects in the psycopg3.pq module.

pq module implementations

There are actually several implementations of the module, all offering the same interface. Current implementations are:

  • python: a pure-python implementation, implemented using the ctypes module. It is less performing than the others, but it doesn’t need a C compiler to install. It requires the libpq installed in the system.

  • c: a C implementation of the libpq wrapper (more precisely, implemented in Cython). It is much better performing than the python implementation, however it requires development packages installed on the client machine. It can be installed using the c extra, i.e. running pip install psycopg3[c].

  • binary: a pre-compiled C implementation, bundled with all the required libraries. It is the easiest option to deal with, fast to install and it should require no development tool or client library, however it may be not available for every platform. You can install it using the binary extra, i.e. running pip install psycopg3[binary].

The implementation currently used is available in the __impl__ module constant.

At import, psycopg3 will try to use the best implementation available and will fail if none is usable. You can force the use of a specific implementation by exporting the env var PSYCOPG3_IMPL: importing the library will fail if the requested implementation is not available.

Module content

psycopg3.pq.__impl__: str = 'python'

The currently loaded implementation of the psycopg3.pq package.

Possible values include python, c, binary.

The choice of implementation is automatic but can be forced setting the PSYCOPG3_IMPL env var.

psycopg3.pq.version()

Return the version number of the libpq currently loaded.

Return type

int

TODO

Document pg10 quirk.

See also

the PQlibVersion() function

psycopg3.pq.error_message(obj, encoding='utf8')

Return an error message from a PGconn or PGresult.

The return value is a str (unlike pq data which is usually bytes): use the connection encoding if available, otherwise the encoding parameter as a fallback for decoding. Don’t raise exceptions on decoding errors.

Return type

str

Objects wrapping libpq structures and functions

TODO

finish documentation

class psycopg3.pq.PGconn(pgconn_ptr)

Python representation of a libpq connection.

pgconn_ptr: Optional[int]

The pointer to the underlying PGconn structure, as integer.

None if the connection is closed.

The value can be used to pass the structure to libpq functions which psycopg3 doesn’t (currently) wrap, either in C or in Python using FFI libraries such as ctypes.

get_cancel()

Create an object with the information needed to cancel a command.

See PQgetCancel for details.

Return type

PGcancel

class psycopg3.pq.PGresult(pgresult_ptr)

Python representation of a libpq result.

pgresult_ptr: Optional[int]

The pointer to the underlying PGresult structure, as integer.

None if the result waas cleared.

The value can be used to pass the structure to libpq functions which psycopg3 doesn’t (currently) wrap, either in C or in Python using FFI libraries such as ctypes.

class psycopg3.pq.Conninfo

Utility object to manipulate connection strings.

class psycopg3.pq.Escaping(conn=None)

Utility object to escape strings for SQL interpolation.

class psycopg3.pq.PGcancel(pgcancel_ptr)

Token to cancel the current operation on a connection.

Created by PGconn.get_cancel().

free()

Free the data structure created by PQgetCancel.

Automatically invoked by __del__().

See PQfreeCancel for details.

cancel()

Requests that the server abandon processing of the current command.

See PQcancel() for details.

Enumerations

class psycopg3.pq.ConnStatus(value)

Current status of the connection.

Other possible status are only seen during the connection phase.

See also

PQstatus() returns this value.

OK = 0

The connection is in a working state.

BAD = 1

The connection is closed.

class psycopg3.pq.PollingStatus(value)

The status of the socket during a connection.

If READING or WRITING you may select before polling again.

See also

PQconnectPoll for a description of these states.

FAILED = 0

Connection attempt failed.

READING = 1

Will have to wait before reading new data.

WRITING = 2

Will have to wait before writing new data.

OK = 3

Connection completed.

class psycopg3.pq.TransactionStatus(value)

The transaction status of a connection.

See also

PQtransactionStatus for a description of these states.

IDLE = 0

Connection ready, no transaction active.

ACTIVE = 1

A command is in progress.

INTRANS = 2

Connection idle in an open transaction.

INERROR = 3

An error happened in the current transaction.

UNKNOWN = 4

Unknown connection state, broken connection.

class psycopg3.pq.ExecStatus(value)

The status of a command.

See also

PQresultStatus for a description of these states.

EMPTY_QUERY = 0

The string sent to the server was empty.

COMMAND_OK = 1

Successful completion of a command returning no data.

TUPLES_OK = 2

Successful completion of a command returning data (such as a SELECT or SHOW).

COPY_OUT = 3

Copy Out (from server) data transfer started.

COPY_IN = 4

Copy In (to server) data transfer started.

BAD_RESPONSE = 5

The server’s response was not understood.

NONFATAL_ERROR = 6

A nonfatal error (a notice or warning) occurred.

FATAL_ERROR = 7

A fatal error occurred.

COPY_BOTH = 8

Copy In/Out (to and from server) data transfer started.

This feature is currently used only for streaming replication, so this status should not occur in ordinary applications.

SINGLE_TUPLE = 9

The PGresult contains a single result tuple from the current command.

This status occurs only when single-row mode has been selected for the query.

class psycopg3.pq.Format(value)

Enum representing the format of a query argument or return value.

These values are only the ones managed by the libpq. psycopg3 may also support automatically-chosen values: see psycopg3.adapt.Format.

TEXT = 0

Text parameter.

BINARY = 1

Binary parameter.

class psycopg3.pq.DiagnosticField(value)

Fields in an error report.

Available attributes:

SEVERITY
SEVERITY_NONLOCALIZED
SQLSTATE
MESSAGE_PRIMARY
MESSAGE_DETAIL
MESSAGE_HINT
STATEMENT_POSITION
INTERNAL_POSITION
INTERNAL_QUERY
CONTEXT
SCHEMA_NAME
TABLE_NAME
COLUMN_NAME
DATATYPE_NAME
CONSTRAINT_NAME
SOURCE_FILE
SOURCE_LINE
SOURCE_FUNCTION

See also

PQresultErrorField for a description of these values.

class psycopg3.pq.Ping(value)

Response from a ping attempt.

See also

PQpingParams for a description of these values.

OK = 0

The server is running and appears to be accepting connections.

REJECT = 1

The server is running but is in a state that disallows connections.

NO_RESPONSE = 2

The server could not be contacted.

NO_ATTEMPT = 3

No attempt was made to contact the server.