Data Retention & Database

DBackup keeps its configuration, users and history in its own SQLite database. This page covers how long that history is kept, how to give the space of removed records back to the disk, and how to download a copy of the database.

Backup files are not affected

Everything on this page is about DBackup's own records. Backup files on your destinations follow the retention policy of each job.

Data Retention

Go to Settings → Data retention. Each kind of record shows how many there are now. A change waits in the bar at the foot of the part until Save changes. Cleanup runs with the Clean old data system task, daily at midnight and when DBackup starts. Run it by hand under Settings → System tasks to apply a change right away.

Setting	What is removed	Default	Options
Run logs	The step log of finished backup, restore and system task runs. The run stays in History with its status, size and timestamps.	1 year	7 days to 2 years, Never
Run history	Finished runs, including their entry in History.	Never	30 days to 5 years, Never
Audit log	Records of user actions such as sign-ins and configuration changes.	90 days	30 days to 5 years
Notification history	Notifications sent by DBackup, including their rendered content.	90 days	7 days to 5 years
Storage history	Hourly size measurements behind the storage charts and usage alerts.	90 days	7 days to 5 years
Health check history	Connection checks against sources and destinations, recorded every minute.	2 days	1 to 30 days
Deleted items	Keys, saved logins, connections, jobs and users in Recently deleted, which cannot be restored afterwards.	30 days	1 to 90 days

The step log is by far the largest part of a run. Keeping the History entries while removing old logs frees most of the space without losing statistics.

What the Run history cleanup always keeps

• Runs that are still queued or running.
• The newest 10 runs of every job, however old they are. Runs without a job, such as restores and integrity checks, keep their newest 10 per type.
• Every run of the incremental chain a job is currently extending, since the next incremental backup builds on it.

Effects on the rest of DBackup

• The dashboard statistics and the backup calendar only count runs that are still in History. The calendar shows up to a year, as many weeks as the screen fits, so with a shorter Run history its oldest weeks stay empty.
• A run whose log was removed says so on its page in History, and Copy and Download are disabled.
• The error field of GET /api/executions/{id} is read from the log, so it is empty for a failed run whose log was removed.
• Notification History entries that belonged to a deleted run stay until their own retention period removes them.

Database

Go to Settings → Database.

Figure	Meaning
Size	The database file plus its WAL file.
Reclaimable	About how much space Optimize gives back.
Free disk space	Free space on the volume that holds the database.
Journal	WAL or DELETE, see SQLITE_WAL_MODE in the environment reference.

The path of the database file is shown below the figures.

Optimize

SQLite never shrinks its file on its own. Space from removed records is reused for new data, but the file stays as large as it ever was. Optimize asks first, then runs VACUUM to rebuild the file without that space and truncates the WAL file.

• Needs the settings:write permission and is recorded in the audit log.
• Is refused while a backup, restore or integrity check is running. Jobs that become due while it runs wait in the queue and start once it has finished.
• Needs free space on the database volume for the data in use.
• DBackup may not respond for a moment while it runs on a large database.

The system task Optimize the database does the same by itself on the 1st of every month at 05:00, once at least a fifth of the file and at least 1 MB is unused. Instead of being refused, it holds back the runs that would start and waits up to an hour for the running ones. The held runs start right after. When runs keep going for the whole hour, it leaves the file as it is and its row under Settings → System tasks needs a look.

TIP

After lowering a retention period, run Clean old data first and then optimize the database. Removing records alone does not make the file smaller.

Download the database

Download hands you a copy of the whole SQLite file after it asked first. DBackup writes the copy with VACUUM INTO to its temp directory (TMPDIR), so it is consistent, compacted and a single .db file with nothing left in a WAL file.

• Only members of the SuperAdmin group see the button. API keys cannot download the database.
• Is refused while a backup, restore or integrity check is running.
• Needs free space in the temp directory for the data in use.
• The temp copy is deleted once the download finishes or is cancelled, and a few minutes later if it was never collected.
• Every download is recorded in the audit log.

Treat the file like a password

The file holds every user with their password hash, active session tokens, API key hashes and all stored credentials. Credentials stay encrypted and can only be read with this instance's ENCRYPTION_KEY, but a session token can be used as it is. Store the file safely and delete it when you no longer need it.

To move the configuration to another instance without the execution history, use the system backup instead.

Restoring a downloaded copy

1. Stop the DBackup container.
2. In the db folder of the /data volume, replace dbackup.db with the downloaded file, renamed to dbackup.db.
3. Delete dbackup.db-wal and dbackup.db-shm if they exist. They belong to the old file.
4. Start the container with the same ENCRYPTION_KEY and the same or a newer DBackup version. Pending migrations are applied on startup.