Documentation
Backup and restore
Updated 17 Nov 2026
Backups are logical dumps of PostgreSQL, kept under the data directory, seven copies. ClickHouse click history is not in the file. Restore replaces rows in one transaction after you send the confirmation word, and it does not include master.key.
What is in the file
The backup covers the PostgreSQL tables the tracker uses for configuration, users, the conversion ledger, tokens, and the audit log. schema_migrations, license_runtime, and outbox are not replaced on restore. ClickHouse is not in the logical backup. The project treats it as a rebuildable copy of the click log. After a disaster, configuration and booked conversions come back from PostgreSQL. Click detail depends on whatever ClickHouse still has, plus what you can reconcile with the ad platforms.
The file contains password hashes, license keys, and integration credentials in their encrypted form. It does not contain master.key. That file lives in the data directory (/var/lib/velotrak/master.key on an install from the script). Without it, stored credentials cannot be decrypted. Back up the data directory, or at least master.key, next to the logical backup. The backup directory is VELOTRAK_DATA_DIR/backups/, mode 0700, files mode 0600.
Create one
The process takes a backup about a minute after start, then checks hourly, and writes one when the newest file is at least 24 hours old. It keeps the 7 newest. The admin backup page and MCP can create one immediately: list_backups and create_backup. create_backup is an admin action. API keys cannot call the backup routes; a write-scoped API key is only an operator. Use an MCP token that has the backups scope.
Restore
POST /api/backups/restore requires "confirm": "RESTORE". The server writes a pre-restore snapshot first, then reloads rows in one transaction and checks the row counts against the manifest. MCP restore_backup is explicit-only: a wildcard write scope does not grant it, and it uses the same diff confirmation as other destructive tools. Restoring an older file brings back that file’s session generation. The operator notes suggest signing in again or changing the password after a restore from before an upgrade that rotated sessions.
The install page lists the directories to copy if you move the server.