Chatting

If you have a question, looking for an interactive troubleshooting help or want to chat with other Patroni users, join us on channel #patroni in the PostgreSQL Slack .

Reporting bugs

Before reporting a bug please make sure to reproduce it with the latest Patroni version ! Also please double check if the issue already exists in our Issues Tracker .

Running tests

Requirements for running behave tests:

  1. PostgreSQL packages including contrib modules need to be installed.

  2. PostgreSQL binaries must be available in your PATH . You may need to add them to the path with something like PATH=/usr/lib/postgresql/11/bin:$PATH python -m behave .

  3. If you’d like to test with external DCSs (e.g., Etcd, Consul, and Zookeeper) you’ll need the packages installed and respective services running and accepting unencrypted/unprotected connections on localhost and default port. In the case of Etcd or Consul, the behave test suite could start them up if binaries are available in the PATH .

Install dependencies: 

# You may want to use Virtualenv or specify pip3.
pip install -r requirements.txt
pip install -r requirements.dev.txt

After you have all dependencies installed, you can run the various test suites: 

# You may want to use Virtualenv or specify python3.

# Run flake8 to check syntax and formatting:
python setup.py flake8

# Run the pytest suite in tests/:
python setup.py test

# Moreover, you may want to run tests in different scopes for debugging purposes,
# the -s option include print output during test execution.
# Tests in pytest typically follow the pattern: FILEPATH::CLASSNAME::TESTNAME.
pytest -s tests/test_api.py
pytest -s tests/test_api.py::TestRestApiHandler
pytest -s tests/test_api.py::TestRestApiHandler::test_do_GET

# Run the behave (https://behave.readthedocs.io/en/latest/) test suite in features/;
# modify DCS as desired (raft has no dependencies so is the easiest to start with):
DCS=raft python -m behave

Testing with tox

To run tox tests you only need to install one dependency (other than Python) 

pip install tox>=4

If you wish to run behave tests then you also need docker installed.

Tox configuration in tox.ini has "environments" to run the following tasks:

  • lint: Python code lint with flake8

  • test: unit tests for all available python interpreters with pytest , generates XML reports or HTML reports if a TTY is detected

  • dep: detect package dependency conflicts using pipdeptree

  • type: static type checking with pyright

  • black: code formatting with black

  • docker-build: build docker image used for the behave env

  • docker-cmd: run arbitrary command with the above image

  • docker-behave-etcd: run tox for behave tests with above image

  • py*behave: run behave with available python interpreters (without docker, although this is what is called inside docker containers)

  • docs: build docs with sphinx

Running tox

To run the default env list; dep, lint, test, and docs, just run: 

tox

The test envs can be run with the label test : 

tox -m test

The behave docker tests can be run with the label behave : 

tox -m behave

Similarly, docs has the label docs .

All other envs can be run with their respective env names: 

tox -e lint
tox -e py39-test-lin

It is also possible to select partial env lists using factors . For example, if you want to run all envs for python 3.10: 

tox -f py310

This is equivalent to running all the envs listed below: 

$ tox -l -f py310
py310-test-lin
py310-test-mac
py310-test-win
py310-type-lin
py310-type-mac
py310-type-win
py310-behave-etcd-lin
py310-behave-etcd-win
py310-behave-etcd-mac

You can list all configured combinations of environments with tox (>=v4) like so 

tox l

The envs test and docs will attempt to open the HTML output files when the job completes, if tox is run with an active terminal. This is intended to be for benefit of the developer running this env locally. It will attempt to run open on a mac and xdg-open on Linux. To use a different command set the env var OPEN_CMD to the name or path of the command. If this step fails it will not fail the run overall. If you want to disable this facility set the env var OPEN_CMD to the : no-op command. 

OPEN_CMD=: tox -m docs

Behave tests

Behave tests with -m behave will build docker images based on PG_MAJOR version 11 through 16 and then run all behave tests. This can take quite a long time to run so you might want to limit the scope to a select version of Postgres or to a specific feature set or steps.

To specify the version of postgres include the full name of the dependent image build env that you want and then the behave env name. For instance if you want Postgres 14 use: 

tox -e pg14-docker-build,pg14-docker-behave-etcd-lin

If on the other hand you want to test a specific feature you can pass positional arguments to behave. This will run the watchdog behave feature test scenario with all versions of Postgres. 

tox -m behave -- features/watchdog.feature

Of course you can combine the two.

Contributing a pull request

  1. Fork the repository, develop and test your code changes.

  2. Reflect changes in the user documentation.

  3. Submit a pull request with a clear description of the changes objective. Link an existing issue if necessary.

You’ll get feedback about your pull request as soon as possible.

Happy Patroni hacking ;-)