Module restore 

Restore a store from a backup prefix: mushroomdb restore --from s3://….

A restore reads one restore point (W4 §3.1):

1. {prefix}/LATEST names the newest manifest. A point in time (--at) uses the earliest manifest of the same lineage that holds the target commit instead; a timestamp is first resolved to a commit through the newest manifest’s commit_times.bin, over the commits the restore can see. When the instant is at or after the newest recorded time and commits with no recorded time follow, it is refused (RestoreS3Error::CommitTimesEnd) rather than placed before them.
2. Every file the manifest names is downloaded and its size and CRC-32 checked; its segments are checked the same way, must be of the manifest’s generation and contiguous from offset 0, and are concatenated into wal.bin. The manifest, its entries and the store’s backup.lineage file must all name one lineage. A restore of the newest point also takes the segments of its generation shipped after the manifest, up to the last contiguous one. No manifest names those, so they are checked by their own frame checksums, size and offsets, not against an entry; a restore loses at most the segment cadence.
3. With --at, the copy is cut back to the state right after the target commit (mushroomdb::restore::cut_at_commit): what open_at shows there, as an ordinary store. Either way commit_times.bin is trimmed to the commits restored, so the store stamps its own next commit.
4. The copy gets a new backup lineage. A restored store is a new history: its next backup can never resume into the prefix it came from or delete anything there (defect-ledger row 138). Back it up to a new prefix.
5. The copy is opened, read-only, and must hold the commits the restore point says it does. Only then is it moved into place, with one directory rename.

Everything up to that rename happens in a staging directory beside the target, every file fsynced. A restore that fails at any point, or a crash, leaves the target exactly as it was — absent, or an empty directory — never a part of a store. A failed restore removes the staging directory; one killed outright can leave it behind, as a hidden .<name>.restore-… directory and lock file beside the target, and the next restore into the same target removes such leftovers no running restore holds. A target that holds anything is refused before anything is downloaded.

A restore on boot (crate::boot) installs in place instead: its target is a server’s data directory, often a volume’s mount point, which no rename can replace and whose parent may not be writable. It stages inside the data directory, records the restore point it came from (crate::disk::PARENT_FILE), and moves the staged files into the directory under an install marker (INSTALL_MARKER) naming them. The marker is removed last: a data directory holding it holds a part of a store, and the next boot removes exactly the files it names (undo_interrupted_install) before restoring again.

Structs

RestoreS3Outcome

What a restore did.

Enums

RestoreS3Error

Why a restore failed. The target is in every case as it was before the restore — absent, or an empty directory. (Once the store is in place nothing is reported as a failure; see RestoreS3Outcome::install_note.)

RestoreTarget

The point in time to restore (--at).

Constants

INSTALL_MARKER

The file in a data directory that says a restore on boot is moving a store into it: one line per file it moves, <name>\t<size>\t<mtime ns>, as the file was staged. mushroomdb::GraphDb::open refuses a directory holding it. The file a restore on boot (MUSHROOMDB_RESTORE_FROM_S3) writes into a data directory while it moves a restored store into it, naming the files it moves. While it is there the directory holds a part of a store, and GraphDb::open refuses it (refuse_half_installed).

STALE_STAGING_AFTER

How old an unlocked lock file, or a staging directory without one, must be before a sweep counts it as a killed restore’s. A restore creates its lock file, then locks it, then creates its directory: one younger than this may be a restore between those steps.

Functions

install_interrupted

Whether dir holds a restore on boot that stopped while it moved its files in (INSTALL_MARKER): what the directory holds is then a part of a store, and must not be opened.

restore_from_s3

Restore the backup at from (s3://bucket/prefix, r2://… or minio://…) into into, at at or at the newest restore point.

restore_from_s3_with

restore_from_s3 over any variable lookup.

restore_from_store

Restore from prefix in store into into: the object-store half of restore_from_s3, for any ObjectStore.

restore_in_place

Restore the newest restore point of prefix into the data directory dir, in place (see the module docs), recording where it came from in crate::disk::PARENT_FILE. dir may be absent, empty, or hold only lost+found, a LOCK file, an empty wal.bin and the leftovers of killed restores into it.

undo_interrupted_install

Undo a restore on boot that stopped while it moved its files into dir: remove the files its INSTALL_MARKER names, then the marker. Returns the files removed; nothing when there is no marker. Only plain file names directly in dir are touched.