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
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
ctypesmodule. 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
pythonimplementation, however it requires development packages installed on the client machine. It can be installed using the
cextra, 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
binaryextra, i.e. running
pip install "psycopg[binary]".
The implementation currently used is available in the
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
Possible values include
The choice of implementation is automatic but can be forced setting the
- psycopg.pq.version() int #
Return the version number of the libpq currently loaded.
The number is in the same format of
Certain features might not be available if the libpq library used is too old.
- psycopg.pq.__build_version__: int = 160000#
The libpq version the C package was built with.
A number in the same format of
server_versionrepresenting the libpq used to build the speedup module (
binary) if available.
Certain features might not be available if the built version is too old.
- psycopg.pq.error_message(obj: Union[PGconn, PGresult], encoding: str = 'utf8') str #
The return value is a
str(unlike pq data which is usually
bytes): use the connection encoding if available, otherwise the
encodingparameter as a fallback for decoding. Don’t raise exceptions on decoding errors.
Objects wrapping libpq structures and functions#
- class psycopg.pq.PGconn#
Python representation of a libpq connection.
The pointer to the underlying
PGconnstructure, as integer.
Noneif 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
- get_cancel() PGcancel #
Create an object with the information needed to cancel a command.
True if the connection authentication method required a password, but none was available.
True if the connection authentication method used a password.
- encrypt_password(passwd: bytes, user: bytes, algorithm: Optional[bytes] = None) bytes #
Return the encrypted form of a PostgreSQL password.
>>> enc = conn.info.encoding >>> encrypted = conn.pgconn.encrypt_password(password.encode(enc), rolename.encode(enc)) b'SCRAM-SHA-256$4096:...
- trace(fileno: int)#
Enable tracing of the client/server communication to a file stream.
- set_trace_flags(flags: Trace)#
Configure tracing behavior of client/server communication.
flags – operating mode of tracing.
>>> 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()
- class psycopg.pq.PGresult#
Python representation of a libpq result.
- class psycopg.pq.Conninfo#
Utility object to manipulate connection strings.
- class psycopg.pq.Escaping(conn: Optional[PGconn] = None)#
Utility object to escape strings for SQL interpolation.
- class psycopg.pq.PGcancel#
Token to cancel the current operation on a connection.
Free the data structure created by
Automatically invoked by
- class psycopg.pq.ConnStatus(value)#
Current status of the connection.
PQstatus()returns this value.
- OK = 0#
- BAD = 1#
- class psycopg.pq.PollingStatus(value)#
The status of the socket during a connection.
WRITINGyou may select before polling again.
PQconnectPollfor a description of these states.
- FAILED = 0#
- READING = 1#
- WRITING = 2#
- OK = 3#
- class psycopg.pq.TransactionStatus(value)#
The transaction status of a connection.
PQtransactionStatusfor a description of these states.
- IDLE = 0#
- ACTIVE = 1#
- INTRANS = 2#
- INERROR = 3#
- UNKNOWN = 4#
- class psycopg.pq.ExecStatus(value)#
The status of a command.
PQresultStatusfor a description of these states.
- EMPTY_QUERY = 0#
- COMMAND_OK = 1#
- TUPLES_OK = 2#
- COPY_OUT = 3#
- COPY_IN = 4#
- BAD_RESPONSE = 5#
- NONFATAL_ERROR = 6#
- FATAL_ERROR = 7#
- COPY_BOTH = 8#
- SINGLE_TUPLE = 9#
- PIPELINE_SYNC = 10#
- PIPELINE_ABORTED = 11#
- class psycopg.pq.PipelineStatus(value)#
Pipeline mode status of the libpq connection.
PQpipelineStatusfor a description of these states.
- OFF = 0#
- ON = 1#
- ABORTED = 2#
- class psycopg.pq.Format(value)#
Enum representing the format of a query argument or return value.
- TEXT = 0#
- BINARY = 1#
- class psycopg.pq.DiagnosticField(value)#
Fields in an error report.
PQresultErrorFieldfor a description of these values.
- class psycopg.pq.Ping(value)#
Response from a ping attempt.
PQpingParamsfor a description of these values.
- OK = 0#
- REJECT = 1#
- NO_RESPONSE = 2#
- NO_ATTEMPT = 3#