Restore

sctl restore postgres <artifact-id> --database scratch

Restore happens entirely on your machine. The artifact is downloaded through a presigned URL, decrypted with your own private key, decompressed, and reconstructed according to its source type. Neither the target nor its credentials are ever sent to us.

We are not in the path and could not be: we have no private key.

One subcommand per target

Restoring a folder is not the same operation as restoring a database, so the target type is the subcommand and its flags are only the ones that type needs.

# Postgres: replayed into a database
sctl restore postgres <artifact-id> --host localhost --database scratch --user postgres

# MySQL: replayed with the mysql client
sctl restore mysql <artifact-id> --database scratch --user root

# Written to a path
sctl restore file <artifact-id> --path ./uploads.tar
sctl restore folder <artifact-id> --path ./restored.zip

The target is described with the same field names its source type uses, so a source: block in a manifest and a restore command name things identically.

file and folder do the same thing: they write the artifact to --path. Neither unpacks it, because extracting into a tree you have not looked at is not a backup tool's decision.

--key applies to all of them: a private key file, defaulting to your gpg keyring or agent.

The target is validated before anything is downloaded, so a missing --database costs you nothing:

$ sctl restore postgres <artifact-id>
Error: postgres target: database is required

What it does

download → decrypt → decompress → reconstruct

Compression is applied before encryption, so an artifact with both peels in that order and neither step substitutes for the other. Doing this by hand is where that bites: stopping at gpg --decrypt hands you a gzip stream, which psql, mysql, tar and the RDB reader all reject. See the four combinations.

For Postgres it reads the first bytes of the dump to decide: PGDMP means custom format and pg_restore, anything else means plain SQL and psql. You do not have to know which you have.

Using a key file

sctl restore file <artifact-id> --path ./uploads.tar --key ./prod-private.asc

The key is imported into a temporary keyring that is deleted when the command exits, so nothing is left behind in your own keyring. That is the right choice on a machine you do not own, such as a recovery box during an incident.

Without --key, your normal gpg keyring and agent are used, and a passphrase prompt appears if the key has one.

Restoring without the backup definition

sctl restore folder <artifact-id> --path ./data.tar

You name the target yourself, so nothing is looked up from the backup. That matters when the definition has been deleted but the artifact has not: you need the artifact and your key, and nothing else.

Requirements

If a tool is missing the command says which one and stops, rather than failing partway through. See installing gpg.

Restore into scratch first

Always, and especially during an incident.

createdb scratch
sctl restore postgres <artifact-id> --host localhost --database scratch
psql -d scratch -c 'SELECT max(created_at) FROM orders;'

That last query gives your actual recovery point, which is when the dump started rather than when the run finished. It is the number to report to everyone else.

Doing it without sctl

The CLI is a convenience, not a dependency. Every step is a standard tool:

sctl artifact download <artifact-id> --output ./artifact
gpg --decrypt ./artifact > ./app.dump.gz
gunzip ./app.dump.gz
pg_restore --dbname scratch ./app.dump

Rehearse that path at least once, so you know the recovery does not depend on us shipping a working binary. See Recover.

Troubleshooting

Next