Migrating to Patroni
Suggest editsThis page describes how to migrate an existing Postgres cluster to Patroni managed cluster.
Overview of steps
- Disable current HA solution, if any.
- Perform the following steps on all nodes, starting with the primary and then going with standbys:
- Disable Postgres systemd unit.
- Create a YAML configuration file for Patroni. If you use replication slots in the existing cluster, then make sure to configure permanent slots so Patroni does not delete them while migrating.
- Enable Patroni systemd unit.
- Start Patroni systemd unit.
- Let Patroni take over the "startup procedure" of Postgres:
- Restart all standby nodes.
- Schedule a restart of the primary node during a maintenance window.
- Clean up slots from original cluster, if any:
- Once Postgres is able to consume all WALs between the original slots and the new slots that have been created by Patroni, then remove the permanent slots configuration. This will allow Patroni to drop the original slots.
Note: The above procedure was designed for minimal downtime. We strongly recommend that you conduct these steps during a scheduled maintenance window, and test at least a switchover/switchback operation after all the above steps have been performed.
More detailed example
In this section we will cover an example with more detailed steps for migrating an existing Postgres cluster to a Patroni managed cluster.
For the sake of simplicity, we will put some notes, when relevant, considering three possibilities for an existing cluster, just so we don't repeat ourselves regarding similar steps:
For the example, the following assumptions are made:
- You already have a working
etcd
cluster — refer to Installing and configuring etcd to install and set upetcd
to be used with Patroni. Theetcd
cluster here is composed of the following nodes:etcd-node-1
.etcd-node-2
.etcd-node-3
.
- The Postgres cluster that needs to be migrated has the following nodes:
postgres-node-1
— the primary node.postgres-node-2
— a standby ofpostgres-node-1
.postgres-node-3
— a standby ofpostgres-node-1
.
- The existing Postgres cluster uses replication slots to control replication from primary to standbys, and they are named:
slot_for_postgres_node_2
— slot used by replica nodepostgres-node-2
.slot_for_postgres_node_3
— slot used by replica nodepostgres-node-3
.
- You already have the following Postgres users in the cluster:
postgres
with passwordpostgres_password
— Postgres superuser.replicator
with passwordreplicator_password
— used by replication connections.rewind
with passwordrewind_password
— user with rights for executingpg_rewind
.
- You are running PostgreSQL with the following characteristics:
- Postgres is running on port
5432
. - Postgres data directory is
/var/lib/postgres/data
. - Postgres binaries directory is
/usr/postgres/bin
.
- Postgres is running on port
- You have already installed Patroni on all the Postgres nodes.
- The systemd unit names are:
postgres
— for Postgres.patroni
— for Patroni.edb-efm
— in case EFM is being used in the existing cluster.repmgrd
— in case repmgr is being used in the existing cluster.
- The configuration files are:
/etc/patroni.yml
— for Patroni./etc/repmgr.conf
— in case repmgr is being used in the existing cluster.
- The cluster name is
test_cluster
. This is relevant only for EFM and Patroni.
Notes: