Getting Started

Database Backuper is a job service in Open Source Cloud that creates and restores backups for database instances. 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.

Supported databases: PostgreSQL, MariaDB/MySQL, Valkey/Redis, ClickHouse, CouchDB.

Prerequisites

  • An OSC account. Sign up here.
  • A running database instance (e.g. a PostgreSQL or MariaDB instance on OSC).
  • An S3-compatible storage bucket (e.g. a MinIO instance on OSC) where backups will be kept.

Create a backup

Navigate to Database Backuper → Create db-backuper and fill in:

Field Required Description
name Yes A unique name for this job run.
Operation Yes backup to create a backup, or restore to restore from an existing backup.
DatabaseUrl Yes Connection URL for your database. The URL scheme selects the database type — see formats below.
S3Endpoint No S3-compatible endpoint URL (e.g. your MinIO instance URL).
S3Bucket No Name of the S3 bucket where the backup is stored.
S3ObjectKey No Path within the bucket (e.g. mydb/2026-04-25.dump).
S3AccessKey No S3 access key. Use a service secret reference.
S3SecretKey No S3 secret key. Use a service secret reference.
EncryptionKey No Optional AES-256-CBC key to encrypt backups at rest. Not supported for ClickHouse backups.

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

Store the full connection URL as a service secret and reference it as {{secrets.dburl}} to avoid exposing credentials.

Example: Backing up a PostgreSQL instance on OSC

  1. Create a MinIO instance to store the backup.
  2. Note the MinIO internal URL, access key (RootUser), and secret key (RootPassword).
  3. Create a service secret called dburl containing your PostgreSQL connection URL, and a secret miniocreds with your MinIO secret key.
  4. Create a Database Backuper job:
osc create eyevinn-db-backuper pgbackup20260425 \
  -o Operation="backup" \
  -o DatabaseUrl="{{secrets.dburl}}" \
  -o S3Endpoint="https://myminio.minio-minio.auto.prod.osaas.io" \
  -o S3Bucket="backups" \
  -o S3ObjectKey="mydb/2026-04-25.dump" \
  -o S3AccessKey="myrootuser" \
  -o S3SecretKey="{{secrets.miniocreds}}"

The job runs, uploads the dump to MinIO, and exits. Check the instance status in the dashboard to confirm it completed successfully.

Example: Restoring a backup

Run a new Database Backuper job with Operation=restore pointing to the same S3 object key:

osc create eyevinn-db-backuper pgrestore20260425 \
  -o Operation="restore" \
  -o DatabaseUrl="{{secrets.dburl}}" \
  -o S3Endpoint="https://myminio.minio-minio.auto.prod.osaas.io" \
  -o S3Bucket="backups" \
  -o S3ObjectKey="mydb/2026-04-25.dump" \
  -o S3AccessKey="myrootuser" \
  -o S3SecretKey="{{secrets.miniocreds}}"

Troubleshooting failed backups

When a Database Backuper job fails, the platform now surfaces the Kubernetes failure condition message directly in the backup record. You can retrieve this via the backup list API or the My Backups dashboard.

The error field in the backup record contains the raw failure message from the K8s job (truncated to 1000 characters). Common causes include:

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

The error message is redacted to remove any embedded credentials before being stored.

Backup scheduling via My Agent Tasks

Database Backuper is a one-shot job, not a long-running service. To run backups on a schedule, create a My Agent Task with a prompt that calls the OSC CLI or MCP tool to launch a new Database Backuper instance at the desired interval.

Using the OSC Database Backups UI

For databases managed through OSC, a higher-level backup UI is available at My Backups that wraps Database Backuper automatically. See Database Backups for details.

Resources