Database Backup & Maintenance
Athena stores its whole state — agents, collections, deployments, commands, compliance data, users, and the audit trail — in a single database. This page covers how to protect that data with backups you can take on demand or on a schedule, how to reclaim disk space with an optimize pass, and where to read the current database and backup details. All of it is Admin-only and available from the console, the REST API, and PowerShell.
Every action and settings view on this page requires the Admin role. See Roles & Permissions.
Where to find it#
In the console, open Settings → Database. The tab is organized into three sections:
- Database Information — the current provider, database size, server name, and database path (read-only).
- Backup Information — the backup directory, total number of backup files, and the timestamp, size, and filename of the most recent backup.
- Database Maintenance — the Backup Database, Optimize Database, and Schedule Backup buttons.
Database configuration (the provider and connection string) is read-only in the console because it is bound at startup; changing it is a configuration task that requires a server restart. Backups and optimization, by contrast, run live against the database that is already loaded.
Backing up the database#
A backup writes a point-in-time copy of the database into the server's backup directory. On the
default SQLite provider this is a straight copy of the database file, so a backup is a complete,
self-contained snapshot you can archive or restore by putting the file back. Each backup is
named with a timestamp — athena_backup_<yyyy_MM_dd_HH_mm_ss>.db — so backups
never overwrite one another and are easy to sort by age.
Click Backup Database in Settings → Database (the button shows Creating Backup… while it runs). On success the page shows the path of the file that was written, and the Backup Information section's total count and “last backup” details update.
Backups are written to the server's backup directory. In a container deployment that is the
/app/backups volume — mount it on a persistent disk so backups survive a
container restart, and copy the files off the host on a schedule for true disaster recovery.
See Installation for the volume layout.
Scheduling recurring backups#
For unattended protection, turn a backup into a recurring job. In Settings → Database, click Schedule Backup — this opens the scheduler pre-set to the Database Backup action so you only have to choose when it runs (for example, a nightly cron expression). A scheduled database backup does exactly what the manual button does: it writes a fresh timestamped file into the backup directory on each run.
Once a backup job exists, the Database Maintenance section shows its schedule and next run time, with an Edit link back into the scheduler. Full details on schedule types, cron format, and the job lifecycle are on the Scheduled Jobs page.
Backups accumulate as separate timestamped files and are not pruned automatically, so a
recurring job will grow the backup directory over time. Pair it with your own retention
step — for example a scheduled Log Cleanup job handles application logs, and you can
prune or archive old athena_backup_*.db files with your normal file-retention
tooling. Watch the Disk component on the health
report so the data volume never fills up.
Optimizing the database#
Over time — after large deployments, bulk agent cleanup, or audit-trail growth — the database
file can hold free space that is no longer in use. Optimize Database reclaims
it. On the SQLite provider this runs a VACUUM, which rebuilds the database file and
repacks it into the smallest amount of disk space. The button shows Optimizing… while
it runs.
A rebuild touches the whole file, so on a large database the optimize pass may run for some time. Run it during a quiet window, and take a backup first as a matter of routine. Optimization applies to the SQLite provider; on other providers the action reports that optimization is not applicable.
Reading database & backup details#
The Database Information and Backup Information sections (and the corresponding API response and cmdlet) report the following. These are read-only status values — useful for a monitoring or audit script:
| Field | Meaning |
|---|---|
| Provider | The database engine in use (default Sqlite). |
| Database Path | Location of the database file (SQLite). |
| Database Size | Current size of the database, in bytes and a friendly format (e.g. 1.5 MB). |
| Server | Name of the machine hosting the database. |
| Backup Directory | Folder where backup files are written. |
| Total Backups | Number of backup files currently in the backup directory. |
| Last Backup | Timestamp of the most recent backup (or No backups found). |
| Last Backup Size / Last Backup File | Size and filename of the most recent backup. |
REST API#
The same actions are available over the JWT-authenticated REST API on
port 8443. Send the bearer token as
Authorization: Bearer <token>; all three endpoints require the Admin role.
| Endpoint | Role | Purpose |
|---|---|---|
GET api/settings/database | Admin | Read the database and backup details listed above. |
POST api/settings/database/backup | Admin | Create a backup now. Returns the backup file path, creation time, and who created it. |
POST api/settings/database/optimize | Admin | Optimize (VACUUM) the database to reclaim space. |
# Create a backup now
curl -k -X POST -H "Authorization: Bearer <token>" \
https://athena.example.com:8443/api/settings/database/backup
# Read database + backup status
curl -k -H "Authorization: Bearer <token>" \
https://athena.example.com:8443/api/settings/databaseA successful backup returns the path of the file that was written; a failed backup or optimize returns an error response so a script can react. Both actions are recorded in the audit trail (see Auditing).
PowerShell#
The Athena PowerShell module wraps the two maintenance actions
as dedicated cmdlets, and the database details are returned by
Get-AthenaSettings. Both action cmdlets support -WhatIf/
-Confirm, so you can preview or gate them in a script. Sign in with
Connect-Athena as an Admin first.
| Cmdlet | What it does |
|---|---|
Backup-AthenaDatabase | Creates a backup now and returns the backup path, creation time, and creator. |
Optimize-AthenaDatabase | Runs the optimize (VACUUM) pass to reclaim disk space. |
# Connect as an Admin
Connect-Athena -Server "athena.contoso.com"
# Back up now, then optimize
Backup-AthenaDatabase
Optimize-AthenaDatabase
# Preview without running
Backup-AthenaDatabase -WhatIf
# A simple scheduled-backup script (pair with your own retention)
$result = Backup-AthenaDatabase
Write-Output "Backup written to $($result.BackupPath)"To automate a recurring backup from PowerShell instead of the console, create a Database Backup scheduled job with the scheduler cmdlets — see Scheduled Jobs.
Auditing#
Every manual backup and optimize is written to the audit trail with the acting user and their IP address — a backup is recorded as a Database / Backup event and an optimize as a Database / Optimize event, both at Information severity. Scheduled backups run under the server's scheduler and appear in the scheduled-job history. This gives you a complete record of who protected the data and when.
Related#
- Scheduled Jobs — schedule recurring backups and other server-maintenance tasks such as log and cleanup jobs.
- Server Health & Monitoring — watch the database and disk components so the data volume never fills up.
- Configuration — the database provider and connection string, set at startup.
- Using PostgreSQL for the Database — run Athena on PostgreSQL instead of the default embedded SQLite database.
- Installation — the persistent data and backup volumes.