Backups

Create, manage, and restore database backups

The Backups API allows superusers to create, download, and restore full database backups. All backup endpoints require superuser authentication.

All backup operations require superuser authentication.

List backups

Retrieve a list of all available backup files.

GET /api/backups

Authentication: Superuser required

Response

Returns an array of backup file information.

key · string

Backup file name/key

size · number

File size in bytes

modified · string

Last modification timestamp (ISO 8601)

curl

curl http://127.0.0.1:8090/api/backups \
  -H "Authorization: Bearer SUPERUSER_TOKEN"

Create backup

Create a new backup of the entire database.

POST /api/backups

Authentication: Superuser required

Request body

name · string · required

Backup file name (must match pattern: [a-z0-9_-]+\.zip)

Response

Returns 204 No Content on success.

curl

curl -X POST http://127.0.0.1:8090/api/backups \
  -H "Authorization: Bearer SUPERUSER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my_backup_2024_01_15.zip"}'

If no name is provided, PocketBase generates one automatically based on the current timestamp.

Validation

• Name must be 1-150 characters
• Only lowercase letters, numbers, hyphens, and underscores allowed
• Must end with .zip
• Must be unique (cannot overwrite existing backup)
• Only one backup/restore operation can run at a time

Common errors

Code	Description
400	Invalid name format or backup already in progress
401	Not authenticated as superuser

Download backup

Download a backup file.

GET /api/backups/{key}

key · string · required

The backup file key/name

token · string · required

Superuser file token (see Generate file token)

Authentication: File token required (superuser only)

Response

Returns the backup file as a ZIP archive.

Step 1: Generate token

curl -X POST http://127.0.0.1:8090/api/files/token \
  -H "Authorization: Bearer SUPERUSER_TOKEN"

Backup downloads use file tokens instead of auth tokens for security. The token must belong to a superuser account.

Delete backup

Delete a backup file.

DELETE /api/backups/{key}

key · string · required

The backup file key/name to delete

Authentication: Superuser required

Response

Returns 204 No Content on success.

curl

curl -X DELETE http://127.0.0.1:8090/api/backups/my_backup.zip \
  -H "Authorization: Bearer SUPERUSER_TOKEN"

Common errors

Code	Description
400	Backup is currently in use (being created or restored)
404	Backup file not found

Restore backup

Restore the database from a backup file.

POST /api/backups/{key}/restore

key · string · required

The backup file key/name to restore

Authentication: Superuser required

Response

Returns 204 No Content on success. The server will restart after restoring.

curl

curl -X POST http://127.0.0.1:8090/api/backups/my_backup.zip/restore \
  -H "Authorization: Bearer SUPERUSER_TOKEN"

Restoring a backup will:

1. Replace the current database with the backup data
2. Restart the PocketBase application
3. Close all active connections

This operation cannot be undone. Always create a current backup before restoring.

Restore process

1. Request is validated
2. Response is sent (204 No Content)
3. After ~1 second delay, restore begins
4. Database is replaced with backup data
5. Application automatically restarts

Common errors

Code	Description
400	Another backup/restore is in progress or backup file not found
500	Restore operation failed

Upload backup

Upload an external backup file to the server.

POST /api/backups/upload

Authentication: Superuser required

Request

Use multipart/form-data to upload the backup file.

file · file · required

The backup ZIP file to upload

Response

Returns 204 No Content on success.

curl

curl -X POST http://127.0.0.1:8090/api/backups/upload \
  -H "Authorization: Bearer SUPERUSER_TOKEN" \
  -F "file=@/path/to/backup.zip"

The uploaded backup must be a valid PocketBase backup ZIP file. Invalid or corrupted files will be rejected.

Backup contents

PocketBase backups are ZIP archives containing:

• Database - SQLite database file (data.db)
• Storage - All uploaded files from pb_data/storage/
• Metadata - Backup information and checksums

Backup structure

backup.zip
├── data.db           # SQLite database
├── storage/          # All uploaded files
│   ├── collection_id/
│   │   ├── record_id/
│   │   │   └── files...
└── backup.json       # Backup metadata

Automated backups

The Backups API is designed for manual operations. For automated backups:

1. Create a scheduled task/cron job
2. Call POST /api/backups with superuser auth
3. Optionally download and store externally

Example backup script

#!/bin/bash
SUPERUSER_TOKEN="your_token_here"
BACKUP_NAME="auto_backup_$(date +%Y_%m_%d).zip"

# Create backup
curl -X POST http://127.0.0.1:8090/api/backups \
  -H "Authorization: Bearer $SUPERUSER_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$BACKUP_NAME\"}"

# Wait for backup to complete
sleep 5

# Generate file token
TOKEN=$(curl -X POST http://127.0.0.1:8090/api/files/token \
  -H "Authorization: Bearer $SUPERUSER_TOKEN" \
  | jq -r '.token')

# Download backup
curl "http://127.0.0.1:8090/api/backups/$BACKUP_NAME?token=$TOKEN" \
  --output "/backups/$BACKUP_NAME"

Storage locations

Backups are stored in the location configured in your PocketBase settings:

• Local storage: pb_data/backups/
• S3-compatible: Configured S3 bucket

When using S3 storage, backups may not be immediately available due to eventual consistency. Wait a few seconds after creation before attempting to list or download.

Best practices

1. Regular backups - Schedule automated backups daily or more frequently
2. Off-site storage - Download and store backups externally
3. Test restores - Periodically test backup restoration
4. Backup before changes - Always backup before schema changes or major updates
5. Retention policy - Delete old backups to manage storage

Performance considerations

• Backup creation locks the database briefly
• Large databases may take several minutes to backup
• Only one backup/restore operation can run at a time
• Restore operations require application restart

Common errors

Code	Description
400	Invalid backup name, operation in progress, or missing file
401	Not authenticated as superuser
403	File token doesn’t belong to superuser
404	Backup file not found
500	Backup/restore operation failed