pg_dump logical dumps

The Rust server can create a logical archive of the one PostgreSQL database it currently serves. This complements pgBackRest: pgBackRest protects a physical cluster and its WAL history, while pg_dump produces a portable logical archive for one database.

Server operation only

There is currently no make dump target or standalone dump script. A superadmin starts StartDump through the server. Nothing schedules dumps automatically.

What the dump contains

The archive contains the objects and data in the configured application database, including komp.ac profiles, table definitions, business rows, accounting records, application users, roles stored as application data, migrations, and sequences.

It is not a physical cluster backup. Cluster-level objects outside that database—such as PostgreSQL login roles, server configuration, and other databases—are not captured by this operation. External files, including the original Search subsystem’s Tantivy index, are also outside the dump.

The output uses pg_dump’s custom archive format. It is intended for pg_restore, not direct input to psql.

Configuration

The server reads the dump configuration when the backup service is created:

Variable	Default	Meaning
PG_DUMP_BIN	pg_dump	Executable used to create the archive
PG_RESTORE_BIN	pg_restore	Executable used to verify that the archive can be read
PG_DUMP_DIR	dumps	Directory on the server host where artifacts are written

Restart komp.ac after changing these values. A relative dump directory is resolved from the server process’s working directory. Successful operation status reports its canonical absolute path.

The database target is not configured separately for dumps. The operation reuses the server’s startup database configuration:

RUST_DB_HOST
RUST_DB_PORT
RUST_DB_USER
RUST_DB_PASSWORD
RUST_DB_NAME

Before starting, the service queries current_database() through its existing pool and refuses to continue if it differs from RUST_DB_NAME. This prevents stale configuration from quietly dumping a database other than the one the server is actually serving.

The server host must have compatible pg_dump and pg_restore executables, database connectivity using those settings, and permission to create and write the dump directory.

The implementation assumes a Unix-like server: it applies Unix permission modes and verifies through /dev/null.

Creation and verification lifecycle

One dump follows this sequence:

1. Create the dump directory if necessary and restrict it to mode 0700.
2. Generate a timestamped, UUID-qualified filename.
3. Pre-create a .partial dump file with mode 0600.
4. Run pg_dump against the server’s database in custom format.
5. Read the complete archive back through pg_restore into /dev/null without connecting to a destination database.
6. Compute SHA-256 over the verified partial archive.
7. Write and publish a private .sha256 companion file.
8. Rename the verified dump from its partial name to its final name.

A final artifact is named like:

dump-20260809T201530Z-550e8400-e29b-41d4-a716-446655440000.dump
dump-20260809T201530Z-550e8400-e29b-41d4-a716-446655440000.dump.sha256

The timestamp is UTC, and the UUID prevents collisions between dumps created in the same second.

Verification is stronger than listing the archive

The implementation does not use only pg_restore --list. It asks pg_restore to traverse the archive and write its reconstructed output to /dev/null, which reads the data payload as well as the catalog.

This still is not a test restoration. Verification proves that pg_restore can read the produced archive; it does not create a database, execute the archive, validate permissions in a destination cluster, rebuild external indexes, or prove that komp.ac starts correctly afterwards.

The pg_dump invocation

The server supplies the configured host, port, username, and database name, selects custom format, disables an interactive password prompt, and writes to the partial file. The database password is passed only in the child process’s PGPASSWORD environment variable, not in command-line arguments.

The dump runs while the database is online and observes pg_dump’s consistent database snapshot. Changes committed after that snapshot are not part of the artifact. Long-running dumps still consume database, storage, CPU, and network resources and may retain database state needed by their snapshot.

Success result

Starting a dump returns immediately with an operation ID and running status. Poll the normal backup-operation status until it becomes succeeded or failed.

For a successful dump, status contains:

• operation kind dump;
• final absolute path on the server host;
• lowercase SHA-256 digest;
• start and finish timestamps;
• a text result containing the path and digest.

The path is not a path on the caller’s computer, and the API does not download the artifact. An operator or separate secure transfer mechanism must move it to durable storage.

After moving both files, run the platform’s SHA-256 verification from the directory containing them. With GNU coreutils, for example:

sha256sum -c dump-20260809T201530Z-550e8400-e29b-41d4-a716-446655440000.dump.sha256

Failure behavior

If directory creation, permission changes, pg_dump, verification, hashing, checksum publication, or final publication fails, the operation becomes failed and retains an actionable text error.

The runner removes the partial dump, partial checksum, and published checksum during ordinary failure cleanup. A .partial file is never a completed dump. A file under the final .dump name is published only after full readback and hashing succeed.

Operation state is held only in server memory. A server restart loses the operation ID and status history. Inspect the dump directory and operating-system processes before starting replacement work after an interrupted server process.

Concurrency

A dump shares the server’s single asynchronous backup-operation slot with pgBackRest full, differential, and incremental backups and with pgBackRest checks. If any one of them is running in that server process, another start request fails.

This lock does not coordinate with:

• Makefile pgBackRest commands;
• pg_dump or pgBackRest started directly;
• schedulers;
• another komp.ac server replica;
• synchronous pgBackRest information requests.

Coordinate these sources operationally rather than treating the in-process lock as a host-wide backup lock.

Security and retention

The dump contains every row in the application database, including password hashes and data beyond ordinary table grants. Only superadmin can start or inspect its operation through komp.ac. Filesystem access to PG_DUMP_DIR must be protected independently.

Modes 0700 and 0600 restrict ordinary Unix filesystem access, but they do not provide encryption. Repository placement, encryption at rest, off-host replication, access auditing, retention, and deletion are deployment responsibilities.

The server does not:

• schedule dumps;
• rotate or expire old dumps;
• copy them away from the database host;
• encrypt them;
• upload or download them through the API;
• restore them.

If PG_DUMP_DIR is left as relative dumps/, artifacts remain below the server’s working directory. For production, choose an explicit durable location and a separate process for secure off-host storage and retention.

Operational checklist

Before relying on logical dumps:

• verify the configured database and dump directory;
• verify available space and directory ownership;
• confirm pg_dump and pg_restore are installed and compatible with the PostgreSQL deployment;
• schedule dumps externally;
• monitor failed or overdue operations;
• copy successful artifacts and checksum files to durable storage;
• verify checksums after transfer;
• perform isolated restore rehearsals using the actual archived files;
• document how PostgreSQL roles and other cluster-level prerequisites will be recreated;
• rebuild the external Search index after any eventual recovery.

There is no restore operation in komp.ac. Restoration and validation require a separate reviewed PostgreSQL runbook.