Backups

Automated backup scheduling, compression, encryption, and multi-target uploads for all your managed databases.

Overview

Voxeltron includes an automated backup system for every managed database. The pipeline runs in four stages:

1. Dump

Native database dump via pg_dump, mysqldump, redis-cli, or mongodump.

2. Compress

Gzip compression to minimize storage and transfer costs.

3. Encrypt

Optional AES-256-GCM encryption before the backup leaves the host.

4. Upload

Push to one or more configured backup targets.

Backups are scheduled per-database with cron expressions, and each job can target a different storage backend. The entire pipeline is managed by the BackupScheduler inside voxeltrond — no external tools or cron daemons required.

Backup Targets

Backups can be sent to any combination of the following targets:

Local

Store backups on the host filesystem. Fast restores, no network dependency. Best paired with a remote target for disaster recovery.

S3-Compatible

AWS S3, MinIO, Wasabi, Backblaze B2, or any S3-compatible endpoint. Configure bucket, region, access key, and secret key.

Google Cloud Storage

Upload directly to GCS buckets using a service account JSON key file. Supports all GCS storage classes.

Voxeltron Cloud

Managed backup storage via Voxeltron Cloud. Zero configuration — just link your instance and backups are stored securely in your cloud account.

Scheduling

Backup jobs are driven by cron expressions evaluated by the built-in BackupScheduler. Each database can have its own schedule, target, and retention policy. Schedules are defined in /etc/voxeltron/config.toml:

[[backup.jobs]]
database = "mydb"
schedule = "0 3 * * *"        # Daily at 03:00 UTC
target   = "s3"
compress = true
encrypt  = true

[[backup.jobs]]
database = "mycache"
schedule = "0 */6 * * *"      # Every 6 hours
target   = "local"
compress = true
encrypt  = false

The scheduler runs inside voxeltrond and triggers jobs without relying on the system cron daemon. Missed schedules (e.g. during daemon restarts) are detected and run on the next startup.

Compression & Encryption

Compression

When compress = true, the raw database dump is piped through gzip before storage. This typically reduces backup size by 70-90% for text-heavy databases. Compression is enabled by default.

Encryption

When encrypt = true, the backup is encrypted with AES-256-GCM authenticated encryption. The encryption key is configured globally or per-job:

[backup]
encryption_key = "your-256-bit-base64-encoded-key"

The encryption key is stored in the secrets store and never logged. Each backup gets a unique nonce to prevent key reuse attacks. Without the key, backup files are unrecoverable — store it securely.

Restore

Restore a backup from any configured target. Voxeltron handles decompression and decryption automatically, then pipes the dump into the appropriate database engine:

Engine	Restore Tool
PostgreSQL	`pg_restore`
MySQL	`mysql`
Redis	`redis-cli`
MongoDB	`mongorestore`

Restore from the CLI:

# Restore the latest backup
voxeltron db restore mydb --latest

# Restore a specific backup by timestamp
voxeltron db restore mydb --timestamp 2026-02-25T03:00:00Z

# Restore from a specific target
voxeltron db restore mydb --latest --target s3

Restores are performed in-place. The target database is stopped, the backup is loaded, and the database is restarted. Connected apps are notified via health check failures and will reconnect automatically.

Retention

Each backup job can define a retention_days value. Backups older than this threshold are automatically pruned from the target storage. Retention is evaluated after each successful backup.

[[backup.jobs]]
database       = "mydb"
schedule       = "0 3 * * *"
target         = "s3"
retention_days = 30            # Keep 30 days of backups

If retention_days is omitted, backups are kept indefinitely. Set a retention policy to avoid unbounded storage growth, especially on cloud targets with per-GB billing.

Configuration

Full backup configuration lives in /etc/voxeltron/config.toml. Here is a complete example with S3 and GCS targets:

[backup]
encryption_key = "base64-encoded-256-bit-key"

[backup.targets.local]
path = "/var/lib/voxeltron/backups"

[backup.targets.s3]
endpoint   = "https://s3.amazonaws.com"
bucket     = "my-voxeltron-backups"
region     = "us-east-1"
access_key = "AKIA..."
secret_key = "wJal..."

[backup.targets.gcs]
bucket           = "my-voxeltron-backups"
credentials_file = "/etc/voxeltron/gcs-service-account.json"

[[backup.jobs]]
database       = "mydb"
schedule       = "0 3 * * *"
target         = "s3"
compress       = true
encrypt        = true
retention_days = 30

[[backup.jobs]]
database       = "analytics"
schedule       = "0 0 * * 0"       # Weekly on Sunday
target         = "gcs"
compress       = true
encrypt        = true
retention_days = 90

[[backup.jobs]]
database       = "mycache"
schedule       = "0 */6 * * *"
target         = "local"
compress       = true
encrypt        = false
retention_days = 7