Introduction - Psycopg 2.7.3 documentation
Introduction
Psycopg is a PostgreSQL adapter for the Python programming language. It is a wrapper for the libpq , the official PostgreSQL client library.
The
psycopg2
package is the current mature implementation of the adapter: it
is a C extension and as such it is only compatible with
CPython
. If you want
to use Psycopg on a different Python implementation (PyPy, Jython, IronPython)
there is an experimental
porting of Psycopg for Ctypes
, but it is not as
mature as the C implementation yet.
The current
psycopg2
implementation supports:
- Python 2 versions from 2.6 to 2.7
- Python 3 versions from 3.2 to 3.6
- PostgreSQL server versions from 7.4 to 9.6
- PostgreSQL client library version from 9.1
Binary install from PyPI
psycopg2
is
available on PyPI
in the form of
wheel
packages for the
most common platform (Linux, OSX, Windows): this should make you able to
install a binary version of the module including all the dependencies simply
using:
$ pip install psycopg2
Make sure to use an up-to-date version of
pip
(you can upgrade it
using something like
pip
install
-U
pip
)
Note
The binary packages come with their own versions of a few C libraries,
among which
libpq
and
libssl
, which will be used regardless of other
libraries available on the client: upgrading the system libraries will not
upgrade the libraries used by
psycopg2
. Please build
psycopg2
from
source if you want to maintain binary upgradeability.
Warning
Because the
psycopg
wheel package uses its own
libssl
binary, it is
incompatible with other extension modules binding with
libssl
as well,
for instance the Python
ssl
module: the result will likely be a
segfault. If you need using both
psycopg2
and other libraries using
libssl
please
install psycopg from source
.
If you prefer to use the system libraries available on your client you can use
the
pip
--no-binary
option:
$ pip install --no-binary psycopg2
which can be specified in your
requirements.txt
files too, e.g. use:
psycopg2>=2.7,<2.8 --no-binary :all:
to use the last bugfix release of the
psycopg2
2.7 package, specifying to
always compile it from source. Of course in this case you will have to meet
the
build prerequisites
.
Install from source
You can download a copy of Psycopg source files from the Psycopg download page or from PyPI .
Build prerequisites
These notes illustrate how to compile Psycopg on Linux. If you want to compile Psycopg on other platforms you may have to adjust some details accordingly.
Psycopg is a C wrapper around the libpq PostgreSQL client library. To install it from sources you will need:
-
A C compiler.
-
The Python header files. They are usually installed in a package such as python-dev . A message such as error: Python.h: No such file or directory is an indication that the Python headers are missing.
-
The libpq header files. They are usually installed in a package such as libpq-dev . If you get an error: libpq-fe.h: No such file or directory you are missing them.
-
The pg_config program: it is usually installed by the libpq-dev package but sometimes it is not in a
PATH
directory. Having it in thePATH
greatly streamlines the installation, so try runningpg_config --version
: if it returns an error or an unexpected version number then locate the directory containing the pg_config shipped with the right libpq version (usually/usr/lib/postgresql/X.Y/bin/
) and add it to thePATH
:$ export PATH=/usr/lib/postgresql/X.Y/bin/:$PATH
You only need pg_config to compile
psycopg2
, not for its regular usage.
Once everything is in place it’s just a matter of running the standard:
$ python setup.py build
$ python setup.py install
Runtime requirements
Unless you compile
psycopg2
as a static library, or you install it from a
self-contained wheel package, it will need the
libpq
library at runtime
(usually distributed in a
libpq.so
or
libpq.dll
file).
psycopg2
relies on the host OS to find the library if the library is installed in a
standard location there is usually no problem; if the library is in a
non-standard location you will have to tell somehow Psycopg how to find it,
which is OS-dependent (for instance setting a suitable
LD_LIBRARY_PATH
on Linux).
Note
The libpq header files used to compile
psycopg2
should match the
version of the library linked at runtime. If you get errors about missing
or mismatching libraries when importing
psycopg2
check (e.g. using
ldd
) if the module
psycopg2/_psycopg.so
is linked to the
right
libpq.so
.
Note
Whatever version of libpq
psycopg2
is compiled with, it will be
possible to connect to PostgreSQL servers of any supported version: just
install the most recent libpq version or the most practical, without
trying to match it to the version of the PostgreSQL server you will have
to connect to.
Non-standard builds
If you have less standard requirements such as:
- creating a debug build ,
-
using
pg_config
not in the
PATH
, -
supporting
mx.DateTime
,
then take a look at the
setup.cfg
file.
Some of the options available in
setup.cfg
are also available as command
line arguments of the
build_ext
sub-command. For instance you can specify
an alternate
pg_config
location using:
$ python setup.py build_ext --pg-config /path/to/pg_config build
Use
python
setup.py
build_ext
--help
to get a list of the options
supported.
Creating a debug build
In case of problems, Psycopg can be configured to emit detailed debug messages, which can be very useful for diagnostics and to report a bug. In order to create a debug package:
- Download and unpack the Psycopg source package.
-
Edit the
setup.cfg
file adding thePSYCOPG_DEBUG
flag to thedefine
option. - Compile and install the package.
-
Set the
PSYCOPG_DEBUG
environment variable:
$ export PSYCOPG_DEBUG=1
-
Run your program (making sure that the
psycopg2
package imported is the one you just compiled and not e.g. the system one): you will have a copious stream of informations printed on stderr.
Running the test suite
Once
psycopg2
is installed you can run the test suite to verify it is
working correctly. You can run:
$ python -c "from psycopg2 import tests; tests.unittest.main(defaultTest='tests.test_suite')" --verbose
The tests run against a database called
psycopg2_test
on UNIX socket and
the standard port. You can configure a different database to run the test by
setting the environment variables:
-
PSYCOPG2_TESTDB
-
PSYCOPG2_TESTDB_HOST
-
PSYCOPG2_TESTDB_PORT
-
PSYCOPG2_TESTDB_USER
The database should already exist before running the tests.
If you still have problems
Try the following. In order:
- Read again the Build prerequisites .
- Read the FAQ .
-
Google for
psycopg2
your error message . Especially useful the week after the release of a new OS X version. - Write to the Mailing List .
-
Complain on your blog or on Twitter that
psycopg2
is the worst package ever and about the quality time you have wasted figuring out the correctARCHFLAGS
. Especially useful from the Starbucks near you.