Files
roonge 1a19f0d984 feat(backup): add gramsrv-backup tool, restore scripts and migration guide
Operators had no supported way to move a deployment or to recover one. This
adds cmd/gramsrv-backup, which captures the PostgreSQL databases, the media and
key tree, Redis and the configuration into a single verifiable bundle, and
restores it on another host.

backup / restore / verify, with MANIFEST.json recording the source commit, the
schema version and exact row counts, and SHA256SUMS in sha256sum(1) format.
Components are captured independently (server, grammystore) since each has its
own database and usually its own container; pg_dump and redis-cli can come from
the host or from docker exec.

Portability is the point of the dump format:

  - plain SQL rather than the custom format, so any psql can replay it and the
    client need not match the server
  - --clean --if-exists so a bundle can be replayed over a populated database
  - --no-owner --no-privileges, and no --create, so the target role and database
    name are not baked into the artifact
  - restored with ON_ERROR_STOP=1 and --single-transaction, so a failure cannot
    leave a half-applied schema
  - \restrict, \unrestrict and SET transaction_timeout are stripped on the way
    in; they are PostgreSQL 17 specific and break older clients and servers
  - the target major version is checked before the restore starts

Freezing (--freeze-units, --freeze-containers) is optional because pg_dump is
already MVCC-consistent; it exists so the media tree is byte consistent, and
everything stopped is restarted from a defer even when the capture fails.

Verification re-hashes every artifact, decompresses it, walks tar members, and
cross-checks file_blobs against the media tree, reporting missing and corrupt
objects. check-media.sh runs the live form of that check.

Also included: shell and PowerShell wrappers, a migration runbook in
docs/backup-restore.md, and internal/doclint, which fails the build when tracked
markdown leaks a key, a token or a credential so documentation stays safe to
publish.
2026-10-04 07:34:54 +00:00

82 lines
2.4 KiB
Bash
Executable File

#!/usr/bin/env bash
# Restore a gramsrv backup bundle produced by ./scripts/backup.sh.
#
# The bundle carries the database, the media and key tree, and the configuration,
# so a restore is: put the repository in place, replay the bundle, then start the
# services. Read this script before running it against a live instance; it will
# refuse to overwrite files unless --force is given.
set -euo pipefail
usage() {
cat <<'EOF'
Usage: ./scripts/restore.sh --from DIR [gramsrv-backup flags]
Runs gramsrv-backup restore with defaults for a monolith deployment:
--from bundle directory (required)
--repo-dir deployment root receiving .env and data/ (default: repo root)
--component server, grammystore or all (default: every component present)
--dsn target PostgreSQL DSN (default: read from the restored .env)
--pg-tools local or docker (default: docker when docker is available)
--dry-run print the plan without writing anything
--force overwrite existing files in the data tree
Examples:
# Inspect what a bundle would do.
./scripts/restore.sh --from /srv/backups/20261004 --dry-run
# Restore the database and the media tree onto this host.
./scripts/restore.sh --from /srv/backups/20261004 --force
# Restore only the store bot database.
./scripts/restore.sh --from /srv/backups/20261004 --component grammystore
Run './scripts/restore.sh --help' for the full flag list.
EOF
}
script_dir=$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
repo_root=$(CDPATH='' cd -- "$script_dir/.." && pwd)
binary="$repo_root/bin/gramsrv-backup"
has_flag() {
local name=$1
shift
local arg
for arg in "$@"; do
[[ $arg == "$name" || $arg == "$name="* ]] && return 0
done
return 1
}
build_binary() {
command -v go >/dev/null 2>&1 || {
printf 'restore.sh: go is required to build %s\n' "$binary" >&2
return 1
}
printf 'restore.sh: building %s\n' "$binary" >&2
(cd "$repo_root" && GOFLAGS=-p=1 go build -o "$binary" ./cmd/gramsrv-backup)
}
docker_available() {
command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1
}
if has_flag --help "$@"; then
usage
exit 0
fi
[[ -x $binary ]] || build_binary
args=()
if ! has_flag --repo-dir "$@"; then
args+=(--repo-dir "$repo_root")
fi
if ! has_flag --pg-tools "$@" && docker_available; then
args+=(--pg-tools docker)
fi
cd "$repo_root"
exec "$binary" restore "${args[@]}" "$@"