Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# `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'

## Module content

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 :pq:`PQlibVersion()` function

psycopg.pq.__build_version__: int = 170004

  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: PGconn | PGresult | 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.

## Objects wrapping libpq structures and functions

TODO

finish documentation

class psycopg.pq.PGconn

  Python representation of a libpq connection.

  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 :pq:`PQcancelCreate` for details.

  get_cancel() → PGcancel

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

    See :pq:`PQgetCancel` for details.

  needs_password

    True if the connection authentication method required a password, but none was available.

    See :pq:`PQconnectionNeedsPassword` for details.

  used_password

    True if the connection authentication method used a password.

    See :pq:`PQconnectionUsedPassword` for details.

  encrypt_password(passwd: bytes, user: bytes, algorithm: bytes | None = None) → bytes

    Return the encrypted form of a PostgreSQL password.

    See :pq:`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 :pq:`PQchangePassword` for details.

  trace(fileno: int) → None

    Enable tracing of the client/server communication to a file stream.

    See :pq:`PQtrace` for details.

  set_trace_flags(flags: Trace) → None

    Configure tracing behavior of client/server communication.

    Parameters:

      flags – operating mode of tracing.

    See :pq:`PQsetTraceFlags` for details.

  untrace() → None

    Disable tracing, previously enabled through `trace()`.

    See :pq:`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()

class psycopg.pq.PGresult

  Python representation of a libpq result.

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

  Utility object to manipulate connection strings.

class psycopg.pq.Escaping(conn: PGconn | None = None)

  Utility object to escape strings for SQL interpolation.

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 :pq:`PQcancelStart` for details.

  blocking() → None

    Requests that the server abandons processing of the current command in a blocking manner.

    See :pq:`PQcancelBlocking` for details.

  finish() → None

    Free the data structure created by `PQcancelCreate()`.

    Automatically invoked by `__del__()`.

    See :pq:`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 :pq:`PQgetCancel()`.

    Automatically invoked by `__del__()`.

    See :pq:`PQfreeCancel()` for details.

  cancel() → None

    Requests that the server abandon processing of the current command.

    See :pq:`PQcancel()` for details.

## Enumerations

class psycopg.pq.ConnStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  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

  :pq:`PQstatus()` and :pq:`PQcancelStatus()` return this value.

  OK = 0
  BAD = 1
  ALLOCATED = 14

class psycopg.pq.PollingStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  The status of the socket during a connection.

  If `READING` or `WRITING` you may select before polling again.

  See also

  :pq:`PQconnectPoll` for a description of these states.

  FAILED = 0
  READING = 1
  WRITING = 2
  OK = 3

class psycopg.pq.TransactionStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  The transaction status of a connection.

  See also

  :pq:`PQtransactionStatus` for a description of these states.

  IDLE = 0
  ACTIVE = 1
  INTRANS = 2
  INERROR = 3
  UNKNOWN = 4

class psycopg.pq.ExecStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  The status of a command.

  See also

  :pq:`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
  TUPLES_CHUNK = 12

class psycopg.pq.PipelineStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Pipeline mode status of the libpq connection.

  See also

  :pq:`PQpipelineStatus` for a description of these states.

  OFF = 0
  ON = 1
  ABORTED = 2

class psycopg.pq.Format(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  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, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  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

  :pq:`PQresultErrorField` for a description of these values.

class psycopg.pq.Ping(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Response from a ping attempt.

  See also

  :pq:`PQpingParams` for a description of these values.

  OK = 0
  REJECT = 1
  NO_RESPONSE = 2
  NO_ATTEMPT = 3

class psycopg.pq.Trace(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Enum to control tracing of the client/server communication.

  See also

  :pq:`PQsetTraceFlags` for a description of these values.

  SUPPRESS_TIMESTAMPS = 1
  REGRESS_MODE = 2