Backups, retention and restoring

sloop backup shop dumps the database, counts what arrived, and writes a manifest beside it. Everything else on this page is a variation on that sentence — more than one database, keeping fewer of them, or going the other way.

Showing Linux. Change it in the strip above and every path on this page follows.

The key comes first, once

Backups are encrypted, and the first one will not run until the key has been copied somewhere sloop cannot reach. This is not a nag that can be dismissed and forgotten — it is a refusal, and with no terminal to ask at it exits 2:

sloop key export once, and every run after it goes through. The backup key is the page for what that key is and what losing it costs; everything below assumes it has been done.

Taking one

Two timestamps, both deliberate. The directory is named in UTC so backups sort correctly and survive a daylight-saving change; every line a human reads is in local time. The sha256 is over the dump as written, and backups list --check compares it again later.

Every database, and the one that fails

--all is the one you schedule, and its rule is the important one: it never stops on a failure. One unreachable database in a set of thirty must not cost you the other twenty-nine.

The run worked to the end, backed up the three that answered, and named the one that did not. The last line is the one to read in a log — zero, one or several, always counted and always named. The exit code is the failure's own: 3 here, because what went wrong was a connection.

A directory per run, or one kept current

--sequential is the default and is what you saw above: a directory per run, named for the moment it was taken, kept until retention removes it.

--replace keeps exactly one, at a fixed path ending in latest. For a database you want a current copy of rather than a history — and the path never changes, so something else can pick it up without being told where to look.

What is written to disk

Inside the registry the database belongs to — /home/you/projects/acme-api/.sloop/backups for this project, or /home/you/.sloop for the global one. Backups never leave the registry that took them.

Two files, and the second is why any of this can be checked later. The manifest is plain JSON and holds everything needed to judge the dump without opening it:

Per-table row counts are the part that matters. They are what a restore checks itself against, and what makes it finished and it is correct two different statements rather than one. Note what is not here: no password, no key, nothing that could not be pasted into a public issue. The recipient is the public half of the key.

Seeing what is there

That reads sizes and manifests — fast, and enough for a glance. --check does the expensive thing instead: it hashes every dump on disk and compares each one with what its manifest recorded. One byte of the oldest archive dump was overwritten before this run:

It names both hashes rather than saying "corrupt", and the listing exits 6. A listing that returned success over a backup that cannot be restored would be worse than no listing at all — so the exit code carries it, and a scheduled --check can act on it.

Retention

backups prune deletes what is past a limit, after showing you which. Two limits, and they can be combined: --keep <N> for the newest N, and --older-than <AGE> for 12h, 30d, 6w.

--dry-run is a real rehearsal: it does every bit of reading and deciding and stops where it would delete. The list it prints is the list the real run removes.

A --replace copy is skipped by retention and says so. There is one of it, at a fixed path, and deleting it on age would leave a database with no current copy at all — which is the opposite of what a retention rule is for. --include-broken widens the sweep to unfinished and damaged directories, which are otherwise left alone so that a failure is still there to look at.

Putting one back

restore replaces what is in the database now. It is destructive, so it is typed rather than clicked — and from a scheduled run, where there is nobody to type, it refuses:

With no --from it takes the newest. Everything after loaded in is the part that makes this a restore rather than a file copy: it reads the per-table counts out of the manifest and counts the database it has just written, table by table, and only then says the two matched.

--from takes the directory's own name — the UTC stamp, exactly as backups list shows it. A name that is not there is an error before anything is touched, not halfway through.

One lockfile per database

A backup that overruns must not race the next scheduled run. Each database has one lock, and a run that finds it held takes nothing and exits 7. Two backups of the same 2,000,000-row table, started at the same moment — this is what the one that lost printed:

It names the command holding the lock, its process id, when it started, and the file. And the hint says the thing that matters to whatever is reading the exit code: 7 means this run did not start, not that your backup failed. The data is exactly as it was.

Verification is exact, not estimated

Every table is counted on both sides with count(*) — one query_to_xml statement against one snapshot for PostgreSQL, one UNION ALL for the MySQL family. Not a sample, not the catalogue's opinion.

The estimate is still available, for a table too large to count on every run. SLOOP_VERIFY=fast asks for it, and sloop labels it wherever it appears:

a glance and not a proof is sloop's own wording, printed every time. And under fast mode a count can never fail a run on its own — only a table that is genuinely not there, which is a fact from the catalogue rather than from a statistic.

Drift is not loss

A source that is still being written to gains and loses rows while a dump is being taken, so two sides differing by a few rows is the normal state of a live database, not a fault. sloop says so in those words rather than calling it an error.

What is not normal, and what does fail: a table that arrived empty when the source had rows, or a table that did not arrive at all. Those are the two things a dump silently losing data looks like, and both are failures.

Exit 0 against exit 6

Both mean the work completed. Only one of them means the work was proved, and automation that treats them the same is automation that will one day keep a backup nobody can restore.

So 6 is neither success nor a crash, which is exactly why it has its own number. A script that checks if exit == 0 and nothing else will treat a backup whose dump no longer matches its manifest as a good night's work.

Every flag on this page, and every one it did not need, is on the command reference — generated from --help rather than written beside it.