User Guide: Database Backups - EyevinnOSC/community GitHub Wiki

Database Backups

The Databases & Gitea tab in My Apps lets you manage automatic and on-demand backups for database instances and Gitea instances you run on OSC. Supported databases include PostgreSQL, MariaDB, Valkey, ClickHouse, and CouchDB. Gitea instances are also supported.

MinIO is not supported. MinIO is object storage, not a structured database, and requires a different backup strategy. It does not appear in the backup UI. MinIO backup support is on the OSC roadmap.

Backups are stored in OSC-managed object storage (MinIO). Automatic backups run on a schedule; you can also trigger a backup immediately at any time.

Prerequisites

  • An Eyevinn Open Source Cloud account on a paid plan. Automatic and on-demand backups are not available on the Free plan.
  • At least one database or Gitea service instance running in your OSC account.

Using the Databases & Gitea Tab

View your databases and Gitea instances

  1. Go to My Apps
  2. Click the Databases & Gitea tab
  3. All your database and Gitea instances are listed with their type and creation date

Enable automatic backups

  1. Find the database instance you want to back up
  2. Toggle the Auto Backup switch to on
  3. OSC schedules backups according to the configured policy (default: daily at 02:00 UTC)

To disable automatic backups, toggle the switch back to off.

Note: The Auto Backup toggle is disabled on the Free plan. The text "Paid plan required" appears next to the toggle. Upgrade your plan to enable it.

Configure backup schedule and retention

Once automatic backups are enabled, you can control when backups run and how long they are kept.

  1. Find the database instance in the Databases tab
  2. Click the gear icon next to the Auto Backup toggle
  3. The Backup Schedule & Retention modal opens, pre-filled with the current policy
  4. Choose a schedule preset or enter a custom cron expression:
    • Daily at 02:00 UTC (default)
    • Weekly on Sunday at 02:00 UTC
    • Monthly on the 1st at 02:00 UTC
    • Custom cron expression — enter any standard 5-field cron expression (e.g. 0 3 * * 1-5 for weekdays at 03:00 UTC). All times are in UTC.
  5. Optionally set a Retention (days) value. Backups older than this number of days are deleted automatically. Leave blank to keep backups indefinitely.
  6. Click Save

Note: The gear icon is only visible on paid plans. Custom schedule and retention require the Auto Backup toggle to be enabled.

Last Backup Time

The Databases tab shows a Last Backup column with the relative time of the most recent successful backup for each instance (e.g., "2 hours ago"). If no backup has been taken yet, the column shows "—".

When a scheduled backup run fails, the column shows a red "Last attempt failed" chip instead of the last backup time. Hover over the chip to see the error message (truncated to 200 characters). The time of the failed attempt is shown below the chip. This lets you identify broken backup schedules at a glance without opening the backup history.

To investigate a failure in more detail:

  1. Click the gear icon next to the Auto Backup toggle to open the Backup Schedule & Retention modal
  2. If the most recent scheduled run failed, a red error banner appears at the top of the modal with the full error message
  3. Use the error text to diagnose the cause — for example, a Gitea backup may fail because the Gitea instance is unreachable, or a PostgreSQL backup may fail due to a changed password

Trigger a manual backup

  1. Find the database instance in the Databases tab
  2. Click Backup Now
  3. A confirmation message appears briefly once the backup is triggered

The backup runs asynchronously. The "Backup Now" button shows a loading state while the request is in progress.

View backup history

  1. Find the database instance in the Databases tab
  2. Click View History
  3. A panel expands below the database row showing all backups for that instance
  4. Each backup record shows the date and time it was taken and its status (Complete, Running, or Failed)
  5. Click Close to collapse the panel

Restore from the web console

You can restore a database or Gitea instance from any completed backup directly in the Databases & Gitea tab.

  1. Open the backup history panel for the instance you want to restore (click View History)
  2. Find the backup you want to restore from
  3. Click Restore next to that backup record
  4. A confirmation prompt appears: "Restore will create a new database or Gitea instance. Continue?"
  5. Click Yes, Restore to proceed, or Cancel to go back
  6. A restore job starts asynchronously. A status message appears next to the backup record when the job is submitted

Note: Restore creates a new database or Gitea instance rather than overwriting the existing one. The original instance and its data remain intact. You will need to update your application's connection string to point to the new instance once it is ready.

Using MCP (AI Agent)

If you have OSC connected to an AI agent, you can manage database backups through natural language.

Trigger a backup

Back up my PostgreSQL database called mydb

The agent uses the create-backup tool and will confirm the backup name and status once triggered.

List existing backups

List backups for my CouchDB instance called nosql

The agent uses the list-backups tool and returns a table of backup records with name, source (manual or scheduled), status, and creation date.

Restore from a backup

Restore my database called mydb from the most recent backup

The agent uses the restore-backup tool. It will identify the correct backup record and trigger a restore job.

Warning: Restoring a database overwrites current data with the backup snapshot. Always verify you are restoring the right backup before confirming with the agent.

Configure scheduled backups

Scheduled backups let you automate recurring backup runs on a cron expression of your choosing, entirely through the AI chat assistant. Supported databases are PostgreSQL, MariaDB, Valkey, ClickHouse, and CouchDB.

Supported services. The schedule-backup tool works with the following OSC service IDs: birme-osc-postgresql, linuxserver-docker-mariadb, valkey-io-valkey, clickhouse-clickhouse, apache-couchdb. MinIO (minio-minio) is not supported — it requires a separate object-storage backup strategy.

Plan requirement. Scheduled backups require a paid OSC plan. Free-tier accounts receive an error when attempting to enable a schedule.

Create a schedule

Tell the agent what you want in plain language:

Schedule daily backups for my PostgreSQL instance prod-db and keep 14 days

Set up weekly backups for my MariaDB instance mydb, retaining 30 days

The agent uses the schedule-backup tool, which takes the instance name, a retention period in days, and a cron expression. If you do not specify a cron expression, the agent will ask or apply a sensible default.

Cron expressions use the standard five-field format: minute hour day-of-month month day-of-week. For example, 0 2 * * * runs at 02:00 UTC every day, and 0 3 * * 0 runs at 03:00 UTC every Sunday. All times are in UTC. Use crontab.guru to build and verify expressions.

How retention works

When a scheduled backup run completes, the platform prunes backups beyond the configured retentionDays limit. The pruning is not source-aware: it counts all backups sharing the same instance prefix, including ones you triggered manually with "Back up my database...". If you have manual backups you want to keep long-term, set retentionDays conservatively or avoid mixing manual and scheduled backups for the same instance.

List active schedules

List my backup schedules for prod-db

The agent uses the list-backup-schedules tool and returns the schedule details, including the cron expression and retention period.

Diagnose failing schedules

When a scheduled backup fails, the AI can tell you when the last attempt ran and what error occurred:

Why isn't my backup schedule for prod-db running?

Show me the last error for my PostgreSQL backup schedule

The list-backup-schedules tool returns lastAttemptAt (when the schedule last tried to run) and lastError (the error message from the most recent failed run) alongside the existing fields. This helps you diagnose silent failures — for example, a Gitea backup that is failing because the Gitea instance is unreachable, or a PostgreSQL backup failing due to a changed password.

Credential status and automatic renewal

Scheduled backups authenticate using a Personal Access Token (PAT) stored securely by the platform. The list-backup-schedules tool also returns two fields that reflect the health of this credential:

Field Values Meaning
credentialStatus ok The PAT is valid and not close to expiry
credentialStatus renewed The PAT was expiring within 14 days and was automatically renewed
credentialStatus expired The PAT has expired and could not be renewed — backups will fail
credentialCheckedAt Unix timestamp When the platform last evaluated the credential

The platform automatically renews expiring PATs before scheduled backup runs. In most cases a renewed status means everything is working — the credential was silently refreshed and the backup will proceed normally. An expired status requires manual action: contact OSC support or delete and recreate the backup schedule.

You can also ask the AI agent directly:

What is the credential status for my prod-db backup schedule?

Remove a schedule

Delete the backup schedule for prod-db

The agent uses the delete-backup-schedule tool. Existing backups are not affected; only the schedule is removed. Future automated runs will no longer occur for that instance.

Restore from a scheduled backup

Restoring works the same way whether the backup was triggered manually or by a schedule. See Restore from a backup above.

Related Resources