Repository navigation
User Guide: 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, which is Silo (an S3-compatible store). The credentials of the storage instance are secret-backed: they live in your workspace's secret store and the instance only references them, so they never appear as plain values in the instance configuration. Workspaces whose backups were first created on an older MinIO-based store are moved to Silo by the platform team, and existing backup objects are copied over, not deleted. Automatic backups run on a schedule; you can also trigger a backup immediately at any time.
- 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.
- Go to My Apps
- Click the Databases & Gitea tab
- All your database and Gitea instances are listed with their type and creation date
- Find the database instance you want to back up
- Toggle the Auto Backup switch to on
- 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.
Once automatic backups are enabled, you can control when backups run and how long they are kept.
- Find the database instance in the Databases tab
- Click the gear icon next to the Auto Backup toggle
- The Backup Schedule & Retention modal opens, pre-filled with the current policy
- 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-5for weekdays at 03:00 UTC). All times are in UTC.
- Optionally set a Retention (days) value. Backups older than this number of days are deleted automatically. Leave blank to keep backups indefinitely.
- Click Save
Note: The gear icon is only visible on paid plans. Custom schedule and retention require the Auto Backup toggle to be enabled.
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:
- Click the gear icon next to the Auto Backup toggle to open the Backup Schedule & Retention modal
- If the most recent scheduled run failed, a red error banner appears at the top of the modal with the full error message
- 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
- Find the database instance in the Databases tab
- Click Backup Now
- 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.
- Find the database instance in the Databases tab
- Click View History
- A panel expands below the database row showing all backups for that instance
- Each backup record shows the date and time it was taken and its status (Complete, Running, or Failed)
- Click Close to collapse the panel
You can restore a database or Gitea instance from any completed backup directly in the Databases & Gitea tab.
- Open the backup history panel for the instance you want to restore (click View History)
- Find the backup you want to restore from
- Click Restore next to that backup record
- A confirmation prompt appears: "Restoring will overwrite all current data in "" with the backup from . Data written after that time will be lost. This cannot be undone. Continue?"
- Type the instance name in the Type the instance name to confirm field. The Yes, overwrite button stays disabled until the name matches exactly. Click it to proceed, or Cancel to go back
- A restore job starts asynchronously. A status message appears next to the backup record when the job is submitted
Warning: Restore overwrites the existing database or Gitea instance in place. Data written after the backup was taken is lost and the restore cannot be undone. Create a fresh backup of the instance first if you may need its current state.
Gitea instances: Backup, restore and backup schedules act on the Gitea instance you select. A request for an instance that does not exist, or for a non-default Gitea instance that has no valid admin credential registered, is rejected with a message explaining why instead of acting on another instance. A restore can use a backup taken from another Gitea instance in your account; the restore always overwrites the instance you chose as the target.
You can check that a backup can be restored without touching your production data. Verify restores the backup into a temporary scratch instance of the same service, reads the result of the restore job, and deletes the scratch instance.
- Open the backup history panel for the instance (click View History)
- Click Verify next to the backup record (it sits to the left of Restore)
- Wait while the progress message is shown. The result appears in the same dialog
The result is one of:
- Passed: the backup restored successfully into the scratch instance
- Failed: the restore did not succeed. The message and an optional log excerpt explain why
- Inconclusive: verification could not reach a verdict, for example because the scratch instance was not ready in time or ran out of disk space
Good to know:
- Verification requires a paid plan.
- The scratch instance is a normal billable instance for its short life and needs one free instance slot for the same service. If you are at your instance limit, verification fails with an instance limit message.
- Verification is available for PostgreSQL, MariaDB and CouchDB. For other services, such as Gitea, ClickHouse and Valkey, the dialog tells you that verification is not supported.
- Only one verification per backup runs at a time. Starting a second one attaches to the one in progress.
If you have OSC connected to an AI agent, you can manage database backups through natural language.
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 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 my database called mydb from the most recent backup
The agent uses the restore-backup tool. It will identify the correct backup record and, after you confirm, trigger a restore job that overwrites the instance in place. Before asking for confirmation the tool tells the agent to run list-backups and create-backup for the same instance and wait for the new backup to finish, so the current state can be recovered.
Warning: Restoring a database overwrites current data with the backup snapshot. Always verify you are restoring the right backup before confirming with the agent.
Verify my latest PostgreSQL backup for mydb without touching production
The agent uses the verify-backup tool, which requires your confirmation because the scratch instance is billable and needs a free instance slot. The tool returns a verificationId and a status straight away. The agent then uses get-backup-verification to read the status, reason, message, log tail and whether the scratch instance was deleted.
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.
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.
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 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.
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.
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?
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.
Restoring works the same way whether the backup was triggered manually or by a schedule. See Restore from a backup above.
- AI-Assisted App Management — Manage apps and databases using natural language
- Managing Custom Apps — Restart, rebuild, HA mode, and custom domains
- Developer Guide: Databases — Using databases in your applications