`pq` – libpq wrapper module #

Psycopg 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 psycopg.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 "psycopg[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 "psycopg[binary]" .

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

At import time, Psycopg 3 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 PSYCOPG_IMPL : importing the library will fail if the requested implementation is not available:

$ PSYCOPG_IMPL=c python -c "import psycopg"
Traceback (most recent call last):
ImportError: couldn't import requested psycopg 'c' implementation: No module named 'psycopg_c'
psycopg.pq.__impl__: str = 'python'#
The currently loaded implementation of the psycopg.pq package.
Possible values include python, c, binary.
The choice of implementation is automatic but can be forced setting the
PSYCOPG_IMPL env var.
psycopg.pq.version() → int#
Return the version number of the libpq currently loaded.
The number is in the same format of server_version.
Certain features might not be available if the libpq library used is too old.
See also
the PQlibVersion() function
psycopg.pq.__build_version__: int = 170000#
The libpq version the C package was built with.
A number in the same format of server_version
representing the libpq used to build the speedup module (c, binary) if
available.
Certain features might not be available if the built version is too old.
psycopg.pq.error_message(obj: psycopg.pq.abc.PGconn | psycopg.pq.abc.PGresult |




    
 psycopg.pq.abc.PGcancelConn, encoding: str = '') → str#
Return an error message from a PGconn, PGresult, PGcancelConn.
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.
pgconn_ptr#
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
psycopg doesn’t (currently) wrap, either in C or in Python using FFI
libraries such as ctypes.
cancel_conn() → PGcancelConn#
Create a connection over which a cancel request can be sent.
See PQcancelCreate for details.
get_cancel() → PGcancel#
Create an object with the information needed to cancel a command.
See PQgetCancel for details.
needs_password#
True if the connection authentication method required a password,
but none was available.
See PQconnectionNeedsPassword for details.
encrypt_password(passwd: bytes, user: bytes, algorithm: Optional[bytes] = None) → bytes#
Return the encrypted form of a PostgreSQL password.
See PQencryptPasswordConn for details.
>>> enc = conn.info.encoding
>>> encrypted = conn.pgconn.encrypt_password(password.encode(enc), rolename.encode(enc))
b'SCRAM-SHA-256$4096:...
change_password(user: bytes, passwd: bytes) → None#
Change a PostgreSQL password.
Raises:
OperationalError – if the command to change password failed.
See PQchangePassword for details.
trace(fileno: int) → None#
Enable tracing of the client/server communication to a file stream.
See PQtrace for details.
set_trace_flags(flags: Trace) → None#
Configure tracing behavior of client/server communication.
Parameters:
flags – operating mode of tracing.
See PQsetTraceFlags for details.
untrace() → None#
Disable tracing, previously enabled through trace().
See PQuntrace for details.
>>> conn.pgconn.trace(sys.stderr.fileno())
>>> conn.pgconn.set_trace_flags(pq.Trace.SUPPRESS_TIMESTAMPS | pq.Trace.REGRESS_MODE)
>>> conn.execute("select now()")
F       13      Parse    "" "BEGIN" 0
F       14      Bind     "" "" 0 0 1 0
F       6       Describe         P ""
F       9       Execute  "" 0
F       4       Sync
B       4       ParseComplete
B       4       BindComplete
B       4       NoData
B       10      CommandComplete  "BEGIN"
B       5       ReadyForQuery    T
F       17      Query    "select now()"
B       28      RowDescription   1 "now" NNNN 0 NNNN 8 -1 0
B       39      DataRow  1 29 '2022-09-14 14:12:16.648035+02'
B       13      CommandComplete  "SELECT 1"
B       5       ReadyForQuery    T
<psycopg.Cursor [TUPLES_OK] [INTRANS] (database=postgres) at 0x7f18a18ba040>
>>> conn.pgconn.untrace()
pgresult_ptr#
The pointer to the underlying PGresult structure, as integer.
None if the result was cleared.
The value can be used to pass the structure to libpq functions which
psycopg doesn’t (currently) wrap, either in C or in Python using FFI
libraries such as ctypes.
class psycopg.pq.PGcancelConn#
Token to handle non-blocking cancellation requests.
Created by PGconn.cancel_conn().
start() → None#
Requests that the server abandons processing of the current command
in a non-blocking manner.
See PQcancelStart for details.
blocking() → None#
Requests that the server abandons processing of the current command
in a blocking manner.
See PQcancelBlocking




    
 for details.
finish() → None#
Free the data structure created by PQcancelCreate().
Automatically invoked by __del__().
See PQcancelFinish() for details.
class psycopg.pq.PGcancel#
Token to cancel the current operation on a connection.
Created by PGconn.get_cancel().
free() → None#
Free the data structure created by PQgetCancel().
Automatically invoked by __del__().
See PQfreeCancel() for details.
class psycopg.pq.ConnStatus(value)#
Current status of the connection.
There are other values in this enum, but only OK and BAD are seen
after a connection has been established. Other statuses might only be seen
during the connection phase and are considered internal.
ALLOCATED is only expected to be returned by PGcancelConn.status.
See also
PQstatus() and PQcancelStatus() return this value.
OK = 0#
class psycopg.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#
class psycopg.pq.PipelineStatus(value)#
Pipeline mode status of the libpq connection.
See also
PQpipelineStatus for a description of these states.
OFF = 0#
class psycopg.pq.Format(value)#
Enum representing the format of a query argument or return value.
These values are only the ones managed by the libpq. psycopg may also
support automatically-chosen values: see psycopg.adapt.PyFormat.
TEXT = 0#
class psycopg.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 psycopg.pq.Trace(value)#
Enum to control tracing of the client/server communication.
See also
PQsetTraceFlags for a description of these values.
SUPPRESS_TIMESTAMPS = 1#
DiagnosticField.SEVERITY_NONLOCALIZED
DiagnosticField.SQLSTATE
DiagnosticField.MESSAGE_PRIMARY
DiagnosticField.MESSAGE_DETAIL
DiagnosticField.MESSAGE_HINT
DiagnosticField.STATEMENT_POSITION
DiagnosticField.INTERNAL_POSITION
DiagnosticField.INTERNAL_QUERY
DiagnosticField.CONTEXT
DiagnosticField.SCHEMA_NAME
DiagnosticField.TABLE_NAME
DiagnosticField.COLUMN_NAME
DiagnosticField.DATATYPE_NAME
DiagnosticField.CONSTRAINT_NAME
DiagnosticField.SOURCE_FILE
DiagnosticField.SOURCE_LINE
DiagnosticField.SOURCE_FUNCTION
Ping.OK
Ping.REJECT
Ping.NO_RESPONSE
Ping.NO_ATTEMPT
Trace
Trace.SUPPRESS_TIMESTAMPS
Trace.REGRESS_MODE

pq – libpq wrapper module #

pq module implementations #

`pq` – libpq wrapper module #

`pq` module implementations #