Upgrading

Back up first

trench backup /backups/trench-$(date +%F).tar.gz

The archive covers the whole data directory: query log, users and API tokens, custom rules and zone data. Restoring is trench restore <archive>.

Versioning

Trench follows semantic versioning. Within a major version, configuration files keep working and the database migrates itself forward on first start. Anything that changes defaults or on-the-wire behaviour is called out in the changelog.

From GitHub

Let Trench do it — it checks GitHub Releases, verifies the wheel's sha256 and smoke-tests it before installing:

trench upgrade apply
systemctl restart trench
journalctl -u trench -n 50

trench upgrade status shows the installed and the newest available version without changing anything.

Or by hand, into the same virtual environment it was installed into:

/opt/trench/bin/pip install --upgrade "git+https://github.com/dev-doshi/trench@v2.1.0"
systemctl restart trench

From a checkout

git pull
pip install -e .
systemctl restart trench

With Compose, which builds the image from the checkout:

git pull
docker compose up -d --build

Docker

Once images are published, point Compose at the registry instead of build: and pin a version rather than tracking latest on anything you depend on:

image: ghcr.io/dev-doshi/trench:2.0.0

docker compose pull
docker compose up -d

Database migrations

Migrations run automatically at startup and are logged:

INFO trench.db: applied migration 5: blocklist update reviews

They only move forward. Downgrading after a migration needs the backup you took before upgrading — which is why that step is first.

After upgrading

Check the startup log for warnings. New releases can add checks against your existing configuration, and those surface as warnings rather than failures:

journalctl -u trench -n 50 | grep WARN