Updating and uninstalling the agent
How the agent updates itself safely, how to control updates, upgrade by hand, and remove the agent.
Automatic updates
On a server, the agent keeps itself up to date. Each step protects your database server:
- Signed. Rowsafe offers a release in the heartbeat response. The agent checks its Ed25519 signature against a key built into the agent, and refuses anything unsigned, or older than itself.
- Between tasks only. It never interrupts a backup, drill or restore point.
- Checked. It downloads the new binary and checks its size and SHA-256 against the signed manifest.
- Self-tested. The new version must load the configuration, find pgBackRest, reach Rowsafe and connect to every database, before the agent switches to it.
- On probation. The new version takes no tasks until it has run for a minute and reached Rowsafe. If it doesn't reach Rowsafe within 10 minutes, or fails to start 3 times in a row, the agent goes back to the previous version by itself.
A version that failed isn't retried for 24 hours. rowsafe hosts list shows each host's version and last update result (staged, switched, confirmed, rolled_back or failed).
In Docker, the agent never updates itself: change the image tag.
Control updates
| To | Run |
|---|---|
| Move a host to another channel | rowsafe hosts channel db-1 beta |
| Keep a host on one version | rowsafe hosts pin db-1 0.4.2 |
| Follow the channel again | rowsafe hosts unpin db-1 |
| Turn off automatic updates | Set ROWSAFE_AUTO_UPDATE='false' in /etc/rowsafe/agent.env, then sudo systemctl restart rowsafe-agent |
| Upgrade or reinstall by hand | Run the installer again (below) |
A pin never downgrades an agent: the agent refuses older versions.
Upgrade by hand
Running the installer again is safe. It changes only what differs, keeps your configuration, and doesn't restart the agent while a backup or drill is running:
curl -fsSL https://rowsafe.sh | sudo shTo install one exact version:
curl -fsSL https://rowsafe.sh | sudo ROWSAFE_VERSION=0.4.2 shIt refuses to go back to an older version unless you also set ROWSAFE_ALLOW_DOWNGRADE=1. See the installer options.
Change the configuration
Edit /etc/rowsafe/agent.env (sudoedit /etc/rowsafe/agent.env), then either run the installer again (it self-tests first) or restart the agent:
sudo systemctl restart rowsafe-agentAfter rotating bucket keys, restart the agent, then run rowsafe verify app for each database on the server. This rewrites the pgBackRest configuration that PostgreSQL's archive_command uses, and proves the new keys work.
Never change the passphrase, bucket or path of a repository with backups
pgBackRest can't re-encrypt an existing repository. Old backups would become unreadable, or new WAL would go somewhere else. To move to a new bucket, adopt the database afresh, and keep the old bucket settings and passphrase in your secret manager until its old backups have expired.
Uninstall
Uninstalling the agent doesn't touch PostgreSQL, and WAL archiving keeps working: it only needs pgBackRest and /etc/rowsafe/pgbackrest.
curl -fsSL https://rowsafe.sh | sudo sh -s -- --uninstallThis stops and removes the service and the agent's binaries. It keeps its configuration, state and logs, pgBackRest, and your backups.
To also delete the configuration, state and logs, first turn off WAL archiving (see Rollback), then:
curl -fsSL https://rowsafe.sh | sudo sh -s -- --uninstall --purge--purge refuses while PostgreSQL's configuration still points archive_command at /etc/rowsafe/pgbackrest, because every archive attempt would then fail and pg_wal would fill the disk. It only checks the usual Debian and Ubuntu configuration paths: if your data directory lives elsewhere, check archive_command yourself first.
Finally, remove the server from Rowsafe:
rowsafe db remove app --keep-archiving # for each database on it
rowsafe hosts remove db-1In Docker, turn off archiving first (the same ALTER SYSTEM commands), then remove the rowsafe-agent service. Otherwise archive_command keeps copying WAL into the spool with nothing pushing it, and the spool volume grows.