Agent mode

The Databasus agent enables physical backups, incremental backups, WAL archiving and Point-in-Time Recovery (PITR) for PostgreSQL databases.

When to use the agent

For most databases, remote backups are the simplest option. Databasus connects directly to the database over the network, performs logical backups using pg_dump, and requires no additional software on the database server. Remote backups work with cloud-managed databases (RDS, Cloud SQL, Supabase) and self-hosted instances alike.

The agent is designed for scenarios where remote backups are not sufficient:

Disaster recovery with PITR — restore to any second between backups with near-zero data loss
Physical backups — file-level copy of the entire database cluster, faster backup and restore for large datasets
Databases not exposed publicly — the agent connects outbound to Databasus, so the database never needs a public endpoint
Incremental backups — continuous WAL segment archiving combined with periodic base backups

In-app guided setup

Databasus provides interactive installation and restore instructions directly in the UI. When you open the agent settings for a database, all commands are pre-filled with your specific values: architecture, database ID, agent token, Databasus host, and PostgreSQL deployment type. You can copy each command and run it on your server.

The documentation below covers the same steps for reference and for users who prefer to follow a guide outside the UI.

Requirements

PostgreSQL 15 or newer
Linux (amd64 or arm64)
Network access from the agent to your Databasus instance (outbound only — the database does not need to be reachable from Databasus)

Installation

Step 1 — Download the agent

Download the agent binary on the server where PostgreSQL runs. Replace <DATABASUS_HOST> with your Databasus instance URL and <ARCH> with amd64 or arm64.

curl -L -o databasus-agent "<DATABASUS_HOST>/api/v1/system/agent?arch=<ARCH>" && chmod +x databasus-agent

Step 2 — Configure postgresql.conf

Add or update these settings in your postgresql.conf, then restart PostgreSQL.

For host installations (replace <WAL_QUEUE_DIR> with the actual path, e.g. /opt/databasus/wal-queue):

wal_level = replica
archive_mode = on
archive_command = 'cp %p <WAL_QUEUE_DIR>/%f.tmp && mv <WAL_QUEUE_DIR>/%f.tmp <WAL_QUEUE_DIR>/%f'

For Docker installations, the archive_command path (/wal-queue) is the path inside the container. It must match the volume mount target — see Step 5.

wal_level = replica
archive_mode = on
archive_command = 'cp %p /wal-queue/%f.tmp && mv /wal-queue/%f.tmp /wal-queue/%f'

Step 3 — Configure pg_hba.conf

Add this line to pg_hba.conf. This is required for pg_basebackup to take full backups — not for streaming replication. Adjust the address and auth method as needed, then reload PostgreSQL.

host    replication   all   127.0.0.1/32   md5

Step 4 — Grant replication privilege

This is a PostgreSQL requirement for running pg_basebackup — it does not set up a replica.

ALTER ROLE <YOUR_PG_USER> WITH REPLICATION;

Step 5 — Create WAL queue directory

PostgreSQL places WAL archive files here for the agent to upload.

mkdir -p /opt/databasus/wal-queue

Ensure the directory is writable by PostgreSQL and readable by the agent:

chown postgres:postgres /opt/databasus/wal-queue
chmod 755 /opt/databasus/wal-queue

For Docker installations, the WAL queue directory must be a volume mount shared between the PostgreSQL container and the host. The agent reads WAL files from the host path, while PostgreSQL writes to the container path via archive_command.

# In your docker run command:
docker run ... -v /opt/databasus/wal-queue:/wal-queue ...

# Or in docker-compose.yml:
volumes:
  - /opt/databasus/wal-queue:/wal-queue

Ensure the directory inside the container is owned by the postgres user:

# Inside the container (or via docker exec):
chown postgres:postgres /wal-queue

Step 6 — Start the agent

Replace placeholders in <ANGLE_BRACKETS> with your actual values.

System-wide PostgreSQL (pg_basebackup available in PATH):

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=host \
  --pg-wal-dir=/opt/databasus/wal-queue

PostgreSQL in a specific folder (e.g. /usr/lib/postgresql/17/bin):

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=host \
  --pg-host-bin-dir=<PATH_TO_PG_BIN_DIR> \
  --pg-wal-dir=/opt/databasus/wal-queue

Docker (use the PostgreSQL port inside the container, usually 5432, not the host-mapped port):

./databasus-agent start \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --pg-host=localhost \
  --pg-port=5432 \
  --pg-user=<YOUR_PG_USER> \
  --pg-password=<YOUR_PG_PASSWORD> \
  --pg-type=docker \
  --pg-docker-container-name=<CONTAINER_NAME> \
  --pg-wal-dir=/opt/databasus/wal-queue

After installation

The agent runs in the background after start
Check status: ./databasus-agent status
View logs: databasus.log in the working directory
Stop the agent: ./databasus-agent stop

Restore from agent backup

Restore a physical or incremental backup to a target directory. For Point-in-Time Recovery, add the --target-time flag to restore to a specific moment.

Step 1 — Download the agent

Download the agent binary on the server where you want to restore (same command as installation Step 1).

curl -L -o databasus-agent "<DATABASUS_HOST>/api/v1/system/agent?arch=<ARCH>" && chmod +x databasus-agent

Step 2 — Stop PostgreSQL

PostgreSQL must be stopped before restoring. The target directory must be empty.

pg_ctl -D <PGDATA_DIR> stop

For Docker:

docker stop <CONTAINER_NAME>

Step 3 — Run restore

Replace <YOUR_AGENT_TOKEN> with your agent token and <PGDATA_DIR> with the path to an empty PostgreSQL data directory.

Host installation:

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --target-dir=<PGDATA_DIR>

Docker installation (<HOST_PGDATA_PATH> is the path on the host that will be mounted as the container's pgdata volume):

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --pg-type=docker \
  --target-dir=<HOST_PGDATA_PATH>

For Point-in-Time Recovery (PITR), add --target-time with an RFC 3339 timestamp (e.g. 2025-01-15T14:30:00Z):

./databasus-agent restore \
  --databasus-host=<DATABASUS_HOST> \
  --db-id=<DB_ID> \
  --token=<YOUR_AGENT_TOKEN> \
  --backup-id=<BACKUP_ID> \
  --target-dir=<PGDATA_DIR> \
  --target-time=<RFC3339_TIMESTAMP>

Step 4 — Handle archive_command

The restored backup includes the original archive_command configuration. PostgreSQL will fail to archive WAL files after recovery unless you either:

Re-attach the agent — mount the WAL queue directory and start the Databasus agent on the restored instance, same as the original setup.
Disable archiving — if you don't need continuous backups yet, comment out or reset the archive settings in postgresql.auto.conf:

# In <PGDATA_DIR>/postgresql.auto.conf, remove or comment out:
# archive_mode = on
# archive_command = '...'

Step 5 — Start PostgreSQL

Start PostgreSQL to begin WAL recovery. It will automatically replay WAL segments.

pg_ctl -D <PGDATA_DIR> start

For Docker:

docker start <CONTAINER_NAME>

Step 6 — Clean up

After recovery completes, remove the WAL restore directory:

rm -rf <PGDATA_DIR>/databasus-wal-restore/

How it works

The Databasus agent is a lightweight Go binary that runs two concurrent processes:

WAL streaming — picks up WAL segment files from the queue directory approximately every 10 seconds and uploads them to Databasus
Periodic base backups — runs pg_basebackup on the configured schedule to create full physical backups of the database cluster

During restoration, the agent downloads the base backup and all relevant WAL segments, then configures recovery.signal and restore_command in postgresql.auto.conf. When PostgreSQL starts, it replays the WAL segments to reach the target recovery point.

The agent always initiates the connection to Databasus (outbound). The database server does not need to accept incoming connections from Databasus, making it suitable for private networks and firewalled environments.