Skip to content
excalibase
backup-restore
Provisioningbeta

Backup & Restore

Self-hosting. This page is for operating your own Excalibase install. On Excalibase Cloud the platform runs the provisioner for you: create, back up and restore projects in Studio. The routes below belong to your install's control plane, not to api.excalibase.io.

PostgreSQL backups use CloudNativePG's native barmanObjectStore integration — continuous WAL archiving + scheduled base backups to S3.

How It Works

PostgreSQL Pod
  → WAL archiving (every 5 min) → S3 bucket
  → Scheduled base backup (cron) → S3 bucket
  • WAL archiving enables point-in-time recovery to any second
  • Base backups provide full snapshots for faster restore
  • Storage: LocalStack (POC) or AWS S3 (production)

Enable Backups at Provision Time

Include backup configuration in the provisioning request:

curl -X POST http://localhost:24005/api/provision \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "my-db",
    "orgId": "myorg",
    "databaseType": "POSTGRESQL",
    "tier": "STANDARD",
    "backup": {
      "enabled": true,
      "schedule": "0 2 * * *",
      "retention": 30
    }
  }'

This creates:

  1. S3 credentials secret in the namespace
  2. CNPG Cluster CRD with barmanObjectStore config
  3. ScheduledBackup CRD with the cron schedule

Manual Backup

curl -X POST http://localhost:24005/api/provision/my-db/backup/trigger
{
  "id": "my-db-backup-20260326-142040",
  "projectId": "my-db",
  "type": "MANUAL",
  "status": "IN_PROGRESS"
}

Status automatically updates to COMPLETED or FAILED by checking the K8s Backup CRD status.

List Backups

curl http://localhost:24005/api/provision/my-db/backup/list
{
  "backups": [
    {
      "id": "my-db-backup-20260326-142040",
      "status": "COMPLETED",
      "type": "MANUAL",
      "timestamp": "2026-03-26T14:20:40Z"
    }
  ],
  "backupEnabled": true,
  "schedule": "0 2 * * *",
  "retentionDays": 30
}

Restore into a New Project

A restore into a new project never touches the source. Give the copy a name; the platform picks its project id and answers with a restore job to poll:

curl -X POST http://localhost:24005/api/provision/my-db/backup/restore \
  -H "Content-Type: application/json" \
  -d '{
    "newProjectName": "my-db-restored"
  }'
{
  "id": "restore-3f2a9c1d7b6e4a10",
  "sourceProjectId": "my-db",
  "newProjectId": "proj-a3k9fx7b2k",
  "mode": "new_project",
  "status": "RUNNING",
  "targetKind": "latest"
}

Poll GET /api/provision/my-db/backup/restore/{jobId} until status is COMPLETED or FAILED; a failed job carries failureReason. The new project uses its own CNPG Cluster with bootstrap.recovery reading the source's backups, and new database credentials.

The restore takes one of the organisation's project slots when it is submitted. A plan with no free slot is refused with 409 and "code": "project_limit_reached"; pass "mode": "in_place" and "confirmReplace": true to replace the source's own data instead.

What the copy carries

  • With the database: tables, data, database functions, realtime tables, and end users. Sessions, API keys and email links the source issued are revoked.
  • From the source's settings: table permissions (columns and row filters), tracked functions and who may call them, the CORS origins a person added, and auth settings (email verification, site URL). They are copied as the source has them at restore time.
  • The migration history (list_migrations), as the source has it at restore time. A restore to an earlier point still lists migrations applied after that point.
  • Not carried: apps, sites and domains, CORS origins an app added, edge functions with their secrets and outbound hosts, stored files, and project members. Deploy them to the copy if you need them.

Point-in-Time Recovery (PITR)

Restore to an exact timestamp:

curl -X POST http://localhost:24005/api/provision/my-db/backup/restore \
  -H "Content-Type: application/json" \
  -d '{
    "newProjectName": "my-db-pitr",
    "targetTime": "2026-03-26T12:00:00Z"
  }'

PITR replays WAL segments and stops at the exact targetTime. The new project will contain all data up to that second — no more, no less.

S3 Storage Setup

LocalStack (local development)

kubectl create namespace localstack
# Deploy LocalStack (see Quick Start)

# Create bucket
kubectl exec -n localstack deployment/localstack -- \
  sh -c "AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test \
  aws --endpoint-url=http://localhost:4566 s3 mb s3://postgres-backups"

AWS S3 (production)

Replace the S3 credentials secret with real AWS credentials:

kubectl create secret generic backup-s3-creds \
  -n {namespace} \
  --from-literal=ACCESS_KEY_ID={your-key} \
  --from-literal=ACCESS_SECRET_KEY={your-secret}

Update the CNPG Cluster CRD endpointURL to point to your AWS region endpoint (or remove it to use the default).