Skip to main content

​
On-demand backup

Use arrow keys to select your connection and press Enter, then choose Backup now. Capsule runs the backup immediately, encrypts it on your server, and uploads the result to your dashboard. You can also trigger on-demand backups from the web dashboard without touching the CLI. When to use: Any time you want a snapshot before a risky change — a schema migration, a deployment, a bulk delete — and you don’t want to wait for the next scheduled backup to fire.

​
Scheduled backups

Backups run automatically according to the schedules you configure. See capsule schedule for setup. The Capsule service must be running for scheduled backups to fire. Check with:
When to use: Set these up once per connection during initial setup. Scheduled backups are the backbone of your data safety — on-demand backups are a supplement, not a replacement.

​
Restore

There are several ways to restore, covered in detail below. Most people only ever need the first one — start here and only read further if your situation doesn’t match:

​
From the TUI

Select your connection → Backups → select a snapshot → Restore. Capsule will:
  1. Download the encrypted backup from the cloud
  2. Verify the SHA-256 checksum
  3. Decrypt it locally using your server’s encryption key
  4. Pipe it into your database using the native restore tool (psql, mysql, mongorestore)
When to use: When you need to roll back the same server that originally took the backup. This is the standard disaster recovery path.
Restoring overwrites the current contents of the target database. Capsule will ask you to confirm before proceeding.

​
From the dashboard

Open your dashboard, find the backup you want to restore, and click Restore. The dashboard sends a signal to the agent running on your server — the restore runs locally, never through Capsule’s servers. When to use: When you prefer a GUI, or when you want to trigger a restore on your server from a different machine.

​
From a local file (capsule restore --file)

Restores a database directly from a local .sql.gz file (typically produced by capsule download). No cloud connection is required — the file is piped straight into the target database. If you have only one connection configured:
--connection can be omitted. Capsule selects your one connection automatically — you’ll see Using connection: <label> printed before the confirmation prompt. If you have more than one connection configured:
--connection <label> is now required. Capsule never guesses or falls back to “the first one” — omit it here and the command lists every connection you have and exits with an error instead of restoring, so nothing is overwritten by accident. When to use:
  • You used capsule download to get a decrypted copy and want to restore it locally or on a different server
  • Cross-environment restore (production backup → staging database)
  • Air-gapped or offline recovery where the cloud is not reachable
  • You want to inspect the SQL before restoring (unzip the .sql.gz, review, re-zip, then restore)
Flags:

​
Download and decrypt a backup (capsule download)

Downloads an encrypted backup from cloud storage, decrypts it using your server’s local encryption key, and saves it as a standard .sql.gz file you can open, inspect, or restore anywhere. When to use:
  • You need a readable copy of your data outside of Capsule — importing into a local dev environment, sharing with a colleague, or loading into a data analysis tool
  • You’re migrating to a different server and want to seed the new database from an existing backup
  • You want to restore a backup on a machine that is not running the Capsule agent (e.g. a local laptop)
  • You want to archive a specific snapshot to cold storage or an external system
The .enc file you can download from the dashboard is encrypted and not directly usable. capsule download is the command that gives you the plain, readable .sql.gz.
Typical workflow:
Flags:
capsule download must be run on the same server that took the backup, or any server that has imported the same encryption key via capsule auth --restore. Running it on a server with a different key will fail at decryption.

​
Migrating to a new server (decommissioning the old one)

Everything above assumes the server that originally took the backup is still alive and reachable. If you’re replacing that server entirely — the old one is being wiped, returned, or shut down for good — that assumption breaks, because the encryption key lives only on the server that generated it, not in Capsule’s cloud. Without it, on any machine, existing backups are permanently unreadable — Capsule itself cannot recover a lost key. This means server migration has an extra step that’s easy to miss, and has to happen before the old server is gone:
  1. On the old server, before decommissioning it: save the encryption key.
    Copy the 64-character key it prints into a password manager or secrets vault. See capsule key for the full explanation of why this matters and how to store it safely.
  2. On the new server: install Capsule as normal, then import the saved key instead of generating a new one.
    This prompts for your license key, then for the saved encryption key (input hidden). Once it completes, the new server can decrypt every backup the old one ever took. Full walkthrough, including the exact prompts you’ll see: capsule auth — disaster recovery.
  3. Now you can download and restore normally — capsule download <backup-id> and capsule restore --file both work on the new server exactly as they did on the old one, because it holds the same key.
If you skip step 1 and the old server is already gone, there is no recovery path — not through support, not through the dashboard. The key is never sent to Capsule’s servers in any form, by design (that’s what “zero-knowledge” means here). Save it before you decommission anything, not after.
When to use: Replacing a server outright — a hardware refresh, moving providers, or rebuilding from scratch — where the original machine won’t exist afterward.

​
Restore to a different host (source server still exists)

To copy a specific snapshot onto a different server or database instance, while the original server is still alive and reachable:
  1. Run capsule download <backup-id> on the server that has the encryption key
  2. Copy the resulting .sql.gz to the target server (via scp, a shared volume, etc.)
  3. On the target server, run capsule restore --file ./backup.sql.gz --connection <target>
The target server doesn’t need the encryption key for this — the file is already decrypted by the time it gets there. Compare this with migrating to a new server above: that’s for when the source server won’t exist anymore either, which needs the key itself to move, not just one decrypted file. When to use: Seeding a staging environment from a production backup, or testing a restore on a separate machine before doing it in production — the original server keeps running either way.

​
How backups are stored

Plan retention periods — every backup gets an expiry date based on your plan at the time it was created; a background worker deletes it once that date passes: If you upgrade or downgrade, existing backups’ expiry dates are recalculated against the new plan automatically — you don’t need to do anything for the new retention period to apply.

​
See also

  • capsule key — save your encryption key before decommissioning a server, and understand what happens if it’s lost
  • capsule auth — the full --restore flow for importing a saved key onto a new server, with exact prompts and output
  • capsule download — download and decrypt a specific backup by ID
  • capsule backup list — find a backup’s ID before downloading it