pgBackRest server operations

The komp.ac server can launch pgBackRest backups and checks for an authenticated administrative client. It can also return pgBackRest backup information and let the client poll an operation started through that server process.

These operations use the same pgBackRest backup format and stanza as the command-line targets. The server is only an orchestration layer around the local pgBackRest executable.

Backup only

The current API cannot restore a database. It exposes no latest, point-in-time, or other recovery operation.

Authorization

Only superadmin can use the backup service. Backup authority is the fixed structural permission struct:backup with the manage action. It is deliberately absent from the admin role and cannot be delegated through an ordinary data grant.

A physical backup can contain every row in the PostgreSQL cluster, regardless of profile or table grants. Treat access to this service and its returned output as access to highly sensitive production data and metadata.

Available operations

Operation	Behavior	Purpose
Start backup	Asynchronous	Starts an explicitly selected full, differential, or incremental backup
Start check	Asynchronous	Starts a pgBackRest check for the configured stanza
Get backup information	Synchronous	Runs pgBackRest info and returns its combined output
Get operation status	Synchronous	Returns the in-memory status of one asynchronous backup or check

There are no server operations for restoration, stanza creation, backup expiration, repository maintenance, cancellation, operation history, or listing all operations. The same service also starts pg_dump logical dumps, documented separately because they use different tools, configuration, scope, and artifacts.

Starting a backup

The caller must select one of the three supported types:

• full becomes --type=full backup;
• differential becomes --type=diff backup;
• incremental becomes --type=incr backup.

An absent, unspecified, or unknown type is rejected. Unlike the Makefile’s make backup alias, the server has no implicit default to incremental.

The response is returned as soon as the operation has been registered. It contains a generated operation ID, kind backup, status running, a start timestamp, and an empty output field. The pgBackRest child process continues in the background.

Starting a check

A check runs pgBackRest check asynchronously. It has the same operation-ID and polling behavior as a backup and shares the same one-operation-at-a-time guard.

A successful check confirms that pgBackRest accepted the check and exited successfully. It is not a recovery rehearsal and does not prove that komp.ac can be started from a recovered cluster.

Reading backup information

Backup information runs pgBackRest info synchronously. The request waits until pgBackRest exits, then receives:

• a success flag based on the process exit status;
• standard output and standard error combined into one text field.

This operation does not create an operation ID and does not use the tracked-operation lock. It can therefore overlap a backup or check started through the server. Its output is pgBackRest’s human-readable text, not structured backup records interpreted by komp.ac.

Polling an operation

Poll the returned operation ID until its status becomes succeeded or failed. The remembered operation contains:

• the operation ID;
• kind backup or check;
• status running, succeeded, or failed;
• a short server message;
• combined pgBackRest output after completion;
• start time in Unix seconds;
• finish time in Unix seconds, which is zero while running.

An empty ID is rejected and an unknown ID returns not found. Output is collected only when the child process exits, so the service provides no live logs, byte counts, percentage, or phase progress.

Concurrency and lifetime

Only one asynchronous pgBackRest backup, pgBackRest check, or pg_dump operation can run at a time within one komp.ac server process. Starting any of these while another is tracked as running fails with a precondition error.

That guard does not coordinate with:

• Makefile commands;
• pgBackRest started directly or by a scheduler;
• another komp.ac server replica;
• the synchronous backup-information operation.

Operation records and the running marker exist only in memory. Restarting the server loses all operation IDs and status history. There is no cancellation and no timeout in this service.

A lost status is not proof that work stopped

If the server restarts during an operation, inspect pgBackRest processes, logs, repository locks, and backup information before launching more work. The new server process cannot recover the old in-memory operation record.

Success and failure

When pgBackRest exits with zero status, the operation becomes succeeded and its combined output is stored. A non-zero exit becomes failed with the command output. Failure to start the configured binary also becomes a failed operation with the execution error.

Success only means that pgBackRest exited successfully. Operators still need monitoring, retention review, and isolated recovery tests to establish that the backup meets the required recovery objective.

See Backup safety for the operational controls that the service does not provide.