Documentation
¶
Overview ¶
Package backup builds and verifies graphdb store backup archives.
An archive is a gzip+tar of a store's dataDir: the snapshot file, rules.json (ADR 0001's uniqueness-rules registry) if present, plus the wal/, auth/, lsa/, and edgestore/ trees, with a manifest trailer recording per-file size + SHA-256 for integrity. The package has no dependency on the HTTP server (pkg/api) or storage, so offline tooling (the graphdb-admin CLI) can build, verify, and restore archives without opening a graph.
Index ¶
- Constants
- func Extract(r io.Reader, destDir string) error
- func ExtractWithFS(fsys vfs.FileSystem, r io.Reader, destDir string) error
- func WriteArchive(w io.Writer, dataDir, version string) error
- func WriteArchiveWithFS(fsys vfs.FileSystem, w io.Writer, dataDir, version string) error
- type File
- type Manifest
Constants ¶
const ManifestName = "manifest.json"
ManifestName is the archive member holding the manifest.
const ManifestVersion = 1
ManifestVersion is the schema version of the manifest envelope. Bump when the manifest shape changes incompatibly; verify/restore tooling refuses versions it does not understand.
Variables ¶
This section is empty.
Functions ¶
func Extract ¶
Extract unpacks a backup archive into destDir, on the default filesystem driver. See ExtractWithFS.
func ExtractWithFS ¶ added in v1.4.0
ExtractWithFS unpacks a backup archive into destDir, through fsys, reconstructing the store's dataDir layout. The manifest.json metadata entry is skipped — only the store's own files are written. destDir is created if absent.
Each entry's destination is constrained to destDir: an entry whose path escapes the directory (a "zip-slip" traversal) aborts the extraction with an error. Callers should Verify the archive first; ExtractWithFS performs no integrity checking of its own.
The driver exists so a test can observe the write, and so a fault or crash simulator can reach this path at all — the same reason WriteArchiveWithFS has one. Before it, Extract called the os package directly: no driver saw a restore ever happen.
func WriteArchive ¶
WriteArchive streams a gzip+tar archive of the store's dataDir to w, on the default filesystem driver. See WriteArchiveWithFS.
func WriteArchiveWithFS ¶ added in v1.4.0
WriteArchiveWithFS streams a gzip+tar archive of the store's dataDir to w, through fsys: each backup file with its dataDir-relative path, then a manifest.json trailer.
The driver exists so a test can observe the read, and so a fault or crash simulator can reach this path at all. Before it, WriteArchive called the os package (and filepath.Walk) directly: no driver saw a single one of its operations, so a crash sweep over graphdb ran, reported, and never observed this function. A path outside the seam produces no signal — "the sweep found nothing" and "the sweep never saw it" render identically.
Types ¶
type File ¶
type File struct {
Path string `json:"path"` // path relative to dataDir, slash-separated
SizeBytes int64 `json:"size_bytes"` // bytes written into the archive
Sha256 string `json:"sha256"` // hex SHA-256 of exactly those bytes
}
File records one archived member with the integrity data needed to detect a corrupt or truncated archive before it is restored over live data.
type Manifest ¶
type Manifest struct {
ManifestVersion int `json:"manifest_version"`
GraphdbVersion string `json:"graphdb_version"`
CreatedAtUTC string `json:"created_at_utc"`
SnapshotMode string `json:"snapshot_mode"` // "json" | "mmap" | "none"
Files []File `json:"files"`
}
Manifest is the provenance + integrity record. It is written as the archive's LAST entry (a trailer) so each file's recorded hash describes exactly the bytes streamed into the tar — immune to a WAL segment being appended between enumeration and streaming on a live backup.
func Verify ¶
Verify reads a backup archive stream and checks its integrity against the manifest trailer: every manifest file must be present with a matching size and SHA-256, and every archived file (other than the manifest) must be listed. It returns the parsed manifest on success, or an error naming the offending path(s). It does not write anything — safe to run against an archive before restoring it over live data.
Source Files