Command reference

Look up each stage-pg command, its required arguments, and the files or processes it changes.

Common form

stage-pg <command> <instance> [options]

An instance is the folder containing one staging PostgreSQL database.

There are four commands:

Command	What it does
init	Creates a new instance and initializes PostgreSQL.
run	Starts PostgreSQL and the optional local cloudflared process.
backup	Creates and verifies one logical backup.
restore	Restores a backup into a new database.

stage-pg has no separate status, doctor, or connect command in v1.

init

stage-pg init <instance> --tls-cert <path> --tls-key <path> [options]

Required options:

Option	Meaning
--tls-cert <path>	PostgreSQL server certificate.
--tls-key <path>	PostgreSQL server private key.

Optional options:

Option	Default	Meaning
--tls-ca <path>	none	CA bundle for PostgreSQL TLS.
--postgres-bin-dir <path>	PATH	Directory containing PostgreSQL tools.
--postgres-major <number>	17	PostgreSQL major version to use.
--database <name>	staging	Database created for the instance.
--app-role <name>	stage_app	Least-privilege Worker role.
--admin-role <name>	stage_admin	Administrator and backup role.
--cloudflare-token-file <path>	none	Local token file used by cloudflared during run.

init creates:

<instance>/
  config.json
  secrets.json
  state.json
  data/
  backups/

It chooses and saves one free port. It does not ask Tailscale or Cloudflare to create anything.

run

stage-pg run <instance>

run:

1. checks local configuration, files, executables, and the saved port;
2. starts PostgreSQL;
3. starts cloudflared when a token file is configured;
4. waits in the foreground until you stop it or a required process fails.

Press Ctrl+C for a graceful stop.

run does not test whether Cloudflare or Tailscale can reach the machine before starting. A real network check belongs in an end-to-end smoke test.

backup

stage-pg backup <instance>

The command uses the administrator role and creates a PostgreSQL custom-format dump. It also creates a JSON manifest and SHA-256 sidecar file.

The local dump is published only after it is non-empty and pg_restore --list can read it. If S3 is configured, the local files stay available even when upload fails.

restore

stage-pg restore <instance> <backup>

<backup> can be a dump filename in the instance backup folder, a manifest filename, or a path to one of those files.

The command checks the manifest, file size, SHA-256 checksum, dump format, and PostgreSQL major version. It creates a new database with a name like:

staging_restore_20260807_180000

It never replaces the original staging database. The original database remains untouched if validation fails.

Exit status and errors

• 0 means the command completed successfully.
• 1 means stage-pg printed an error.

Passwords, token contents, and private keys are not printed in normal diagnostics.