Skip to main content

Backup and Restore

Scheduler0 provides built-in database backup and restore capabilities using SQLite's Online Backup API. This allows you to safely backup and restore your database even while the cluster is running.

Overview​

The backup/restore feature provides:

  • Automatic timestamped backups - Create backups with automatic naming
  • Database restore - Restore from any backup file (by file name or path)
  • Leader-only operations - Ensures consistency by restricting to leader node
  • Safe concurrent access - Uses SQLite Online Backup API for safe operation

API Endpoints​

Start Automatic Backup​

Initiates a backup with an automatic timestamped filename.

POST /api/v1/cluster/backup

Response (202 Accepted):

{
  "success": true,
  "data": {
    "status": "backup initiated",
    "requestId": "<request-id>"
  }
}

Use requestId with the async-tasks endpoint to track progress.

Restore from Backup​

Initiates a restore from a backup file. The body must include the backup file name: when S3 is configured this is the S3 object key (e.g. db-20260113-143000.db); when not using S3, it is the local file path.

POST /api/v1/cluster/restore
Content-Type: application/json

{
  "filePath": "db-20260113-143000.db"
}

Response (202 Accepted):

{
  "success": true,
  "data": {
    "status": "restore initiated",
    "requestId": "<request-id>"
  }
}

Client SDKs​

Go Client​

import scheduler0 "github.com/scheduler0/scheduler0-go-client"

// Create client with basic auth (for cluster operations)
client, _ := scheduler0.NewBasicAuthClient(
    "http://localhost:7070",
    "v1",
    "username",
    "password",
)

// Start automatic backup
result, err := client.BackupDatabase()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Status: %s\n", result.Data["status"])

// Restore from backup (file name; when S3 configured this is the S3 object key)
result, err = client.RestoreDatabase("db-20260113-143000.db")

Node.js Client​

import { Client } from 'scheduler0-node-client';

// Create client with basic auth
const client = Client.newBasicAuthClient(
  'http://localhost:7070',
  'v1',
  'username',
  'password'
);

// Start automatic backup
const result = await client.backupDatabase();
console.log(`Status: ${result.data.status}`);

// Restore from backup (file name; when S3 configured this is the S3 object key)
await client.restoreDatabase('db-20260113-143000.db');

Python Client​

from scheduler0 import Client, backup

# Create client with basic auth
client = Client.NewBasicAuthClient(
    "http://localhost:7070",
    "v1",
    "username",
    "password"
)

# Start automatic backup
result = backup.backup_database(client)
print(f"Status: {result['data']['status']}")

# Restore from backup (file name; when S3 configured this is the S3 object key)
backup.restore_database(client, 'db-20260113-143000.db')

CLI​

Start Automatic Backup​

scheduler0 backup start

Restore from Backup​

Pass the backup file name (when S3 is configured, this is the S3 object key; otherwise use a local path):

scheduler0 backup restore db-20260113-143000.db

Backup Location​

By default, automatic backups are stored in:

<database-directory>/backups/<database-name>-YYYYMMDD-HHMMSS.db

For example:

/path/to/sqlite_data/backups/db-20260113-143015.db

Best Practices​

  1. Regular Backups - Schedule regular backups using cron or similar
  2. Off-site Storage - Copy backups to off-site storage for disaster recovery
  3. Test Restores - Periodically test restore operations to ensure backups are valid
  4. Leader Node - Backup/restore operations are automatically restricted to the leader node
  5. Pre-restore Backup - The system automatically creates a pre-restore backup for safety

Safety Features​

  • Pre-restore Backup - Before restoring, the current database is automatically backed up to .pre-restore-backup
  • Atomic Operations - Uses SQLite's Online Backup API for safe, atomic operations
  • Connection Locking - Prevents concurrent database modifications during backup/restore
  • Error Recovery - Failed operations are logged and partial backups are cleaned up

Troubleshooting​

Backup Fails to Start​

  • Ensure you're authenticated with proper credentials
  • Verify the node is the cluster leader
  • Check disk space availability

Restore Fails​

  • Verify the backup file exists and is readable
  • Ensure the backup file is a valid SQLite database
  • Check that no other operations are in progress

Notes​

  • Only one backup/restore operation can run at a time
  • Operations are restricted to the leader node for consistency
  • The database remains accessible during backup operations
  • Restore operations temporarily close and reopen the database connection