{"id":24215,"library":"patroni","title":"Patroni","description":"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.","status":"active","version":"4.1.2","language":"python","source_language":"en","source_url":"https://github.com/patroni/patroni","tags":["postgresql","high-availability","orchestrator","database","etcd","consul","zookeeper","raft"],"install":[{"cmd":"pip install patroni","lang":"bash","label":"Install Patroni with default dependencies (etcd, consul, zookeeper, raft)."}],"dependencies":[{"reason":"Required for PostgreSQL connectivity.","package":"psycopg2-binary","optional":false},{"reason":"etcd DCS support (optional if using other DCS).","package":"python-etcd","optional":true},{"reason":"Consul DCS support (optional).","package":"python-consul","optional":true},{"reason":"ZooKeeper DCS support (optional).","package":"kazoo","optional":true},{"reason":"RAFT consensus (optional, for standalone).","package":"pysyncobj","optional":true}],"imports":[{"note":"Patroni is a class, not a module. Direct import of patroni does not give access to the Patroni constructor.","wrong":"import patroni","symbol":"Patroni","correct":"from patroni import Patroni"},{"note":"","wrong":"","symbol":"Ha","correct":"from patroni.ha import Ha"},{"note":"","wrong":"","symbol":"SlotManager","correct":"from patroni.postgresql.slots import SlotManager"}],"quickstart":{"code":"from patroni import Patroni\n\nconfig = {\n    'namespace': '/service/',\n    'scope': 'batman',\n    'name': 'postgresql0',\n    'restapi': {'listen': '0.0.0.0:8008', 'connect_address': '127.0.0.1:8008'},\n    'etcd': {'host': '127.0.0.1:2379'},\n    'bootstrap': {\n        'dcs': {'ttl': 30, 'loop_wait': 10, 'retry_timeout': 10, 'maximum_lag_on_failover': 1048576},\n        'initdb': [{'encoding': 'UTF8'}, {'data-checksums': 'true'}],\n        'pg_hba': ['host replication replicator 127.0.0.1/32 md5', 'host all all 0.0.0.0/0 md5'],\n        'users': {'admin': {'password': 'admin', 'options': ['createrole', 'createdb']}}\n    },\n    'postgresql': {\n        'listen': '0.0.0.0:5432',\n        'connect_address': '127.0.0.1:5432',\n        'data_dir': 'data/postgresql0',\n        'bin_dir': '/usr/lib/postgresql/14/bin',\n        'pgpass': '/tmp/pgpass',\n        'authentication': {'replication': {'username': 'replicator', 'password': 'rep-pass'},\n                           'superuser': {'username': 'postgres', 'password': 'secret-password'}},\n        'parameters': {'unix_socket_directories': '.'}\n    },\n    'tags': {'nofailover': False, 'noloadbalance': False}\n}\n\npatroni = Patroni(config)\npatroni.run()","lang":"python","description":"Minimal Patroni instance using etcd as DCS. Adjust listen addresses, credentials, and PostgreSQL paths."},"warnings":[{"fix":"Upgrade Python to 3.8 or higher.","message":"Patroni v4.x drops support for Python 3.6/3.7. Requires Python 3.8+.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure 'name' in config is unique per node (e.g., postgresql0, postgresql1).","message":"Running multiple Patroni instances with identical config name can cause split-brain. Each node must have a unique 'name'.","severity":"gotcha","affected_versions":"all"},{"fix":"Use 'etcd' key instead of 'etcd2'. Refer to docs for the new format.","message":"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.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Update systemd unit to include Restart=always or use the template from the official repository.","message":"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.","severity":"gotcha","affected_versions":"<4.0.0"},{"fix":"Set 'postgresql.bin_dir' to the directory containing PostgreSQL binaries (e.g., /usr/lib/postgresql/14/bin).","message":"Configuration option 'postgresql.bin_dir' is now required in v4.x if psql is not on PATH.","severity":"breaking","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Ensure you have installed Patroni via pip install patroni or from a proper wheel. If using the source, build it first.","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.","error":"ImportError: cannot import name 'Patroni' from 'patroni'"},{"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.","cause":"Patroni cannot connect to the Distributed Configuration Store (etcd, consul, etc.) during bootstrap.","error":"patroni.exceptions.PatroniException: bootstrap: DCS is not accessible"},{"fix":"Add 'namespace': '/service/' to the top-level configuration dictionary.","cause":"The configuration is missing the 'namespace' key, which is required.","error":"KeyError: 'namespace'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}