README.rst
Psycopg 3 is a modern implementation of a PostgreSQL adapter for Python.
Quick version::
pip install "psycopg[binary,pool]"
For further information about installation please check the documentation__.
.. __: https://www.psycopg.org/psycopg3/docs/basic/install.html
.. _Hacking:
In order to work on the Psycopg source code, you must have the
libpq PostgreSQL client library installed on the system. For instance, on
Debian systems, you can obtain it by running::
sudo apt install libpq5
On macOS, run::
brew install libpq
On Windows you can use EnterpriseDB's installers__ to obtain libpq
which is included in the Command Line Tools.
.. __: https://www.enterprisedb.com/downloads/postgres-postgresql-downloads
You can then clone this repository to develop Psycopg::
git clone https://github.com/psycopg/psycopg.git
cd psycopg
Please note that the repository contains the source code of several Python packages, which may have different requirements:
The psycopg directory contains the pure python implementation of
psycopg. The package has only a runtime dependency on the libpq, the
PostgreSQL client library, which should be installed in your system.
The psycopg_c directory contains an optimization module written in
C/Cython. In order to build it you will need a few development tools: please
look at Local installation__ in the docs for the details.
The psycopg_pool directory contains the connection pools__
implementations. This is kept as a separate package to allow a different
release cycle.
.. __: https://www.psycopg.org/psycopg3/docs/basic/install.html#local-installation .. __: https://www.psycopg.org/psycopg3/docs/advanced/pool.html
You can create a local virtualenv and install the packages in development mode__, together with their development and testing
requirements::
python -m venv .venv
source .venv/bin/activate
# Install the base Psycopg package in editable mode
pip install --config-settings editable_mode=strict -e "./psycopg[dev,test]"
# Install the connection pool package in editable mode
pip install --config-settings editable_mode=strict -e ./psycopg_pool
# Install the C speedup extension
pip install ./psycopg_c
.. __: https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs
The --config-settings editable_mode=strict will be probably required
to work around the problem of the editable mode broken__.
.. __: https://github.com/pypa/setuptools/issues/3557
Now hack away! You can run the tests using::
psql -c 'create database psycopg_test'
export PSYCOPG_TEST_DSN="dbname=psycopg_test"
pytest
The project includes some pre-commit__ hooks to check that the code is valid
according to the project coding convention. Please make sure to install them
by running::
pre-commit install
This will allow to check lint errors before submitting merge requests, which will save you time and frustrations.
.. __: https://pre-commit.com/
To use cross-platform zipapps created with shiv__ that include Psycopg
as a dependency you must also have libpq installed. See
the section above <Hacking_>_ for install instructions.