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'

Module content #

psycopg.pq. __impl__ : str = 'binary' #

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 ( ) #

See also

the PQlibVersion() function

psycopg.pq. __build_version__ : int = 150001 #

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 , 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 #

class psycopg.pq. PGconn #

pgconn_ptr #

get_cancel ( ) #

Return type :

PGcancel

needs_password #

used_password #

encrypt_password ( passwd , user , algorithm = None ) #

Return type :

bytes

>>> enc = conn.info.encoding
>>> encrypted = conn.pgconn.encrypt_password(password.encode(enc), rolename.encode(enc))
b'SCRAM-SHA-256$4096:...

trace ( fileno ) #

Return type :

None

set_trace_flags ( flags ) #

Return type :

None

untrace ( ) #

Return type :

None

>>> 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

>>> conn.pgconn.untrace()

class psycopg.pq. PGresult #

pgresult_ptr #

class psycopg.pq. Conninfo #

class psycopg.pq. Escaping #

class psycopg.pq. PGcancel #

Enumerations #

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.

See also

PQstatus() returns this value.

OK = 0 #

BAD = 1 #

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 #

READING = 1 #

WRITING = 2 #

OK = 3 #

class psycopg.pq. TransactionStatus ( value ) #

The transaction status of a connection.

See also

PQtransactionStatus for 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.

See also

PQresultStatus for 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.

See also

PQpipelineStatus for 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.

These values are only the ones managed by the libpq. ~psycopg may also support automatically-chosen values: see psycopg.adapt.PyFormat .

TEXT = 0 #

BINARY = 1 #

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. Ping ( value ) #

Response from a ping attempt.

See also

PQpingParams for a description of these values.

OK = 0 #

REJECT = 1 #

NO_RESPONSE = 2 #

NO_ATTEMPT = 3 #

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 #

REGRESS_MODE = 2 #