0% found this document useful (0 votes)

7 views

Distribution For Postgresql Documentation: 15.3 (June 28, 2023)

Uploaded by

Vijay

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

7 views

Distribution For Postgresql Documentation: 15.3 (June 28, 2023)

Uploaded by

Vijay

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 112

Distribution for

PostgreSQL
Documentation
15.3 (June 28, 2023)

Percona Technical Documentation Team

Percona LLC, © 2023

Table of contents

1. Percona Distribution for PostgreSQL 15 Documentation 3

2. Release Notes 5

2.1 Percona Distribution for PostgreSQL release notes 5

2.2 Percona Distribution for PostgreSQL 15.3 (2023-06-28) 6

2.3 Percona Distribution for PostgreSQL 15.2 Update (2023-05-22) 8

2.4 Percona Distribution for PostgreSQL 15.2 (2023-03-20) 9

2.5 Percona Distribution for PostgreSQL 15.1 (2022-11-21) 11

2.6 Percona Distribution for PostgreSQL 15.0 (2022-10-24) 13

3. Installation and Upgrade 16

3.1 Install Percona Distribution for PostgreSQL 16

3.2 Migrate from PostgreSQL to Percona Distribution for PostgreSQL 29

3.3 Upgrading Percona Distribution for PostgreSQL from 14 to 15 34

3.4 Minor Upgrade of Percona Distribution for PostgreSQL 43

4. Extensions 45

4.1 pg_stat_monitor 45

5. Solutions 52

5.1 High availability 52

5.2 Backup and disaster recovery 82

5.3 Spatial data handling 97

5.4 LDAP Authentication 106

6. Uninstalling Percona Distribution for PostgreSQL 107

7. Copyright and licensing information 109

7.1 Documentation licensing 109

8. Trademark Policy 111

2 of 112 Percona LLC, © 2023

1. Percona Distribution for PostgreSQL 15 Documentation

Percona Distribution for PostgreSQL is a collection of tools to assist you in managing your PostgreSQL
database system: it installs PostgreSQL and complements it by a selection of extensions that enable solving
essential practical tasks efficiently:

• HAProxy - a high-availability and load-balancing solution

• Patroni is an HA (High Availability) solution for PostgreSQL.
• pgAudit provides detailed session or object audit logging via the standard PostgreSQL logging facility
• pgAudit set_user - The set_user part of pgAudit extension provides an additional layer of logging and
control when unprivileged users must escalate themselves to superuser or object owner roles in order to
perform needed maintenance tasks.

• pgBackRest is a backup and restore solution for PostgreSQL

• pgBadger - a fast PostgreSQL Log Analyzer.

• PgBouncer - a lightweight connection pooler for PostgreSQL

• pgpool2 - a middleware between PostgreSQL server and client for high availability, connection pooling
and load balancing.

• pg_repack rebuilds PostgreSQL database objects

• pg_stat_monitor collects and aggregates statistics for PostgreSQL and provides histogram information.

• PostGIS allows storing and manipulating spacial data in PostgreSQL.

• wal2json - a PostgreSQL logical decoding JSON output plugin.

• A collection of additional PostgreSQL contrib extensions

Get started{ .md-button } What's new{ .md-button }

See also

Percona Blog:

• pgBackRest - A Great Backup Solution and a Wonderful Year of Growth

• Securing PostgreSQL as an Enterprise-Grade Environment

Percona Distribution for PostgreSQL is also shipped with the libpq library. It contains "a set of library functions
that allow client programs to pass queries to the PostgreSQL backend server and to receive the results of
these queries."

3 of 112 Percona LLC, © 2023

1. Percona Distribution for PostgreSQL 15 Documentation

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: June 28, 2023

Created: June 4, 2021

4 of 112 Percona LLC, © 2023

2. Release Notes

2.1 Percona Distribution for PostgreSQL release notes

• Percona Distribution for PostgreSQL 15.3 (2023-06-28)
• Percona Distribution for PostgreSQL 15.2 Update (2023-05-22)
• Percona Distribution for PostgreSQL 15.2 (2023-03-20)
• Percona Distribution for PostgreSQL 15.1 (2022-11-21)
• Percona Distribution for PostgreSQL 15 (2022-10-24)

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: June 28, 2023

Created: June 4, 2021

5 of 112 Percona LLC, © 2023

2.2 Percona Distribution for PostgreSQL 15.3 (2023-06-28)

Release date: June 28, 2023

Installation: Installing Percona Distribution for PostgreSQL

Percona Distribution for PostgreSQL is a solution with the collection of tools from PostgreSQL community that
are tested to work together and serve to assist you in deploying and managing PostgreSQL. The aim of
Percona Distribution for PostgreSQL is to address the operational issues like High-Availability, Disaster
Recovery, Security, Performance and Scalability and others that enterprises are facing.

This release of Percona Distribution for PostgreSQL is based on PostgreSQL 15.3.

2.2.1 Release Highlights

• Percona Distribution for PostgreSQL components now include PostGIS - the open-source extension that
allows storing and manipulating spacial data in PostgreSQL.

The following is the list of extensions available in Percona Distribution for PostgreSQL.

Extension Version Description

HAProxy 2.6.13 a high-availability and load-balancing solution

Patroni 3.0.2 a HA (High Availability) solution for PostgreSQL

PgAudit 1.7.0 provides detailed session or object audit logging via the standard
logging facility provided by PostgreSQL

pgAudit set_user 4.0.1 provides an additional layer of logging and control when
unprivileged users must escalate themselves to superusers or
object owner roles in order to perform needed maintenance
tasks.

pgBackRest 2.44 a backup and restore solution for PostgreSQL

pgBadger 12.1 a fast PostgreSQL Log Analyzer.

PgBouncer 1.19.1 a lightweight connection pooler for PostgreSQL

pgpool2 4.4.3 a middleware between PostgreSQL server and client for high
availability, connection pooling and load balancing.

pg_repack 1.4.8 rebuilds PostgreSQL database objects

pg_stat_monitor 2.0.1 collects and aggregates statistics for PostgreSQL and provides
histogram information.

PostGIS 3.3.3 a spatial extension for PostgreSQL.

PostgreSQL 250 PostgreSQL database-cluster manager. It provides a structure

Common under which multiple versions of PostgreSQL may be installed
and/or multiple clusters maintained at one time.

wal2json 2.5 a PostgreSQL logical decoding JSON output plugin

6 of 112 Percona LLC, © 2023

2.2.1 Release Highlights

Percona Distribution for PostgreSQL also includes the following packages:

• llvm 12.0.1 packages for Red Hat Enterprise Linux 8 / CentOS 8. This fixes compatibility issues with LLVM
from upstream.
• supplemental ETCD packages which can be used for setting up Patroni clusters. These packages are
available for the following operating systems:

Operating Package Version Description

System

CentOS 8 etcd 3.3.11 A consistent, distributed key-value

store

python3-python- 0.4.3 A Python client for ETCD

etcd

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: June 28, 2023

Created: November 21, 2022

7 of 112 Percona LLC, © 2023

2.3 Percona Distribution for PostgreSQL 15.2 Update (2023-05-22)

Release date: May 22, 2023

Installation: Installing Percona Distribution for PostgreSQL

This update of Percona Distribution for PostgreSQL includes the new version of pg_stat_monitor 2.0.1 that
fixes the issues with the database failure.

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: May 22, 2023

Created: May 17, 2023

8 of 112 Percona LLC, © 2023

2.4 Percona Distribution for PostgreSQL 15.2 (2023-03-20)

Release date: March 20, 2023

Installation: Installing Percona Distribution for PostgreSQL

This release of Percona Distribution for PostgreSQL is based on PostgreSQL 15.2.

2.4.1 Release Highlights

• A new major version of pg_stat_monitor 2.0.0 has been released and is now generally available with
Percona Distribution for PostgreSQL.

• A new extension pgpool - a middleware between PostgreSQL server and client for high availability,
connection pooling and load balancing - is added.

• Percona Distribution for PostgreSQL is now available on Red Hat Enterprise Linux 9 and compatible
derivatives

The following is the list of extensions available in Percona Distribution for PostgreSQL.

Extension Version Description

Patroni 3.0.1 a HA (High Availability) solution for PostgreSQL

PgAudit 1.7.0 provides detailed session or object audit logging via the standard
logging facility provided by PostgreSQL

pgBackRest 2.43 a backup and restore solution for PostgreSQL

pgBadger 12.0 a fast PostgreSQL Log Analyzer.

PgBouncer 1.18.0 a lightweight connection pooler for PostgreSQL

pg_repack 1.4.8 rebuilds PostgreSQL database objects

pg_stat_monitor 2.0.0 collects and aggregates statistics for PostgreSQL and provides
histogram information.

PostgreSQL 247 PostgreSQL database-cluster manager. It provides a structure

Common under which multiple versions of PostgreSQL may be installed
and/or multiple clusters maintained at one time.

wal2json 2.5 a PostgreSQL logical decoding JSON output plugin

HAProxy 2.5.11 a high-availability and load-balancing solution

pgpool2 4.4.2 a middleware between PostgreSQL server and client for high
availability, connection pooling and load balancing.

9 of 112 Percona LLC, © 2023

2.4.1 Release Highlights

Percona Distribution for PostgreSQL also includes the following packages:

Operating Package Version Description

System

CentOS 8 etcd 3.3.11 A consistent, distributed key-value

store

python3-python- 0.4.3 A Python client for ETCD

etcd

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: April 14, 2023

Created: November 21, 2022

10 of 112 Percona LLC, © 2023

2.5 Percona Distribution for PostgreSQL 15.1 (2022-11-21)

Release date: November 21, 2022

Installation: Installing Percona Distribution for PostgreSQL

This release of Percona Distribution for PostgreSQL is based on PostgreSQL 15.1.

Percona Distribution for PostgreSQL now includes the meta-packages that simplify its installation. The
percona-ppg-server meta-package installs PostgreSQL and the extensions, while percona-ppg-server-ha
package installs high-availability components that are recommended by Percona.

The following is the list of extensions available in Percona Distribution for PostgreSQL.

Extension Version Description

Patroni 2.1.4 a HA (High Availability) solution for PostgreSQL

pgaudit 1.7.0 provides detailed session or object audit logging via the standard
logging facility provided by PostgreSQL

pgAudit set user 4.0.0 provides an additional layer of logging and control when
unprivileged users must escalate themselves to superuser or
object owner roles in order to perform needed maintenance
tasks.

pgBackRest 2.41 a backup and restore solution for PostgreSQL

pgBadger 12.0 a fast PostgreSQL Log Analyzer.

pgBouncer 1.17.0 lightweight connection pooler for PostgreSQL

pg_repack 1.4.8 rebuilds PostgreSQL database objects

pg_stat_monitor 1.1.1 collects and aggregates statistics for PostgreSQL and provides
histogram information.

PostgreSQL 241 PostgreSQL database-cluster manager. It provides a structure

Common under which multiple versions of PostgreSQL may be installed
and/or multiple clusters maintained at one time.

wal2json 2.5 a PostgreSQL logical decoding JSON output plugin.

HAProxy 2.5.9 The high-availability and load balancing solution for PostgreSQL

11 of 112 Percona LLC, © 2023

2.5 Percona Distribution for PostgreSQL 15.1 (2022-11-21)

Percona Distribution for PostgreSQL also includes the following packages:

Operating Package Version Description

System

CentOS 8 etcd 3.3.11 A consistent, distributed key-value

store

python3-python- 0.4.3 A Python client for ETCD

etcd

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: December 8, 2022

Created: November 21, 2022

12 of 112 Percona LLC, © 2023

2.6 Percona Distribution for PostgreSQL 15.0 (2022-10-24)

Release date: October 24, 2022

Installation: Installing Percona Distribution for PostgreSQL

Upgrade Upgrading Percona Distribution for PostgreSQL from 14 to 15

We are pleased to announce the launch of Percona Distribution for PostgreSQL 15.0 - a solution with the
collection of tools from PostgreSQL community that are tested to work together and serve to assist you in
deploying and managing PostgreSQL. The aim of Percona Distribution for PostgreSQL is to address the
operational issues like High-Availability, Disaster Recovery, Security, Performance and Scalability and others
that enterprises are facing.

This release of Percona Distribution for PostgreSQL is based on PostgreSQL 15.

2.6.1 Release Highlights

Percona Distribution for PostgreSQL 15 features a lot of new functionalities and enhancements to
performance, replication, statistics collection, logging and more. Among them are the following:

• Added the MERGE command, which allows your developers to write conditional SQL statements that can
include INSERT , UPDATE , and DELETE actions within a single statement.

• A view can now be created with the permissions of the caller, instead of the view creator. This adds an
additional layer of protection to ensure that view callers have the correct permissions for working with the
underlying data.

• Enhanced logical replication management:

• Row filtering and column lists for publishers lets users choose to replicate a subset of data from a table
• The ability to skip replaying a conflicting transaction and to automatically disable a subscription if an
error is detected simplifies the conflict management.

• The ability to use two-phase commit (2PC) with logical replication.

• A new logging format jsonlog outputs log data using a defined JSON structure, which allows PostgreSQL
logs to be processed in structured logging systems
• Now DBAs can manage the PostgreSQL configuration by granting users permission to alter server-level
configuration parameters. Users can also browse the configuration from psql using the \dconfig
command.
• Server-level statistics are now collected in shared memory, eliminating both the statistics collector
process and periodically writing this data to disk
• A new built-in extension, pg_walinspect , lets users inspect the contents of write-ahead log files directly
from a SQL interface.

• Performance optimizations:

• Improved performance of window functions such as rank() , row_number() and count() . Read more about
performance and benchmarking results in Introducing Performance Improvement of Window Functions in
PostgreSQL 15.

• Parallel execution of queries using the SELECT DISTINCT command.

• The support for LZ4 and zstd compression methods to write-ahead logs (WAL) and backup files improves
performance and storage capabilities of your database.

13 of 112 Percona LLC, © 2023

2.6.1 Release Highlights

See also

• PostgreSQL 15 release notes

• Percona Blog:

• A Quick Peek at the PostgreSQL 15 Beta 1

• PostgreSQL 15 – New Features to Be Excited About

• PostgreSQL 15: Stats Collector Gone? What’s New?

• Highly Available PostgreSQL From Percona

The following is the list of extensions available in Percona Distribution for PostgreSQL.

Extension Version Description

Patroni 2.1.4 a HA (High Availability) solution for PostgreSQL

pgaudit 1.7.0 provides detailed session or object audit logging via the standard
logging facility provided by PostgreSQL

pgAudit set user 3.0.0 provides an additional layer of logging and control when
unprivileged users must escalate themselves to superuser or
object owner roles in order to perform needed maintenance
tasks.

pgBackRest 2.41 a backup and restore solution for PostgreSQL

pgBadger 12.0 a fast PostgreSQL Log Analyzer.

pgBouncer 1.17.0 lightweight connection pooler for PostgreSQL

pg_repack 1.4.8 rebuilds PostgreSQL database objects

pg_stat_monitor 1.1.1 collects and aggregates statistics for PostgreSQL and provides
histogram information.

PostgreSQL 241 PostgreSQL database-cluster manager. It provides a structure

Common under which multiple versions of PostgreSQL may be installed
and/or multiple clusters maintained at one time.

wal2json 2.5 a PostgreSQL logical decoding JSON output plugin.

HAProxy 2.5.9 The high-availability and load balancing solution for PostgreSQL

Percona Distribution for PostgreSQL also includes the following packages:

Operating Package Version Description

System

CentOS 8 etcd 3.3.11 A consistent, distributed key-value

store

python3-python- 0.4.3 A Python client for ETCD

etcd

14 of 112 Percona LLC, © 2023

2.6.1 Release Highlights

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: October 24, 2022

Created: October 24, 2022

15 of 112 Percona LLC, © 2023

3. Installation and Upgrade

3.1 Install Percona Distribution for PostgreSQL

3.1.1 Install Percona Distribution for PostgreSQL

Percona provides installation packages in DEB and RPM format for 64-bit Linux distributions. Find the full list
of supported platforms on the Percona Software and Platform Lifecycle page.

Like many other Percona products, we recommend installing Percona Distribution for PostgreSQL from
Percona repositories by using the percona-release utility. The percona-release utility automatically
enables the required repository for you so you can easily install and update Percona Distribution for
PostgreSQL packages and their dependencies through the package manager of your operating system.

Package contents

In addition to individual packages for its components, Percona Distribution for PostgreSQL also includes two
meta-packages: percona-ppg-server and percona-ppg-server-ha .

Using a meta-package, you can install all components it contains in one go.

PERCONA-PPG-SERVER

Package name on Debian/Ubuntu

percona-ppg-server-15

Package name on RHEL/derivatives

percona-ppg-server15

The percona-ppg-server meta-package installs the PostgreSQL server with the following packages:

Package contents Description

percona-postgresql% The PostgreSQL server package.

{pgmajorversion}-server

percona-postgresql-common PostgreSQL database-cluster manager. It provides a structure under which

multiple versions of PostgreSQL may be installed and/or multiple clusters
maintained at one time.

percona-postgresql% A collection of additional PostgreSQLcontrib extensions

{pgmajorversion}-contrib

percona-pg-stat-monitor% A Query Performance Monitoring tool for PostgreSQL.

{pgmajorversion}

percona-pgaudit Provides detailed session or object audit logging via the standard
PostgreSQL logging facility.

percona-pg_repack% rebuilds PostgreSQL database objects.

{pgmajorversion}

percona-wal2json% a PostgreSQL logical decoding JSON output plugin.

{pgmajorversion}

The %{pgmajorversion} variable stands for the major version of PostgreSQL.

16 of 112 Percona LLC, © 2023

3.1.1 Install Percona Distribution for PostgreSQL

PERCONA-PPG-SERVER-HA

Package name on Debian/Ubuntu

percona-ppg-server-ha-15

Package name on RHEL/derivatives

percona-ppg-server-ha15

The percona-ppg-server-ha meta-package installs high-availability components that are recommended by

Percona:

Package contents Description

percona-patroni A high-availability solution for PostgreSQL.

percona-haproxy A high-availability and load-balancing solution

etcd A consistent, distributed key-value store

python3-python-etcd A Python client for ETCD.[^1]

To install Percona Distribution for PostgreSQL, refer to the following tutorials:

• On Debian and Ubuntu

• On Red Hat Enterprise Linux and derivatives

[^1]: Is included in repositories for RHEL 8 / CentOS 8 operating systems

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: January 13, 2023

Created: June 4, 2021

17 of 112 Percona LLC, © 2023

3.1.2 Install Percona Distribution for PostgreSQL on Debian and Ubuntu

This document describes how to install Percona Server for PostgreSQL from Percona repositories on DEB-
based distributions such as Debian and Ubuntu.

Preconditions

Debian and other systems that use the apt package manager include the upstream PostgreSQL server
package (postgresql-15) by default. The components of Percona Distribution for PostgreSQL 15 can only be
installed together with the PostgreSQL server shipped by Percona (percona-postgresql-15). If you wish to
use Percona Distribution for PostgreSQL, uninstall the PostgreSQL package provided by your distribution
(postgresql-15) and then install the chosen components from Percona Distribution for PostgreSQL.

Procedure

Run all the commands in the following sections as root or using the sudo command:

CONFIGURE PERCONA REPOSITORY

1. Install the percona-release repository management tool to subscribe to Percona repositories:

• Fetch percona-release packages from Percona web:

$ wget https://repo.percona.com/apt/percona-release_latest.$(lsb_release -sc)_all.deb

• Install the downloaded package with dpkg :

$ sudo dpkg -i percona-release_latest.$(lsb_release -sc)_all.deb

• Refresh the local cache:

$ sudo apt update

2. Enable the repository

Percona provides two repositories for Percona Distribution for PostgreSQL. We recommend enabling the
Major release repository to timely receive the latest updates.

To enable a repository, we recommend using the setup command:

$ sudo percona-release setup ppg-15

18 of 112 Percona LLC, © 2023

3.1.2 Install Percona Distribution for PostgreSQL on Debian and Ubuntu

INSTALL PACKAGES

19 of 112 Percona LLC, © 2023

3.1.2 Install Percona Distribution for PostgreSQL on Debian and Ubuntu

Install using meta-package

$ sudo apt install percona-ppg-server-15

Install packages individually

1. Install the PostgreSQL server package:

$ sudo apt install percona-postgresql-15

2. Install the components:

Install pg_repack :

$ sudo apt install percona-postgresql-15-repack

Install pgAudit :

$ sudo apt install percona-postgresql-15-pgaudit

Install pgBackRest :

$ sudo apt install percona-pgbackrest

Install Patroni :

$ sudo apt install percona-patroni

Install pg_stat_monitor
Install pgBouncer :

$ sudo apt install percona-pgbouncer

Install pgAudit-set_user :

$ sudo apt install percona-pgaudit15-set-user

Install pgBadger :

$ sudo apt install percona-pgbadger

Install wal2json :

$ sudo apt install percona-postgresql-15-wal2json

Install PostgreSQL contrib extensions:

$ sudo apt install percona-postgresql-contrib

Install HAProxy

$ sudo apt install percona-haproxy

Install pgpool2

20 of 112 Percona LLC, © 2023

$ sudo apt install percona-pgpool2
3.1.2 Install Percona Distribution for PostgreSQL on Debian and Ubuntu

START THE SERVICE

The installation process automatically initializes and starts the default database. You can check the
database status using the following command:

$ sudo systemctl status postgresql.service

CONNECT TO THE POSTGRESQL SERVER

By default, postgres user and postgres database are created in PostgreSQL upon its installation and
initialization. This allows you to connect to the database as the postgres user.

$ sudo su postgres

Open the PostgreSQL interactive terminal:

$ psql

Hint

You can connect to psql as the postgres user in one go:

$ sudo su - postgres -c psql

To exit the psql terminal, use the following command:

$ \q

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: June 8, 2023

Created: November 21, 2022

21 of 112 Percona LLC, © 2023

3.1.3 Install Percona Distribution for PostgreSQL on Red Hat Enterprise Linux and derivatives

This document describes how to install Percona Distribution for PostgreSQL from Percona repositories on
RPM-based distributions such as Red Hat Enterprise Linux and compatible derivatives.

Platform specific notes

If you intend to install Percona Distribution for PostgreSQL on Red Hat Enterprise Linux v8, disable the
postgresql and llvm-toolset modules:

$ sudo dnf module disable postgresql llvm-toolset

On CentOS 7, you should install the epel-release package:

$ sudo yum -y install epel-release

$ sudo yum repolist

Procedure

Run all the commands in the following sections as root or using the sudo command:

CONFIGURE THE REPOSITORY

1. Install the percona-release repository management tool to subscribe to Percona repositories:

$ sudo yum install https://repo.percona.com/yum/percona-release-latest.noarch.rpm

2. Enable the repository

Percona provides two repositories for Percona Distribution for PostgreSQL. We recommend enabling the
Major release repository to timely receive the latest updates.

To enable a repository, we recommend using the setup command:

$ sudo percona-release setup ppg-15

22 of 112 Percona LLC, © 2023

3.1.3 Install Percona Distribution for PostgreSQL on Red Hat Enterprise Linux and derivatives

INSTALL PACKAGES

23 of 112 Percona LLC, © 2023

3.1.3 Install Percona Distribution for PostgreSQL on Red Hat Enterprise Linux and derivatives

Install using meta-package

$ sudo yum install percona-ppg-server15

Install packages individually

1. Install the PostgreSQL server package:

$ sudo yum install percona-postgresql15-server

2. Install the components:

Install pg_repack :

$ sudo yum install percona-pg_repack15

Install pgaudit :

$ sudo yum install percona-pgaudit

Install pgBackRest :

$ sudo yum install percona-pgbackrest

Install Patroni :

$ sudo yum install percona-patroni

Install pg_stat_monitor :
Install pgBouncer :

$ sudo yum install percona-pgbouncer

Install pgAudit-set_user :

$ sudo yum install percona-pgaudit15_set_user

Install pgBadger :

$ sudo yum install percona-pgbadger

Install wal2json :

$ sudo yum install percona-wal2json15

Install PostgreSQL contrib extensions:

$ sudo yum install percona-postgresql15-contrib

Install HAProxy

$ sudo yum install percona-haproxy

Install pgpool

To install pgpool2 on Red Hat Enterprise Linux and compatible

24 of 112 derivatives, enable the codeready builder
Percona LLC, © 2023
repository first to resolve dependencies conflict for pgpool2 . The following examples show steps for Red Hat
Enterprise Linux 9.
3.1.3 Install Percona Distribution for PostgreSQL on Red Hat Enterprise Linux and derivatives

START THE SERVICE

After the installation, the default database storage is not automatically initialized. To complete the
installation and start Percona Distribution for PostgreSQL, initialize the database using the following
command:

$ /usr/pgsql-15/bin/postgresql-15-setup initdb

Start the PostgreSQL service:

$ sudo systemctl start postgresql-15

CONNECT TO THE POSTGRESQL SERVER

By default, postgres user and postgres database are created in PostgreSQL upon its installation and
initialization. This allows you to connect to the database as the postgres user.

$ sudo su postgres

Open the PostgreSQL interactive terminal:

$ psql

Hint

You can connect to psql as the postgres user in one go:

$ sudo su - postgres -c psql

To exit the psql terminal, use the following command:

$ \q

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: June 27, 2023

Created: November 21, 2022

25 of 112 Percona LLC, © 2023

3.1.4 Enable Percona Distribution for PostgreSQL extensions

Some extensions require additional configuration before using them with Percona Distribution for
PostgreSQL. This sections provides configuration instructions per extension.

Patroni

Patroni is the third-party high availability solution for PostgreSQL. The High Availability in PostgreSQL with
Patroni chapter provides details about the solution overview and architecture deployment.

While setting up a high availability PostgreSQL cluster with Patroni, you will need the following components:

• Patroni installed on every postresql node.

• Distributed Configuration Store (DCS). Patroni supports such DCSs as ETCD, zookeeper, Kubernetes though
ETCD is the most popular one. It is available upstream as DEB packages for Debian 10, 11 and Ubuntu 18.04,
20.04, 22.04.

For CentOS 8, RPM packages for ETCD is available within Percona Distribution for PostreSQL. You can install
it using the following command:

$ sudo yum install etcd python3-python-etcd

• HAProxy.

See the configuration guidelines for Debian and Ubuntu and RHEL and CentOS.

See also

• Patroni documentation

• Percona Blog:

• PostgreSQL HA with Patroni: Your Turn to Test Failure Scenarios

pgBadger

Enable the following options in postgresql.conf configuration file before starting the service:

log_min_duration_statement = 0
log_line_prefix = '%t [%p]: '
log_checkpoints = on
log_connections = on
log_disconnections = on
log_lock_waits = on
log_temp_files = 0
log_autovacuum_min_duration = 0
log_error_verbosity = default

For details about each option, see pdBadger documentation.

pgAudit set-user

Add the set-user to shared_preload_libraries in postgresql.conf . The recommended way is to use the
ALTER SYSTEM command. Connect to psql and use the following command:

ALTER SYSTEM SET shared_preload_libraries = 'set-user';

26 of 112 Percona LLC, © 2023

3.1.4 Enable Percona Distribution for PostgreSQL extensions

Start / restart the server to apply the configuration.

You can fine-tune user behavior with the custom parameters supplied with the extension.

wal2json

After the installation, enable the following option in postgresql.conf configuration file before starting the
service:

wal_level = logical

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: May 22, 2023

Created: November 21, 2022

27 of 112 Percona LLC, © 2023

3.1.5 Repositories overview

Percona provides two repositories for Percona Distribution for PostgreSQL.

Major release repository Minor release repository

Major Release repository ( ppg-15 ) it Minor Release repository includes a particular minor release of
includes the latest version packages. the database and all of the packages that were tested and
Whenever a package is updated, the verified to work with that minor release (e.g. ppg-15.1 ). You
package manager of your operating may choose to install Percona Distribution for PostgreSQL from
system detects that and prompts you the Minor Release repository if you have decided to
to update. As long as you update all standardize on a particular release which has passed rigorous
Distribution packages at the same time, testing procedures and which has been verified to work with
you can ensure that the packages your applications. This allows you to deploy to a new host and
you’re using have been tested and ensure that you’ll be using the same version of all the
verified by Percona. Distribution packages, even if newer releases exist in other
repositories.
We recommend installing Percona
Distribution for PostgreSQL from the The disadvantage of using a Minor Release repository is that
Major Release repository you are locked in this particular release. When potentially
critical fixes are released in a later minor version of the
database, you will not be prompted for an upgrade by the
package manager of your operating system. You would need
to change the configured repository in order to install the
upgrade.

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: November 21, 2022

Created: November 21, 2022

28 of 112 Percona LLC, © 2023

3.2 Migrate from PostgreSQL to Percona Distribution for PostgreSQL

Percona Distribution for PostgreSQL includes the PostgreSQL database and additional extensions that have
been selected to cover the needs of the enterprise and are guaranteed to work together. Percona
Distribution for PostgreSQL is available as a software collection that is easy to deploy.

We encourage users to migrate from their PostgreSQL deployments based on community binaries to
Percona Distribution for PostgreSQL. This document provides the migration instructions.

Depending on your business requirements, you may migrate to Percona Distribution for PostgreSQL either on
the same server or onto a different server.

29 of 112 Percona LLC, © 2023

3.2.1 Migrate on the same server

30 of 112 Percona LLC, © 2023

3.2.1 Migrate on the same server

On Debian and Ubuntu Linux

To ensure that your data is safe during the migration, we recommend to make a backup of your data and
all configuration files (such as pg_hba.conf , postgresql.conf , postgresql.auto.conf ) using the tool of your
choice. The backup process is out of scope of this document. You can use pg_dumpall or other tools of your
choice.

1. Stop the postgresql server

$ sudo systemctl stop postgresql.service

2. Remove community packages

$ sudo apt-get --purge remove postgresql

3. Install percona-release

4. Enable the repository

$ sudo percona-release setup ppg15

5. Install Percona Distribution for PostgreSQL packages

6. (Optional) Restore the data from the backup.

7. Start the postgresql service. The installation process starts and initializes the default cluster automatically.
You can check its status with:

$ sudo systemctl status postgresql

If postresql service is not started, start it manually:

$ sudo systemctl start postgresql.service

On RHEL and derivatives

1. Stop the postgresql server

$ sudo systemctl stop postgresql-15

2. Remove community packages

$ sudo yum remove postgresql

3. Install percona-release
4. Enable the repository

$ sudo percona-release setup ppg15

5. Install Percona Distribution for PostgreSQL packages

6. (Optional) Restore the data from the backup.

7. Start the postgresql service

$ sudo systemctl start postgresql-15

3.2.2 Migrate on a different server

In this scenario, we will refer to the server with PostgreSQL Community as the "source" and to the server with
Percona Distribution for PostgreSQL as the "target".

To migrate from PostgreSQL Community to Percona Distribution for PostgreSQL on a different server, do the
following:

On the source server:

1. Back up your data and all configuration files (such as pg_hba.conf , postgresql.conf , postgresql.auto.conf )
using the tool of your choice.

2. Stop the postgresql service

On Debian and Ubuntu

$ sudo systemctl stop postgresql.service

On RHEL and derivatives

$ sudo systemctl stop postgresql-15

3. Optionally, remove PostgreSQL Community packages

On the target server:

1. Install percona-release

2. Enable the repository

$ sudo percona-release setup ppg15

3. Install Percona Distribution for PostgreSQL packages on the target server.

4. Restore the data from the backup

5. Start postgresql service

On Debian and Ubuntu

$ sudo systemctl start postgresql.service

On RHEL and derivatives

$ sudo systemctl start postgresql-15

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

32 of 112 Percona LLC, © 2023

3.2.2 Migrate on a different server

Last update: December 5, 2022

Created: July 22, 2022

33 of 112 Percona LLC, © 2023

3.3 Upgrading Percona Distribution for PostgreSQL from 14 to 15

This document describes the in-place upgrade of Percona Distribution for PostgreSQL using the pg_upgrade
tool.

The in-place upgrade means installing a new version without removing the old version and keeping the
data files on the server.

See also

pg_upgrade Documentation

Similar to installing, we recommend you to upgrade Percona Distribution for PostgreSQL from Percona
repositories.

Important

A major upgrade is a risky process because of many changes between versions and issues that might occur
during or after the upgrade. Therefore, make sure to back up your data first. The backup tools are out of scope of
this document. Use the backup tool of your choice.

The general in-place upgrade flow for Percona Distribution for PostgreSQL is the following:

1. Install Percona Distribution for PostgreSQL 15 packages.

2. Stop the PostgreSQL service.

3. Check the upgrade without modifying the data.

4. Upgrade Percona Distribution for PostgreSQL.

5. Start PostgreSQL service.

6. Execute the analyze_new_cluster.sh script to generate statistics so the system is usable.

7. Delete old packages and configuration files.

The exact steps may differ depending on the package manager of your operating system.

34 of 112 Percona LLC, © 2023

3.3.1 On Debian and Ubuntu using apt

Important

Run all commands as root or via sudo.

35 of 112 Percona LLC, © 2023

3.3.1 On Debian and Ubuntu using apt

1. Install Percona Distribution for PostgreSQL 15 packages.

• Install percona-release
• Enable Percona repository:

$ sudo percona-release setup ppg-15

• Install Percona Distribution for PostgreSQL 15 package:

$ sudo apt install percona-postgresql-15

• Install the components:

$ sudo apt install percona-postgresql-15-repack \

percona-postgresql-15-pgaudit \
percona-pgbackrest \
percona-patroni \
percona-pgbadger \
percona-pgaudit15-set-user \
percona-pgbadger \
percona-postgresql-15-wal2json \
percona-pg-stat-monitor15 \
percona-postgresql-contrib
percona-haproxy
percona-pgpool2

2. Stop the postgresql service.

$ sudo systemctl stop postgresql.service

This stops both Percona Distribution for PostgreSQL 14 and 15.

3. Run the database upgrade.

• Log in as the postgres user.

$ sudo su postgres

• Change the current directory to the tmp directory where logs and some scripts will be recorded:

$ cd tmp/

• Check the ability to upgrade Percona Distribution for PostgreSQL from 14 to 15:

$ /usr/lib/postgresql/15/bin/pg_upgrade
--old-datadir=/var/lib/postgresql/14/main \
--new-datadir=/var/lib/postgresql/15/main \
--old-bindir=/usr/lib/postgresql/14/bin \
--new-bindir=/usr/lib/postgresql/15/bin \
--old-options '-c config_file=/etc/postgresql/14/main/postgresql.conf' \
--new-options '-c config_file=/etc/postgresql/15/main/postgresql.conf' \
--check

The --check flag here instructs pg_upgrade to only check the upgrade without changing any data.

Sample output

36 of 112 Percona LLC, © 2023

3.3.1 On Debian and Ubuntu using apt

Performing Consistency Checks

-----------------------------
Checking cluster versions ok
Checking database user is the install user ok
Checking database connection settings ok
Checking for prepared transactions ok
Checking for reg* data types in user tables ok
Checking for contrib/isn with bigint-passing mismatch ok
Checking for tables WITH OIDS ok
Checking for invalid "sql_identifier" user columns ok
Checking for presence of required libraries ok
Checking database user is the install user ok
Checking for prepared transactions ok

Clusters are compatible

• Upgrade the Percona Distribution for PostgreSQL

The --link flag creates hard links to the files on the old version cluster so you don’t need to copy data.

If you don’t wish to use the --link option, make sure that you have enough disk space to store 2 copies of files
for both old version and new version clusters.

• Go back to the regular user:

$ exit

• The Percona Distribution for PostgreSQL 14 uses the 5432 port while the Percona Distribution for PostgreSQL 15
is set up to use the 5433 port by default. To start the Percona Distribution for PostgreSQL 15, swap ports in the
configuration files of both versions.

$ sudo vim /etc/postgresql/15/main/postgresql.conf

$ port = 5433 # Change to 5432 here
$ sudo vim /etc/postgresql/14/main/postgresql.conf
$ port = 5432 # Change to 5433 here

4. Start the postgreqsl service.

$ sudo systemctl start postgresql.service

5. Check the postgresql version.

• Log in as a postgres user

$ sudo su postgres

• Check the database version

37 of 112 Percona LLC, © 2023

3.3.1 On Debian and Ubuntu using apt

$ psql -c "SELECT version();"

6. Run the analyze_new_cluster.sh script

$ tmp/analyze_new_cluster.sh
$ #Logout
$ exit

7. Delete Percona Distribution for PostgreSQL 14 packages and configuration files

• Remove packages

$ sudo apt remove percona-postgresql-14* percona-pgbackrest percona-patroni percona-pg-stat-

monitor14 percona-pgaudit14-set-user percona-pgbadger percona-pgbouncer percona-postgresql-14-
wal2json

• Remove old files

$ rm -rf /etc/postgresql/14/main

38 of 112 Percona LLC, © 2023

3.3.2 On Red Hat Enterprise Linux and CentOS using yum

Important

Run all commands as root or via sudo.

39 of 112 Percona LLC, © 2023

3.3.2 On Red Hat Enterprise Linux and CentOS using yum

1. Install Percona Distribution for PostgreSQL 15 packages

• Install percona-release
• Enable Percona repository:

$ sudo percona-release setup ppg-15

• Install Percona Distribution for PostgreSQL 15:

$ sudo yum install percona-postgresql15-server

• Install components:

$ sudo yum install percona-pgaudit \

percona-pgbackrest \
percona-pg_repack15 \
percona-patroni \
percona-pg-stat-monitor15 \
percona-pgbadger \
percona-pgaudit15_set_user \
percona-pgbadger \
percona-wal2json15 \
percona-postgresql15-contrib
percona-haproxy
percona-pgpool-II-pg15

2. Set up Percona Distribution for PostgreSQL 15 cluster

3. Log is as the postgres user

$ sudo su postgres

4. Set up locale settings

export LC_ALL="en_US.UTF-8"
export LC_CTYPE="en_US.UTF-8"

5. Initialize cluster with the new data directory

$ /usr/pgsql-15/bin/initdb -D /var/lib/pgsql/15/data

6. Stop the postgresql 14 service

$ systemctl stop postgresql-14

7. Run the database upgrade.

• Log in as the postgres user

$ sudo su postgres

• Check the ability to upgrade Percona Distribution for PostgreSQL from 14 to 15:

$ /usr/pgsql-15/bin/pg_upgrade \
--old-bindir /usr/pgsql-14/bin \

40 of 112 Percona LLC, © 2023

3.3.2 On Red Hat Enterprise Linux and CentOS using yum

--new-bindir /usr/pgsql-15/bin \
--old-datadir /var/lib/pgsql/14/data \
--new-datadir /var/lib/pgsql/15/data \
--check

The --check flag here instructs pg_upgrade to only check the upgrade without changing any data.

Sample output

Performing Consistency Checks

Clusters are compatible

• Upgrade the Percona Distribution for PostgreSQL

$ /usr/pgsql-15/bin/pg_upgrade \
--old-bindir /usr/pgsql-14/bin \
--new-bindir /usr/pgsql-15/bin \
--old-datadir /var/lib/pgsql/14/data \
--new-datadir /var/lib/pgsql/15/data \
--link

The --link flag creates hard links to the files on the old version cluster so you don’t need to copy data. If you
don’t wish to use the --link option, make sure that you have enough disk space to store 2 copies of files for
both old version and new version clusters.

8. Start the postgresql 15 service.

$ systemctl start postgresql-15

9. Check postgresql status

$ systemctl status postgresql-15

10. Run the analyze_new_cluster.sh script

• Log in as the postgres user

$ sudo su postgres

• Run the script

$ ./analyze_new_cluster.sh

11. Delete Percona Distribution for PostgreSQL 14 configuration files

41 of 112 Percona LLC, © 2023

3.3.2 On Red Hat Enterprise Linux and CentOS using yum

$ ./delete_old_cluster.sh

12. Delete Percona Distribution for PostgreSQL 14 packages

• Remove packages

$ sudo yum -y remove percona-postgresql14*

• Remove old files

$ rm -rf /var/lib/pgsql/14/data

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: May 22, 2023

Created: June 4, 2021

42 of 112 Percona LLC, © 2023

3.4 Minor Upgrade of Percona Distribution for PostgreSQL

Minor releases of PostgreSQL include bug fixes and feature enhancements. We recommend that you keep
your Percona Distribution for PostgreSQL updated to the latest minor version.

Though minor upgrades do not change the behavior, we recommend you to back up your data first, in order
to be on the safe side.

Minor upgrade of Percona Distribution for PostgreSQL includes the following steps:

1. Stop the postgresql cluster;

2. Install new version packages;

3. Restart the postgresql cluster.

Note

These steps apply if you installed Percona Distribution for PostgreSQL from the Major Release repository. In this
case, you are always upgraded to the latest available release.

If you installed Percona Distribution for PostgreSQL from the Minor Release repository, you will need to enable a
new version repository to upgrade.

For more information about Percona repositories, refer to Installing Percona Distribution for PostgreSQL.

Before the upgrade, update the percona-release utility to the latest version. This is required to install the new
version packages of Percona Distribution for PostgreSQL. Refer to Percona Software Repositories Documentation
for update instructions.

43 of 112 Percona LLC, © 2023

3.4 Minor Upgrade of Percona Distribution for PostgreSQL

Important

Run all commands as root or via sudo.

1. Stop the postgresql service.

On Debian / Ubuntu

$ sudo systemctl stop postgresql.service

On Red Hat Enterprise Linux / derivatives

$ sudo systemctl stop postgresql-15

2. Install new version packages. See Installing Percona Distribution for PostgreSQL.

3. Restart the postgresql service.

On Debian / Ubuntu

$ sudo systemctl start postgresql.service

On Red Hat Enterprise Linux / derivatives

$ sudo systemctl start postgresql-15

If you wish to upgrade Percona Distribution for PostgreSQL to the major version, refer to Upgrading Percona
Distribution for PostgreSQL from 14 to 15.

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: December 5, 2022

Created: June 4, 2021

44 of 112 Percona LLC, © 2023

4. Extensions

4.1 pg_stat_monitor

Note

This document describes the functionality of pg_stat_monitor 2.0.0.

4.1.1 Overview

pg_stat_monitor is a Query Performance Monitoring tool for PostgreSQL. It collects various statistics data
such as query statistics, query plan, SQL comments and other performance insights. The collected data is
aggregated and presented in a single view. This allows you to view queries from performance, application
and analysis perspectives.

pg_stat_monitor groups statistics data and writes it in a storage unit called bucket. The data is added and
stored in a bucket for the defined period – the bucket lifetime. This allows you to identify performance issues
and patterns based on time.

You can specify the following:

• The number of buckets. Together they form a bucket chain.

• Bucket size. This is the amount of shared memory allocated for buckets. Memory is divided equally among
buckets.
• Bucket lifetime.

When a bucket lifetime expires, pg_stat_monitor resets all statistics and writes the data in the next bucket in
the chain. When the last bucket’s lifetime expires, pg_stat_monitor returns to the first bucket.

Important

The contents of the bucket will be overwritten. In order not to lose the data, make sure to read the bucket before
pg_stat_monitor starts writing new data to it.

Views

PG_STAT_MONITOR VIEW

The pg_stat_monitor view contains all the statistics collected and aggregated by the extension. This view
contains one row for each distinct combination of metrics and whether it is a top-level statement or not (up
to the maximum number of distinct statements that the module can track). For details about available
metrics, refer to the pg_stat_monitor view reference.

45 of 112 Percona LLC, © 2023

4.1.2 Installation

The following are the primary keys for pg_stat_monitor:

• bucket
• userid

• datname

• queryid
• client_ip

• planid
• application_name

A new row is created for each key in the pg_stat_monitor view.

For security reasons, only superusers and members of the pg_read_all_stats role are allowed to see the SQL
text, client_ip and queryid of queries executed by other users. Other users can see the statistics, however,
if the view has been installed in their database.

PG_STAT_MONITOR_SETTINGS VIEW (DROPPED)

Starting with version 2.0.0, the pg_stat_monitor_settings view is deprecated and removed. All
pg_stat_monitor configuration parameters are now available though the pg_settings view using the
following query:

SELECT name, setting, unit, context, vartype, source, min_val, max_val, enumvals, boot_val,
reset_val, pending_restart FROM pg_settings WHERE name LIKE '%pg_stat_monitor%';

For backward compatibility, you can create the pg_stat_monitor_settings view using the following SQL
statement:

CREATE VIEW pg_stat_monitor_settings

SELECT *

FROM pg_settings

WHERE name like 'pg_stat_monitor.%';

In pg_stat_monitor version 1.1.1 and earlier, the pg_stat_monitor_settings view shows one row per
pg_stat_monitor configuration parameter. It displays configuration parameter name, value, default value,
description, minimum and maximum values, and whether a restart is required for a change in value to be
effective.

To learn more, see the Changing the configuration section.

4.1.2 Installation

This section describes how to install pg_stat_monitor from Percona repositories. To learn about other
installation methods, see the Installation section in the pg_stat_monitor documentation.

Preconditions:

To install pg_stat_monitor from Percona repositories, you need to subscribe to them. To do this, you must
have the percona-release repository management tool up and running.

46 of 112 Percona LLC, © 2023

4.1.2 Installation

To install pg_stat_monitor , run the following commands:

On Debian and Ubuntu

1. Enable the repository

$ sudo percona-release setup ppg15

2. Install the package:

$ sudo apt-get install percona-pg-stat-monitor15

On Red Hat Enterprise Linux and derivatives

1. Enable the repository

$ sudo percona-release setup ppg15

2. Install the package:

$ sudo yum install percona-pg-stat-monitor15

47 of 112 Percona LLC, © 2023

4.1.3 Setup

pg_stat_monitor requires additional setup in order to use it with PostgreSQL. The setup steps are the
following:

1. Add pg_stat_monitor in the shared_preload_libraries configuration parameter.

The recommended way to modify PostgreSQL configuration file is using the ALTER SYSTEM command. Connect
to psql and use the following command:

ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_monitor';

The parameter value is written to the postgresql.auto.conf file which is read in addition with postgresql.conf
file.

Note

To use pg_stat_monitor together with pg_stat_statements , specify both modules separated by commas for the
ALTER SYSTEM SET command.

The order of modules is important: pg_stat_monitor must be specified after pg_stat_statements :

ALTER SYSTEM SET shared_preload_libraries = ‘pg_stat_statements, pg_stat_monitor’

2. Start or restart the postgresql instance to enable pg_stat_monitor . Use the following command for restart:

On Debian and Ubuntu

$ sudo systemctl restart postgresql.service

On Red Hat Enterprise Linux and derivatives

$ sudo systemctl restart postgresql-15

3. Create the extension. Connect to psql and use the following command:

CREATE EXTENSION pg_stat_monitor;

By default, the extension is created against the postgres database. You need to create the extension on every
database where you want to collect statistics.

Tip

To check the version of the extension, run the following command in the psql session:

SELECT pg_stat_monitor_version();

4.1.4 Usage

For example, to view the IP address of the client application that made the query, run the following
command:

48 of 112 Percona LLC, © 2023

4.1.5 Changing the configuration

SELECT DISTINCT userid::regrole, pg_stat_monitor.datname, substr(query,0, 50) AS query,

calls, bucket, bucket_start_time, queryid, client_ip
FROM pg_stat_monitor, pg_database
WHERE pg_database.oid = oid;

Output:

userid | datname | query | calls | bucket |

bucket_start_time | queryid | client_ip
----------+----------+---------------------------------------------------+-------+--------
+---------------------+------------------+-----------
postgres | postgres | SELECT name,description FROM pg_stat_monitor_sett | 1 | 9 |
2022-10-24 07:29:00 | AD536A8DEA7F0C73 | 127.0.0.1
postgres | postgres | SELECT c.oid, +| 1 | 9 |
2022-10-24 07:29:00 | 34B888E5C844519C | 127.0.0.1
| | n.nspname, +| |
| | |
| | c.relname +| |
| | |
| | FROM pg_ca | |
| | |
postgres | postgres | SELECT DISTINCT userid::regrole, pg_stat_monitor. | 1 | 1 |
2022-10-24 07:31:00 | 6230793895381F1D | 127.0.0.1
postgres | postgres | SELECT pg_stat_monitor_version() | 1 | 9 |
2022-10-24 07:29:00 | B617F5F12931F388 | 127.0.0.1
postgres | postgres | CREATE EXTENSION pg_stat_monitor | 1 | 8 |
2022-10-24 07:28:00 | 14B98AF0776BAF7B | 127.0.0.1
postgres | postgres | SELECT a.attname, +| 1 | 9 |
2022-10-24 07:29:00 | 96F8E4B589EF148F | 127.0.0.1
| | pg_catalog.format_type(a.attt | |
| | |
postgres | postgres | SELECT c.relchecks, c.relkind, c.relhasindex, c.r | 1 | 9 |
2022-10-24 07:29:00 | CCC51D018AC96A25 | 127.0.0.1

Find more usage examples in the pg_stat_monitor user guide.

4.1.5 Changing the configuration

Run the following query to list available configuration parameters.

SELECT name, short_desc FROM pg_settings WHERE name LIKE '%pg_stat_monitor%';

Output

name
| short_desc
-------------------------------------------
+------------------------------------------------------------------------------------------------------------
pg_stat_monitor.pgsm_bucket_time | Sets the time in seconds per bucket.
pg_stat_monitor.pgsm_enable_overflow | Enable/Disable pg_stat_monitor to grow beyond
shared memory into swap space.
pg_stat_monitor.pgsm_enable_pgsm_query_id | Enable/disable PGSM specific query id
calculation which is very useful in comparing same query across databases and clusters..
pg_stat_monitor.pgsm_enable_query_plan | Enable/Disable query plan monitoring.
pg_stat_monitor.pgsm_extract_comments | Enable/Disable extracting comments from
queries.
pg_stat_monitor.pgsm_histogram_buckets | Sets the maximum number of histogram buckets.
pg_stat_monitor.pgsm_histogram_max | Sets the time in millisecond.
pg_stat_monitor.pgsm_histogram_min | Sets the time in millisecond.

49 of 112 Percona LLC, © 2023

4.1.5 Changing the configuration

pg_stat_monitor.pgsm_max | Sets the maximum size of shared memory in (MB)

used for statement's metadata tracked by pg_stat_monitor.
pg_stat_monitor.pgsm_max_buckets | Sets the maximum number of buckets.
pg_stat_monitor.pgsm_normalized_query | Selects whether save query in normalized
format.
pg_stat_monitor.pgsm_overflow_target | Sets the overflow target for pg_stat_monitor.
(Deprecated, use pgsm_enable_overflow)
pg_stat_monitor.pgsm_query_max_len | Sets the maximum length of query.
pg_stat_monitor.pgsm_query_shared_buffer | Sets the maximum size of shared memory in (MB)
used for query tracked by pg_stat_monitor.
pg_stat_monitor.pgsm_track | Selects which statements are tracked by
pg_stat_monitor.
pg_stat_monitor.pgsm_track_planning | Selects whether planning statistics are
tracked.
pg_stat_monitor.pgsm_track_utility | Selects whether utility commands are tracked.

You can change a parameter by setting a new value in the configuration file. Some parameters require
server restart to apply a new value. For others, configuration reload is enough. Refer to the configuration
parameters of the pg_stat_monitor documentation for the parameters’ description, how you can change
their values and if the server restart is required to apply them.

As an example, let’s set the bucket lifetime from default 60 seconds to 40 seconds. Use the ALTER SYSTEM
command:

ALTER SYSTEM set pg_stat_monitor.pgsm_bucket_time = 40;

Restart the server to apply the change:

On Debian and Ubuntu

$ sudo systemctl restart postgresql.service

On Red Hat Enterprise Linux and derivatives

$ sudo systemctl restart postgresql-15

Verify the updated parameter:

SELECT name, setting

FROM pg_settings
WHERE name = 'pg_stat_monitor.pgsm_bucket_time';

name | setting
----------------------------------+---------
pg_stat_monitor.pgsm_bucket_time | 40

See also

pg_stat_monitor Documentation

Percona Blog:

• pg_stat_monitor: A New Way Of Looking At PostgreSQL Metrics

• Improve PostgreSQL Query Performance Insights with pg_stat_monitor

50 of 112 Percona LLC, © 2023

4.1.5 Changing the configuration

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: May 22, 2023

Created: June 4, 2021

51 of 112 Percona LLC, © 2023

5. Solutions

5.1 High availability

5.1.1 High Availability in PostgreSQL with Patroni

Summary

• Solution overview

• Cluster deployment
• Testing the cluster

PostgreSQL has been widely adopted as a modern, high-performance transactional database. A highly
available PostgreSQL cluster can withstand failures caused by network outages, resource saturation,
hardware failures, operating system crashes, or unexpected reboots. Such cluster is often a critical
component of the enterprise application landscape, where four nines of availability is a minimum
requirement.

This document provides instructions on how to set up and test a highly-available, single-primary, three-
node cluster with Percona PostgreSQL and Patroni.

???+ admonition "High availability overview"

There are a few methods for achieving high availability with PostgreSQL:

- shared disk failover,

- file system replication,
- trigger-based replication,
- statement-based replication,
- logical replication, and
- Write-Ahead Log (WAL) shipping.

In recent times, PostgreSQL high availability is most commonly achieved with [streaming
replication](#streaming-replication).

## Streaming replication

Streaming replication is part of Write-Ahead Log shipping, where changes to the WALs are
immediately made available to standby replicas. With this approach, a standby instance is
always up-to-date with changes from the primary node and can assume the role of primary in
case of a failover.

### Why native streaming replication is not enough

Although the native streaming replication in PostgreSQL supports failing over to the primary
node, it lacks some key features expected from a truly highly-available solution. These
include:

* No consensus-based promotion of a “leader” node during a failover

* No decent capability for monitoring cluster status
* No automated way to bring back the failed primary node to the cluster
* A manual or scheduled switchover is not easy to manage

52 of 112 Percona LLC, © 2023

5.1.1 High Availability in PostgreSQL with Patroni

To address these shortcomings, there are a multitude of third-party, open-source extensions

for PostgreSQL. The challenge for a database administrator here is to select the right utility
for the current scenario.

Percona Distribution for PostgreSQL solves this challenge by providing the [Patroni](https://
patroni.readthedocs.io/en/latest/) extension for achieving PostgreSQL high availability.

Patroni

Patroni provides a template-based approach to create highly available PostgreSQL clusters. Running atop
the PostgreSQL streaming replication process, it integrates with watchdog functionality to detect failed
primary nodes and take corrective actions to prevent outages. Patroni also provides a pluggable
configuration store to manage distributed, multi-node cluster configuration and comes with REST APIs to
monitor and manage the cluster. There is also a command-line utility called patronictl that helps manage
switchovers and failure scenarios.

Architecture layout

The following diagram shows the architecture of a three-node PostgreSQL cluster with a single-leader node.

COMPONENTS

The following are the components:

• Three PosgreSQL nodes: node1 , node2 and node3

• A dedicated HAProxy node HAProxy-demo . HAProxy is an open-source load balancing software through
which client connections to the cluster are routed.

• ETCD - a distributed configuration storage

• Softdog - a watchdog utility which is used to detect unhealthy nodes in an acceptable time frame.

Deployment

Use the links below to navigate to the setup instructions relevant to your operating system

• Deploy on Debian or Ubuntu

• Deploy on Red Hat Enterprise Linux or CentOS

53 of 112 Percona LLC, © 2023

5.1.1 High Availability in PostgreSQL with Patroni

Testing

See the Testing PostgreSQL cluster for the guidelines on how to test your PostgreSQL cluster for replication,
failure, switchover.

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: October 24, 2022

Created: December 15, 2021

54 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

This guide provides instructions on how to set up a highly available PostgreSQL cluster with Patroni on
Debian or Ubuntu.

Preconditions

For this setup, we will use the nodes running on Ubuntu 20.04 as the base operating system and having the
following IP addresses:

Node name Public IP address Internal IP address

node1 157.230.42.174 10.104.0.7

node2 68.183.177.183 10.104.0.2

node3 165.22.62.167 10.104.0.8

HAProxy-demo 134.209.111.138 10.104.0.6

Note

In a production (or even non-production) setup, the PostgreSQL nodes will be within a private subnet without any
public connectivity to the Internet, and the HAProxy will be in a different subnet that allows client traffic coming
only from a selected IP range. To keep things simple, we have implemented this architecture in a DigitalOcean VPS
environment, and each node can access the other by its internal, private IP.

SETTING UP HOSTNAMES IN THE /ETC/HOSTS FILE

To make the nodes aware of each other and allow their seamless communication, resolve their hostnames
to their public IP addresses. Modify the /etc/hosts file of each node as follows:

node 1 node 2 node 3

127.0.0.1 localhost node1 127.0.0.1 localhost node2 127.0.0.1 localhost node3

10.104.0.7 node1 10.104.0.7 node1 10.104.0.7 node1
10.104.0.2 node2 10.104.0.2 node2 10.104.0.2 node2
10.104.0.8 node3 10.104.0.8 node3 10.104.0.8 node3

The /etc/hosts file of the HAProxy-demo node looks like the following:

127.0.1.1 HAProxy-demo HAProxy-demo

127.0.0.1 localhost
10.104.0.6 HAProxy-demo
10.104.0.7 node1
10.104.0.2 node2
10.104.0.8 node3

INSTALL PERCONA DISTRIBUTION FOR POSTGRESQL

1. Follow the installation instructions to install Percona Distribution for PostgreSQL on node1 , node2 and node3 .
2. Remove the data directory. Patroni requires a clean environment to initialize a new cluster. Use the following
commands to stop the PostgreSQL service and then remove the data directory:

55 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

$ sudo systemctl stop postgresql

$ sudo rm -rf /var/lib/postgresql/14/main

Configure ETCD distributed store

The distributed configuration store helps establish a consensus among nodes during a failover and will
manage the configuration for the three PostgreSQL instances. Although Patroni can work with other
distributed consensus stores (i.e., Zookeeper, Consul, etc.), the most commonly used one is etcd .

56 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

The etcd cluster is first started in one node and then the subsequent nodes are added to the first node
using the add command. The configuration is stored in the /etc/default/etcd file.

57 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

1. Install etcd on every PostgreSQL node using the following command:

$ sudo apt install etcd

2. Modify the /etc/default/etcd configuration file on each node.

• On node1 , add the IP address of node1 to the ETCD_INITIAL_CLUSTER parameter. The configuration file looks as
follows:

ETCD_NAME=node1
ETCD_INITIAL_CLUSTER="node1=http://10.104.0.7:2380"
ETCD_INITIAL_CLUSTER_TOKEN="devops_token"
ETCD_INITIAL_CLUSTER_STATE="new"
ETCD_INITIAL_ADVERTISE_PEER_URLS="http://10.104.0.7:2380"
ETCD_DATA_DIR="/var/lib/etcd/postgresql"
ETCD_LISTEN_PEER_URLS="http://10.104.0.7:2380"
ETCD_LISTEN_CLIENT_URLS="http://10.104.0.7:2379,http://localhost:2379"
ETCD_ADVERTISE_CLIENT_URLS="http://10.104.0.7:2379"
…

• On node2 , add the IP addresses of both node1 and node2 to the ETCD_INITIAL_CLUSTER parameter:

ETCD_NAME=node2
ETCD_INITIAL_CLUSTER="node1=http://10.104.0.7:2380,node2=http://10.104.0.2:2380"
ETCD_INITIAL_CLUSTER_TOKEN="devops_token"
ETCD_INITIAL_CLUSTER_STATE="existing"
ETCD_INITIAL_ADVERTISE_PEER_URLS="http://10.104.0.2:2380"
ETCD_DATA_DIR="/var/lib/etcd/postgresql"
ETCD_LISTEN_PEER_URLS="http://10.104.0.2:2380"
ETCD_LISTEN_CLIENT_URLS="http://10.104.0.2:2379,http://localhost:2379"
ETCD_ADVERTISE_CLIENT_URLS="http://10.104.0.2:2379"
…

• On node3 , the ETCD_INITIAL_CLUSTER parameter includes the IP addresses of all three nodes:

ETCD_NAME=node3
ETCD_INITIAL_CLUSTER="node1=http://10.104.0.7:2380,node2=http://10.104.0.2:2380,node3=http://
10.104.0.8:2380"
ETCD_INITIAL_CLUSTER_TOKEN="devops_token"
ETCD_INITIAL_CLUSTER_STATE="existing"
ETCD_INITIAL_ADVERTISE_PEER_URLS="http://10.104.0.8:2380"
ETCD_DATA_DIR="/var/lib/etcd/postgresql"
ETCD_LISTEN_PEER_URLS="http://10.104.0.8:2380"
ETCD_LISTEN_CLIENT_URLS="http://10.104.0.8:2379,http://localhost:2379"
ETCD_ADVERTISE_CLIENT_URLS="http://10.104.0.8:2379"
…

3. On node1 , add node2 and node3 to the cluster using the add command:

$ sudo etcdctl member add node2 http://10.104.0.2:2380

$ sudo etcdctl member add node3 http://10.104.0.8:2380

4. Restart the etcd service on node2 and node3 :

$ sudo systemctl restart etcd

5. Check the etcd cluster members.

58 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

$ sudo etcdctl member list

The output resembles the following:

21d50d7f768f153a: name=node1 peerURLs=http://10.104.0.7:2380 clientURLs=http://10.104.0.7:2379

isLeader=true
af4661d829a39112: name=node2 peerURLs=http://10.104.0.2:2380 clientURLs=http://10.104.0.2:2379
isLeader=false
e3f3c0c1d12e9097: name=node3 peerURLs=http://10.104.0.8:2380 clientURLs=http://10.104.0.8:2379
isLeader=false

Set up the watchdog service

The Linux kernel uses the utility called a watchdog to protect against an unresponsive system. The
watchdog monitors a system for unrecoverable application errors, depleted system resources, etc., and
initiates a reboot to safely return the system to a working state. The watchdog functionality is useful for
servers that are intended to run without human intervention for a long time. Instead of users finding a hung
server, the watchdog functionality can help maintain the service.

In this example, we will configure Softdog - a standard software implementation for watchdog that is
shipped with Ubuntu 20.04.

59 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

Complete the following steps on all three PostgreSQL nodes to load and configure Softdog.

1. Load Softdog:

$ sudo sh -c 'echo "softdog" >> /etc/modules'

2. Patroni will be interacting with the watchdog service. Since Patroni is run by the postgres user, this user must
have access to Softdog. To make this happen, change the ownership of the watchdog.rules file to the
postgres user:

$ sudo sh -c 'echo "KERNEL==\"watchdog\", OWNER=\"postgres\", GROUP=\"postgres\"" >> /etc/

udev/rules.d/61-watchdog.rules'

3. Remove Softdog from the blacklist.

• Find out the files where Softdog is blacklisted:

$ grep blacklist /lib/modprobe.d/* /etc/modprobe.d/* |grep softdog

In our case, modprobe is blacklisting the Softdog:

/lib/modprobe.d/blacklist_linux_5.4.0-73-generic.conf:blacklist softdog

• Remove the blacklist softdog line from the /lib/modprobe.d/blacklist_linux_5.4.0-73-generic.conf file.

• Restart the service

$ sudo modprobe softdog

• Verify the modprobe is working correctly by running the lsmod command:

$ sudo lsmod | grep softdog

The output will show a process identifier if it’s running.

softdog 16384 0

4. Check that the Softdog files under the /dev/ folder are owned by the postgres user:

$ ls -l /dev/watchdog*

crw-rw---- 1 postgres postgres 10, 130 Sep 11 12:53 /dev/watchdog

crw------- 1 root root 245, 0 Sep 11 12:53 /dev/watchdog0

Tip

If the ownership has not been changed for any reason, run the following command to manually change it:

$ sudo chown postgres:postgres /dev/watchdog*

60 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

Configure Patroni

1. Install Patroni on every PostgreSQL node:

$ sudo apt install percona-patroni

2. Create the patroni.yml configuration file under the /etc/patroni directory. The file holds the default
configuration values for a PostgreSQL cluster and will reflect the current cluster setup.

3. Add the following configuration for node1 :

scope: stampede1
name: node1

restapi:
listen: 0.0.0.0:8008
connect_address: node1:8008

etcd:
host: node1:2379

bootstrap:
# this section will be written into Etcd:/<namespace>/<scope>/config after initializing new
cluster
dcs:
ttl: 30
loop_wait: 10
retry_timeout: 10
maximum_lag_on_failover: 1048576
# primary_start_timeout: 300
# synchronous_mode: false
postgresql:
use_pg_rewind: true
use_slots: true
parameters:
wal_level: replica
hot_standby: "on"
logging_collector: 'on'
max_wal_senders: 5
max_replication_slots: 5
wal_log_hints: "on"
#archive_mode: "on"
#archive_timeout: 600
#archive_command: "cp -f %p /home/postgres/archived/%f"
#recovery_conf:
#restore_command: cp /home/postgres/archived/%f %p

# some desired options for 'initdb'

initdb: # Note: It needs to be a list (some options need values, others are switches)
- encoding: UTF8
- data-checksums

pg_hba: # Add following lines to pg_hba.conf after running 'initdb'

- host all all 10.104.0.7/32 md5
- host replication replicator 127.0.0.1/32 trust
- host all all 10.104.0.2/32 md5
- host all all 10.104.0.8/32 md5
- host all all 10.104.0.6/32 trust
# - hostssl all all 0.0.0.0/0 md5

# Additional script to be launched after initial cluster creation (will be passed the
connection URL as parameter)

61 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

# post_init: /usr/local/bin/setup_cluster.sh
# Some additional users users which needs to be created after initializing new cluster
users:
admin:
password: admin
options:
- createrole
- createdb
replicator:
password: password
options:
- replication
postgresql:
listen: 0.0.0.0:5432
connect_address: node1:5432
data_dir: "/var/lib/postgresql/14/main"
bin_dir: "/usr/lib/postgresql/14/bin"
# config_dir:
pgpass: /tmp/pgpass0
authentication:
replication:
username: replicator
password: password
superuser:
username: postgres
password: password
parameters:
unix_socket_directories: '/var/run/postgresql'

watchdog:
mode: required # Allowed values: off, automatic, required
device: /dev/watchdog
safety_margin: 5

tags:
nofailover: false
noloadbalance: false
clonefrom: false
nosync: false

Patroni configuration file

Let’s take a moment to understand the contents of the patroni.yml file.

The first section provides the details of the first node ( node1 ) and its connection ports. After that, we have the etcd
service and its port details.

Following these, there is a bootstrap section that contains the PostgreSQL configurations and the steps to run once
the database is initialized. The pg_hba.conf entries specify all the other nodes that can connect to this node and
their authentication mechanism.

4. Create the configuration files for node2 and node3 . Replace the reference to node1 with node2 and node3 ,
respectively.
5. Enable and restart the patroni service on every node. Use the following commands:

$ sudo systemctl enable patroni

$ sudo systemctl restart patroni

When Patroni starts, it initializes PostgreSQL (because the service is not currently running and the data
directory is empty) following the directives in the bootstrap section of the configuration file.

62 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

Troubleshooting Patroni

To ensure that Patroni has started properly, check the logs using the following command:

$ sudo journalctl -u patroni.service -n 100 -f

The output shouldn't show any errors:

Sep 23 12:50:21 node01 systemd[1]: Started PostgreSQL high-availability manager.

Sep 23 12:50:22 node01 patroni[10119]: 2021-09-23 12:50:22,022 INFO: Selected new etcd server
http://10.104.0.2:2379
Sep 23 12:50:22 node01 patroni[10119]: 2021-09-23 12:50:22,029 INFO: No PostgreSQL configuration
items changed, nothing to reload.
Sep 23 12:50:22 node01 patroni[10119]: 2021-09-23 12:50:22,168 INFO: Lock owner: None; I am node1
Sep 23 12:50:22 node01 patroni[10119]: 2021-09-23 12:50:22,177 INFO: trying to bootstrap a new
cluster
Sep 23 12:50:22 node01 patroni[10140]: The files belonging to this database system will be owned
by user "postgres".
Sep 23 12:50:22 node01 patroni[10140]: This user must also own the server process.
Sep 23 12:50:22 node01 patroni[10140]: The database cluster will be initialized with locale
"C.UTF-8".
Sep 23 12:50:22 node01 patroni[10140]: The default text search configuration will be set to
"english".
Sep 23 12:50:22 node01 patroni[10140]: Data page checksums are enabled.
Sep 23 12:50:22 node01 patroni[10140]: creating directory /var/lib/postgresql/12/main ... ok
Sep 23 12:50:22 node01 patroni[10140]: creating subdirectories ... ok
Sep 23 12:50:22 node01 patroni[10140]: selecting dynamic shared memory implementation ... posix
Sep 23 12:50:22 node01 patroni[10140]: selecting default max_connections ... 100
Sep 23 12:50:22 node01 patroni[10140]: selecting default shared_buffers ... 128MB
Sep 23 12:50:22 node01 patroni[10140]: selecting default time zone ... Etc/UTC
Sep 23 12:50:22 node01 patroni[10140]: creating configuration files ... ok
Sep 23 12:50:22 node01 patroni[10140]: running bootstrap script ... ok
Sep 23 12:50:23 node01 patroni[10140]: performing post-bootstrap initialization ... ok
Sep 23 12:50:23 node01 patroni[10140]: syncing data to disk ... ok
Sep 23 12:50:23 node01 patroni[10140]: initdb: warning: enabling "trust" authentication for local
connections
Sep 23 12:50:23 node01 patroni[10140]: You can change this by editing pg_hba.conf or using the
option -A, or
Sep 23 12:50:23 node01 patroni[10140]: --auth-local and --auth-host, the next time you run
initdb.
Sep 23 12:50:23 node01 patroni[10140]: Success. You can now start the database server using:
Sep 23 12:50:23 node01 patroni[10140]: /usr/lib/postgresql/14/bin/pg_ctl -D /var/lib/
postgresql/14/main -l logfile start
Sep 23 12:50:23 node01 patroni[10156]: 2021-09-23 12:50:23.672 UTC [10156] LOG: redirecting log
output to logging collector process
Sep 23 12:50:23 node01 patroni[10156]: 2021-09-23 12:50:23.672 UTC [10156] HINT: Future log
output will appear in directory "log".
Sep 23 12:50:23 node01 patroni[10119]: 2021-09-23 12:50:23,694 INFO: postprimary pid=10156
Sep 23 12:50:23 node01 patroni[10165]: localhost:5432 - accepting connections
Sep 23 12:50:23 node01 patroni[10167]: localhost:5432 - accepting connections
Sep 23 12:50:23 node01 patroni[10119]: 2021-09-23 12:50:23,743 INFO: establishing a new patroni
connection to the postgres cluster
Sep 23 12:50:23 node01 patroni[10119]: 2021-09-23 12:50:23,757 INFO: running post_bootstrap
Sep 23 12:50:23 node01 patroni[10119]: 2021-09-23 12:50:23,767 INFO: Software Watchdog activated
with 25 second timeout, timing slack 15 seconds
Sep 23 12:50:23 node01 patroni[10119]: 2021-09-23 12:50:23,793 INFO: initialized a new cluster
Sep 23 12:50:33 node01 patroni[10119]: 2021-09-23 12:50:33,810 INFO: no action. I am (node1) the
leader with the lock
Sep 23 12:50:33 node01 patroni[10119]: 2021-09-23 12:50:33,899 INFO: no action. I am (node1) the
leader with the lock
Sep 23 12:50:43 node01 patroni[10119]: 2021-09-23 12:50:43,898 INFO: no action. I am (node1) the
leader with the lock
Sep 23 12:50:53 node01 patroni[10119]: 2021-09-23 12:50:53,894 INFO: no action. I am (node1) the
leader with the

63 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

Changing the patroni.yml file and restarting the service will not have any effect here because the bootstrap
section specifies the configuration to apply when PostgreSQL is first started in the node. It will not repeat the
process even if the Patroni configuration file is modified and the service is restarted.

If Patroni has started properly, you should be able to locally connect to a PostgreSQL node using the
following command:

$ sudo psql -U postgres

The command output looks like the following:

psql (14.1)
Type "help" for help.

postgres=#

Configure HAProxy

HAProxy node will accept client connection requests and route those to the active node of the PostgreSQL
cluster. This way, a client application doesn’t have to know what node in the underlying cluster is the current
primary. All it needs to do is to access a single HAProxy URL and send its read/write requests there. Behind-
the-scene, HAProxy routes the connection to a healthy node (as long as there is at least one healthy node
available) and ensures that client application requests are never rejected.

HAProxy is capable of routing write requests to the primary node and read requests - to the secondaries in a
round-robin fashion so that no secondary instance is unnecessarily loaded. To make this happen, provide

64 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

different ports in the HAProxy configuration file. In this deployment, writes are routed to port 5000 and reads
- to port 5001.

1. Install HAProxy on the HAProxy-demo node:

$ sudo apt install percona-haproxy

2. The HAProxy configuration file path is: /etc/haproxy/haproxy.cfg . Specify the following configuration in this file.

global
maxconn 100

defaults
log global
mode tcp
retries 2
timeout client 30m
timeout connect 4s
timeout server 30m
timeout check 5s

listen stats
mode http
bind *:7000
stats enable
stats uri /

listen primary
bind *:5000
option httpchk /primary
http-check expect status 200
default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions
server node1 node1:5432 maxconn 100 check port 8008
server node2 node2:5432 maxconn 100 check port 8008
server node3 node3:5432 maxconn 100 check port 8008

listen standbys
balance roundrobin
bind *:5001
option httpchk /replica
http-check expect status 200
default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions
server node1 node1:5432 maxconn 100 check port 8008
server node2 node2:5432 maxconn 100 check port 8008
server node3 node3:5432 maxconn 100 check port 8008

HAProxy will use the REST APIs hosted by Patroni to check the health status of each PostgreSQL node and route
the requests appropriately.

3. Restart HAProxy:

$ sudo systemctl restart haproxy

4. Check the HAProxy logs to see if there are any errors:

$ sudo journalctl -u haproxy.service -n 100 -f

65 of 112 Percona LLC, © 2023

5.1.2 Deploying PostgreSQL for high availability with Patroni on Debian or Ubuntu

Testing

See the Testing PostgreSQL cluster for the guidelines on how to test your PostgreSQL cluster for replication,
failure, switchover.

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: December 5, 2022

Created: December 15, 2021

66 of 112 Percona LLC, © 2023

5.1.3 Deploying PostgreSQL for high availability with Patroni on RHEL or CentOS

This guide provides instructions on how to set up a highly available PostgreSQL cluster with Patroni on Red
Hat Enterprise Linux or CentOS.

Preconditions

For this setup, we will use the nodes running on CentOS 8 as the base operating system and having the
following IP addresses:

Hostname Public IP address Internal IP address

node1 157.230.42.174 10.104.0.7

node2 68.183.177.183 10.104.0.2

node3 165.22.62.167 10.104.0.8

etcd 159.102.29.166 10.104.0.5

HAProxy-demo 134.209.111.138 10.104.0.6

Note

In a production (or even non-production) setup, the PostgreSQL and ETCD nodes will be within a private subnet
without any public connectivity to the Internet, and the HAProxy will be in a different subnet that allows client traffic
coming only from a selected IP range. To keep things simple, we have implemented this architecture in a
DigitalOcean VPS environment, and each node can access the other by its internal, private IP.

Setting up hostnames in the /etc/hosts file

To make the nodes aware of each other and allow their seamless communication, resolve their hostnames
to their public IP addresses. Modify the /etc/hosts file of each PostgreSQL node to include the hostnames
and IP addresses of the remaining nodes. The following is the /etc/hosts file for node1 :

127.0.0.1 localhost node1

10.104.0.7 node1
10.104.0.2 node2
10.104.0.8 node3

The /etc/hosts file of the HAProxy-demo node hostnames and IP addresses of all PostgreSQL nodes:

127.0.1.1 HAProxy-demo HAProxy-demo

127.0.0.1 localhost
10.104.0.6 HAProxy-demo
10.104.0.7 node1
10.104.0.2 node2
10.104.0.8 node3

Keep the /etc/hosts file of the etcd node unchanged.

67 of 112 Percona LLC, © 2023

5.1.3 Deploying PostgreSQL for high availability with Patroni on RHEL or CentOS

Configure ETCD distributed store

In this setup we will configure ETCD on a dedicated node.

1. Install etcd on the ETCD node. For CentOS 8, the etcd packages are available from Percona repository:
2. Install percona-release .
3. Enable the repository:

$ sudo percona-release setup ppg14

4. Install the etcd packages using the following command:

$ sudo yum install etcd python3-python-etcd

5. Modify the /etc/etcd/etcd.conf configuration file:

[Member]
ETCD_DATA_DIR="/var/lib/etcd/default.etcd"
ETCD_LISTEN_PEER_URLS="http://10.104.0.5:2380,http://localhost:2380"
ETCD_LISTEN_CLIENT_URLS="http://10.104.0.5:2379,http://localhost:2379"

ETCD_NAME="default"
ETCD_INITIAL_ADVERTISE_PEER_URLS="http://10.104.0.5:2380"
ETCD_ADVERTISE_CLIENT_URLS="http://10.104.0.5:2379"
ETCD_INITIAL_CLUSTER="default=http://10.104.0.5:2380"
ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster"
ETCD_INITIAL_CLUSTER_STATE="new"

1. Start the etcd to apply the changes:

$ sudo systemctl enable etcd

$ sudo systemctl start etcd
$ sudo systemctl status etcd

2. Check the etcd cluster members.

$ sudo etcdctl member list

The output resembles the following:

21d50d7f768f153a: name=default peerURLs=http://10.104.0.5:2380 clientURLs=http://

10.104.0.5:2379 isLeader=true

68 of 112 Percona LLC, © 2023

5.1.3 Deploying PostgreSQL for high availability with Patroni on RHEL or CentOS

Install Percona Distribution for PostgreSQL

Install Percona Distribution for PostgreSQL on node1 , node2 and node3 from Percona repository:

1. Install percona-release .
2. Enable the repository:

$ sudo percona-release setup ppg14

3. Install Percona Distribution for PostgreSQL packages.

Important

Don't initialize the cluster and start the postgresql service. The cluster initialization and setup are handled by
Patroni during the bootsrapping stage.

Configure Patroni

1. Install Patroni on every PostgreSQL node:

$ sudo yum install percona-patroni

2. Install the Python module that enables Patroni to communicate with ETCD.

$ sudo python3 -m pip install patroni[etcd]

3. Create the directories required by Patroni

• Create the directory to store the configuration file and make it owned by the postgres user.

$ sudo mkdir -p /etc/patroni/

$ sudo chown -R postgres:postgres /etc/patroni/

• Create the data directory for Patroni. Change its ownership to the postgres user and restrict the access to it

$ sudo mkdir /data/patroni -p

$ sudo chown -R postgres:postgres /data/patroni
$ sudo chmod 700 /data/patroni

4. Create the patroni.yml configuration file.

$ su postgres
$ vim /etc/patroni/patroni.yml

5. Specify the following configuration:

scope: postgres
namespace: /pg_cluster/
name: node1

restapi:
listen: 10.104.0.7:8008 # PostgreSQL node IP address
connect_address: 10.104.0.7:8008 # PostgreSQL node IP address

69 of 112 Percona LLC, © 2023

5.1.3 Deploying PostgreSQL for high availability with Patroni on RHEL or CentOS

etcd:
host: 10.104.0.5:2379 # ETCD node IP address

bootstrap:
# this section will be written into Etcd:/<namespace>/<scope>/config after initializing new
cluster
dcs:
ttl: 30
loop_wait: 10
retry_timeout: 10
maximum_lag_on_failover: 1048576
postgresql:
use_pg_rewind: true
use_slots: true
parameters:
wal_level: replica
hot_standby: "on"
logging_collector: 'on'
max_wal_senders: 5
max_replication_slots: 5
wal_log_hints: "on"

# some desired options for 'initdb'

initdb: # Note: It needs to be a list (some options need values, others are switches)
- encoding: UTF8
- data-checksums

pg_hba: # Add following lines to pg_hba.conf after running 'initdb'

- host replication replicator 127.0.0.1/32 md5
- host replication replicator 10.104.0.2/32 md5
- host replication replicator 10.104.0.8/32 md5
- host replication replicator 10.104.0.7/32 md5
- host all all 0.0.0.0/0 md5
# - hostssl all all 0.0.0.0/0 md5

# Some additional users users which needs to be created after initializing new cluster
users:
admin:
password: admin
options:
- createrole
- createdb

postgresql:
listen: 10.104.0.7:5432 # PostgreSQL node IP address
connect_address: 10.104.0.7:5432 # PostgreSQL node IP address
data_dir: /data/patroni # The datadir you created
bin_dir: /usr/pgsql-14/bin
pgpass: /tmp/pgpass0
authentication:
replication:
username: replicator
password: replicator
superuser:
username: postgres
password: postgres
parameters:
unix_socket_directories: '.'

tags:
nofailover: false
noloadbalance: false

70 of 112 Percona LLC, © 2023

5.1.3 Deploying PostgreSQL for high availability with Patroni on RHEL or CentOS

clonefrom: false
nosync: false

6. Create the configuration files for node2 and node3 . Replace the node and IP address of node1 to those of
node2 and node3 , respectively.

7. Create the systemd unit file patroni.service in /etc/systemd/system .

$ sudo vim /etc/systemd/system/patroni.service

Add the following contents in the file:

[Unit]
Description=Runners to orchestrate a high-availability PostgreSQL
After=syslog.target network.target

[Service]
Type=simple

User=postgres
Group=postgres

# Start the patroni process

ExecStart=/bin/patroni /etc/patroni/patroni.yml

# Send HUP to reload from patroni.yml

ExecReload=/bin/kill -s HUP $MAINPID

# only kill the patroni process, not its children, so it will gracefully stop postgres
KillMode=process

# Give a reasonable amount of time for the server to start up/shut down
TimeoutSec=30

# Do not restart the service if it crashes, we want to manually inspect database on failure
Restart=no

[Install]
WantedBy=multi-user.target

8. Make systemd aware of the new service:

$ sudo systemctl daemon-reload

$ sudo systemctl enable patroni
$ sudo systemctl start patroni

71 of 112 Percona LLC, © 2023

5.1.3 Deploying PostgreSQL for high availability with Patroni on RHEL or CentOS

Troubleshooting Patroni

To ensure that Patroni has started properly, check the logs using the following command:

$ sudo journalctl -u patroni.service -n 100 -f

The output shouldn't show any errors:

Sep 23 12:50:21 node01 systemd[1]: Started PostgreSQL high-availability manager.

Sep 23 12:50:22 node01 patroni[10119]: 2021-09-23 12:50:22,022 INFO: Selected new etcd server
http://10.104.0.2:2379
Sep 23 12:50:22 node01 patroni[10119]: 2021-09-23 12:50:22,029 INFO: No PostgreSQL configuration
items changed, nothing to reload.
Sep 23 12:50:22 node01 patroni[10119]: 2021-09-23 12:50:22,168 INFO: Lock owner: None; I am node1
Sep 23 12:50:22 node01 patroni[10119]: 2021-09-23 12:50:22,177 INFO: trying to bootstrap a new
cluster
Sep 23 12:50:22 node01 patroni[10140]: The files belonging to this database system will be owned by
user "postgres".
Sep 23 12:50:22 node01 patroni[10140]: This user must also own the server process.
Sep 23 12:50:22 node01 patroni[10140]: The database cluster will be initialized with locale
"C.UTF-8".
Sep 23 12:50:22 node01 patroni[10140]: The default text search configuration will be set to
"english".
Sep 23 12:50:22 node01 patroni[10140]: Data page checksums are enabled.
Sep 23 12:50:22 node01 patroni[10140]: creating directory /var/lib/postgresql/12/main ... ok
Sep 23 12:50:22 node01 patroni[10140]: creating subdirectories ... ok
Sep 23 12:50:22 node01 patroni[10140]: selecting dynamic shared memory implementation ... posix
Sep 23 12:50:22 node01 patroni[10140]: selecting default max_connections ... 100
Sep 23 12:50:22 node01 patroni[10140]: selecting default shared_buffers ... 128MB
Sep 23 12:50:22 node01 patroni[10140]: selecting default time zone ... Etc/UTC
Sep 23 12:50:22 node01 patroni[10140]: creating configuration files ... ok
Sep 23 12:50:22 node01 patroni[10140]: running bootstrap script ... ok
Sep 23 12:50:23 node01 patroni[10140]: performing post-bootstrap initialization ... ok
Sep 23 12:50:23 node01 patroni[10140]: syncing data to disk ... ok
Sep 23 12:50:23 node01 patroni[10140]: initdb: warning: enabling "trust" authentication for local
connections
Sep 23 12:50:23 node01 patroni[10140]: You can change this by editing pg_hba.conf or using the
option -A, or
Sep 23 12:50:23 node01 patroni[10140]: --auth-local and --auth-host, the next time you run initdb.
Sep 23 12:50:23 node01 patroni[10140]: Success. You can now start the database server using:
Sep 23 12:50:23 node01 patroni[10140]: /usr/lib/postgresql/14/bin/pg_ctl -D /var/lib/
postgresql/14/main -l logfile start
Sep 23 12:50:23 node01 patroni[10156]: 2021-09-23 12:50:23.672 UTC [10156] LOG: redirecting log
output to logging collector process
Sep 23 12:50:23 node01 patroni[10156]: 2021-09-23 12:50:23.672 UTC [10156] HINT: Future log output
will appear in directory "log".
Sep 23 12:50:23 node01 patroni[10119]: 2021-09-23 12:50:23,694 INFO: postprimary pid=10156
Sep 23 12:50:23 node01 patroni[10165]: localhost:5432 - accepting connections
Sep 23 12:50:23 node01 patroni[10167]: localhost:5432 - accepting connections
Sep 23 12:50:23 node01 patroni[10119]: 2021-09-23 12:50:23,743 INFO: establishing a new patroni
connection to the postgres cluster
Sep 23 12:50:23 node01 patroni[10119]: 2021-09-23 12:50:23,757 INFO: running post_bootstrap
Sep 23 12:50:23 node01 patroni[10119]: 2021-09-23 12:50:23,767 INFO: Software Watchdog activated
with 25 second timeout, timing slack 15 seconds
Sep 23 12:50:23 node01 patroni[10119]: 2021-09-23 12:50:23,793 INFO: initialized a new cluster
Sep 23 12:50:33 node01 patroni[10119]: 2021-09-23 12:50:33,810 INFO: no action. I am (node1) the
leader with the lock
Sep 23 12:50:33 node01 patroni[10119]: 2021-09-23 12:50:33,899 INFO: no action. I am (node1) the
leader with the lock
Sep 23 12:50:43 node01 patroni[10119]: 2021-09-23 12:50:43,898 INFO: no action. I am (node1) the
leader with the lock
Sep 23 12:50:53 node01 patroni[10119]: 2021-09-23 12:50:53,894 INFO: no action. I am (node1) the
leader with the

72 of 112 Percona LLC, © 2023

5.1.3 Deploying PostgreSQL for high availability with Patroni on RHEL or CentOS

A common error is Patroni complaining about the lack of proper entries in the pg_hba.conf file. If you see such
errors, you must manually add or fix the entries in that file and then restart the service.
Changing the patroni.yml file and restarting the service will not have any effect here because the bootstrap section
specifies the configuration to apply when PostgreSQL is first started in the node. It will not repeat the process even if
the Patroni configuration file is modified and the service is restarted.
If Patroni has started properly, you should be able to locally connect to a PostgreSQL node using the following
command:

$ sudo psql -U postgres

psql (14.1)
Type "help" for help.

postgres=#

9. Configure, enable and start Patroni on the remaining nodes.

10. When all nodes are up and running, you can check the cluster status using the following command:

$ sudo patronictl -c /etc/patroni/patroni.yml list

Output:

+ Cluster: postgres (7011110722654005156) -----------+

Configure HAProxy

73 of 112 Percona LLC, © 2023

5.1.3 Deploying PostgreSQL for high availability with Patroni on RHEL or CentOS

different ports in the HAProxy configuration file. In this deployment, writes are routed to port 5000 and reads
- to port 5001.

74 of 112 Percona LLC, © 2023

5.1.3 Deploying PostgreSQL for high availability with Patroni on RHEL or CentOS

1. Install HAProxy on the HAProxy-demo node:

$ sudo yum install percona-haproxy

2. The HAProxy configuration file path is: /etc/haproxy/haproxy.cfg . Specify the following configuration in this file.

global
maxconn 100

defaults
log global
mode tcp
retries 2
timeout client 30m
timeout connect 4s
timeout server 30m
timeout check 5s

listen stats
mode http
bind *:7000
stats enable
stats uri /

HAProxy will use the REST APIs hosted by Patroni to check the health status of each PostgreSQL node and route
the requests appropriately.
3. Enable a SELinux boolean to allow HAProxy to bind to non standard ports:

$ sudo setsebool -P haproxy_connect_any on

4. Restart HAProxy:

$ sudo systemctl restart haproxy

5. Check the HAProxy logs to see if there are any errors:

$ sudo journalctl -u haproxy.service -n 100 -f

75 of 112 Percona LLC, © 2023

5.1.3 Deploying PostgreSQL for high availability with Patroni on RHEL or CentOS

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: December 5, 2022

Created: December 15, 2021

5.1.4 Testing the Patroni PostgreSQL Cluster

This document covers the following scenarios to test the PostgreSQL cluster:

• replication,

• connectivity,
• failover, and
• manual switchover.

TESTING REPLICATION

1. Connect to the cluster and establish the psql session from a client machine that can connect to the HAProxy
node. Use the HAProxy-demo node's public IP address:

$ psql -U postgres -h 134.209.111.138 -p 5000

2. Run the following commands to create a table and insert a few rows:

CREATE TABLE customer(name text,age integer);

INSERT INTO CUSTOMER VALUES('john',30);
INSERT INTO CUSTOMER VALUES('dawson',35);

3. To ensure that the replication is working, we can log in to each PostgreSQL node and run a simple SQL
statement against the locally running instance:

$ sudo psql -U postgres -c "SELECT * FROM CUSTOMER;"

The results on each node should be the following:

name | age
--------+-----
john | 30
dawson | 35
(2 rows)

TESTING FAILOVER

In a proper setup, client applications won't have issues connecting to the cluster, even if one or even two of
the nodes go down. We will test the cluster for failover in the following scenarios:

Scenario 1. Intentionally stop the PostgreSQL on the primary node and verify access to PostgreSQL.

1. Run the following command on any node to check the current cluster status:

$ sudo patronictl -c /etc/patroni/patroni.yml list

Output:

+ Cluster: stampede1 (7011110722654005156) -----------+

5.1.4 Testing the Patroni PostgreSQL Cluster

| node3 | node3 | Replica | running | 1 | 0 |

+--------+-------+---------+---------+----+-----------+

2. node1 is the current leader. Stop Patroni in node1 to see how it changes the cluster:

$ sudo systemctl stop patroni

3. Once the service stops in node1 , check the logs in node2 and node3 using the following command:

$ sudo journalctl -u patroni.service -n 100 -f

??? admonition "Output"

```
Sep 23 14:18:13 node03 patroni[10042]: 2021-09-23 14:18:13,905 INFO: no action. I am a
secondary (node3) and following a leader (node1)
Sep 23 14:18:20 node03 patroni[10042]: 2021-09-23 14:18:20,011 INFO: Got response from node2
http://node2:8008/patroni: {"state": "running", "postprimary_start_time": "2021-09-23
12:50:29.460027+00:00", "role": "replica", "server_version": 130003, "cluster_unlocked": true,
"xlog": {"received_location": 67219152, "replayed_location": 67219152, "replayed_timestamp":
"2021-09-23 13:19:50.329387+00:00", "paused": false}, "timeline": 1,
"database_system_identifier": "7011110722654005156", "patroni": {"version": "2.1.0", "scope":
"stampede1"}}
Sep 23 14:18:20 node03 patroni[10042]: 2021-09-23 14:18:20,031 WARNING: Request failed to
node1: GET http://node1:8008/patroni (HTTPConnectionPool(host='node1', port=8008): Max retries
exceeded with url: /patroni (Caused by ProtocolError('Connection aborted.',
ConnectionResetError(104, 'Connection reset by peer'))))
Sep 23 14:18:20 node03 patroni[10042]: 2021-09-23 14:18:20,038 INFO: Software Watchdog
activated with 25 second timeout, timing slack 15 seconds
Sep 23 14:18:20 node03 patroni[10042]: 2021-09-23 14:18:20,043 INFO: promoted self to leader
by acquiring session lock
Sep 23 14:18:20 node03 patroni[13641]: server promoting
Sep 23 14:18:20 node03 patroni[10042]: 2021-09-23 14:18:20,049 INFO: cleared rewind state
after becoming the leader
Sep 23 14:18:21 node03 patroni[10042]: 2021-09-23 14:18:21,101 INFO: no action. I am (node3)
the leader with the lock
Sep 23 14:18:21 node03 patroni[10042]: 2021-09-23 14:18:21,117 INFO: no action. I am (node3)
the leader with the lock
Sep 23 14:18:31 node03 patroni[10042]: 2021-09-23 14:18:31,114 INFO: no action. I am (node3)
the leader with the lock
...
```

The logs in node3 show that the requests to node1 are failing, the watchdog is coming into action, and node3
is promoting itself as the leader:
4. Verify that you can still access the cluster through the HAProxy instance and read data:

$ psql -U postgres -h 10.104.0.6 -p 5000 -c "SELECT * FROM CUSTOMER;"

name | age
--------+-----
john | 30
dawson | 35
(2 rows)

5. Restart the Patroni service in node1

5.1.4 Testing the Patroni PostgreSQL Cluster

$ sudo systemctl start patroni

6. Check the current cluster status:

$ sudo patronictl -c /etc/patroni/patroni.yml list

Output:

+ Cluster: stampede1 (7011110722654005156) -----------+

As we see, node3 remains the leader and the rest are replicas.

5.1.4 Testing the Patroni PostgreSQL Cluster

Scenario 2. Abrupt machine shutdown or power outage

To emulate the power outage, let's kill the service in node3 and see what happens in node1 and node2 .

1. Identify the process ID of Patroni and then kill it with a -9 switch.

$ ps aux | grep -i patroni

postgres 10042 0.1 2.1 647132 43948 ? Ssl 12:50 0:09 /usr/bin/python3 /usr/bin/
patroni /etc/patroni/patroni.yml

$ sudo kill -9 10042

2. Check the logs on node2 :

$ sudo journalctl -u patroni.service -n 100 -f

??? admonition "Output"

```
Sep 23 14:40:41 node02 patroni[10577]: 2021-09-23 14:40:41,656 INFO: no action. I am a
secondary (node2) and following a leader (node3)
…
Sep 23 14:41:01 node02 patroni[10577]: 2021-09-23 14:41:01,373 INFO: Got response from node1
http://node1:8008/patroni: {"state": "running", "postprimary_start_time": "2021-09-23
14:25:30.076762+00:00", "role": "replica", "server_version": 130003, "cluster_unlocked": true,
"xlog": {"received_location": 67221352, "replayed_location": 67221352, "replayed_timestamp":
null, "paused": false}, "timeline": 2, "database_system_identifier": "7011110722654005156",
"patroni": {"version": "2.1.0", "scope": "stampede1"}}
Sep 23 14:41:03 node02 patroni[10577]: 2021-09-23 14:41:03,364 WARNING: Request failed to
node3: GET http://node3:8008/patroni (HTTPConnectionPool(host='node3', port=8008): Max retries
exceeded with url: /patroni (Caused by ConnectTimeoutError(<urllib3.connection.HTTPConnection
object at 0x7f57e06dffa0>, 'Connection to node3 timed out. (connect timeout=2)')))
Sep 23 14:41:03 node02 patroni[10577]: 2021-09-23 14:41:03,373 INFO: Software Watchdog
activated with 25 second timeout, timing slack 15 seconds
Sep 23 14:41:03 node02 patroni[10577]: 2021-09-23 14:41:03,385 INFO: promoted self to leader
by acquiring session lock
Sep 23 14:41:03 node02 patroni[15478]: server promoting
Sep 23 14:41:03 node02 patroni[10577]: 2021-09-23 14:41:03,397 INFO: cleared rewind state
after becoming the leader
Sep 23 14:41:04 node02 patroni[10577]: 2021-09-23 14:41:04,450 INFO: no action. I am (node2)
the leader with the lock
Sep 23 14:41:04 node02 patroni[10577]: 2021-09-23 14:41:04,475 INFO: no action. I am (node2)
the leader with the lock
…
…
```

node2 realizes that the leader is dead, and promotes itself as the leader.

3. Try accessing the cluster using the HAProxy endpoint at any point in time between these operations. The
cluster is still accepting connections.

MANUAL SWITCHOVER

Typically, a manual switchover is needed for planned downtime to perform maintenance activity on the
leader node. Patroni provides the switchover command to manually switch over from the leader node.

Run the following command on node2 (the current leader node):

5.1.4 Testing the Patroni PostgreSQL Cluster

$ sudo patronictl -c /etc/patroni/patroni.yml switchover

Patroni asks the name of the current primary node and then the node that should take over as the
switched-over primary. You can also specify the time at which the switchover should happen. To trigger the
process immediately, specify the value now:

primary [node2]: node2

Restart the Patroni service in node2 (after the "planned maintenance"). The node rejoins the cluster as a
secondary.

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: December 5, 2022

Created: December 15, 2021

5.2 Backup and disaster recovery

5.2.1 Backup and disaster recovery in Percona Distribution for PostgreSQL

Summary

• Overview
• Architecture

• Deployment
• Testing

Overview

A Disaster Recovery (DR) solution ensures that a system can be quickly restored to a normal operational
state if something unexpected happens. When operating a database, you would back up the data as
frequently as possible and have a mechanism to restore that data when needed. Disaster Recovery is often
mistaken for high availability (HA), but they are two different concepts altogether:

• High availability ensures guaranteed service levels at all times. This solution involves configuring one or
more standby systems to an active database, and the ability to switch seamlessly to that standby when
the primary database becomes unavailable, for example, during a power outage or a server crash. To
learn more about high-availability solutions with Percona Distribution for PostgreSQL, refer to High
Availability in PostgreSQL with Patroni.

• Disaster Recovery protects the database instance against accidental or malicious data loss or data
corruption. Disaster recovery can be achieved by using either the options provided by PostgreSQL, or
external extensions.

??? "PostgreSQL disaster recovery options"

PostgreSQL offers multiple options for setting up database disaster recovery.

- **[pg_dump](https://www.postgresql.org/docs/15/app-pgdump.html) or the [pg_dumpall](https://

www.postgresql.org/docs/15/app-pg-dumpall.html) utilities**

This is the basic backup approach. These tools can generate the backup of one or more
PostgreSQL databases (either just the structure, or both the structure and data), then restore
them through the [pg_restore](https://www.postgresql.org/docs/15/app-pgrestore.html) command.

| Advantages | Disadvantages |
| ------------ | --------------- |
| Easy to use | 1. Backup of only one database at a time. 2. No incremental backups. 3.
No point-in-time recovery since the backup is a snapshot in time. 4. Performance
degradation when the database size is large.|

- File-based backup and restore

This method involves backing up the PostgreSQL data directory to a different location, and
restoring it when needed.

| Advantages | Disadvantages |
| ------------ | --------------- |
| Consistent snapshot of the data directory or the whole data disk volume | 1. Requires
stopping PostgreSQL in order to copy the files. This is not practical for most production
setups. 2. No backup of individual databases or tables.|

5.2.1 Backup and disaster recovery in Percona Distribution for PostgreSQL

- **PostgreSQL [pg_basebackup](https://www.postgresql.org/docs/15/app-pgbasebackup.html)**

This backup tool is provided by PostgreSQL. It is used to back up data when the database
instance is running. `pgasebackup` makes a binary copy of the database cluster files, while
making sure the system is put in and out of backup mode automatically.

| Advantages | Disadvantages |
| ------------ | --------------- |
| 1. Supports backups when the database is running. 2. Supports point-in-time recovery | 1.
No incremental backups. 2. No backup of individual databases or tables.|

To achieve a production grade PostgreSQL disaster recovery solution, you need something that can take full
or incremental database backups from a running instance, and restore from those backups at any point in
time. Percona Distribution for PostgreSQL is supplied with pgBackRest: a reliable, open-source backup and
recovery solution for PostgreSQL.

This document focuses on the Disaster recovery solution in Percona Distribution for PostgreSQL. The
Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL tutorial provides
guidelines of how to set up and test this solution.

PGBACKREST

pgBackRest is an easy-to-use, open-source solution that can reliably back up even the largest of
PostgreSQL databases. pgBackRest supports the following backup types:

• full backup - a complete copy of your entire data set.

• differential backup - includes all data that has changed since the last full backup. While this means the
backup time is slightly higher, it enables a faster restore.

• incremental backup - only backs up the files that have changed since the last full or differential backup,
resulting in a quick backup time. To restore to a point in time, however, you will need to restore each
incremental backup in the order they were taken.

When it comes to restoring, pgBackRest can do a full or a delta restore. A full restore needs an empty
PostgreSQL target directory. A delta restore is intelligent enough to recognize already-existing files in the
PostgreSQL data directory, and update only the ones the backup contains.

pgBackRest supports remote repository hosting and can even use cloud-based services like AWS S3, Google
Cloud Services Cloud Storage, Azure Blob Storage for saving backup files. It supports parallel backup
through multi-core processing and compression. By default, backup integrity is verified through checksums,
and saved files can be encrypted for enhanced security.

pgBackRest can restore a database to a specific point in time in the past. This is the case where a database
is not inaccessible but perhaps contains corrupted data. Using the point-in-time recovery, a database
administrator can restore the database to the last known good state.

Finally, pgBackRest also supports restoring PostgreSQL databases to a different PostgreSQL instance or a
separate data directory.

Setup overview

This section describes the architecture of the backup and disaster recovery solution. For the configuration
steps, refer to the Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL.

SYSTEM ARCHITECTURE

As the configuration example, we will use a three server architecture where pgBackRest resides on a
dedicated remote host. The servers communicate with each other via passwordless SSH.

5.2.1 Backup and disaster recovery in Percona Distribution for PostgreSQL

Important

Passwordless SSH may not be an ideal solution for your environment. In this case, consider using other methods,
for example, TLS with client certificates.

The following diagram illustrates the architecture layout:

Components:

The architecture consists of three server instances:

• pg-primary hosts the primary PostgreSQL server. Note that "primary" here means the main database
instance and does not refer to the primary node of a PostgreSQL replication cluster or a HA setup.
• pg-repo is the remote backup repository and hosts pgBackRest . It's important to host the backup
repository on a physically separate instance, to be accessed when the target goes down.
• pg-secondary is the secondary PostgreSQL node. Don't confuse it with a hot standby. "Secondary" in this
context means a PostgreSQL instance that's idle. We will restore the database backup to this instance
when the primary PostgreSQL instance goes down.

Note

For simplicity, we use a single-node PostgreSQL instance as the primary database server. In a production scenario,
you will use some form of high-availability solution to protect the primary instance. When you are using a high-
availability setup, we recommend configuring pgBackRest to back up the hot standby server so the primary node
is not unnecessarily loaded.

DEPLOYMENT

Refer to the Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL tutorial.

For free technical help, visit the Percona Community Forum.

5.2.1 Backup and disaster recovery in Percona Distribution for PostgreSQL

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: October 24, 2022

Created: January 21, 2022

5.2.2 Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL

This document provides instructions of how to set up and test the backup and disaster recovery solution in
Percona Distribution for PostgreSQL with pgBackRest . For technical overview and architecture description of
this solution, refer to Backup and disaster recovery in Percona Distribution for PostgreSQL.

Deployment

As the example configuration, we will use the nodes with the following IP addresses:

Node name Internal IP address

pg-primary 10.104.0.3

pg-repo 10.104.0.5

pg-secondary 10.104.0.4

SET UP HOSTNAMES

In our architecture, the pgBackRest repository is located on a remote host. To allow communication among
the nodes, passwordless SSH is required. To achieve this, properly setting up hostnames in the /etc/hosts
files is very important.

1. Define the hostname for every server in the /etc/hostname file. The following are the examples of how
the /etc/hostname file in three nodes looks like:

cat /etc/hostname
pg-primary

cat /etc/hostname
pg-repo

cat /etc/hostname
pg-secondary

2. For the nodes to communicate seamlessly across the network, resolve their hostnames to their IP addresses in
the /etc/hosts file. (Alternatively, you can make appropriate entries in your internal DNS servers)

The /etc/hosts file for the pg-primary node looks like this:

```
127.0.1.1 pg-primary pg-primary
127.0.0.1 localhost
10.104.0.5 pg-repo
```

The /etc/hosts file in the pg-repo node looks like this:

```
127.0.1.1 pg-repo pg-repo
127.0.0.1 localhost
10.104.0.3 pg-primary
10.104.0.4 pg-secondary
```

5.2.2 Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL

The /etc/hosts file in the pg-secondary node is shown below:

```
127.0.1.1 pg-secondary pg-secondary
127.0.0.1 localhost
10.104.0.3 pg-primary
10.104.0.5 pg-repo
```

5.2.2 Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL

SET UP PASSWORDLESS SSH

Before setting up passwordless SSH, ensure that the postgres user in all three instances has a password.

5.2.2 Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL

1. To set or change the password, run the following command as a root user:

$ passwd postgres

2. Type the new password and confirm it.

3. After setting up the password, edit the /etc/ssh/sshd_config file and ensure the PasswordAuthentication
variable is set as yes .

PasswordAuthentication yes

4. In the pg-repo node, restart the sshd service. Without the restart, the SSH server will not allow you to connect
to it using a password while adding the keys.

$ sudo service sshd restart

5. In the pg-primary node, generate an SSH key pair and add the public key to the pg-repo node.

Important

Run the commands as the postgres user.

• Generate SSH keys:

$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa
Your public key has been saved in /root/.ssh/id_rsa.pub
The key fingerprint is:
...

• Copy the public key to the pg-repo node:

$ ssh-copy-id -i ~/.ssh/id_rsa.pub postgres@pg-repo

/usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/root/.ssh/id_rsa.pub"
/usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that
are already installed
/usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is
to install the new keys
postgres@pg-repo's password:

Number of key(s) added: 1

Now try logging into the machine, with: "ssh 'postgres@pg-repo'"

and check to make sure that only the key(s) you wanted were added.

6. To verify everything has worked as expected, run the following command from the pg-primary node.

$ ssh postgres@pg-repo

You should be able to connect to the pg-repo terminal without a password.

5.2.2 Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL

7. Repeat the SSH connection from pg-repo to pg-primary to ensure that passwordless SSH is working.

8. Set up bidirectional passwordless SSH between pg-repo and pg-secondary using the same method. This will
allow pg-repo to recover the backups to pg-secondary .

INSTALL PERCONA DISTRIBUTION FOR POSTGRESQL

Install Percona Distribution for PostgreSQL in the primary and the secondary nodes from Percona repository.

1. Install percona-release .
2. Enable the repository:

$ sudo percona-release setup ppg14

3. Install Percona Distribution for PostgreSQL packages

On Debian and Ubuntu

$ sudo apt install percona-postgresql-14 -y

On RedHat Enterprise Linux and derivatives

$ sudo yum install percona-postgresql14-server

CONFIGURE POSTGRESQL ON THE PRIMARY NODE FOR CONTINUOUS BACKUP

At this step, configure the PostgreSQL instance on the pg-primary node for continuous archiving of the WAL
files.

Note

On Debian and Ubuntu, the path to the configuration file is /etc/postgresql/14/main/postgresql.conf .

On RHEL and CentOS, the path to the configuration file is /var/lib/pgsql/14/data/ .

1. Edit the postgresql.conf configuration file to include the following changes:

archive_command = 'pgbackrest --stanza=prod_backup archive-push %p'

archive_mode = on
listen_addresses = '*'
log_line_prefix = ''
max_wal_senders = 3
wal_level = replica

2. Once the changes are saved, restart PostgreSQL.

$ sudo systemctl restart postgresql

5.2.2 Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL

INSTALL PGBACKREST

Install pgBackRest in all three instances from Percona repository. Use the following command:

On Debian / Ubuntu

$ sudo apt-get install percona-pgbackrest

On RHEL / derivatives

$ sudo yum install percona-pgbackrest

CREATE THE PGBACKREST CONFIGURATION FILE

Run the following commands on all three nodes to set up the required configuration file for pgBackRest .

1. Configure a location and permissions for the pgBackRest log rotation:

$ sudo mkdir -p -m 770 /var/log/pgbackrest

$ sudo chown postgres:postgres /var/log/pgbackrest

2. Configure the location and permissions for the pgBackRest configuration file:

$ sudo mkdir -p /etc/pgbackrest

$ sudo mkdir -p /etc/pgbackrest/conf.d
$ sudo touch /etc/pgbackrest/pgbackrest.conf
$ sudo chmod 640 /etc/pgbackrest/pgbackrest.conf
$ sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf
$ sudo mkdir -p /home/pgbackrest
$ sudo chmod postgres:postgres /home/pgbackrest

UPDATE PGBACKREST CONFIGURATION FILE IN THE PRIMARY NODE

Configure pgBackRest on the pg-primary node by setting up a stanza. A stanza is a set of configuration
parameters that tells pgBackRest where to backup its files. Edit the /etc/pgbackrest/pgbackrest.conf file in
the pg-primary node to include the following lines:

[global]
repo1-host=pg-repo
repo1-host-user=postgres
process-max=2
log-level-console=info
log-level-file=debug

[prod_backup]
pg1-path=/var/lib/postgresql/14/main

You can see the pg1-path attribute for the prod_backup stanza has been set to the PostgreSQL data folder.

UPDATE PGBACKREST CONFIGURATION FILE IN THE REMOTE BACKUP REPOSITORY NODE

Add a stanza for the pgBackRest in the pg-repo node. Edit the /etc/pgbackrest/pgbackrest.conf configuration
file to include the following lines:

[global]
repo1-path=/home/pgbackrest/pg_backup
repo1-retention-full=2

5.2.2 Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL

process-max=2
log-level-console=info
log-level-file=debug
start-fast=y
stop-auto=y

[prod_backup]
pg1-path=/var/lib/postgresql/14/main
pg1-host=pg-primary
pg1-host-user=postgres
pg1-port = 5432

INITIALIZE PGBACKREST STANZA IN THE REMOTE BACKUP REPOSITORY NODE

After the configuration files are set up, it’s now time to initialize the pgBackRest stanza. Run the following
command in the remote backup repository node ( pg-repo ).

$ sudo -u postgres pgbackrest --stanza=prod_backup stanza-create

2021-11-07 11:08:18.157 P00 INFO: stanza-create command begin 2.36: --exec-
id=155883-2277a3e7 --log-level-console=info --log-level-file=off --pg1-host=pg-primary --
pg1-host-user=postgres --pg1-path=/var/lib/postgresql/14/main --pg1-port=5432 --repo1-path=/
home/pgbackrest/pg_backup --stanza=prod_backup
2021-11-07 11:08:19.453 P00 INFO: stanza-create for stanza 'prod_backup' on repo1
2021-11-07 11:08:19.566 P00 INFO: stanza-create command end: completed successfully
(1412ms)

Once the stanza is created successfully, you can try out the different use cases for disaster recovery.

Testing Backup and Restore with pgBackRest

This section covers a few use cases where pgBackRest can back up and restore databases either in the
same instance or a different node.

USE CASE 1: CREATE A BACKUP WITH PGBACKREST

1. To start our testing, let’s create a table in the postgres database in the pg-primary node and add some data.

CREATE TABLE CUSTOMER (id integer, name text);

INSERT INTO CUSTOMER VALUES (1,'john');
INSERT INTO CUSTOMER VALUES (2,'martha');
INSERT INTO CUSTOMER VALUES (3,'mary');

2. Take a full backup of the database instance. Run the following commands from the pg-repo node:

$ pgbackrest -u postgres --stanza=prod_backup backup --type=full

If you want an incremental backup, you can omit the type attribute. By default, pgBackRest always takes an
incremental backup except the first backup of the cluster which is always a full backup.

If you need a differential backup, use diff for the type field:

$ pgbackrest -u postgres --stanza=prod_backup backup --type=diff

5.2.2 Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL

USE CASE 2: RESTORE A POSTGRESQL INSTANCE FROM A FULL BACKUP

For testing purposes, let's "damage" the PostgreSQL instance.

1. Run the following command in the pg-primary node to delete the main data directory.

$ rm -rf /var/lib/postgresql/14/main/*

2. To restore the backup, run the following commands.

• Stop the postgresql instance

$ sudo systemctl stop postgresql

• Restore the backup:

$ pgbackrest -u postgres --stanza=prod_backup restore

• Start the postgresql instance

$ sudo systemctl start postgresql

3. After the command executes successfully, you can access PostgreSQL from the psql command line tool and
check if the table and data rows have been restored.

USE CASE 3: POINT-IN-TIME RECOVERY

If your target PostgreSQL instance has an already existing data directory, the full restore option will fail. You
will get an error message stating there are existing data files. In this case, you can use the --delta option to
restore only the corrupted files.

For example, let's say one of your developers mistakenly deleted a few rows from a table. You can use
pgBackRest to revert your database to a previous point in time to recover the lost rows.

5.2.2 Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL

To test this use case, do the following:

1. Take a timestamp when the database is stable and error-free. Run the following command from the
psql prompt.

SELECT CURRENT_TIMESTAMP;
current_timestamp
-------------------------------
2021-11-07 11:55:47.952405+00
(1 row)

Note down the above timestamp since we will use this time in the restore command. Note that in a real life
scenario, finding the correct point in time when the database was error-free may require extensive
investigation. It is also important to note that all changes after the selected point will be lost after the roll back.

2. Delete one of the customer records added before.

DELETE FROM CUSTOMER WHERE ID=3;

3. To recover the data, run a command with the noted timestamp as an argument. Run the commands below to
recover the database up to that time.

• Stop the postgresql instance

$ sudo systemctl stop postgresql

• Restore the backup

$ pgbackrest -u postgres --stanza=prod_backup --delta \

--type=time "--target= 2021-11-07 11:55:47.952405+00" \
--target-action=promote restore

• Start the postgresql instance

$ sudo systemctl start postgresql

4. Check the database table to see if the record has been restored.

SELECT * FROM customer;

id | name
----+--------
1 | john
2 | martha
3 | mary
(3 rows)

USE CASE 4: RESTORING TO A SEPARATE POSTGRESQL INSTANCE

Sometimes a PostgreSQL server may encounter hardware issues and become completely inaccessible. In
such cases, we will need to recover the database to a separate instance where pgBackRest is not initially
configured. To restore the instance to a separate host, you have to first install both PostgreSQL and
pgBackRest in this host.

In our test setup, we already have PostgreSQL and pgBackRest installed in the third node, pg-secondary .
Change the pgBackRest configuration file in the pg-secondary node as shown below.

5.2.2 Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL

[global]
repo1-host=pg-repo
repo1-host-user=postgres
process-max=2
log-level-console=info
log-level-file=debug

[prod_backup]
pg1-path=/var/lib/postgresql/14/main

There should be bidirectional passwordless SSH communication between pg-repo and pg-secondary . Refer
to the Set up passwordless SSH section for the steps, if you haven’t configured it.

Stop the PostgreSQL instance

$ sudo systemctl stop postgresql

Restore the database backup from pg-repo to pg-secondary .

$ pgbackrest -u postgres --stanza=prod_backup --delta restore

2021-11-07 13:34:08.897 P00 INFO: restore command begin 2.36: --delta --exec-id=109728-
d81c7b0b --log-level-console=info --log-level-file=debug --pg1-path=/var/lib/postgresql/14/
main --process-max=2 --repo1-host=pg-repo --repo1-host-user=postgres --stanza=prod_backup
2021-11-07 13:34:09.784 P00 INFO: repo1: restore backup set
20211107-111534F_20211107-131807I, recovery will start at 2021-11-07 13:18:07
2021-11-07 13:34:09.786 P00 INFO: remove invalid files/links/paths from '/var/lib/
postgresql/14/main'
2021-11-07 13:34:11.803 P00 INFO: write updated /var/lib/postgresql/14/main/
postgresql.auto.conf
2021-11-07 13:34:11.819 P00 INFO: restore global/pg_control (performed last to ensure
aborted restores cannot be started)
2021-11-07 13:34:11.819 P00 INFO: restore size = 23.2MB, file total = 937
2021-11-07 13:34:11.820 P00 INFO: restore command end: completed successfully (2924ms)

After the restore completes successfully, restart PostgreSQL:

$ sudo systemctl start postgresql

Check the database contents from the local psql shell.

SELECT * FROM customer;

id | name
----+--------
1 | john
2 | martha
3 | mary
(3 rows)

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

5.2.2 Deploying backup and disaster recovery solution in Percona Distribution for PostgreSQL

Last update: December 5, 2022

Created: January 21, 2022

5.3 Spatial data handling

5.3.1 Spatial data manipulation

Version added: 15.3

Organizations dealing with spatial data need to store it somewhere and manipulate it. PostGIS is the open-
source extension for PostgreSQL that allows doing just that. It adds support for storing the spatial data types
such as:

• Geographical data like points, lines, polygons, GPS coordinates that can be mapped on a sphere.

• Geometrical data. This is also points, lines and polygons but they apply to a 2D surface.

To operate with spacial data inside SQL queries, PostGIS supports spacial functions like distance, area, union,
intersection. It uses the spacial indexes like R-Tree and Quadtree for efficient processing of database
operations. Read more about supported spacial functions and indexes in PostGIS documentation.

By deploying PostGIS with Percona Distribution for PostgreSQL, you receive the open-source spatial
database that you can use in various areas without vendor lock-in.

When to use PostGIS

You can use PostGIS in the following cases:

• To store and manage spatial data, create and store spatial shapes, calculate areas and distances

• To build the software that visualizes spacial data on a map,

• To work with raster data, such as satellite imagery or digital elevation models.

• To integrate spatial and non-spatial data such as demographic or economic data in a database

When not to use PostGIS

Despite its power and flexibility, PostGIS may not suit your needs if:

• You need to store only a couple of map locations. Consider using the built-in geometric functions and
operations of PostgreSQL
• You need real-time data analysis. While PostGIS can handle real-time spatial data, it may not be the best
option for real-time data analysis on large volumes of data.

• You need complex 3D analysis or visualization.

• You need to acquire spatial data. Use other tools for this purpose and import spatial data into PostGIS to
manipulate it.

Next steps:

Deployment

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

5.3.1 Spatial data manipulation

Last update: June 28, 2023

Created: June 28, 2023

5.3.2 Deploy spatial data with PostgreSQL

The following document provides guidelines how to install PostGIS and how to run the basic queries.

Preconditions

1. We assume that you have the basic knowledge of spatial data, GIS (Geographical Information System) and of
shapefiles.
2. You need to acquire spacial data. For the following examples, we'll use the same data set as is used in PostGIS
tutorial.

Install PostGIS

1. Enable Percona repository.

As other components of Percona Distribution for PostgreSQL, PostGIS is available from Percona repositories.
Use the percona-release repository management tool to enable the repository.

$ sudo percona-release setup ppg15

5.3.2 Deploy spatial data with PostgreSQL

2. Install PostGIS packages

5.3.2 Deploy spatial data with PostgreSQL

On Debian and Ubuntu

$ sudo apt install percona-postgis

This installs the set of PostGIS extensions. To check what extensions are available, run the following query from
the psql terminal:

SELECT name, default_version,installed_version

FROM pg_available_extensions WHERE name LIKE 'postgis%' or name LIKE 'address%';

Note

To enable the postgis_sfcgal-3 extension on Ubuntu 18.04, you need to manually install the required dependency:

$ sudo apt-get install libsfcgal1

On RHEL and derivatives

a. Install epel repository

$ sudo yum install epel-release

b. Enable the llvm-toolset dnf module

$ sudo dnf module enable llvm-toolset

c. Enable the codeready builder repository to resolve dependencies conflict. For Red Hat Enterprise Linux 8,
replace the operating system version in the following commands accordingly.

RHEL 9

$ sudo dnf config-manager --set-enabled codeready-builder-for-rhel-9-x86_64-rpms

CentOS 9

$ sudo dnf config-manager --set-enabled crb

Oracle Linux 9

$ sudo dnf config-manager --set-enabled ol9_codeready_builder

d. Install the extension

$ sudo yum install percona-postgis33

This installs the set of PostGIS extensions. To check what extensions are available, run the following query from
the psql terminal:

SELECT name, default_version,installed_version

FROM pg_available_extensions WHERE name LIKE 'postgis%' or name LIKE 'address%';

5.3.2 Deploy spatial data with PostgreSQL

3. Create a database and a schema to store your data. A schema is a container that logically segments objects
(tables, functions, views, and so on) for better management. Run the following commands from the psql
terminal:

CREATE database nyc;

CREATE SCHEMA gis;

4. To make PostGIS functions and operations work, you need to enable the postgis extension. From the psql
terminal, switch to the database you created and run the following command:

\c nyc;
CREATE EXTENSION postgis;

5. Check that the extension is enabled:

SELECT postgis_full_version();

The output should be similar to the following:

postgis_full_version
---------------------------------------------------------------------------------------------------------------
POSTGIS="3.3.3dev 0" [EXTENSION] PGSQL="140" GEOS="3.10.2-CAPI-1.16.0" PROJ="8.2.1"
LIBXML="2.9.13" LIBJSON="0.15" LIBPROTOBUF="1.3.3" WAGYU="0.5.0 (Internal)"

Upload spatial data to PostgreSQL

PostGIS provides the shp2pgsql command line utility that converts the binary data from shapefiles into the
series of SQL commands and loads them into the database.

1. From the folder where the .shp files are located, execute the following command and replace the dbname
value with the name of your database:

shp2pgsql \
-D \
-I \
-s 26918 \
nyc_streets.shp \
nyc_streets \
| psql -U postgres dbname=nyc

The command does the following:

• -D flag instructs the command to generate the dump format
• -I flag instructs to create the spatial index on the table upon the data load

• -s indicates the spatial reference identifier of the data. The data we load is in the Projected coordinate
system for North America and has the value 26918.
• nyc_streets.shp is the source shapefile
• nyc_streets is the table name to create in the database

• dbname=nyc is the database name

2. Check the uploaded data

5.3.2 Deploy spatial data with PostgreSQL

1. Repeat the command to upload other shapefiles in the data set: nyc_census_blocks , nyc_neighborhoods ,
nyc_subway_stations

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: June 28, 2023

Created: June 28, 2023

5.3.3 Query spatial data

After you installed and set up PostGIS, let’s find answers to the following questions by querying the
database:

What is the population of the New York City?

SELECT Sum(popn_total) AS population

FROM nyc_census_blocks;

Output:

population
------------
8175032
(1 row)

What is the area of Central Park?

To get the answer we will use the ST_Area function that returns the areas of polygons.

SELECT ST_Area(geom) / 1000

FROM nyc_neighborhoods
WHERE name = 'Central Park';

Output:

st_area
--------------------
3519.8365965413293
(1 row)

By default, the output is given in square meters. To get the value in square kilometers, divide it by 1000.

How long is Columbus Circle?

SELECT ST_Length(geom)
FROM nyc_streets
WHERE name = 'Columbus Cir';

Output:

st_length
-------------------
308.3419936909855
(1 row)

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

5.3.3 Query spatial data

Last update: June 28, 2023

Created: June 28, 2023

5.4 LDAP Authentication

When a client application or a user that runs the client application connects to the database, it must identify
themselves. The process of validating the client's identity and determining whether this client is permitted to
access the database it has requested is called authentication.

Percona Distribution for PortgreSQL supports several authentication methods, including the LDAP
authentication. The use of LDAP is to provide a central place for authentication - meaning the LDAP server
stores usernames and passwords and their resource permissions.

The LDAP authentication in Percona Distribution for PortgreSQL is implemented the same way as in upstream
PostgreSQL.

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: October 24, 2022

Created: May 30, 2022

6. Uninstalling Percona Distribution for PostgreSQL

To uninstall Percona Distribution for PostgreSQL, remove all the installed packages and data / configuration
files.

NOTE: Should you need the data files later, back up your data before uninstalling Percona Distribution for
PostgreSQL.

On Debian and Ubuntu using apt

To uninstall Percona Distribution for PostgreSQL on platforms that use apt package manager such as
Debian or Ubuntu, complete the following steps.

Run all commands as root or via sudo.

1. Stop the Percona Distribution for PostgreSQL service.

$ sudo systemctl stop postgresql.service

2. Remove the percona-postgresql packages.

$ sudo apt remove percona-postgresql-15* percona-patroni percona-pgbackrest percona-

pgbadger percona-pgbouncer

3. Remove configuration and data files.

$ rm -rf /etc/postgresql/15/main

On Red Hat Enterprise Linux and derivatives using yum

To uninstall Percona Distribution for PostgreSQL on platforms that use yum package manager such as Red
Hat Enterprise Linux or CentOS, complete the following steps.

Run all commands as root or via sudo.

1. Stop the Percona Distribution for PostgreSQL service.

$ sudo systemctl stop postgresql-15

2. Remove the percona-postgresql packages

$ sudo yum remove percona-postgresql15* percona-pgbadger

3. Remove configuration and data files

$ rm -rf /var/lib/pgsql/15/data

6. Uninstalling Percona Distribution for PostgreSQL

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: March 20, 2023

Created: June 4, 2021

7. Copyright and licensing information

Percona Distribution for PostgreSQL is licensed under the PostgreSQL license and licenses of all components
included in the Distribution.

7.1 Documentation licensing

Percona Distribution for PostgreSQL documentation is (C)2009-2023 Percona LLC and/or its affiliates and is
distributed under the Creative Commons Attribution 4.0 International License.

7.1 Documentation licensing

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: June 28, 2023

Created: June 4, 2021

8. Trademark Policy

8. Trademark Policy
This Trademark Policy is to ensure that users of Percona-branded products or services know that what they
receive has really been developed, approved, tested and maintained by Percona. Trademarks help to
prevent confusion in the marketplace, by distinguishing one company’s or person’s products and services
from another’s.

Percona owns a number of marks, including but not limited to Percona, XtraDB, Percona XtraDB, XtraBackup,
Percona XtraBackup, Percona Server, and Percona Live, plus the distinctive visual icons and logos
associated with these marks. Both the unregistered and registered marks of Percona are protected.

Use of any Percona trademark in the name, URL, or other identifying characteristic of any product, service,
website, or other use is not permitted without Percona’s written permission with the following three limited
exceptions.

First, you may use the appropriate Percona mark when making a nominative fair use reference to a bona
fide Percona product.

Second, when Percona has released a product under a version of the GNU General Public License (“GPL”),
you may use the appropriate Percona mark when distributing a verbatim copy of that product in
accordance with the terms and conditions of the GPL.

Third, you may use the appropriate Percona mark to refer to a distribution of GPL-released Percona software
that has been modified with minor changes for the sole purpose of allowing the software to operate on an
operating system or hardware platform for which Percona has not yet released the software, provided that
those third party changes do not affect the behavior, functionality, features, design or performance of the
software. Users who acquire this Percona-branded software receive substantially exact implementations of
the Percona software.

Percona reserves the right to revoke this authorization at any time in its sole discretion. For example, if
Percona believes that your modification is beyond the scope of the limited license granted in this Policy or
that your use of the Percona mark is detrimental to Percona, Percona will revoke this authorization. Upon
revocation, you must immediately cease using the applicable Percona mark. If you do not immediately
cease using the Percona mark upon revocation, Percona may take action to protect its rights and interests
in the Percona mark. Percona does not grant any license to use any Percona mark for any other modified
versions of Percona software; such use will require our prior written permission.

Neither trademark law nor any of the exceptions set forth in this Trademark Policy permit you to truncate,
modify or otherwise use any Percona mark as part of your own brand. For example, if XYZ creates a modified
version of the Percona Server, XYZ may not brand that modification as “XYZ Percona Server” or “Percona XYZ
Server”, even if that modification otherwise complies with the third exception noted above.

In all cases, you must comply with applicable law, the underlying license, and this Trademark Policy, as
amended from time to time. For instance, any mention of Percona trademarks should include the full
trademarked name, with proper spelling and capitalization, along with attribution of ownership to Percona
Inc. For example, the full proper name for XtraBackup is Percona XtraBackup. However, it is acceptable to
omit the word “Percona” for brevity on the second and subsequent uses, where such omission does not
cause confusion.

In the event of doubt as to any of the conditions or exceptions outlined in this Trademark Policy, please
contact [email protected] for assistance and we will do our very best to be helpful.

8. Trademark Policy

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: June 28, 2023

Created: June 28, 2023

List of 200 Free High DA-PA Do-Follow Backlinks Sites
50% (2)
List of 200 Free High DA-PA Do-Follow Backlinks Sites
6 pages
ASMedia ASM3142 Datasheet
No ratings yet
ASMedia ASM3142 Datasheet
21 pages
EDB Postgres Distributed (PGD)
No ratings yet
EDB Postgres Distributed (PGD)
307 pages
Đề 1
No ratings yet
Đề 1
53 pages
NR Sa
No ratings yet
NR Sa
65 pages
Youtube Training Course Book
100% (2)
Youtube Training Course Book
13 pages
Percona Distribution PostgreSQL-14
No ratings yet
Percona Distribution PostgreSQL-14
109 pages
Webinar - Enterprise Grade PostgreSQL
No ratings yet
Webinar - Enterprise Grade PostgreSQL
23 pages
White Paper - Why Customers Choose Percona For PostgreSQL
No ratings yet
White Paper - Why Customers Choose Percona For PostgreSQL
15 pages
PostgreSQL Tutorial
100% (1)
PostgreSQL Tutorial
13 pages
Introduction To Postgresql
100% (1)
Introduction To Postgresql
54 pages
1.Introduction2PostgreSQL
No ratings yet
1.Introduction2PostgreSQL
27 pages
PostgreSQL Cookbook Sample Chapter
No ratings yet
PostgreSQL Cookbook Sample Chapter
24 pages
Edb Postgis User
No ratings yet
Edb Postgis User
24 pages
PostgreSQL RPM Installation PGDG
No ratings yet
PostgreSQL RPM Installation PGDG
7 pages
PostgreSQL RPM Installation PGDG
No ratings yet
PostgreSQL RPM Installation PGDG
7 pages
52492-rc071 Postgresql PDF
No ratings yet
52492-rc071 Postgresql PDF
11 pages
HH C5 C0
No ratings yet
HH C5 C0
114 pages
Postgresql Management and Automation With Clustercontrol
50% (2)
Postgresql Management and Automation With Clustercontrol
42 pages
Instalar Postgres Rhel
No ratings yet
Instalar Postgres Rhel
3 pages
535 PGCon 2019 Borodin Odyssey
No ratings yet
535 PGCon 2019 Borodin Odyssey
66 pages
PostgreSQL For Data Architects - Sample Chapter
No ratings yet
PostgreSQL For Data Architects - Sample Chapter
23 pages
Elephant Roads: 17 Years of Postgres Forks and Variants
No ratings yet
Elephant Roads: 17 Years of Postgres Forks and Variants
53 pages
PostgreSQL_Training_72622
No ratings yet
PostgreSQL_Training_72622
3 pages
Foundations PostgreSQL Administration 13
100% (1)
Foundations PostgreSQL Administration 13
307 pages
Introbook v4 en
No ratings yet
Introbook v4 en
145 pages
PostgreSQL Cassandra Upgrade
No ratings yet
PostgreSQL Cassandra Upgrade
41 pages
Edb Pgpool User
No ratings yet
Edb Pgpool User
53 pages
Postgres Admin
No ratings yet
Postgres Admin
109 pages
Resumo Postgresql
No ratings yet
Resumo Postgresql
6 pages
Postgres The First Experience
No ratings yet
Postgres The First Experience
173 pages
Modul PostgreSQL Terbaru - WebHozz
No ratings yet
Modul PostgreSQL Terbaru - WebHozz
175 pages
Postgres Articles
No ratings yet
Postgres Articles
78 pages
3.backup Restore Tools
No ratings yet
3.backup Restore Tools
12 pages
Postgre SQL
No ratings yet
Postgre SQL
21 pages
Install Postgres
No ratings yet
Install Postgres
4 pages
PostgreSQL For Beginners
100% (6)
PostgreSQL For Beginners
142 pages
Postgrre
No ratings yet
Postgrre
14 pages
EPAS_Essentials_v15
No ratings yet
EPAS_Essentials_v15
432 pages
Administration
No ratings yet
Administration
117 pages
Postgresql - Software Catalogue - Clustering - Replication - 2
No ratings yet
Postgresql - Software Catalogue - Clustering - Replication - 2
7 pages
PostgreSQL Proficiency For Python People
No ratings yet
PostgreSQL Proficiency For Python People
215 pages
6 Things A Developer Should Know About Postgres
No ratings yet
6 Things A Developer Should Know About Postgres
14 pages
PostgreSQL 13 Press Kit - 2020
No ratings yet
PostgreSQL 13 Press Kit - 2020
3 pages
13. Advanced SQL Injections - @CyberFreeCourses
No ratings yet
13. Advanced SQL Injections - @CyberFreeCourses
57 pages
ELO11 Brochure
No ratings yet
ELO11 Brochure
13 pages
Administration
100% (1)
Administration
112 pages
jasperreports-installation
No ratings yet
jasperreports-installation
61 pages
Readme First Linux32
No ratings yet
Readme First Linux32
5 pages
Distributed PostgreSQL
No ratings yet
Distributed PostgreSQL
118 pages
Postgre SQL
100% (1)
Postgre SQL
85 pages
PGD v5 Documentation
No ratings yet
PGD v5 Documentation
443 pages
These Notes Will Serve As A Guide To Installing PostgreSQL
No ratings yet
These Notes Will Serve As A Guide To Installing PostgreSQL
19 pages
Installing Adempiere With Postgresql 8.2
No ratings yet
Installing Adempiere With Postgresql 8.2
13 pages
Pgpool Feat and Devel
No ratings yet
Pgpool Feat and Devel
38 pages
Pgbackrest Installation and Configu
No ratings yet
Pgbackrest Installation and Configu
2 pages
PostgreSQL Installation Guide
No ratings yet
PostgreSQL Installation Guide
55 pages
Introduction Postgre SQLAdministration V11
No ratings yet
Introduction Postgre SQLAdministration V11
274 pages
Admin-7 3 2-A4
No ratings yet
Admin-7 3 2-A4
202 pages
PostgreSQL 16 Cookbook, Second Edition
From Everand
PostgreSQL 16 Cookbook, Second Edition
Peter G
No ratings yet
PostgreSQL 16 Cookbook, Second Edition: Solve challenges across scalability, performance optimization, essential commands, cloud provisioning, backup, and recovery
From Everand
PostgreSQL 16 Cookbook, Second Edition: Solve challenges across scalability, performance optimization, essential commands, cloud provisioning, backup, and recovery
Peter G
No ratings yet
PostgreSQL 17 QuickStart Pro: Add expertise around WAL processing, JSON table, IO performance, logical replication and index vacuuming
From Everand
PostgreSQL 17 QuickStart Pro: Add expertise around WAL processing, JSON table, IO performance, logical replication and index vacuuming
Tessa Vorin
No ratings yet
PostgreSQL 17 QuickStart Pro
From Everand
PostgreSQL 17 QuickStart Pro
Tessa Vorin
No ratings yet
Mastering GeoServer
From Everand
Mastering GeoServer
Colin Henderson
No ratings yet
Advanced PostgreSQL Mastery: In-Depth Database Techniques and Performance Tuning
From Everand
Advanced PostgreSQL Mastery: In-Depth Database Techniques and Performance Tuning
Adam Jones
No ratings yet
Answerssa Cti
No ratings yet
Answerssa Cti
16 pages
EBAY Five Force
100% (4)
EBAY Five Force
14 pages
Resume Final 108
No ratings yet
Resume Final 108
2 pages
Tummis Admission User Manual
No ratings yet
Tummis Admission User Manual
10 pages
Review On Artificial Intelligence in Power System Transient Stability Analysis
No ratings yet
Review On Artificial Intelligence in Power System Transient Stability Analysis
14 pages
Top 10 Digital Forensic Tools
No ratings yet
Top 10 Digital Forensic Tools
10 pages
Web Design Proposal (HTML Css JS)
100% (2)
Web Design Proposal (HTML Css JS)
13 pages
DS DXL Icm 630 P
No ratings yet
DS DXL Icm 630 P
2 pages
LCMSQuickGuide Shimadzu
No ratings yet
LCMSQuickGuide Shimadzu
66 pages
HCD-Research in AI 1.33
No ratings yet
HCD-Research in AI 1.33
20 pages
5 Sem Lab Manual R Programming BCA-BSC
No ratings yet
5 Sem Lab Manual R Programming BCA-BSC
16 pages
What Is A Framework
No ratings yet
What Is A Framework
7 pages
Online car rental system
No ratings yet
Online car rental system
52 pages
Assessment 4 - Attempt Review
No ratings yet
Assessment 4 - Attempt Review
7 pages
IOT M3 - Ktunotes
No ratings yet
IOT M3 - Ktunotes
26 pages
Subsquid Whitepaper v0.6
No ratings yet
Subsquid Whitepaper v0.6
12 pages
Sax Phone
No ratings yet
Sax Phone
188 pages
COMPPP1MS
No ratings yet
COMPPP1MS
8 pages
Programming Model of 8051
No ratings yet
Programming Model of 8051
45 pages
snow modules
No ratings yet
snow modules
19 pages
PPP - RTK Comparison 2016
No ratings yet
PPP - RTK Comparison 2016
31 pages
SP5I Fast AI Setting Instruction-v202202
No ratings yet
SP5I Fast AI Setting Instruction-v202202
17 pages
NG 278-A007-Link 22 Guidebook Overview Ed2
No ratings yet
NG 278-A007-Link 22 Guidebook Overview Ed2
120 pages
Truncated_Doc_4
No ratings yet
Truncated_Doc_4
3 pages
4GE+Dual-Band WIFI ONU: Xpon Ac 5G Sux G2W
No ratings yet
4GE+Dual-Band WIFI ONU: Xpon Ac 5G Sux G2W
4 pages