Get started

Create one staging database, start it locally, and make your first backup.

Before you begin

You need:

  • a machine where PostgreSQL can run;
  • PostgreSQL command-line tools for the configured major version: initdb, pg_ctl, psql, pg_dump, and pg_restore;
  • a PostgreSQL TLS certificate and private key.

The default PostgreSQL major version is 17. The tools on PATH must match the version used by the instance.

If you want Worker access, also install cloudflared and create a Cloudflare Tunnel outside this tool. If you want administrator access, install and log in to Tailscale.

Important

stage-pg does not create Cloudflare Tunnels, Workers VPC services, Hyperdrive bindings, Tailscale devices, or Tailscale access rules.

Install

When the package is published, install it globally or run it with your package manager:

pnpm add --global stage-pg
stage-pg --help

Create an instance

Choose an empty folder for the database. Supply the TLS certificate and private key that PostgreSQL will use:

stage-pg init ./stage-data \
  --tls-cert /etc/stage-pg/postgres.crt \
  --tls-key /etc/stage-pg/postgres.key

Add --tls-ca /path/to/ca.crt when clients need a specific CA bundle. You can also choose a PostgreSQL binary directory or database name:

stage-pg init ./stage-data \
  --tls-cert /etc/stage-pg/postgres.crt \
  --tls-key /etc/stage-pg/postgres.key \
  --postgres-bin-dir /usr/lib/postgresql/17/bin \
  --database staging

init automatically chooses a free port in the 55432–55531 range and saves it in config.json. It also creates two database roles:

  • stage_app for the Worker;
  • stage_admin for administrators and backups.

The instance folder must be empty before init runs.

Start PostgreSQL

Run the instance in the foreground:

stage-pg run ./stage-data

Press Ctrl+C to stop it cleanly. The PostgreSQL log is written inside the instance data directory at data/stage-pg-postgres.log.

If you supplied --cloudflare-token-file during init, run also starts the local cloudflared process. Otherwise the instance runs locally until you configure private access.

Make a backup

In another terminal:

stage-pg backup ./stage-data

The verified files appear in stage-data/backups/. See Backups and restore for the file names and restore command.

What happens next