Install

The installer puts two things in place: the pgbx extension on the database server (it runs inside Postgres and does the backups) and the pgbx CLI (pgbx, the client you run commands with), plus the optional agent skill. See How it works.

pgbx is set up in two places. Do the server once; do the laptop part on every machine you run pgbx from. Only want a Postgres client (profiles, adapters for SSH and clouds, read queries as JSON, agent memory) and no backups? Skip the server part: Use pgbx as your Postgres client.

On the database server

curl -fsSL https://pgbx.deemwar.com/install.sh | sh
sudo pgbx setup server     # asks for your S3 bucket; prints the ONE restart command, e.g. sudo systemctl restart postgresql@16-main
pgbx doctor                # after that restart

sudo pgbx setup server writes the S3 settings, the credentials file and shared_preload_libraries; it never restarts anything itself. Plain sudo pgbx setup does the same thing. For scripts, pass every value as a flag with --yes (see What the installer does).

On your laptop

Install the pgbx CLI, then tell it how to reach the server. setup client needs no sudo.

Linux / macOS

curl -fsSL https://pgbx.deemwar.com/install.sh | sh
# over SSH, with the ssh example adapter the installer put in ~/.config/pgbx/adapters (needs Node 18+)
pgbx setup client prod --adapter ssh target=ops@db.example.com user=postgres 'password=$PGPASSWORD'
# or, when Postgres is reachable directly, a connection string:
pgbx setup client prod --url 'postgres://postgres:$PGPASSWORD@db.example.com:5432/postgres'

Windows

Command Prompt (recommended: plain cmd.exe, so PowerShell execution policies never block it; uses only Windows’ built-in curl, certutil and tar, and checks the download against the release’s SHA256SUMS):

curl -fsSL https://pgbx.deemwar.com/install.cmd -o install.cmd && install.cmd
pgbx setup client prod --adapter ssh target=ops@db.example.com user=postgres password=$PGPASSWORD

Or PowerShell:

powershell -c "irm https://pgbx.deemwar.com/install.ps1 | iex"
pgbx setup client prod --adapter ssh target=ops@db.example.com user=postgres 'password=$PGPASSWORD'

On Windows you get the pgbx CLI, pgbx.exe (in %LOCALAPPDATA%\pgbx\bin, added to your user PATH), the example adapters (in %APPDATA%\pgbx\adapters) and the agent skill; the extension itself always runs on the Linux database server.

Run setup client with no flags on a terminal and it asks: a connection string, or an adapter name and that adapter’s settings. It saves a profile named prod (the default if it is your first), then tests it: it connects (starting the adapter, if there is one, and stopping it afterwards), and prints the Postgres version, the pgbx extension version and a backup status summary. If something is missing it prints the one next step. A server without the extension is fine: setup client still succeeds and says backups are off there, while queries, profiles and adapters work (see Use pgbx as your Postgres client if that is all you want). Passwords are never stored in the profile: it holds a reference like $PGPASSWORD, which pgbx reads from your environment (or your secrets source) when a command runs; write it in single quotes so your shell leaves it alone. Finally it offers to install the agent skill. To reach Postgres through AWS, GCP, Azure or your own tooling, see Connect through SSH, AWS, GCP, Azure or your own adapter. After that, every command takes --profile prod, or uses the default: pgbx status.

Requirements

	supported
PostgreSQL (extension)	13, 14, 15, 16, 17, 18
Linux	Debian / Ubuntu / RHEL-family (Rocky, Alma, Fedora), amd64 and arm64
pgbx CLI	Linux amd64/arm64 (static), macOS arm64, Windows x64 (Windows on ARM runs it through its built-in x64 emulation)

On a machine without a local PostgreSQL 13–18 server the installer puts only the pgbx CLI in place and says so (pgbx's extension supports PostgreSQL 13–18; found N).

What the installer does

1. Downloads from the latest GitHub Release (https://github.com/deemwar-products/pgbx/releases/latest/download/…, no GitHub API call) or the release given with --version, and checks every file against the release’s SHA256SUMS. A mismatch stops the install before anything is copied.
2. Installs pgbx to /usr/local/bin (with sudo when needed), or ~/.local/bin when there is no sudo.
3. Linux: finds every local PostgreSQL (pg_config on PATH, /usr/lib/postgresql/*/bin, /usr/pgsql-*/bin) and, for each 13–18 (or only --pg-version N), copies the library to pg_config --pkglibdir and the control + SQL files (including upgrade scripts) to pg_config --sharedir/extension.
4. Asks Install the pgbx agent skill for Claude Code / Codex? [Y/n] (Enter = yes). With no terminal it installs it; as root it skips it (run pgbx skill install as your user). Remove with pgbx skill uninstall.
5. Never edits postgresql.conf and never restarts anything.

sudo pgbx setup server then writes one drop-in, <config dir>/conf.d/pgbx.conf, with shared_preload_libraries merged with what the server already loads, and the pgbx.s3_* / server_name / credentials_file settings; and the S3 credentials file (/etc/pgbx/s3.credentials, mode 0600, owned by postgres). Keys are read from environment variables (default AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, or name others with --access-key-env / --secret-key-env) or typed at a hidden prompt, and are never printed. Without --yes it only shows the plan. If postgresql.conf does not include conf.d, --yes adds one include_dir = 'conf.d' line and says so. It prints the one restart command; after the restart the worker creates the extension in every database within seconds.

sudo AWS_ACCESS_KEY_ID=… AWS_SECRET_ACCESS_KEY=… pgbx setup server --yes \
  --s3-endpoint https://s3.eu-central-1.amazonaws.com --s3-bucket my-backups --s3-region eu-central-1 \
  --server-name db-prod-1

On EC2: the instance role, no keys file

Attach an instance profile whose role may use the bucket, and give pgbx no keys at all:

sudo pgbx setup server --yes --credentials aws-default \
  --s3-endpoint https://s3.eu-central-1.amazonaws.com --s3-bucket my-backups --s3-region eu-central-1 \
  --server-name db-prod-1

This writes pgbx.credentials_file = 'aws-default' and no credentials file. pgbx then takes temporary credentials from the instance role through IMDSv2 (never IMDSv1) and renews them before they expire; ECS task roles and EKS (IRSA, Pod Identity) work the same way. The role’s policy, on your bucket only:

{"Version": "2012-10-17", "Statement": [
  {"Effect": "Allow", "Action": ["s3:ListBucket", "s3:ListBucketMultipartUploads"],
   "Resource": "arn:aws:s3:::my-backups"},
  {"Effect": "Allow",
   "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject", "s3:AbortMultipartUpload", "s3:ListMultipartUploadParts"],
   "Resource": "arn:aws:s3:::my-backups/*"}]}

pgbx doctor shows s3 credentials ... source: instance-role (... role NAME ...), or what is missing. Details: S3 credentials without a keys file.

Installer flags

install.sh	install.ps1 / install.cmd
--version v0.5.0	-Version v0.5.0	pin a release (default: latest)
--pg-version 16		extension only for this PostgreSQL
--prefix DIR	-InstallDir DIR	where pgbx goes
--skill / --no-skill	-Skill / -NoSkill	install / skip the agent skill without asking
--no-extension		CLI only
--base-url URL	-BaseUrl URL	download from a mirror (must hold SHA256SUMS)

Flags with the one-liner: curl -fsSL https://pgbx.deemwar.com/install.sh | sh -s -- --pg-version 16 --no-skill.

Manual install

Download from GitHub Releases the files for your machine and SHA256SUMS, then:

sha256sum -c --ignore-missing SHA256SUMS
tar xzf pgbx-ext-pg16-linux-amd64.tar.gz
sudo install -m 755 pgbx-ext-pg16-linux-amd64/lib/*.so "$(pg_config --pkglibdir)/"
sudo install -m 644 pgbx-ext-pg16-linux-amd64/extension/* "$(pg_config --sharedir)/extension/"
tar xzf pgbx-linux-amd64.tar.gz && sudo install -m 755 pgbx-linux-amd64/pgbx /usr/local/bin/

Or configure by hand instead of pgbx setup server: a credentials file readable by postgres only (access_key_id=… and secret_access_key=… lines), and in postgresql.conf or a conf.d file:

shared_preload_libraries = 'pgbx'          # add to any existing list; needs one restart
pgbx.s3_endpoint      = 'https://hel1.your-objectstorage.com'
pgbx.s3_bucket        = 'my-backups'
pgbx.s3_region        = 'hel1'
pgbx.server_name      = 'db-prod-1'        # folder for this server in the bucket
pgbx.credentials_file = '/etc/pgbx/s3.credentials'   # or 'aws-default': the EC2 instance role, no keys file

All settings: Settings reference. Build from source: cargo pgrx package (extension) and cargo build --release --manifest-path cli/Cargo.toml (CLI).

Uninstall

pgbx skill uninstall                                   # as each user that installed the skill
sudo rm /etc/postgresql/*/main/conf.d/pgbx.conf        # then restart Postgres once
# in each database, if you want the schema gone:  DROP EXTENSION pgbx;
sudo rm "$(pg_config --pkglibdir)/pgbx.so" "$(pg_config --sharedir)"/extension/pgbx[.-]*
sudo rm /usr/local/bin/pgbx /etc/pgbx/s3.credentials

Windows: pgbx skill uninstall, then delete %LOCALAPPDATA%\pgbx and remove it from your user PATH.

Need help? Installation, support and training by deemwar

pgbx is free and open source (MIT). If you want it installed on your Postgres servers, restores tested on your data, or a person to call when a backup misbehaves, deemwar does that. We charge for people's time, scoped in writing; rate on request.

Work emailAnything we should know (optional)

SendRunning a quick security check…