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
PutObjectpermission. - 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.