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:
- S3 credentials secret in the namespace
- CNPG Cluster CRD with
barmanObjectStoreconfig ScheduledBackupCRD 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).