Automation

An unattended run has nobody to answer a question, nobody to read a warning, and nobody to notice that it stopped. So the design starts from the worst thing that can happen — a scheduled run hanging on a prompt nobody will ever see — and works backwards from there.

Start with sloop's own service

Before writing a cron line, know that you probably do not need one. sloop registers itself with your machine's own service manager — systemd, launchd or the Service Control Manager — and takes the backups itself, with nobody logged in.

sloop service install runs once and needs an administrator. After that, two commands per database and there is no scheduler to configure at all:

It does the work with the same backup and backups prune you would have typed, with --yes and never --force, and it prunes only after a backup that worked. A missed run is caught up once and labelled late rather than a hundred and sixty-eight times, and a collision with a manual run exits 7 and stands aside.

And it reports itself in the same JSON every other command speaks:

A scheduled run never stops to ask

The best illustration of the rule is a refusal that happens a day early. Scheduling a backup for a registry that has no encryption key yet would mean a first run at three in the morning that makes a key, needs to say something important about it, and finds nobody there. So it is refused now, while there is somebody to read it:

That is the shape of the whole contract. Not fail at the awkward moment, and never quietly guess — refuse at the moment somebody is watching, and name the thing that fixes it.

Saying yes, three different ways

The same run of restore, four times, with nothing attached to standard input. The first three are the argument:

-y did not do it. --force did not do it. Only the database's own name, typed out, did — and a typo in it stops the run before anything is contacted.

None of the three stands in for another, and that is what makes a scheduled line safe to read: a cron entry carrying --confirm orders says out loud which database it will replace, and cannot be repointed at a different one by editing a single flag.

The nine exit codes

Frozen at 1.0. Adding one is a feature; changing what one means is a breaking release, and a test in the source asserts every number and says so. Whatever calls sloop reads these and nothing else.

6 is why a bare success check is not enough. The dump finished, the file is on disk, the checksum is good — and the row counts on the two sides do not agree. Something that only tests for zero files that away as a success and tells you nothing; something that treats everything non-zero as a crash wakes somebody up for it at the same volume as a dead server. It is neither, and it has its own number so it can be treated as neither.

Which makes the calling side about six lines:

7 is the other one worth a branch, in the opposite direction: it means this run did not start, because an earlier one was still going. That is the lock working, not a failure, and alerting on a single one is how a team learns to ignore the alert.

One lockfile per database

An overrunning backup must not race the next scheduled one. Every run takes a lock named for the database it is working on, and a second run that finds it held says who holds it and stops:

The lock names the command, the process and the moment it started, so a stale one — a machine that lost power mid-dump — is identifiable rather than mysterious. It is per database, not per machine: a long backup of one database never blocks another.

Output a script can read

Four flags, and they compose. Every command takes all of them, not a chosen few.

--json

One document, and it is the whole of standard output, so it parses without filtering anything out of it first. Anything the run wants to say about itself goes to standard error instead.

A failure is the same document with the other half filled in — never a half-written one:

ok and exit are on every document sloop prints, successful or not, so a script can branch on the body as well as on the process's own code.

--quiet and --log-file

The pairing worth knowing: silent on the terminal, complete in the file.--quiet silences the running commentary and never a failure, so a job that says nothing is a job that worked — and the file still has all of it if you want to look.

A sloop log is written to be pasted into a public issue: no colour, and anything that reads like a credential taken out on the way. Security shows a token going in and coming out redacted.

--dry-run

A real rehearsal rather than a guess. Every command that would write does all the reading and all the checking first, then stops at the point where it would write — so it resolves the name, opens the connection, counts the rows, and then does not.

--all never stops at the first failure

The whole point of backing up everything on a schedule is that one unreachable database must not cost you the other nine. backup --all carries on to the end and then says exactly which ones failed:

The process still exits non-zero, so a scheduler still knows something went wrong. What it does not do is throw away the work it had already done. In JSON, the same run separates what was taken from what was not:

Passwords with nobody logged in

Here is the thing that catches people on the first night, and it is not sloop's doing: the OS keyring is a per-session store. A cron job has no session keyring, a headless Linux box has no Secret Service running, and a Windows task that runs as LocalSystem has no vault of yours to read. sloop's default route is the right one at a desk and the wrong one at three in the morning.

It says so, rather than failing obscurely:

Two of the four routes are built for exactly this, and neither needs a session:

• --env SLOOP_DB_PW — read from an environment variable at the moment it is needed. Right for CI, where the variable comes from a secret store already.
• --password-from "op read op://vault/db/password" — run something and read the password off its output, through a pipe. Right for a team password manager, and for a machine where the secret should not sit in the environment of every child process.

A missing variable is the failure you will actually meet, and it is a 2 with the variable's name in it:

Which route each record takes is in the listing, so it is never a guess — and a registry holds the route and never the password, so there is nothing there to print:

For a machine with no keyring at all, the fourth route is the encrypted file: --encrypted-file, opened with SLOOP_PASSPHRASE, or with SLOOP_PASSPHRASE_FILE pointing at a file only the service account can read. The second is what sloop's own units use, because a systemd unit is world-readable — systemctl cat sloop prints it to anybody with a shell — so what goes in the definition is a path, and the secret is behind it.

Driving it from cron or a systemd timer

If you already have a scheduler and would rather keep it, sloop is an ordinary command. Nothing below needs sloop service install; these are alternatives to it, not additions.

-q so a working night is a silent night, and --log-file so there is still a record of it. cron mails you whatever the command printed, which with --quiet is nothing at all unless something failed — and then it is the failure and its hint, which is exactly the mail worth getting.

A systemd timer instead, if you would rather have one. Two files, and Persistent=true is the line that makes a machine which was off at three run the backup when it comes back:

Environment=SLOOP_PASSPHRASE_FILE=… rather than the passphrase itself: the unit is world-readable, the file it points at is not.

Whichever drives it, the last thing worth doing is the smallest: sloop doctor exits 8 when a role is short of a privilege that will make its dumps quietly incomplete. Run it on the same schedule and you find that out on a Tuesday, rather than during a restore.