Database Restore & Recovery

A backup is only useful if you can put it back. This page is the companion to Database Backup & Maintenance: it walks through restoring the Athena database from one of your backup files and how to confirm the server is healthy afterwards.

Restore is an offline, whole-database operation

Restoring replaces the entire live database with the contents of the backup — every agent, deployment, command, compliance record, user, and audit entry reverts to the moment the backup was taken. There is no merge. Always take a fresh backup of the current database first so you can roll the restore back if you picked the wrong file.

When you would restore#

Recover from a bad change — an accidental bulk deletion, a misconfiguration, or data corruption. Roll back to the last good backup.
Rebuild a host — the appliance VM was lost. Stand up a fresh appliance and restore your off-box backup onto it so the fleet reconnects to a known state.
Clone to a test environment — bring a copy of production data up on a separate, isolated host for rehearsal or troubleshooting.

Before you start#

Pick the backup file. Backups are timestamped athena_backup_<yyyy_MM_dd_HH_mm_ss>.db files in the server's backup directory (shown under Settings → Database → Backup Information). The automatic backups the appliance takes before every update are kept in /data/athena/backups.
Match the provider. A SQLite .db backup restores onto a SQLite database; a PostgreSQL dump restores onto PostgreSQL. You cannot cross-restore between the two — see Using PostgreSQL for the Database.
Plan a maintenance window. The server is offline while you restore. Agents queue and reconnect once it is back; in-flight remote sessions end.

Restoring on the appliance#

Restore from a backup with the in-app database backup/restore. For a restore on the appliance itself, contact support@sealgrid.ai.

Restore the Root CA too, or re-enroll the fleet

The database holds your configuration and records, but agent trust is anchored by the Root CA, which is kept outside the database. To recover a working server that your existing agents keep trusting, restore both the database and the PKI data from the old server. On the appliance these live in /data/athena and /data/pki — back up /data/athena and /data/pki together. If the CA is lost, a fresh one is generated and agents must be re-enrolled — see Certificates & PKI and Data Directories & Backup for what to preserve.

Verifying the restore#

After the server restarts, confirm it came up cleanly on the restored data before you consider the recovery complete:

Health check. The appliance runs its own health check against /health, including the database probe; its state shows on the VM console status screen and under Settings → Appliance → Overview. For detail, an Admin can open the authenticated health report — see Server Health & Monitoring — and confirm the Database component is healthy.
Sign in and spot-check. Log in to the console and confirm the data reflects the backup's point in time — the agent count, recent deployments, users, and roles.
Watch agents reconnect. Agents reconnect on their next heartbeat and resume reporting; see Agent Status & Health.
Review the audit trail. Restored data starts at the backup's timestamp — any changes made after that backup are not present. Check the audit trail to understand the gap.

# Liveness
curl -k https://athena.example.com:8443/health

# Detailed health (Admin bearer token) — confirms the Database component
curl -k -H "Authorization: Bearer <token>" \
  https://athena.example.com:8443/api/health/details

Things to keep in mind#

Consideration	What to expect
Data loss window	Everything created or changed after the backup timestamp is gone. Restore the newest good backup to minimize the gap, and back up often — see scheduled backups.
Schema version	Migrations run automatically on start, so a backup from an older build is upgraded to the running server's schema. Restoring onto an older server than the one that wrote the backup is not supported.
Bulk file storage	The database does not contain uploaded packages, agent binaries, helper binaries, or session recordings — those are stored separately. Restore them alongside the database if you need a complete point-in-time recovery (Data Directories & Backup).
Root CA & certificates	Agent trust depends on the Root CA in the PKI directory, not the database. Preserve and restore it to avoid re-enrolling agents (Certificates & PKI).
Server TLS certificate	If you restore onto a new appliance, its server TLS certificate is separate from the database. Re-supply your own certificate or let the server regenerate one (Server TLS Certificate).

Database Backup & Maintenance — create the backups this page restores, on demand or on a schedule.
Data Directories & Backup — every persistent directory to preserve for a complete recovery, not just the database.
Using PostgreSQL for the Database — running on PostgreSQL instead of the embedded SQLite database.
Certificates & PKI — the Root CA that anchors agent trust, kept outside the database.
Server Health & Monitoring — the health report used to verify the restore.
Downloads — the appliance and first-boot setup.