Skip to main content
Version: Weekly Build

Managed Service Backups

Codesphere allows you to enable automated backups for your managed services to prevent data loss. Currently, configuring and managing backups is only available through the public API. In the future, this functionality will also be accessible via the Codesphere UI.

Supported services include PostgreSQL and Object Store, and backing up to an arbitrary S3-compatible Backup Store.

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.

Enabling Backups​

You can enable backups when creating a new managed service or by updating an existing one.

To enable backups, provide the backups block in the request body with enabled: true, your intervalH, deleteRetentionDays, and your storage config and secrets.

info

The values you provide for config and secrets (both in the backups block and the recoverFrom block below) are specific to the managed service provider. Codesphere validates these 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.

During Creation​

Use the POST /managed-services endpoint:

curl -X POST "https://api.codesphere.com/managed-services" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": 123,
    "name": "my-postgres-with-backups",
    "provider": {
      "name": "postgresql",
      "version": "15"
    },
    "plan": {
      "id": 1,
      "parameters": { "storage": 10 }
    },
    "config": {
      "max_connections": "100"
    },
    "secrets": {
      "password": "secure-password"
    },
    "backups": {
      "enabled": true,
      "intervalH": 24,
      "deleteRetentionDays": 7,
      "config": {
        "endpointUrl": "https://s3.eu-central-1.amazonaws.com",
        "destinationPath": "s3://my-codesphere-backups/"
      },
      "secrets": {
        "accessKey": "YOUR_S3_ACCESS_KEY",
        "secretKey": "YOUR_S3_SECRET_KEY"
      }
    }
  }'

On an Existing Service​

Use the PATCH /managed-services/{id} endpoint to update the backups configuration:

curl -X PATCH "https://api.codesphere.com/managed-services/YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "backups": {
      "enabled": true,
      "intervalH": 12,
      "deleteRetentionDays": 30,
      "config": {
        "endpointUrl": "https://s3.eu-central-1.amazonaws.com",
        "destinationPath": "s3://my-codesphere-backups/"
      },
      "secrets": {
        "accessKey": "YOUR_S3_ACCESS_KEY",
        "secretKey": "YOUR_S3_SECRET_KEY"
      }
    }
  }'

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.

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

info

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

Point-in-Time Recovery:

curl -X POST "https://api.codesphere.com/managed-services" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": 123,
    "name": "my-postgres-recovered",
    "provider": {
      "name": "postgresql",
      "version": "15"
    },
    "plan": {
      "id": 1,
      "parameters": { "storage": 10 }
    },
    "config": {
      "max_connections": "100"
    },
    "secrets": {
      "password": "secure-password"
    },
    "recoverFrom": {
      "msId": "OLD_MANAGED_SERVICE_ID",
      "time": "2026-04-10T12:00:00Z",
      "config": {
        "endpointUrl": "https://s3.eu-central-1.amazonaws.com",
        "destinationPath": "s3://my-codesphere-backups/"
      },
      "secrets": {
        "accessKey": "YOUR_S3_ACCESS_KEY",
        "secretKey": "YOUR_S3_SECRET_KEY"
      }
    }
  }'

Recover from Specific Backup:

Alternatively, use id without msId or time:

"recoverFrom": {
  "id": "BACKUP_UUID_HERE",
  "config": { ... },
  "secrets": { ... }
}

Triggering a Manual Backup​

You can immediately schedule an on-demand backup for a service that supports it:

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

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

PostgreSQL Specific Disclaimers​

The following limitations and requirements apply specifically to retrieving and recovering PostgreSQL databases:

  • Transaction Required: To recover a Postgres database, there needs to be at least one database transaction that occurred.
  • Prior Backup Required: There must be at least one completed backup before your desired target recovery time.
  • WAL-File Timing: The target recovery time must be before the latest transaction in the latest Write-Ahead Log (WAL) file. Note that it can take a few minutes for the latest WAL-file to be saved to the backup storage bucket.
  • Version Compatibility: Recovering a backup using a different database version than the original backup is not guaranteed to work.
  • Credentials Must Match: When recovering, you cannot change the database users, database name, and passwords to something other than what was originally stored in the backup.