Installation¶
Introduction¶
PoWA-archivist is the core component of the PoWA project. It is composed of 2 elements:
an extension named “powa” containing management functions
a module name “powa” that optionally runs a background worker to collect the performance data on the local instance
Prerequisites¶
PostgreSQL >= 9.4
PostgreSQL contrib modules (pg_stat_statements and btree_gist)
PostgreSQL server headers (if compiling from sources)
Installation¶
The recommended way to install PoWA-archivist is to use the packaged version available in the PGDG repositories, which available for GNU/Linux distributions based on Debian/Ubuntu or RHEL/Rocky/Fedora. If you’re using a distribution where no PGDG repository or prepackaged version is available, we document installation from source code.
Installation from PGDG repository¶
On Debian/Ubuntu, please refer to the APT PGDG repository documentation
<https://apt.postgresql.org> for the initial setup (which should already be
done if you have PostgreSQL installed), and simply install
postgresql-XY-powa
. For instance, if you’re using PostgreSQL 15:
sudo apt-get install postgresql-15-powa
On RHEL/Rock/Fedora, please refer to the YUM PGDG repository documentation
<https://yum.postgresql.org> for the iniial setup (which should already be
done if you have PostgreSQL installed), and simply install
powa_XY
. For instance, if you’re using PostgreSQL 15:
sudo dnf install powa_15
Note
Package names for older PostgreSQL version may vary and not contain an
_
between the package name and the PostgreSQL major version.
Installation from sources¶
On Debian, the PostgreSQL server headers are installed via the
postgresql-server-dev-XY
package:
sudo apt-get install postgresql-server-dev-15 postgresql-contrib-15
On RPM-based distros:
sudo dnf install postgresql15-devel postgresql15-contrib
You also need a C compiler and other standard development tools.
On Debian, these can be installed via the build-essential
package:
apt-get install build-essential
On RPM-based distros, the “Development Tools” can be used:
yum groupinstall "Development Tools"
Grab the latest release, and install it:
wget https://github.com/powa-team/powa-archivist/archive/REL_5_0_0.tar.gz -O powa-archivist-REL_5_0_0.tar.gz tar zxvf powa-archivist-REL_5_0_0.tar.gz cd powa-archivist-REL_5_0_0
Compile and install it:
make
sudo make install
Note
Make sure that sudo
refers to the same PostgreSQL headers. Using
pg_config
and sudo pg_config
should produce the same output.
It should output something like the following :
/bin/mkdir -p '/usr/share/postgresql-15/extension'
/bin/mkdir -p '/usr/share/postgresql-15/extension'
/bin/mkdir -p '/usr/lib64/postgresql-15/lib64'
/bin/mkdir -p '/usr/share/doc/postgresql-15/extension'
/usr/bin/install -c -m 644 powa.control '/usr/share/postgresql-15/extension/'
/usr/bin/install -c -m 644 powa--2.0.sql '/usr/share/postgresql-15/extension/'
/usr/bin/install -c -m 644 README.md '/usr/share/doc/postgresql-15/extension/'
/usr/bin/install -c -m 755 powa.so '/usr/lib64/postgresql-15/lib64/'
PostgreSQL installation¶
Create the PoWA database and create the required extensions, with the following statements:
CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION btree_gist;
CREATE EXTENSION powa;
Example:
bash-4.1$ psql
psql (15.2)
Type "help" for help.
postgres=# create database powa;
CREATE DATABASE
postgres=# \c powa
You are now connected to database "powa" as user "postgres".
powa=# create extension pg_stat_statements ;
CREATE EXTENSION
powa=# create extension btree_gist ;
CREATE EXTENSION
powa=# create extension powa;
CREATE EXTENSION
As PoWA-archivist can provide a background worker, the library must be loaded at server start time if local metric collection is wanted.
For this, modify the postgresql.conf
configuration file, and add powa and
pg_stat_statements to the shared_preload_libraries
parameter:
shared_preload_libraries = 'pg_stat_statements,powa'
If possible, activate track_io_timing
too:
track_io_timing = on
PostgreSQL should then be restarted.
Warning
Since PoWA 4, you need to specify powa in the shared_preload_libraries configuration ONLY if you want to store the performance data locally. For remote storage, please see the Remote setup documentation. The pg_stat_statements extension (as all other Stats Extensions) still required to be configured in the shared_preload_libraries setting.
If you’re setting up a repository database for a remote server, you can also entirely skip the pg_stat_statements configuration and the restart.
Major PostgreSQL Upgrade¶
Warning
There is a known issue with all PostgreSQL versions when using pg_upgrade on a instance having custom background workers, like PoWA in local setup mode: PostgreSQL doesn’t prevent the background workers from doing their usual activity during pg_upgrade. It means that if the background worker performs some write when pg_upgrade expects that no write would happen, the resulting cluster can be corrupted. It’s unfortunately not something that can be fixed from PoWA itself.
If you want to perform a pg_upgrade of any instance having PoWA setup in local mode, you need to disable it before doing the pg_upgrade, and re-enable it once the upgrade is finished.