Most handover notes fail the same way. The author writes a careful description of the backup system — where the repository lives, which tool runs nightly, roughly how a restore works — and the reader, three days into a vacation, discovers the note describes intent rather than a path. The repository is reachable. The command is almost right. The backup set the reader picked cannot actually be restored to the target they need, and nothing in the note said so.
The unit of value in a handover note is not the description of the backup system. It is the executable recovery path: the exact command, the inputs it needs, and the observable that proves it worked. If the substitute cannot run it, the note has failed regardless of how complete it reads.
This is a craft note for lean teams — two to fifteen engineers, no dedicated SRE department, one on-call rotation — about what to write down before the person who can restore the database becomes unreachable for two weeks. It is not a template to fill in. It is a set of decisions about what belongs in the note and what does not.
Start from the failure mode, not the format
The failure mode is specific. The author leaves. A restore is needed. The substitute opens the note, finds a paragraph explaining that PostgreSQL maintains a write ahead log in pg_wal/ that records every change to the database’s data files, and finds a command that looks plausible. They run it. It completes. They start PostgreSQL. It comes up. The table they needed is still missing, because the backup they restored ended after the data was lost, and PostgreSQL can only play forward, not backward.
That is not a hypothetical. The pgBackRest user guide documents exactly this scenario in its point-in-time recovery walkthrough: if the wrong backup is selected, recovery to the required time target fails, and the log output does not make the failure obvious. The key is to look for the presence of the “recovery stopping before…” and “last completed transaction…” log messages. If they are not present, the recovery to the specified point-in-time was not successful.
A note that does not tell the reader to check for those log lines has not equipped them to know whether they succeeded. A note that does not tell them which backup sets are valid together has not equipped them to choose.
What the note must contain for each recovery scenario
For each scenario the team actually cares about — full cluster restore, point-in-time recovery to a timestamp, single-database restore, file-level restore from the object store — the note needs four things:
- The exact command, with the flags that matter, not a paraphrase.
- The inputs the command needs: which repository, which backup set, which target, which key material, which host.
- The dependency chain: what else must be valid for this command to produce a usable result.
- The observable that proves it worked — a log line, a query result, a checksum, a row count.
Anything else is context. Context is useful, but it is not the note. The note is the four items above, written so the reader’s first hour is spent executing rather than interpreting.
The PostgreSQL and PITR path
Continuous archiving combines a file-system-level backup with backup of the WAL files. Recovery restores the file system backup and then replays the backed-up WAL files to bring the system to a current state. That is the mechanism. The note’s job is to make the mechanism’s prerequisites explicit.
The first prerequisite is a continuous sequence of archived WAL files extending back at least as far as the start time of the backup. Not “some WAL files.” A continuous sequence, back to the backup’s start. If there is a gap — an archiving failure that was not noticed, a repository that filled, a version mismatch that stopped archiving — the backup is not recoverable to a point after the gap. The note should say where to check for gaps and what a gap looks like.
The second prerequisite is that pg_dump and pg_dumpall are not part of this path. They do not produce file-system-level backups and cannot be used as part of a continuous-archiving solution. If the team has both a logical dump and a physical backup, the note should say which one is for which purpose, because a substitute under pressure will reach for the one they recognize.
The third is that WAL archiving does not restore changes made to configuration files — postgresql.conf, pg_hba.conf, pg_ident.conf. Those are edited manually rather than through SQL operations. The note should say where the current configuration lives and how it is restored, because a cluster that comes up with the wrong pg_hba.conf is a cluster that comes up but does not accept the connections the application needs.
The fourth is the disk-space failure mode. If the file system containing pg_wal/ fills up, PostgreSQL will do a PANIC shutdown. No committed transactions will be lost, but the database will remain offline until space is freed. The note should say which filesystem to check and what the safe threshold is, because the substitute may be the person who has to free space at 2 a.m.
The pgBackRest path
pgBackRest’s restore command defaults to selecting the latest backup from the first repository where backups exist. That default is convenient and dangerous. The note should state it, because a reader who assumes the tool will pick the right backup will not pass --set or --repo, and the default may not be the backup they need.
For point-in-time recovery of --type=time or --type=lsn, pgBackRest selects a backup whose stop time is before the target time, or whose stop LSN is less than or equal to the target LSN. If no matching backup is found, it raises an error for both types; it does not fall back to the latest backup. That behavior belongs in the note verbatim, because the failure mode is a reader who assumes a fallback exists and does not check the error.
The dependency chain is the other thing the note must state. A differential backup requires both the differential backup and the previous full backup to be valid in order to restore. An incremental backup requires all prior incremental backups back to the prior differential, the prior differential backup, and the prior full backup to all be valid. The note should name which sets are valid together for the scenarios the team cares about, rather than pointing at “the backup.”
Two operational facts belong in the note as well. pgBackRest encrypts the repository based on a user-provided password, so the password is part of the recovery path, not a separate concern. And the local and remote pgBackRest versions must match exactly; if there is a mismatch, WAL archiving and backups will not function until the versions match. A note that does not record the version in use at the time of writing will be wrong after the next upgrade.
The restic and age path
For file-level backups, the note’s job is to separate two claims that are easy to conflate: “the repository exists” and “this person can decrypt and restore it.” Only the second one matters during a vacation.
age is a file encryption tool, format, and Go library with small explicit keys, post-quantum support, no config options, and UNIX-style composability. Files can be encrypted to multiple recipients by repeating the recipient flag, and every recipient will be able to decrypt the file. Identity files contain one or more secret keys, one per line, or an SSH key.
The note should record: where the repository lives, which recipients the backups are encrypted to, where the identity files are stored, and how the substitute obtains access to them. If the identity file is itself passphrase-protected and stored remotely, the note should say so, because that is a second access step that a substitute will not discover until they need it.
The note should also record what a successful restore looks like. For a restic repository, that is a restic check result and a test restore of a known file. For an age-encrypted archive, that is a decryption that produces the expected file. The observable is the point.
Break-glass access and offboarding hygiene
The handover note is where access hygiene and recovery access meet, and the tension is real. Least privilege says the substitute should not hold standing credentials they do not need. Recovery says the substitute must be able to reach the repository and the key material when the author is unreachable.
The resolution is to write down the break-glass path rather than to grant standing access. The note should name: the mechanism by which the substitute obtains elevated access, who approves it, how long it lasts, and how it is revoked. It should name the offboarding step that removes the author’s access when they return, so the break-glass grant does not become permanent. And it should name the person who can approve the grant when the author is the one who normally would.
This is the part of the note most likely to be skipped, because it is administrative rather than technical. It is also the part most likely to be needed, because a substitute who cannot reach the repository cannot run any of the commands the rest of the note describes.
The pre-vacation drill
The note’s only real test is running it as the substitute would. Not reading it. Running it.
The author picks a scratch target — a throwaway instance, a staging cluster, a container — and executes the note’s commands in the order the note presents them, using only the note as a guide. Every place the author has to supply knowledge that is not in the note is a gap. Every command that fails because a prerequisite was not stated is a gap. Every observable the author checks without the note saying to check it is a gap.
The record of that drill is the note’s revision history. It is more useful than a version number, because it says what was tested and when. A note that was drilled against pgBackRest 2.59.3 and PostgreSQL 17 is a different artifact from a note that was written against an earlier version and never re-run.
The drill also surfaces the failure behavior the note needs to record. A substitute who has run the commands once, on a scratch target, with the author watching, is a substitute who will recognize the difference between a restore that succeeded and a restore that completed.
Review, ownership, and re-verification
The note should have a named reviewer and a date. The reviewer is not a second author; they are the person who reads the note as a substitute would and reports what they could not follow. The date is the point from which re-verification is due.
The re-verification trigger is tied to change, not to a calendar. A note that was true at one pgBackRest version may be false at the next, because the local and remote versions must match exactly. A note that was true before a topology change may point at a repository that no longer exists. A note that was true before a key rotation may reference an identity file that has been replaced. The note should say what changes invalidate it, so the team knows when to re-drill.
This is the same discipline the SRE literature applies to postmortems. A postmortem is a written record of an incident, its impact, the actions taken to mitigate or resolve it, the root cause(s), and the follow-up actions to prevent the incident from recurring. An unreviewed postmortem might as well never have existed. The same is true of a handover note. An unreviewed note is a document, not a recovery path.
It is worth defining, before the vacation rather than during it, what triggers a note review. The SRE book’s guidance on postmortem criteria applies here: define the criteria before the event so everyone knows when the process is necessary. For a handover note, the criteria are simpler — a version change, a topology change, a key rotation, or a drill that failed.
What the note is not
The note is not a postmortem. A postmortem explains what happened and why; a handover note explains what to do next. The two share a discipline of specificity and a refusal to blame, but they serve different readers at different times.
The note is not a runbook for every service. It is the recovery path for the things the author uniquely knows how to restore. If the team already has a runbook that a substitute can follow, the note should link to it rather than duplicate it. The Recovery Checklist Before You Need It is a useful companion for the general shape of a recovery checklist; the handover note is the specific, dated, drilled instance of it for one person’s absence.
The note is not a knowledge dump. A note that explains the history of the backup system, the reasons for each architectural choice, and the tradeoffs considered is a design document. Those are valuable. They are not what a substitute reads at 2 a.m. The note should be short enough to read in the first hour and specific enough to execute in the second.
Frequently asked questions
How long should the handover note be?
Long enough to contain the executable recovery paths for the scenarios the team cares about, and no longer. For a single PostgreSQL cluster with pgBackRest and a restic repository, that is typically a few pages: one section per scenario, each with the command, the inputs, the dependency chain, and the observable. Length is not the measure. The measure is whether a substitute can run it without asking the author a question.
Should the note include the backup password or key material?
No. The note should say where the key material is stored and how the substitute obtains access to it, not contain the material itself. pgBackRest encrypts the repository based on a user-provided password, and age identity files contain secret keys; both belong in a secrets manager or an equivalent access-controlled store, with the note recording the path and the approval step. A note that contains the key is a note that leaks when it is shared.
What if the substitute has never run a restore before?
Then the pre-vacation drill is not optional. The author runs the note’s commands as the substitute would, on a scratch target, and records what broke. The substitute should run them too, with the author available but not intervening. A note that has only been read is a hypothesis; a note that has been executed is a procedure.
How often should the note be re-verified?
Tie re-verification to change rather than to a calendar. A pgBackRest version change, a PostgreSQL major-version upgrade, a repository migration, a key rotation, or a topology change all invalidate parts of the note. The note should name those triggers so the team knows when to re-drill. A calendar-based cadence is a fallback for teams that cannot detect the changes, not the primary mechanism.
Does the note replace a postmortem when a restore fails?
No. If a restore fails during the author’s absence, that is an incident, and it merits a postmortem. The SRE book’s guidance is that postmortems are expected after any significant undesirable event, and that a blameless postmortem focuses on identifying the contributing causes without indicting any individual or team. The handover note is what the team uses during the incident; the postmortem is what the team uses afterward to make the next note better.
What is the single most important thing to write down?
The observable that proves the restore worked. Commands can be copied from documentation. The dependency chain can be reconstructed from the tool’s behavior. But the observable — the log line, the query result, the checksum — is the thing that tells the substitute whether they are done or whether they have produced a successful-looking but useless result. Write that down first, and write it for every scenario.