Companion Reference

This document documents every companion command, flag, and default. The companion is a single binary built from the companion directory.

Building the companion

Build the binary with the Go toolchain, version 1.25 or later:

cd companion
go build -o volvra-companion .

The companion depends on github.com/jackc/pglogrepl and github.com/jackc/pgx/v5. Both declare a minimum of Go 1.25, which sets the floor for the companion. Both are client libraries, so neither imposes anything on the database.

Command summary

The following table describes each command:

Common flags

The following table describes the flags every command accepts:

Give the connection string as a URL or as keyword and value pairs. Both forms work, because the companion parses the string rather than appending to it.

The companion registers every flag for every command, so a flag that does not apply to a command is accepted and ignored rather than rejected. The tables below group each flag with the command the flag affects.

The run command

run creates the slot if the slot is absent, resumes from the archive, and streams until interrupted:

volvra-companion run --dsn "$DATABASE_URL" \
    --archive /srv/volvra-archive \
    --slot volvra_companion \
    --publication volvra_pub \
    --segment-bytes 67108864 \
    --lag-warn 536870912 \
    --lag-max 5368709120

The following table describes each flag the command accepts:

The command requires --dsn and --archive.

Object storage

Credentials are never taken as flags, because a flag puts them in the process list and in shell history. The companion reads them from the environment, the shared credentials file, or an instance or workload identity role.

With a bucket configured, the replication slot does not advance past a segment the bucket has not confirmed, so a bucket outage retains write-ahead log rather than releasing it.

Google Cloud Storage does not implement the aws-chunked trailing header that carries a server-side checksum, and asking for one against a Google endpoint fails the upload, so --s3-checksum defaults to auto and selects read-back verification for storage.googleapis.com. Read-back downloads each segment after uploading it, which doubles the traffic; the companion says so at startup.

pgVolvra never sets an object lock retention. If the bucket enforces one, the companion detects it and reports it, because volvra.forget cannot erase an archived object while a retention stands. The Where the Archive Is Stored document explains the consequences.

How run acknowledges progress

The companion tells PostgreSQL that write-ahead log may be discarded only up to a position the companion has written, flushed, and recorded in the manifest. Acknowledging sooner would let PostgreSQL discard log the archive does not hold.

The archive is therefore the authority on what is durable, rather than the slot. On start, the companion resumes from the last position the archive holds, even when the slot has confirmed a later position.

The verify command

verify checks an archive with no database connection:

volvra-companion verify --archive /srv/volvra-archive

The command prints the archive path, the slot, the segment count, and the change count, then either confirms the archive or lists one finding per problem segment. The command exits non-zero when any finding is present.

Reading from a bucket

verify and restore accept the same --s3-* flags as run. Pass an empty --archive to read the bucket alone, which is what a host loss leaves you with:

volvra-companion verify --archive "" \
  --s3-bucket my-archive --s3-endpoint s3.us-east-1.amazonaws.com

The restore command

restore verifies the archive, then loads the changes:

volvra-companion restore --archive /srv/volvra-archive \
    --dsn "$DATABASE_URL"

The following table describes the flag the command adds:

The command refuses an archive that does not verify. Gap and truncate records carry no row image, so the command reports those as skipped.

Restored rows carry actor set to archive: followed by the log position, and db_user set to archive, so restored history is distinguishable from history the trigger tier captured.

The status command

status reports the durable tier as the database sees it:

volvra-companion status --dsn "$DATABASE_URL"

The command calls volvra.companion_status, so the output matches what that function returns in SQL.

The archive on disk

An archive directory holds a manifest and one file per segment. The following table describes the contents:

The following table describes each field of a segment record in the manifest:

The following table describes the top-level manifest fields:

The companion refuses to append to an archive whose slot differs from the one given on the command line, so two slots cannot be mixed into one archive.

Change records

The following table describes each field of a change record:

A gap record replaces the row fields with the following:

Exit codes

The following table describes the exit codes:

Removing a companion

Stop the companion, then drop the slot so the database stops retaining write-ahead log:

SELECT pg_drop_replication_slot('volvra_companion');
DROP PUBLICATION volvra_pub;

Dropping the slot is the important step. A slot with no consumer retains log indefinitely.

Next Steps

• The Companion Overview document explains what the companion is for.
• The Troubleshooting document covers slot and replication problems.