Package: patroni
Patroni: A Template for PostgreSQL HA with ZooKeeper, etcd or ConsulYou can find a version of this documentation that is searchable and also easier to navigate atpatroni.readthedocs.io.There are many ways to run high availability with PostgreSQL; for a list, see thePostgreSQL Documentation.Patroni is a template for high availability (HA) PostgreSQL solutions using Python. For maximum accessibility, Patroni supports a variety of distributed configuration stores likeZooKeeper,etcd,ConsulorKubernetes. Database engineers, DBAs, DevOps engineers, and SREs who are looking to quickly deploy HA PostgreSQL in datacenters - or anywhere else - will hopefully find it useful.We call Patroni a “template” because it is far from being a one-size-fits-all or plug-and-play replication system. It will have its own caveats. Use wisely.Currently supported PostgreSQL versions: 9.3 to 16.Note to Citus users: Starting from 3.0 Patroni nicely integrates with theCitusdatabase extension to Postgres. Please check theCitus support pagein the Patroni documentation for more info about how to use Patroni high availability together with a Citus distributed cluster.Note to Kubernetes users: Patroni can run natively on top of Kubernetes. Take a look at theKuberneteschapter of the Patroni documentation.How Patroni WorksDevelopment StatusCommunityTechnical Requirements/InstallationRunning and ConfiguringYAML ConfigurationEnvironment ConfigurationReplication ChoicesApplications Should Not Use SuperusersHow Patroni WorksPatroni originated as a fork ofGovernor, the project from Compose. It includes plenty of new features.For an example of a Docker-based deployment with Patroni, seeSpilo, currently in use at Zalando.For additional background info, see:Elephants on Automatic: HA Clustered PostgreSQL with Helm, talk by Josh Berkus and Oleksii Kliukin at KubeCon Berlin 2017PostgreSQL HA with Kubernetes and Patroni, talk by Josh Berkus at KubeCon 2016 (video)Feb. 2016 Zalando Tech blog postDevelopment StatusPatroni is in active development and accepts contributions. See ourContributingsection below for more details.We report new releases informationhere.CommunityThere are two places to connect with the Patroni community:on github, via Issues and PRs, and on channel#patroniin thePostgreSQL Slack.  If you’re using Patroni, or just interested, please join us.Technical Requirements/InstallationPre-requirements for Mac OSTo install requirements on a Mac, run the following:brew install postgresql etcd haproxy libyaml pythonPsycopgStarting frompsycopg2-2.8the binary version of psycopg2 will no longer be installed by default. Installing it from the source code requires C compiler and postgres+python dev packages.
Since in the python world it is not possible to specify dependency aspsycopg2 ORpsycopg2-binaryyou will have to decide how to install it.There are a few options available:Use the package manager from your distrosudo apt-get install python3-psycopg2  # install psycopg2 module on Debian/Ubuntu
sudo yum install python3-psycopg2      # install psycopg2 on RedHat/Fedora/CentOSSpecify one ofpsycopg,psycopg2, orpsycopg2-binaryin the list of dependencies when installing Patroni with pip (see below).General installation for pipPatroni can be installed with pip:pip install patroni[dependencies]where dependencies can be either empty, or consist of one or more of the following:etcd or etcd3python-etcdmodule in order to use Etcd as DCSconsulpython-consulmodule in order to use Consul as DCSzookeeperkazoomodule in order to use Zookeeper as DCSexhibitorkazoomodule in order to use Exhibitor as DCS (same dependencies as for Zookeeper)kuberneteskubernetesmodule in order to use Kubernetes as DCS in Patroniraftpysyncobjmodule in order to use python Raft implementation as DCSawsboto3in order to use AWS callbacksallall of the above (except psycopg family)psycopg3psycopg[binary]>=3.0.0modulepsycopg2psycopg2>=2.5.4modulepsycopg2-binarypsycopg2-binarymoduleFor example, the command in order to install Patroni together with psycopg3, dependencies for Etcd as a DCS, and AWS callbacks is:pip install patroni[psycopg3,etcd3,aws]Note that external tools to call in the replica creation or custom bootstrap scripts (i.e. WAL-E) should be installed independently of Patroni.Running and ConfiguringTo get started, do the following from different terminals:> etcd --data-dir=data/etcd --enable-v2=true
> ./patroni.py postgres0.yml
> ./patroni.py postgres1.ymlYou will then see a high-availability cluster start up. Test different settings in the YAML files to see how the cluster’s behavior changes. Kill some of the components to see how the system behaves.Add morepostgres*.ymlfiles to create an even larger cluster.Patroni provides anHAProxyconfiguration, which will give your application a single endpoint for connecting to the cluster’s leader. To configure,
run:> haproxy -f haproxy.cfg> psql --host 127.0.0.1 --port 5000 postgresYAML ConfigurationGoherefor comprehensive information about settings for etcd, consul, and ZooKeeper. And for an example, seepostgres0.yml.Environment ConfigurationGoherefor comprehensive information about configuring(overriding) settings via environment variables.Replication ChoicesPatroni uses Postgres’ streaming replication, which is asynchronous by default. Patroni’s asynchronous replication configuration allows formaximum_lag_on_failoversettings. This setting ensures failover will not occur if a follower is more than a certain number of bytes behind the leader. This setting should be increased or decreased based on business requirements. It’s also possible to use synchronous replication for better durability guarantees. Seereplication modes documentationfor details.Applications Should Not Use SuperusersWhen connecting from an application, always use a non-superuser. Patroni requires access to the database to function properly. By using a superuser from an application, you can potentially use the entire connection pool, including the connections reserved for superusers, with thesuperuser_reserved_connectionssetting. If Patroni cannot access the Primary because the connection pool is full, behavior will be undesirable.