Patroni

4.1.2 verified Fri May 01 auth: no python

Patroni is a Python-based orchestrator for managing high-availability PostgreSQL clusters using Distributed Configuration Stores (DCS) like etcd, Consul, ZooKeeper, or Kubernetes. Current version is 4.1.2. It follows a rapid release cadence with frequent minor and patch releases.

pip install patroni

Common errors

error ImportError: cannot import name 'Patroni' from 'patroni' ↓

cause Importing Patroni directly from the top-level patroni module works only if the package is correctly installed. However, if Patroni was installed from source without building the Cythonized version, the import may fail.

fix

Ensure you have installed Patroni via pip install patroni or from a proper wheel. If using the source, build it first.

error patroni.exceptions.PatroniException: bootstrap: DCS is not accessible ↓

cause Patroni cannot connect to the Distributed Configuration Store (etcd, consul, etc.) during bootstrap.

fix

Check that the DCS endpoint is reachable and that the 'etcd' (or 'consul') configuration section has the correct host/port. If using etcd, verify the cluster is healthy.

error KeyError: 'namespace' ↓

cause The configuration is missing the 'namespace' key, which is required.

fix

Add 'namespace': '/service/' to the top-level configuration dictionary.

Warnings

breaking Patroni v4.x drops support for Python 3.6/3.7. Requires Python 3.8+. ↓

fix Upgrade Python to 3.8 or higher.

gotcha Running multiple Patroni instances with identical config name can cause split-brain. Each node must have a unique 'name'. ↓

fix Ensure 'name' in config is unique per node (e.g., postgresql0, postgresql1).

deprecated Old DCS configuration keys like 'etcd2' and 'consul' changed to 'etcd' and 'consul' with different structure in v3.0+. 'etcd2' is removed in v4.x. ↓

fix Use 'etcd' key instead of 'etcd2'. Refer to docs for the new format.

gotcha Systemd unit files shipped with earlier versions may not restart Patroni automatically on failure. In v4.x, the recommended unit is 'patroni.service' with Restart=always. ↓

fix Update systemd unit to include Restart=always or use the template from the official repository.

breaking Configuration option 'postgresql.bin_dir' is now required in v4.x if psql is not on PATH. ↓

fix Set 'postgresql.bin_dir' to the directory containing PostgreSQL binaries (e.g., /usr/lib/postgresql/14/bin).

Imports

Patroni
wrong
```
import patroni
```
correct
```
from patroni import Patroni
```
Patroni is a class, not a module. Direct import of patroni does not give access to the Patroni constructor.
Ha
```
from patroni.ha import Ha
```

SlotManager

from patroni.postgresql.slots import SlotManager

Quickstart

Minimal Patroni instance using etcd as DCS. Adjust listen addresses, credentials, and PostgreSQL paths.

from patroni import Patroni

config = {
    'namespace': '/service/',
    'scope': 'batman',
    'name': 'postgresql0',
    'restapi': {'listen': '0.0.0.0:8008', 'connect_address': '127.0.0.1:8008'},
    'etcd': {'host': '127.0.0.1:2379'},
    'bootstrap': {
        'dcs': {'ttl': 30, 'loop_wait': 10, 'retry_timeout': 10, 'maximum_lag_on_failover': 1048576},
        'initdb': [{'encoding': 'UTF8'}, {'data-checksums': 'true'}],
        'pg_hba': ['host replication replicator 127.0.0.1/32 md5', 'host all all 0.0.0.0/0 md5'],
        'users': {'admin': {'password': 'admin', 'options': ['createrole', 'createdb']}}
    },
    'postgresql': {
        'listen': '0.0.0.0:5432',
        'connect_address': '127.0.0.1:5432',
        'data_dir': 'data/postgresql0',
        'bin_dir': '/usr/lib/postgresql/14/bin',
        'pgpass': '/tmp/pgpass',
        'authentication': {'replication': {'username': 'replicator', 'password': 'rep-pass'},
                           'superuser': {'username': 'postgres', 'password': 'secret-password'}},
        'parameters': {'unix_socket_directories': '.'}
    },
    'tags': {'nofailover': False, 'noloadbalance': False}
}

patroni = Patroni(config)
patroni.run()