PostgreSQL Adapter Options

The name of the ZConfig section is <postgresql>.

RelStorage 3.0 requires PostgreSQL 9.6 or above.

Tip

PostgreSQL defaults to storing persistent object state data (pickles) on disk in a compressed format if they are longer than roughly 2,000 bytes. Thus wrapper storages like zc.zlibstorage are unlikely to save much disk space. They may still reduce network traffic, however, at the cost of CPU usage in the Python process.

If you used a compressing wrapper, you can disable this disk compression with the SQL command ALTER TABLE object_state ALTER COLUMN STATE SET storage EXTERNAL.

The PostgreSQL adapter accepts:

driver

All of these drivers use the name of the corresponding PyPI package. All drivers support uploading objects using PostgreSQL’s fast binary COPY protocol (except where noted). Only gevent psycopg2 supports RelStorage’s critical commit section. The possible options are:

psycopg2

A C-based driver that uses the C PostgreSQL client libraries. Optimal on CPython, but not compatible with gevent. For non-production, experimental usage, one can install the psycopg2-binary package to be able to use this driver without needing a C compiler.

This is the default and preferred driver everywhere except PyPy.

If psycopg2 has a wait callback installed, this driver will not be available. If no driver is specified, the next choice for ‘auto’ in this case will be gevent psycopg2.

gevent psycopg2

The same as psycopg2, but made to be gevent compatible through the use of a wait callback. If the system is monkey-patched by gevent, RelStorage will automatically install a wait callback optimized for RelStorage. If you won’t be monkey-patching, you must install a compatible wait callback yourself (perhaps using psycogreen).

A wait callback is shared between all connections created by the psycopg2 library. There is no way to have some connections be blocking and some non-blocking. If you’ll be using psycopg2 connections in the same process outside of RelStorage, the wait callback RelStorage installs won’t work for those other connections. You can install a more general callback at a slight expense to the RelStorage connections (this will forfeit support for the critical commit section), or you could use the RelStorage driver module to create the other connections.

This driver forfeits use of the COPY protocol and use of the C-accelerated BLOBs.

This driver will only be available if psycopg2 has a wait callback installed, which, as mentioned above, happens automatically when gevent monkey-patches the system. No attempt is made to check that the wait callback is actually gevent-friendly in case it has been replaced.

Changed in version 3.2.0: Add support for the critical commit section.

psycopg2cffi

A C-based driver that requires the PostgreSQL client libraries. Optimal on PyPy and almost indistinguishable from psycopg2 on CPython. Not compatible with gevent.

This is the default and preferred driver for PyPy.

pg8000

A pure-Python driver suitable for use with gevent (if the system is monkey-patched). Works on all supported platforms, and can use the COPY protocol even when the system is monkey-patched.

This driver makes use of SET SESSION CHARACTERISTICS and thus may not work well with certain configurations of connection load balancers.

This driver cannot handle OID and TID parameters greater than nine quintillion (2^63).

dsn

Specifies the data source name for connecting to PostgreSQL. A PostgreSQL DSN is a list of parameters separated with whitespace. A typical DSN looks like:

dbname='zodb' user='username' host='localhost' password='pass'

If dsn is omitted, the adapter will connect to a local database with no password. Both the user and database name will match the name of the owner of the current process.