Service: Database Backuper - EyevinnOSC/community GitHub Wiki

Database Backuper

Database Backuper (serviceId eyevinn-db-backuper) creates and restores backups of database instances. In Eyevinn Open Source Cloud (OSC) it is a job: each run performs a single operation, backup or restore, and then exits. Backups are stored in, and restored from, an S3-compatible object store such as MinIO. License: MIT.

What it can do

  • Back up PostgreSQL, MariaDB/MySQL, Valkey/Redis, ClickHouse and CouchDB databases to S3-compatible storage.
  • Restore a database from a backup stored in S3.
  • Encrypt backups with AES-256-CBC before upload and decrypt them on restore (not for ClickHouse, which uses its native S3 backup engine).

Supported databases

Database OSC service ID URL scheme
PostgreSQL birme-osc-postgresql postgres:// (also postgresql://)
MariaDB / MySQL linuxserver-docker-mariadb mariadb:// (also mysql://)
Valkey / Redis valkey-io-valkey valkey:// (also redis://)
ClickHouse clickhouse-clickhouse clickhouse://
CouchDB apache-couchdb couchdb://

MinIO is not supported as a backup source: it is object storage, not a structured database, and does not use a connection-string dump model. It is used as the backup destination. The schedule-backup MCP tool only lists instances whose service ID is in the supported set above and returns an error for a MinIO instance.

Creating an instance

Prerequisites: a running database instance (for example PostgreSQL or MariaDB) and an S3-compatible bucket (for example a MinIO instance). Confirm both are running first.

Store the full database connection URL and the S3 secret key with create-service-secret (serviceId eyevinn-db-backuper), for example dburl and miniocreds, then create the job with create-service-instance using serviceId: "eyevinn-db-backuper". The name must be alphanumeric and at most 20 characters.

{
  "name": "pgbackup",
  "Operation": "backup",
  "DatabaseUrl": "{{secrets.dburl}}",
  "S3Endpoint": "https://<minio-instance-url>",
  "S3Bucket": "backups",
  "S3ObjectKey": "mydb/2026-04-25.dump",
  "S3AccessKey": "<minio-access-key>",
  "S3SecretKey": "{{secrets.miniocreds}}"
}

The job runs, uploads the dump to the bucket and exits. Check it with get-instance-status and get-logs-for-instance. To restore, create a new job with "Operation": "restore" and the same S3ObjectKey. OSC CLI form: osc create eyevinn-db-backuper pgbackup20260425 -o Operation="backup" -o DatabaseUrl="{{secrets.dburl}}" -o S3Endpoint=... -o S3Bucket=backups -o S3ObjectKey=mydb/2026-04-25.dump -o S3AccessKey=... -o S3SecretKey="{{secrets.miniocreds}}".

Options

Option Required Type Meaning
name Yes string Name of this job run. Letters, digits and underscore only, at most 20 characters.
Operation Yes string backup to create a backup or restore to restore from one. Only these two values are accepted; the job performs one operation and exits.
DatabaseUrl Yes string, sensitive Connection URL of the database to back up or restore. The scheme selects the database type and tools. Format scheme://[user:password@]host[:port][/database], for example postgres://admin:[email protected]:5432/myapp.
S3Endpoint No string Endpoint URL of the S3-compatible storage, for example a MinIO instance URL.
S3Bucket No string Bucket where the backup is stored or read from, for example backups.
S3ObjectKey No string Object key (path within the bucket) of the backup file, for example mydb/2026-03-12.dump.
S3AccessKey No string, sensitive Access key for the S3 storage.
S3SecretKey No string, sensitive Secret key for the S3 storage.
EncryptionKey No string, sensitive AES-256-CBC key. When set, backups are encrypted before upload and decrypted on restore. Not supported for ClickHouse.

Database URL formats:

Database URL format
PostgreSQL postgres://user:password@host:5432/dbname
MariaDB / MySQL mariadb://user:password@host:3306/dbname
Valkey / Redis valkey://password@host:6379
ClickHouse clickhouse://user:password@host:9000/dbname
CouchDB couchdb://admin:password@host:5984

DatabaseUrl, S3AccessKey, S3SecretKey and EncryptionKey are sensitive: store them as service secrets and reference them as {{secrets.NAME}}, which only works as the entire field value.

Troubleshooting failed backups

When a job fails, the platform surfaces the Kubernetes failure condition message in the backup record's error field (truncated to 1000 characters, with embedded credentials redacted). Common causes:

  • Database connection refused: the URL is wrong or the instance is stopped.
  • S3 credentials rejected: mismatched access key or secret key.
  • Bucket not found, or the access key lacks PutObject permission.
  • Out of disk space: the ephemeral job volume ran out of space during the dump.

Scheduling

Database Backuper is a one-shot job. To run backups on a schedule, create a My Agent Task whose prompt launches a new Database Backuper instance at the desired interval. A higher-level backup workflow that wraps Database Backuper is described in the Database Backups user guide.

Resources