Managed Service Backups

Codesphere allows you to enable automated backups for your managed services to prevent data loss. This page covers the general backup concepts that apply to all managed services. Provider-specific configuration examples and limitations are documented on the respective provider pages.

Key Concepts

• Backup Store: The external storage location where your backups are saved. This can be an external S3-compatible service (like AWS S3) or a Codesphere S3 Managed Service.
• Retention Period: The number of days a backup is kept before it is automatically deleted by Codesphere (deleteRetentionDays).
• Interval: How often a new backup is created, measured in hours (intervalH). Codesphere handles the scheduling automatically.
• Recovery: Creating a new managed service in the exact state of a previous backup or point in time.

Checking Provider Capabilities

Not all managed services support backups or point-in-time recovery. To see if a provider supports it, you can check the /managed-services/providers API endpoint. The capabilities object will list two specific features:

• backups: The provider supports taking automated backups and recovering a service to the exact state at the moment a specific backup was taken.
• pointInTimeRecovery: In addition to standard backups, the provider supports recovering a service to an arbitrary point in time (e.g., a specific minute) between two backups.

If pointInTimeRecovery is true, the backups capability will also be true.

You can also check the capabilities in the UI: the provider details page, which opens when you click Start setup on a provider card in the catalog, lists them as well.

Backups are currently supported for PostgreSQL, Babelfish, DocumentDB, and Object Storage, and can be saved to any S3-compatible backup store.

Enabling Backups

You can enable backups when creating a new managed service or by updating an existing one, either in the UI or via the API.

Via the UI

Services that support backups have a dedicated Backups tab in the service details sheet. The same settings are also available during service creation.

1. Open the service details by clicking on a managed service in your resource group
2. Navigate to the Backups tab
3. Toggle Automatic Backups to enable backups
4. Configure the following settings:
   • Backup Frequency: How often backups are created (in hours)
   • Retention Period: How many days backups are kept before automatic deletion
   • Storage Destination: Your S3-compatible backup store endpoint, credentials, and path
5. Click Save to apply your changes

Via the API

Provide the backups block in the request body with enabled: true, your intervalH, deleteRetentionDays, and your storage config and secrets. This works both when creating a new service (POST) and when updating an existing one (PATCH).

info

The values you provide for config and secrets (both in the backups block and the recoverFrom block below) can vary between providers. Codesphere validates them against the backups.configSchema and backups.secretsSchema defined by the provider. You can inspect these schemas in the response of the /managed-services/providers API endpoint, and find concrete examples in the provider documentation. When you restore from a backup ID, config and secrets in recoverFrom are optional. See Restore using only the backup ID.

Via ci.yml

If you define your managed services in a ci.yml file, you can specify backup configuration directly there. Add a backups block to the managed service entry:

managedServices:
  my-postgres:
    provider:
      name: postgres
      schemaVersion: v1
    plan:
      id: 1
      parameters: {}
    config: {}
    secrets: {}
    backups:
      enabled: true
      deleteRetentionDays: 7
      intervalH: 24
      config:
        bucket: ${{ env.BACKUP_BUCKET }}
      secrets:
        accessKey: ${{ vault.backup_access_key }}

Setting enabled: false disables backups and requires no other fields. See Disabling and Re-enabling Backups for what this means for your service. When enabled: true, the following fields are required:

Field	Description
deleteRetentionDays	Days to keep each backup before automatic deletion. Must be between 1 and 365.
intervalH	Backup frequency in hours. Must be between 1 and 744.
config	Provider-specific storage configuration. Supports environment variable references.
secrets	Provider-specific storage credentials. Supports vault references.

The config and secrets values must match the backups.configSchema and backups.secretsSchema defined by the provider. See the provider documentation for concrete examples.

Viewing Backup History

Via the UI

The Restore section in the Backups tab displays a list of all completed backups with:

• Backup ID: Unique identifier for the backup
• Start Time: When the backup was initiated
• Finish Time: When the backup completed successfully
• Restore: A button to restore the service from this backup. See Restoring from a Backup.

Via the API

List your managed services and check the backups.entries array of the service you are interested in:

curl "https://api.codesphere.com/managed-services?resourceGroup=YOUR_RESOURCE_GROUP_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "id": "8316ee2f-87f8-424e-b925-7382dc50d662",
  "name": "my-postgres",
  "backups": {
    "enabled": true,
    "intervalH": 12,
    "deleteRetentionDays": 30,
    "entries": [
      {
        "id": "0d95627e-2adf-4f04-9b3d-08d258f978c6",
        "scheduledAt": "2026-07-12T19:38:49.410Z",
        "initiatedAt": "2026-07-12T19:38:49.410Z",
        "confirmedAt": "2026-07-12T19:38:49.410Z"
      }
    ]
  }
}

Each backup entry contains the backup id (which you can pass as the backup ID in recoverFrom when restoring), when it was scheduled and initiated, and confirmedAt — the time the backup was confirmed in the backup store.

Restoring from a Backup (Recovery)

Restoring a backup in Codesphere always creates a new managed service, rather than replacing the data in-place. The existing managed service remains untouched and completely independent.

Via the UI

Open the managed service, go to the Backups tab, and click Restore next to a finished backup. This opens the Create Service From Backup dialog, prefilled with the settings of the source service.

The UI restores from a specific backup ID only. Point-in-time recovery is available through the API. The requirements listed in Restore using only the backup ID also apply to restores started from the UI.

Via the API

To restore a backup, you create a new managed service and use the recoverFrom property to either specify a specific backup ID or — if the provider supports point-in-time recovery — a previous managed service ID with a recovery timestamp.

info

When recovering, the backups block is not strictly required. It only controls if the recovered service is taking backups of itself.

Restore using only the backup ID

When you restore from a specific backup ID, you can omit config and secrets from the recoverFrom block and pass only the backup id:

"recoverFrom": {
  "id": "BACKUP_UUID_HERE"
}

Codesphere then looks up the managed service the backup was taken from and reuses its current backup store config and secrets. This only works if:

• You have permission to manage the managed service the backup was taken from.
• The new service uses the same provider and provider schema version as the service the backup was taken from.
• The backup has been confirmed.
• The source service still has a backup store configured.

For concrete recovery examples, see the provider documentation.

Triggering a Manual Backup

You can schedule an immediate on-demand backup for a service that has automatic backups enabled. Manual backups are created outside the regular schedule and do not affect your configured backup frequency.

Via the UI

In the Backups tab of your service details, click the Backup Now button. The button is disabled until automatic backups have been enabled and saved.

Via the API

Use the POST endpoint to schedule a backup:

curl -X POST "https://api.codesphere.com/managed-services/YOUR_SERVICE_ID/backups" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

info

As with enabling backups, the provider-specific config and secrets for your backup store must be provided in the request body. They are validated against the provider's backups.configSchema and backups.secretsSchema — check the provider documentation for concrete examples.

Disabling and Re-enabling Backups

You can turn automatic backups off at any time. Switch off Automatic Backups in the Backups tab, send backups: { "enabled": false } in a PATCH request, or set enabled: false in your ci.yml. No other backups fields are needed.

What Happens When You Disable Backups

• No new backups are created. This includes scheduled backups that have not initiated yet and manual backups.
• Your service stops using the backup store. A full or unreachable backup store can no longer affect it. It can take a short while until this applies.
• Existing backups are kept. They are not deleted automatically while backups are disabled. You can remove them from your backup store yourself.
• Your backup settings are kept. The backup store, frequency and retention period stay saved.

What Happens When You Re-enable Backups

Switch Automatic Backups back on and save, or send backups: { "enabled": true }. Your saved backup settings are used again. You only need to provide the other backups fields if you want to change them.

• Backups continue on your configured schedule.
• Backups that were scheduled but had not started when you disabled backups may be skipped.
• If your provider supports point-in-time recovery, you cannot recover to a point in time within the period when backups were disabled. Restoring from a backup taken before is not affected.

Disclaimers and Limitations

When using managed service backups, please keep the following in mind:

• User Responsibility for S3 Storage: Encryption and redundancy of backups are the responsibility of the user. You must ensure that the S3 storage you configure satisfies your organization's security and redundancy requirements.
• Bucket Capacity: It is your responsibility to make sure the backup store has enough free space. If the target bucket runs out of space or hits a quota, backups will fail.
• Backup Timing: There is no guarantee on the exact time that a scheduled backup will occur. The actual backup creation could be delayed by a couple of minutes depending on system load and network conditions.