Highly available elephant herd: HA PostgreSQL cluster using Docker
Clone or download
CyberDem0n Execute pg_upgrade after custom bootstrap if major version doesn't ma…
…tch (#282)

Before doing the actual call of `pg_upgrade`, the `maybe_pg_upgrade.py` script starts the old postgres binary, waits until `pg_is_in_recovery()` starts returning `False` and does a clean shutdown.
Latest commit 4ac25e1 Jan 16, 2019


Spilo: HA PostgreSQL Clusters with Docker

Spilo is a Docker image that provides PostgreSQL and Patroni bundled together. Patroni is a template for PostgreSQL HA. Multiple Spilos can create a resilient High Available PostgreSQL cluster. For this, you'll need to start all participating Spilos with identical etcd addresses and cluster names.

Spilo's name derives from სპილო [spiːlɒ], the Georgian word for "elephant."

Real-World Usage and Plans

Spilo is currently evolving: Its creators are working on a Postgres operator that would make it simpler to deploy scalable Postgres clusters in a Kubernetes environment, and also do maintenance tasks. Spilo would serve as an essential building block for this. There is already a Helm chart that relies on Spilo and Patroni to provision a five-node PostgreSQL HA cluster in a Kubernetes+Google Compute Engine environment. (The Helm chart deploys Spilo Docker images, not just "bare" Patroni.)

How to Use This Docker Image

Spilo's setup assumes that you've correctly configured a load balancer (HAProxy, ELB, Google load balancer) that directs client connections to the master. There are two ways to achieve this: A) if the load balancer relies on the status code to distinguish between the healthy and failed nodes (like ELB), then one needs to configure it to poll the API URL; otherwise, B) you can use callback scripts to change the load balancer configuration dynamically.

Connecting to PostgreSQL

Administrative Connections

PostgreSQL is configured by default to listen to port 5432. Spilo master initializes PostgreSQL and creates the superuser and replication user (postgres and standby by default).

You'll need to setup Spilo to create a database and roles for your application(s). For example:

psql -h myfirstspilo.example.com -p 5432 -U admin -d postgres

Application Connections

Once you have created a database and roles for your application, you can connect to Spilo just like you want to connect to any other PostgreSQL cluster:

psql -h myfirstspilo.example.com -p 5432 -U wow_app -d wow psql -d "postgresql://myfirstspilo.example.com:5432/wow?user=wow_app"


Spilo is configured via environment variables, the values of which are either supplied manually via the environment (whenever Spilo is launched as a set of Docker containers) or added in the configuration file or manifest (whenever Spilo is used in the Docker orchestration environment, such as Kubernetes or Docker Compose).

Please go here to see our list of environment variables.

Issues and Contributing

Spilo welcomes questions via our issues tracker. We also greatly appreciate fixes, feature requests, and updates; before submitting a pull request, please visit our contributor guidelines.


This project uses the Apache 2.0 license.