Installing the Extension¶

The extension is a set of SQL objects installed once per database. You need PostgreSQL's development headers and standard build tools. Substitute your own PostgreSQL version for 18 throughout these examples.

On a managed cloud database?

Services such as AWS RDS, Azure Flexible Server, and Google Cloud SQL do not allow CREATE EXTENSION for third-party extensions like pg_relay. If that is your situation, skip ahead to the Cloud Setup book instead — it covers the (straightforward) alternative.

RHEL / OEL / Rocky Linux / AlmaLinux 8 or 9¶

sudo dnf install postgresql18-devel make gcc
git clone https://gitlab.com/pebble-it/pg_relay.git
cd pg_relay
sudo make install PG_CONFIG=/usr/pgsql-18/bin/pg_config

Ubuntu / Debian¶

sudo apt install postgresql-server-dev-18 make gcc
git clone https://gitlab.com/pebble-it/pg_relay.git
cd pg_relay
sudo make install PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config

macOS (Homebrew)¶

git clone https://gitlab.com/pebble-it/pg_relay.git
cd pg_relay
make install PG_CONFIG=/opt/homebrew/opt/postgresql@18/bin/pg_config

Windows¶

Run PowerShell as Administrator:

git clone https://gitlab.com/pebble-it/pg_relay.git
cd pg_relay
.\deploy\install-extension.ps1 -PgVersion 18

Creating the extension in your database¶

Once the files are installed on the server, connect to your target database as a superuser (a database role with full administrative rights) and run:

CREATE EXTENSION pg_relay;

That is all. This single command creates the pgrelay schema (a namespace that groups related database objects together), the private tables, all the functions, and the pgrelay role (with no ability to log in, by default). You do not need to run anything else to set up the schema — PostgreSQL applies every install step needed to bring you to the current version, 1.1, automatically.

Upgrading an existing installation¶

If you already have pg_relay installed and are upgrading to the latest version, install the updated files first (make install again, or re-run the PowerShell script on Windows), then run:

ALTER EXTENSION pg_relay UPDATE;

PostgreSQL applies the necessary upgrade script for you. After upgrading to 1.1, re-run pgrelay.grant_user(...) for each of your management roles — register() and update() gained new parameters in 1.1, and recreating a function like this resets any grants that were made directly on it. If you had granted pgrelay.queue_stats() to monitoring roles, re-grant that too, since it gained a new pending_restricted column in 1.1. See Granting Permissions in the Technical Guide for the full detail.

Other Linux distributions

For Fedora, other Linux distributions, and additional platform details, see Platform Support in the Technical Guide.

With the extension installed, continue to Installing the Processor.