Database Backups and Hooks
This guide covers the two optional job features that need local setup on an agent: backing up a PostgreSQL database and running administrator-approved hooks around a backup.
Back up a PostgreSQL database
Check the agent first
Install the PostgreSQL client tools on the agent machine. For backup, the agent needs:
pg_dump9.0 or newer.- Restic 0.17.0 or newer, with
--stdin-from-commandand--stdin-filenamesupport. - Network access from the agent to the PostgreSQL host and port.
The database server can be remote. The PostgreSQL account must be able to connect and read the
schema and data to be included. To restore on a machine, install pg_restore there as well; it
does not have to be the database server.
The agent reports available features when it runs. In the dashboard, open Agents → Capabilities to check the report. Reports older than 30 days are marked stale. After installing or upgrading tools, refresh the report immediately by running:
sudo vecta-agent hooks publish
Despite the command name, this publishes the agent's current capability report; it does not run a backup.
Configure the job and password
In the job builder, select PostgreSQL and enter the host, port, database, username, and SSL
mode (disable, allow, prefer, require, verify-ca, or verify-full). These are
connection settings, not a password. The dashboard has no database-password field, and the
backend never receives the password.
After saving the job, run the setup command on the agent:
sudo vecta-agent setup <JOB_ID>
For a PostgreSQL job, setup checks the local tools, prompts for the database password unless that
connection already has saved credentials, and runs a bounded schema-only pg_dump connection
test. It then handles destination credentials and prepares the Restic repository as usual. The
password is stored in a connection-scoped libpq password file under ~/.config/vecta/ with mode
0600; it is not sent to Vecta or placed in a process argument.
The schema-only test confirms basic connectivity and access. It does not create a full dump or test a Restic upload, so the first backup run is the end-to-end test.
What the backup contains
The agent streams a custom-format archive from pg_dump directly into Restic. The archive appears
in the snapshot as postgresql-<database-name>.dump (with unsafe characters sanitized). Vecta
does not first create a temporary file containing the entire dump. Restic's cache, upload
temporary files, and any local repository still use disk, so allow space for them.
Vecta currently uses pg_dump -Fc -Z 0. Disabling pg_dump's archive compression is intended to
give Restic a better chance to deduplicate similar data between runs; the real effect depends on
the database and repository. Restic compression is available with repository format v2. Vecta
does not automatically upgrade an existing repository, and no particular space saving is
guaranteed.
Register local hooks
Hooks are short local tasks that run before or after a backup—for example, pausing a service before capture or resuming it afterward. You can select them in a job, but the executable and its invocation are configured on the agent by its administrator.
Add and check a hook
First install the executable on the agent. Then use the interactive catalog wizard:
sudo vecta-agent hooks add
sudo vecta-agent hooks validate
vecta-agent hooks list
sudo vecta-agent hooks publish
The wizard records the hook ID and display details, whether it can run before or after a backup,
the executable path, the execution account, allowed parameters, and fixed argument-template
items. A parameter placeholder such as ${service} must fill an entire argument. The agent runs
the executable directly, without a shell; a job cannot submit its own command, path, arguments,
or environment overrides.
hooks validate checks the local catalog, and hooks list shows registered hooks. Both are
read-only and can be run without sudo. Adding or publishing hooks requires root.
Protect hook files and choose privileges
The default catalog is /etc/vecta/hooks.toml. The catalog, its parent directories, and each
executable must be root-owned and not writable by group or other users. Symlinks are rejected. If
the catalog is missing or invalid, hooks are unavailable; if a selected hook was removed or
changed, the agent refuses to run it.
Hooks run as an unprivileged local service account by default. The default account, vecta-hook,
must be created by the administrator; the wizard can use an existing service account instead.
Root execution is an explicit catalog grant, shown in the dashboard. It is never used as a
fallback if the selected account cannot be used.
Only add hooks whose effects are appropriate for a job to trigger. A selected hook is a capability: dashboard users who can configure jobs may invoke it using the allowed parameters. Keep parameters narrow and do not use them to pass secrets. Hook execution is bounded to 120 seconds, captured output is limited to 16 KiB per stream, and hook output is not sent to the backend.
The agent reports its safe hook metadata during each run. After changing the catalog, use
sudo vecta-agent hooks publish to report it immediately. The dashboard uses that report to show
available choices; the agent checks the local catalog again at execution time, so a report does
not override local validation.
Understand a run
Restic repository preparation happens before the visible job pipeline. Once preparation succeeds, the pipeline is:
optional pre-hook → source capture → Restic snapshot → optional post-hook
For a filesystem job, source capture means Restic reads the selected path. For PostgreSQL, it
means pg_dump produces the archive that Restic stores.
- If a pre-hook fails, Vecta skips source capture and the backup.
- If capture or Restic fails, the run fails. The log reports the stage that failed.
- Once pipeline execution has started, a configured post-hook is attempted after a failure or cancellation as a bounded cleanup step.
- If a post-hook fails after a snapshot was created, the overall run is marked failed, but its log retains the snapshot ID and reports the hook failure separately. That completed PostgreSQL archive can still be restored.
For PostgreSQL restore steps and the required local credentials, see Restoring Data. For agent installation and operation, see Agents; for symptoms and checks, see Troubleshooting.