{"id":13440790,"url":"https://github.com/patroni/patroni","last_synced_at":"2025-09-09T20:37:02.427Z","repository":{"id":34763025,"uuid":"38744670","full_name":"patroni/patroni","owner":"patroni","description":"A template for PostgreSQL High Availability with Etcd, Consul, ZooKeeper, or Kubernetes","archived":false,"fork":false,"pushed_at":"2025-05-13T08:12:37.000Z","size":8567,"stargazers_count":7327,"open_issues_count":50,"forks_count":908,"subscribers_count":124,"default_branch":"master","last_synced_at":"2025-05-13T10:58:53.597Z","etag":null,"topics":["consul","etcd","failover","haproxy","high-availability","kubernetes","postgresql","raft","zookeeper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"edx/edx-platform","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patroni.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"docs/CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"docs/security.rst","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-07-08T09:27:19.000Z","updated_at":"2025-05-13T08:12:41.000Z","dependencies_parsed_at":"2023-09-26T14:13:56.273Z","dependency_job_id":"bf7fd176-a471-44f2-8c2a-14583e916044","html_url":"https://github.com/patroni/patroni","commit_stats":{"total_commits":2094,"total_committers":199,"mean_commits":"10.522613065326633","dds":0.7067812798471824,"last_synced_commit":"4c951a29372232789b290721a6159c1d3dc06bdd"},"previous_names":["zalando/patroni"],"tags_count":78,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patroni%2Fpatroni","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patroni%2Fpatroni/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patroni%2Fpatroni/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patroni%2Fpatroni/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patroni","download_url":"https://codeload.github.com/patroni/patroni/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253929358,"owners_count":21985802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["consul","etcd","failover","haproxy","high-availability","kubernetes","postgresql","raft","zookeeper"],"created_at":"2024-07-31T03:01:26.265Z","updated_at":"2025-05-13T10:59:52.740Z","avatar_url":"https://github.com/patroni.png","language":"Python","funding_links":[],"categories":["HarmonyOS","Python","postgresql","kubernetes"],"sub_categories":["Windows Manager"],"readme":"|Tests Status| |Coverage Status|\n\nPatroni: A Template for PostgreSQL HA with ZooKeeper, etcd or Consul\n--------------------------------------------------------------------\n\nYou can find a version of this documentation that is searchable and also easier to navigate at `patroni.readthedocs.io \u003chttps://patroni.readthedocs.io\u003e`__.\n\n\nThere are many ways to run high availability with PostgreSQL; for a list, see the `PostgreSQL Documentation \u003chttps://wiki.postgresql.org/wiki/Replication,_Clustering,_and_Connection_Pooling\u003e`__.\n\nPatroni is a template for high availability (HA) PostgreSQL solutions using Python. For maximum accessibility, Patroni supports a variety of distributed configuration stores like `ZooKeeper \u003chttps://zookeeper.apache.org/\u003e`__, `etcd \u003chttps://github.com/coreos/etcd\u003e`__, `Consul \u003chttps://github.com/hashicorp/consul\u003e`__ or `Kubernetes \u003chttps://kubernetes.io\u003e`__. 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.\n\nWe 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.\n\nCurrently supported PostgreSQL versions: 9.3 to 17.\n\n**Note to Citus users**: Starting from 3.0 Patroni nicely integrates with the `Citus \u003chttps://github.com/citusdata/citus\u003e`__ database extension to Postgres. Please check the `Citus support page \u003chttps://github.com/patroni/patroni/blob/master/docs/citus.rst\u003e`__ in the Patroni documentation for more info about how to use Patroni high availability together with a Citus distributed cluster.\n\n**Note to Kubernetes users**: Patroni can run natively on top of Kubernetes. Take a look at the `Kubernetes \u003chttps://github.com/patroni/patroni/blob/master/docs/kubernetes.rst\u003e`__ chapter of the Patroni documentation.\n\n.. contents::\n    :local:\n    :depth: 1\n    :backlinks: none\n\n=================\nHow Patroni Works\n=================\n\nPatroni (formerly known as Zalando's Patroni) originated as a fork of `Governor \u003chttps://github.com/compose/governor\u003e`__, the project from Compose. It includes plenty of new features.\n\nFor additional background info, see:\n\n* `Elephants on Automatic: HA Clustered PostgreSQL with Helm \u003chttps://www.youtube.com/watch?v=CftcVhFMGSY\u003e`_, talk by Josh Berkus and Oleksii Kliukin at KubeCon Berlin 2017\n* `PostgreSQL HA with Kubernetes and Patroni \u003chttps://www.youtube.com/watch?v=iruaCgeG7qs\u003e`__, talk by Josh Berkus at KubeCon 2016 (video)\n* `Feb. 2016 Zalando Tech blog post \u003chttps://engineering.zalando.com/posts/2016/02/zalandos-patroni-a-template-for-high-availability-postgresql.html\u003e`__\n\n==================\nDevelopment Status\n==================\n\nPatroni is in active development and accepts contributions. See our `Contributing \u003chttps://github.com/patroni/patroni/blob/master/docs/contributing_guidelines.rst\u003e`__ section below for more details.\n\nWe report new releases information `here \u003chttps://github.com/patroni/patroni/releases\u003e`__.\n\n=========\nCommunity\n=========\n\nThere are two places to connect with the Patroni community: `on github \u003chttps://github.com/patroni/patroni\u003e`__, via Issues and PRs, and on channel `#patroni \u003chttps://postgresteam.slack.com/archives/C9XPYG92A\u003e`__ in the `PostgreSQL Slack \u003chttps://pgtreats.info/slack-invite\u003e`__.  If you're using Patroni, or just interested, please join us.\n\n===================================\nTechnical Requirements/Installation\n===================================\n\n**Pre-requirements for Mac OS**\n\nTo install requirements on a Mac, run the following:\n\n::\n\n    brew install postgresql etcd haproxy libyaml python\n\n**Psycopg**\n\nStarting from `psycopg2-2.8 \u003chttp://initd.org/psycopg/articles/2019/04/04/psycopg-28-released/\u003e`__ the 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.\nSince in the python world it is not possible to specify dependency as ``psycopg2 OR psycopg2-binary`` you will have to decide how to install it.\n\nThere are a few options available:\n\n1. Use the package manager from your distro\n\n::\n\n    sudo apt-get install python3-psycopg2  # install psycopg2 module on Debian/Ubuntu\n    sudo yum install python3-psycopg2      # install psycopg2 on RedHat/Fedora/CentOS\n\n2. Specify one of `psycopg`, `psycopg2`, or `psycopg2-binary` in the list of dependencies when installing Patroni with pip (see below).\n\n\n**General installation for pip**\n\nPatroni can be installed with pip:\n\n::\n\n    pip install patroni[dependencies]\n\nwhere dependencies can be either empty, or consist of one or more of the following:\n\netcd or etcd3\n    `python-etcd` module in order to use Etcd as DCS\nconsul\n    `py-consul` module in order to use Consul as DCS\nzookeeper\n    `kazoo` module in order to use Zookeeper as DCS\nexhibitor\n    `kazoo` module in order to use Exhibitor as DCS (same dependencies as for Zookeeper)\nkubernetes\n    `kubernetes` module in order to use Kubernetes as DCS in Patroni\nraft\n    `pysyncobj` module in order to use python Raft implementation as DCS\naws\n    `boto3` in order to use AWS callbacks\nsystemd\n    `systemd-python` in order to use sd_notify integration\nall\n    all of the above (except psycopg family)\npsycopg3\n    `psycopg[binary]\u003e=3.0.0` module\npsycopg2\n    `psycopg2\u003e=2.5.4` module\npsycopg2-binary\n    `psycopg2-binary` module\n\nFor example, the command in order to install Patroni together with psycopg3, dependencies for Etcd as a DCS, and AWS callbacks is:\n\n::\n\n    pip install patroni[psycopg3,etcd3,aws]\n\nNote that external tools to call in the replica creation or custom bootstrap scripts (i.e. WAL-E) should be installed independently of Patroni.\n\n=======================\nRunning and Configuring\n=======================\n\nTo get started, do the following from different terminals:\n::\n\n    \u003e etcd --data-dir=data/etcd --enable-v2=true\n    \u003e ./patroni.py postgres0.yml\n    \u003e ./patroni.py postgres1.yml\n\nYou 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.\n\nAdd more ``postgres*.yml`` files to create an even larger cluster.\n\nPatroni provides an `HAProxy \u003chttp://www.haproxy.org/\u003e`__ configuration, which will give your application a single endpoint for connecting to the cluster's leader. To configure,\nrun:\n\n::\n\n    \u003e haproxy -f haproxy.cfg\n\n::\n\n    \u003e psql --host 127.0.0.1 --port 5000 postgres\n\n==================\nYAML Configuration\n==================\n\nGo `here \u003chttps://github.com/patroni/patroni/blob/master/docs/dynamic_configuration.rst\u003e`__ for comprehensive information about settings for etcd, consul, and ZooKeeper. And for an example, see `postgres0.yml \u003chttps://github.com/patroni/patroni/blob/master/postgres0.yml\u003e`__.\n\n=========================\nEnvironment Configuration\n=========================\n\nGo `here \u003chttps://github.com/patroni/patroni/blob/master/docs/ENVIRONMENT.rst\u003e`__ for comprehensive information about configuring(overriding) settings via environment variables.\n\n===================\nReplication Choices\n===================\n\nPatroni uses Postgres' streaming replication, which is asynchronous by default. Patroni's asynchronous replication configuration allows for ``maximum_lag_on_failover`` settings. 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. See `replication modes documentation \u003chttps://github.com/patroni/patroni/blob/master/docs/replication_modes.rst\u003e`__ for details.\n\n======================================\nApplications Should Not Use Superusers\n======================================\n\nWhen 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 the ``superuser_reserved_connections`` setting. If Patroni cannot access the Primary because the connection pool is full, behavior will be undesirable.\n\n.. |Tests Status| image:: https://github.com/patroni/patroni/actions/workflows/tests.yaml/badge.svg\n   :target: https://github.com/patroni/patroni/actions/workflows/tests.yaml?query=branch%3Amaster\n.. |Coverage Status| image:: https://coveralls.io/repos/patroni/patroni/badge.svg?branch=master\n   :target: https://coveralls.io/github/patroni/patroni?branch=master\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatroni%2Fpatroni","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatroni%2Fpatroni","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatroni%2Fpatroni/lists"}