Upgrading and backups

Read the target release notes and test the upgrade against a restored copy of your database before changing a live deployment. Pin the release version or image digest; do not use an unverified latest tag. Check license maintenance coverage before upgrading a perpetual-key installation.

Back up before upgrading

Janus v2026.9.2 has no backup or restore subcommand. Use database tooling and preserve the original JANUS_ENCRYPTION_KEY, configuration, and license files separately in protected storage. A database without its original encryption key cannot decrypt stored provider credentials. Treat backups and keys as secrets; test restores in isolation.

SQLite local launcher

Stop the local launcher and wait for the gateway process to exit before copying its data. With the default data location and no running writer:

umask 077
data="${XDG_DATA_HOME:-$HOME/.local/share}/janus"
backup="$HOME/janus-backup-$(date -u +%Y%m%dT%H%M%SZ)"
mkdir -m 700 "$backup"
cp -a "$data/." "$backup/"

Copy the whole directory, including any janus.db-wal and janus.db-shm files, not just janus.db. Adjust the path if you passed --data-dir. For Docker/Compose, stop the gateway container and back up the entire janus-data volume plus janus.env or deploy/.env; the volume alone does not contain that environment-file key.

To restore a local-launcher backup, stop the gateway, move the current data directory aside for recovery, and copy the saved directory back to the same data path. Preserve private permissions and restore the matching encryption key. Do not mix old database files with newer WAL/SHM files. Start the matching gateway version first and verify sign-in and provider access before attempting an upgrade.

PostgreSQL

Use PostgreSQL client tools compatible with the server. Configure connection details through a protected service/password file, not a password pasted into shell history. These examples assume a configured janus service; janus_restore must point to a new, empty, isolated database, never production:

umask 077
pg_dump --dbname='service=janus' --format=custom --file=janus-before-upgrade.dump
pg_restore --dbname='service=janus_restore' --no-owner --no-acl --exit-on-error janus-before-upgrade.dump

pg_dump creates a consistent database snapshot while the server is running. Back up roles/grants separately if needed and coordinate the snapshot with the saved configuration and encryption key. Test the restored database using the original gateway version and key, with external integrations disabled or isolated to avoid sending real traffic.

Upgrade and rollback

After a verified backup, stop the gateway, install the explicitly selected release or pull its versioned image, and restart with the existing database, configuration, and encryption key. Database migrations run at startup. Review logs, readiness, sign-in, and provider access before returning traffic.

Do not assume an older binary can read a database migrated by a newer release. There is no blanket one-minor-version rollback guarantee. If rollback requires restoration, stop all gateway writers and restore the pre-upgrade database and matching configuration/key together, then run the original version. Restoration discards writes made since the backup; plan the outage and recovery point accordingly.