# Updating and uninstalling the agent

> How the agent updates itself safely, how to control updates, upgrade by hand, and remove the agent.

Source: https://rowsafe.sh/docs/guides/agent-updates

## Automatic updates

On a server, the agent keeps itself up to date. Each step protects your database server:

1. **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.
2. **Between tasks only.** It never interrupts a backup, drill or restore point.
3. **Checked.** It downloads the new binary and checks its size and SHA-256 against the signed manifest.
4. **Self-tested.** The new version must load the configuration, find pgBackRest, reach Rowsafe and connect to every database, before the agent switches to it.
5. **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](https://rowsafe.sh/docs/guides/docker#upgrade).

## 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:

```sh
curl -fsSL https://rowsafe.sh | sudo sh
```

To install one exact version:

```sh
curl -fsSL https://rowsafe.sh | sudo ROWSAFE_VERSION=0.4.2 sh
```

It refuses to go back to an older version unless you also set `ROWSAFE_ALLOW_DOWNGRADE=1`. See the [installer options](https://rowsafe.sh/docs/reference/agent-configuration#installer).

## 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:

```sh
sudo systemctl restart rowsafe-agent
```

**After 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`.

```sh
curl -fsSL https://rowsafe.sh | sudo sh -s -- --uninstall
```

This 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](https://rowsafe.sh/docs/guides/adopt#rollback)), then:

```sh
curl -fsSL https://rowsafe.sh | sudo sh -s -- --uninstall --purge
```

> **Warning:** `--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:

```sh
rowsafe db remove app --keep-archiving   # for each database on it
rowsafe hosts remove db-1
```

In **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.