# Svalbard

> Svalbard is an open-source Rust CLI that backs up one PostgreSQL or MySQL database per run to Amazon S3, Cloudflare R2, another S3-compatible service, or an SSH server with SFTP or SCP. It dumps from a snapshot with the native client (`pg_dump` or `mysqldump`), closes the snapshot, and only then uploads the dump and its completion record. CI or cron runs it; it has no server.

Supported: PostgreSQL 15 to 18; MySQL 8.4 and 9.7 with InnoDB tables only; destinations `s3`, `r2`, `sftp` and `scp`. Svalbard never prompts, prints JSON with `--json`, and keeps secrets out of its output.

To set up a backup, work through these steps in order. Each step links the page with the details.

1. **Choose the source.** Prefer a dedicated replica or standby that serves no application traffic, then a replica with traffic, then the primary ([database safety](https://withsvalbard.com/docs/database-safety.md)).
2. **Install Svalbard.** The release archive is for Linux x86_64 with glibc 2.39 or newer, such as Ubuntu 24.04. Download `svalbard-<version>-x86_64-unknown-linux-gnu.tar.gz` from `https://github.com/paulrose/svalbard/releases/download/v<version>/` and check it against a SHA-256 pinned in your setup, not only against the release's `SHA256SUMS` ([install](https://withsvalbard.com/docs/install.md)).
3. **Install the native clients on the same machine.** `pg_dump` 15 to 18, of the server's major version or newer. Oracle's `mysqldump` of the server's series (8.4 for 8.4, 9.7 for 9.7), never MariaDB's. OpenSSH 9.0 or newer for `scp`. On Ubuntu 24.04, use the PostgreSQL and MySQL APT repositories; the commands are on the install page.
4. **Create the database account.**
   - PostgreSQL: a login role with `pg_read_all_data`, and `BYPASSRLS` if a table has row-level security policies.
   - MySQL: `SELECT, SHOW VIEW, TRIGGER, EVENT` on the database (`db.*`), `SHOW_ROUTINE` on `*.*`, and `SELECT` on `performance_schema.metadata_locks`, `performance_schema.threads` and `performance_schema.user_variables_by_thread`. Do not grant `LOCK TABLES`, `RELOAD`, `FLUSH_TABLES` or `CONNECTION_ADMIN`.
5. **Prepare the destination** ([storage](https://withsvalbard.com/docs/storage.md)).
   - S3: the credentials need `s3:PutObject` and `s3:AbortMultipartUpload` on the prefix, and `s3:ListBucketMultipartUploads` on the bucket. Add a lifecycle rule with `AbortIncompleteMultipartUpload`. Access keys, a profile, an instance role and OIDC in CI all work through the AWS credential chain.
   - R2: an API token with Object Read & Write on the bucket, its keys in `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, and `destination.endpoint = "https://<account-id>.r2.cloudflarestorage.com"`.
   - SFTP or SCP: an unencrypted key file or an SSH agent, the server's host key already in a known_hosts file (Svalbard never adds it), and the directory of `destination.path` plus any directories in `destination.prefix` already on the server. SFTP servers must offer `fsync@openssh.com`.
6. **Write the configuration file** (TOML), with no secrets in it ([configuration](https://withsvalbard.com/docs/configuration.md)). `[source]` needs `type`, `host`, `database` and `user`; `[destination]` needs `type` and, by type: `bucket` and a region (`destination.region` or `AWS_REGION`) for S3; `bucket` and `endpoint` for R2; `host`, `user` and `path` for SSH. TLS defaults to `verify-full`; set `source.tls_ca_file` for a private CA. Every key also has a flag and an environment variable, such as `SVALBARD_SOURCE_HOST`. The examples in https://github.com/paulrose/svalbard/tree/main/examples are complete files.
7. **Give the secrets.** The database password goes in `SVALBARD_SOURCE_PASSWORD` or in a file named by `source.password_file`, never both and never empty. Storage credentials come from the environment.
8. **Check the configuration.** `svalbard config check --config svalbard.toml --json` prints `{"valid":true}` and exits 0. It makes no network connections.
9. **Run a backup.** `svalbard backup --config svalbard.toml --json` prints one JSON object. Exit codes: 0 complete, 2 usage error, 3 invalid configuration, 4 failed and cleaned up, 5 failed and the cleanup failed too ([back up](https://withsvalbard.com/docs/backup.md)).
10. **Schedule it.** In GitHub Actions, start it with `exec svalbard backup …` so that a cancellation reaches it, limit each database to one run with `concurrency` and `cancel-in-progress: false`, and give the job a `timeout-minutes` above `safety.dump_timeout` plus `destination.upload_timeout` ([run in CI](https://withsvalbard.com/docs/ci.md)). The Action `paulrose/svalbard/action@<commit>` with the inputs `version`, `config`, and optionally `postgresql` or `mysql`, installs everything and runs one backup ([GitHub Action](https://withsvalbard.com/docs/github-action.md)).
11. **Test a restore.** Download the dump and its `.json` record, check the dump's SHA-256 against the record, and restore into a new database with `pg_restore` or `mysql` ([restore](https://withsvalbard.com/docs/restore.md)).

The safety defaults suit most databases: `lock_timeout` 10s, `contention_timeout` 2s, `dump_timeout` 1h, `max_dump_size` 20GiB, `min_free_space` 2GiB. Put `safety.staging_dir` on a filesystem with room for the dump, never on the filesystem of the database files.

## Docs

- [All pages in one file](https://withsvalbard.com/llms-full.txt): every page below, as Markdown.
- [Overview](https://withsvalbard.com/docs/index.md): Svalbard is an open-source CLI for database backups. It backs up PostgreSQL or MySQL to S3, R2 or an SSH server.
- [Install](https://withsvalbard.com/docs/install.md): Download the release archive, install the native clients, or build from source.
- [Configuration](https://withsvalbard.com/docs/configuration.md): Settings, their flags and environment variables, precedence, TLS and secrets.
- [Storage](https://withsvalbard.com/docs/storage.md): Where backups go, how Svalbard checks each upload, and the S3, R2 and SSH destinations.
- [Back up](https://withsvalbard.com/docs/backup.md): The stages of a backup, cancellation, the output and the exit codes.
- [Restore](https://withsvalbard.com/docs/restore.md): Download a backup, check it against its record, and restore it with the native clients.
- [Run in CI](https://withsvalbard.com/docs/ci.md): Run backups from CI: secrets, known_hosts, one backup per database, cancellation and results.
- [GitHub Action](https://withsvalbard.com/docs/github-action.md): Install a released Svalbard and run a backup in one step.

## Optional

- [Database safety contract](https://withsvalbard.com/docs/database-safety.md): How Svalbard protects the reads and writes of the source database, and the limits, checks and measurements behind it.
- [Development](https://withsvalbard.com/docs/development.md): Checks, tests, measurements, CI jobs, releases and the website.