Skip to content

Installing the Processor

The Processor is a single program file (a binary called pg_relay). Pre-built versions for all platforms are on the releases page.

Linux

curl -LO https://gitlab.com/pebble-it/pg_relay/-/releases/permalink/latest/downloads/pg_relay-linux-x86_64
chmod +x pg_relay-linux-x86_64
sudo mv pg_relay-linux-x86_64 /usr/local/bin/pg_relay

systemd is the standard service manager used by most modern Linux distributions — it starts your program automatically and restarts it if it ever crashes.

sudo cp deploy/pg_relay.service /etc/systemd/system/
sudo mkdir -p /etc/pg_relay
sudo install -m 600 deploy/pg_relay.env.example /etc/pg_relay/pg_relay.env

Edit /etc/pg_relay/pg_relay.env with your connection details:

PGHOST=/var/run/postgresql
PGPORT=5432
PGDATABASE=your_database
PGUSER=pgrelay
PGPASSFILE=/var/lib/pgsql/.pgpass
PGSSLMODE=prefer

sudo systemctl enable --now pg_relay
sudo journalctl -u pg_relay -f

macOS

# Apple Silicon
curl -LO https://gitlab.com/pebble-it/pg_relay/-/releases/permalink/latest/downloads/pg_relay-mac-arm64
chmod +x pg_relay-mac-arm64 && sudo mv pg_relay-mac-arm64 /usr/local/bin/pg_relay

# Intel
curl -LO https://gitlab.com/pebble-it/pg_relay/-/releases/permalink/latest/downloads/pg_relay-mac-x86_64
chmod +x pg_relay-mac-x86_64 && sudo mv pg_relay-mac-x86_64 /usr/local/bin/pg_relay

macOS security prompt

If macOS blocks the program the first time you run it, open System Settings → Privacy & Security, scroll down, and click Allow. Alternatively, run xattr -d com.apple.quarantine /usr/local/bin/pg_relay in a terminal.

Windows

Download pg_relay-windows-x86_64.exe, rename it to pg_relay.exe, and install it as a Windows service using NSSM (a small, free tool for running any program as a Windows service):

nssm install pg_relay "C:\path\to\pg_relay.exe"
nssm set pg_relay AppEnvironmentExtra PGHOST=localhost PGPORT=5432 PGDATABASE=your_database PGUSER=pgrelay PGPASSFILE="%APPDATA%\postgresql\pgpass.conf"
nssm start pg_relay

Never put your password directly in the service definition

Always use a PGPASSFILE (a small file that stores connection passwords — see the PostgreSQL documentation) instead.

Windows SmartScreen

If Windows blocks the program, right-click it → Properties → Unblock, or run Unblock-File -Path "C:\path\to\pg_relay.exe" in PowerShell.

With both pieces installed, continue to Getting Started for a complete first run-through.