fix(backup): point the size-cap pause advice at levers that end it (#7074)
The PAUSED warning, the `bd backup status` PAUSED line, CHANGELOG and configuration.md told operators to switch to a fresh destination with `bd backup init <new-path>`. That never ends the pause: backupDir() reads only backup.git-repo, while `bd backup init` registers the separate destination that manual `bd backup sync` pushes to, so auto-backup keeps targeting the over-cap directory and stays paused. Name the two levers that do end it: raise backup.size-cap-mb, or point backup.git-repo at a different git repository. Also correct the backup.git-repo row in configuration.md, which called it a repo URL although backupDir() requires a local path containing .git (anything else falls back to .beads/backup/), so the new advice is actionable. TestPauseAutoBackupForSizeCap_RemediationAdvice and the status PAUSED line now require backup.git-repo and reject `bd backup init`. TestMaybeAutoBackup_RemediationLevers runs all three for real: raising the cap and switching backup.git-repo each resume a sync, while `bd backup init` leaves auto-backup paused. Post-merge review follow-up to #6071. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
e87aceedf9
commit
8adcd25992
5 changed files with 183 additions and 11 deletions
|
|
@ -182,7 +182,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
advice no longer suggests deleting the backup directory — nothing
|
||||
guarantees a deleted destination is cleanly recreated by the next sync, and
|
||||
the server-side backup remote stays registered against that path; it now
|
||||
points at `backup.size-cap-mb` / `bd backup init <new-path>` instead. The
|
||||
points at raising `backup.size-cap-mb` or pointing `backup.git-repo` at a
|
||||
different git repository instead — not `bd backup init`, which configures
|
||||
manual `bd backup sync`'s destination and leaves auto-backup paused. The
|
||||
size-cap check itself runs after both the interval throttle and change
|
||||
detection, so it costs nothing on any path that is not about to sync — an
|
||||
idle workspace never reaches it at all, and a paused destination re-arms
|
||||
|
|
|
|||
|
|
@ -95,8 +95,10 @@ func showSizeCapStatus(dir string) {
|
|||
}
|
||||
capBytes := int64(capMB) * 1024 * 1024
|
||||
if size >= capBytes {
|
||||
// Same two levers as pauseAutoBackupForSizeCap's warning — see
|
||||
// there for why `bd backup init` is not one of them.
|
||||
fmt.Printf(" Size cap: PAUSED (cap exceeded) — %s / %s. Raise backup.size-cap-mb "+
|
||||
"or run `bd backup init <new-path>` to switch destinations.\n",
|
||||
"or point backup.git-repo at a different git repository to switch destinations.\n",
|
||||
formatBytes(size), formatBytes(capBytes))
|
||||
return
|
||||
}
|
||||
|
|
@ -183,6 +185,14 @@ func warnBackupSizeCapUnavailable(err error) {
|
|||
// human-visible warning could effectively never fire; those callers have
|
||||
// `bd backup status --json`'s size_cap field instead.
|
||||
//
|
||||
// The advice names only the levers that end the pause: raising the cap, or
|
||||
// pointing backup.git-repo — the only setting backupDir() reads — at another
|
||||
// repository, whose backup/ directory carries none of this one's size or
|
||||
// throttle state. `bd backup init` registers the separate destination that
|
||||
// manual `bd backup sync` pushes to; auto-backup still targets this
|
||||
// directory afterwards, so it would stay paused (PR #6071 post-merge
|
||||
// review).
|
||||
//
|
||||
// Never returns an error: a failure to persist must not block the
|
||||
// (already-decided) skip of the backup attempt itself.
|
||||
func pauseAutoBackupForSizeCap(dir string, state *backupState, size int64) {
|
||||
|
|
@ -208,7 +218,8 @@ func pauseAutoBackupForSizeCap(dir string, state *backupState, size int64) {
|
|||
fmt.Fprintf(os.Stderr,
|
||||
"Warning: auto-backup PAUSED — destination %s has reached %s. "+
|
||||
"No further syncs will run until you raise backup.size-cap-mb "+
|
||||
"or switch to a fresh destination with `bd backup init <new-path>`.\n",
|
||||
"or point backup.git-repo at a different git repository "+
|
||||
"(auto-backup then syncs to a backup/ directory inside it).\n",
|
||||
dir, formatBytes(size))
|
||||
debug.Logf("backup: size cap exceeded (%s), auto-backup paused\n", formatBytes(size))
|
||||
return
|
||||
|
|
|
|||
|
|
@ -260,8 +260,12 @@ func TestBackupSizeCapExceeded_DisabledWithZero(t *testing.T) {
|
|||
// fix: the warning must not tell operators to delete the backup directory
|
||||
// — nothing confirms the destination is cleanly recreated by the next
|
||||
// sync, and Dolt's server-side backup remote stays registered against that
|
||||
// path. It should point at the safe levers instead: raising the cap, or a
|
||||
// fresh destination via `bd backup init`.
|
||||
// path. It should point at the levers that end the pause instead: raising
|
||||
// the cap, or pointing backup.git-repo at another repository. It must not
|
||||
// point at `bd backup init`, which the original fix suggested (PR #6071
|
||||
// post-merge review): that configures the destination for manual `bd backup
|
||||
// sync` and leaves auto-backup paused — see
|
||||
// TestMaybeAutoBackup_RemediationLevers for all three, run for real.
|
||||
func TestPauseAutoBackupForSizeCap_RemediationAdvice(t *testing.T) {
|
||||
t.Chdir(t.TempDir())
|
||||
t.Setenv("BEADS_DIR", "")
|
||||
|
|
@ -285,8 +289,11 @@ func TestPauseAutoBackupForSizeCap_RemediationAdvice(t *testing.T) {
|
|||
if !strings.Contains(stderr, "backup.size-cap-mb") {
|
||||
t.Errorf("warning missing backup.size-cap-mb pointer: %q", stderr)
|
||||
}
|
||||
if !strings.Contains(stderr, "bd backup init") {
|
||||
t.Errorf("warning missing `bd backup init <new-path>` pointer: %q", stderr)
|
||||
if !strings.Contains(stderr, "backup.git-repo") {
|
||||
t.Errorf("warning missing backup.git-repo pointer: %q", stderr)
|
||||
}
|
||||
if strings.Contains(stderr, "bd backup init") {
|
||||
t.Errorf("warning points at `bd backup init`, which does not move the auto-backup destination: %q", stderr)
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -547,6 +554,142 @@ func TestMaybeAutoBackup_PausedSkipArmsIntervalThrottle(t *testing.T) {
|
|||
}
|
||||
}
|
||||
|
||||
// dirRecordingBackupStore records the destination of every backup, so a
|
||||
// test can tell a sync into the paused destination from one into a new one.
|
||||
type dirRecordingBackupStore struct {
|
||||
failingBackupStore
|
||||
dirs []string
|
||||
}
|
||||
|
||||
func (f *dirRecordingBackupStore) BackupDatabase(ctx context.Context, dir string) error {
|
||||
f.dirs = append(f.dirs, dir)
|
||||
return f.failingBackupStore.BackupDatabase(ctx, dir)
|
||||
}
|
||||
|
||||
// TestMaybeAutoBackup_RemediationLevers runs the PAUSED advice for real
|
||||
// (PR #6071 post-merge review): each lever it names must resume
|
||||
// auto-backup, and `bd backup init <new-path>`, which it used to name, must
|
||||
// not. backupDir() reads only backup.git-repo, so the destination init
|
||||
// configures for manual `bd backup sync` never reaches auto-backup.
|
||||
func TestMaybeAutoBackup_RemediationLevers(t *testing.T) {
|
||||
// paused returns an over-cap destination whose pause has already been
|
||||
// recorded, and the fake store a resumed sync would reach.
|
||||
paused := func(t *testing.T) (string, *dirRecordingBackupStore) {
|
||||
t.Helper()
|
||||
t.Chdir(t.TempDir())
|
||||
// A resumed sync takes the workspace-scoped backup lock, so the
|
||||
// command needs a real workspace.
|
||||
prepareBackupStatusTest(t)
|
||||
|
||||
repo := t.TempDir()
|
||||
if err := os.MkdirAll(filepath.Join(repo, ".git"), 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
t.Setenv("BD_GIT_HOOK", "")
|
||||
t.Setenv("BD_BACKUP_GIT_REPO", repo)
|
||||
t.Setenv("BD_BACKUP_ENABLED", "1")
|
||||
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "1")
|
||||
initConfigForTest(t)
|
||||
|
||||
dir, err := backupDir()
|
||||
if err != nil {
|
||||
t.Fatalf("backupDir: %v", err)
|
||||
}
|
||||
if err := os.WriteFile(filepath.Join(dir, "filler"), make([]byte, 2*1024*1024), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
seeded := &backupState{Timestamp: time.Now().UTC().Add(-time.Hour), LastDoltCommit: "oldcommit"}
|
||||
if err := saveBackupState(dir, seeded); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
oldStore := store
|
||||
fake := &dirRecordingBackupStore{failingBackupStore: failingBackupStore{commit: "deadbeef"}}
|
||||
store = fake
|
||||
t.Cleanup(func() { store = oldStore })
|
||||
|
||||
stderr := captureStderr(t, func() { maybeAutoBackup(context.Background()) })
|
||||
if !strings.Contains(stderr, "auto-backup PAUSED") || len(fake.dirs) != 0 {
|
||||
t.Fatalf("auto-backup did not pause (synced to %q), so this test proves nothing: %q", fake.dirs, stderr)
|
||||
}
|
||||
return dir, fake
|
||||
}
|
||||
// rewindThrottle stands in for waiting out backup.interval, which the
|
||||
// pause re-armed: a lever applied to the same destination takes effect
|
||||
// at its next eligible sync, not on the very next command.
|
||||
rewindThrottle := func(t *testing.T, dir string) time.Time {
|
||||
t.Helper()
|
||||
st, err := loadBackupState(dir)
|
||||
if err != nil {
|
||||
t.Fatalf("loadBackupState: %v", err)
|
||||
}
|
||||
st.Timestamp = time.Now().UTC().Add(-time.Hour)
|
||||
if err := saveBackupState(dir, st); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return st.Timestamp
|
||||
}
|
||||
|
||||
t.Run("raise backup.size-cap-mb", func(t *testing.T) {
|
||||
dir, fake := paused(t)
|
||||
t.Setenv("BD_BACKUP_SIZE_CAP_MB", "10")
|
||||
initConfigForTest(t)
|
||||
rewindThrottle(t, dir)
|
||||
|
||||
maybeAutoBackup(context.Background())
|
||||
if len(fake.dirs) != 1 || fake.dirs[0] != dir {
|
||||
t.Errorf("synced to %q after raising the cap, want one sync to %q", fake.dirs, dir)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("point backup.git-repo at a different git repository", func(t *testing.T) {
|
||||
_, fake := paused(t)
|
||||
other := t.TempDir()
|
||||
if err := os.MkdirAll(filepath.Join(other, ".git"), 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
t.Setenv("BD_BACKUP_GIT_REPO", other)
|
||||
initConfigForTest(t)
|
||||
|
||||
// No rewind: the new destination has no throttle state of its own.
|
||||
maybeAutoBackup(context.Background())
|
||||
want := filepath.Join(other, "backup")
|
||||
if len(fake.dirs) != 1 || fake.dirs[0] != want {
|
||||
t.Errorf("synced to %q after switching backup.git-repo, want one sync to %q", fake.dirs, want)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("bd backup init leaves auto-backup paused", func(t *testing.T) {
|
||||
dir, fake := paused(t)
|
||||
oldCtx, oldWrote := rootCtx, commandDidWrite.Load()
|
||||
rootCtx = context.Background()
|
||||
t.Cleanup(func() {
|
||||
rootCtx = oldCtx
|
||||
commandDidWrite.Store(oldWrote)
|
||||
})
|
||||
stdout := captureStdout(t, func() error {
|
||||
return backupInitCmd.RunE(backupInitCmd, []string{t.TempDir()})
|
||||
})
|
||||
if !strings.Contains(stdout, "Backup destination configured") {
|
||||
t.Fatalf("`bd backup init` did not configure a destination, so this test proves nothing: %q", stdout)
|
||||
}
|
||||
rewound := rewindThrottle(t, dir)
|
||||
|
||||
maybeAutoBackup(context.Background())
|
||||
if len(fake.dirs) != 0 {
|
||||
t.Fatalf("synced to %q after `bd backup init`, want auto-backup still paused", fake.dirs)
|
||||
}
|
||||
st, err := loadBackupState(dir)
|
||||
if err != nil {
|
||||
t.Fatalf("loadBackupState: %v", err)
|
||||
}
|
||||
if !st.Timestamp.After(rewound) {
|
||||
t.Errorf("timestamp = %v, want it re-armed past %v by the size-cap skip: the cap check never ran, so this proves nothing",
|
||||
st.Timestamp, rewound)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
// TestWarnBackupSizeCapUnavailable_IsOperatorVisible pins the PR #6071
|
||||
// review's error-handling minor: getDirSize aborts its whole walk on the
|
||||
// first unreadable entry, and maybeAutoBackup then proceeds UNCAPPED. That
|
||||
|
|
|
|||
|
|
@ -228,8 +228,24 @@ func TestBackupStatusShowsSizeCapPaused(t *testing.T) {
|
|||
if stderr != "" {
|
||||
t.Errorf("stderr = %q, want empty", stderr)
|
||||
}
|
||||
if !strings.Contains(stdout, "PAUSED (cap exceeded)") {
|
||||
t.Errorf("status text missing PAUSED indicator: %s", stdout)
|
||||
var pausedLine string
|
||||
for _, line := range strings.Split(stdout, "\n") {
|
||||
if strings.Contains(line, "PAUSED (cap exceeded)") {
|
||||
pausedLine = line
|
||||
}
|
||||
}
|
||||
if pausedLine == "" {
|
||||
t.Fatalf("status text missing PAUSED indicator: %s", stdout)
|
||||
}
|
||||
// Same levers as the pause warning — see
|
||||
// TestPauseAutoBackupForSizeCap_RemediationAdvice.
|
||||
for _, want := range []string{"backup.size-cap-mb", "backup.git-repo"} {
|
||||
if !strings.Contains(pausedLine, want) {
|
||||
t.Errorf("PAUSED line missing %s pointer: %q", want, pausedLine)
|
||||
}
|
||||
}
|
||||
if strings.Contains(pausedLine, "bd backup init") {
|
||||
t.Errorf("PAUSED line points at `bd backup init`, which does not move the auto-backup destination: %q", pausedLine)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
|
|
|||
|
|
@ -125,7 +125,7 @@ Any key whose name contains `api_key`, `api-key`, `secret`, `token`, or `passwor
|
|||
| `backup.enabled` | — | `BD_BACKUP_ENABLED` | `false` | Enable periodic Dolt-native backup to `.beads/backup/` (see [below](#auto-backup)) |
|
||||
| `backup.interval` | — | `BD_BACKUP_INTERVAL` | `15m` | Minimum time between auto-backups |
|
||||
| `backup.git-push` | — | — | `false` | Auto-push backup repo |
|
||||
| `backup.git-repo` | — | `BD_BACKUP_GIT_REPO` | (none) | Backup git repo URL; when set, backups go to a `backup/` directory inside that repo |
|
||||
| `backup.git-repo` | — | `BD_BACKUP_GIT_REPO` | (none) | Path to a local git repository (`~/` expands); when set, auto-backup syncs to a `backup/` directory inside it. A path without `.git` falls back to `.beads/backup/` with a warning |
|
||||
| `backup.size-cap-mb` | — | `BD_BACKUP_SIZE_CAP_MB` | `2048` | Pause auto-backup once the destination directory reaches this size; `0` disables the cap (see [below](#auto-backup)) |
|
||||
| `backup.size-warn-interval` | — | `BD_BACKUP_SIZE_WARN_INTERVAL` | `24h` | Minimum time between repeated "auto-backup paused" warnings |
|
||||
| `audit.enabled` | — | `BD_AUDIT_ENABLED` | `false` | Enable the optional JSONL interaction sidecar at `.beads/interactions.jsonl`, written by `bd audit record` / `bd audit label`. While disabled, `bd init` does not create the file and `bd audit record` / `bd audit label` refuse to write. Issue history is always recorded in the database either way — see `bd history <id> --events` |
|
||||
|
|
@ -235,7 +235,7 @@ backup:
|
|||
How it works:
|
||||
|
||||
- After each write command, `bd` compares the Dolt HEAD commit hash against the last backup state.
|
||||
- If data changed and the throttle interval has passed, `bd` checks the destination directory's on-disk size against `backup.size-cap-mb`. `CALL DOLT_BACKUP('sync', ...)` only ever adds new chunks to the destination — it never prunes ones that became unreachable on the source (history rewrites, superseded data), and Dolt exposes no supported way to GC a backup destination in place. Left uncapped, the destination can only grow until disk fills; this was the root cause of a 2026-06-19 outage where a 1.7GB store produced a 43GB backup directory. Once the cap is reached, auto-backup pauses — nothing is deleted, but no further syncs run until you raise `backup.size-cap-mb` or point to a fresh destination with `bd backup init <new-path>`. Set `size-cap-mb: 0` to disable the cap entirely.
|
||||
- If data changed and the throttle interval has passed, `bd` checks the destination directory's on-disk size against `backup.size-cap-mb`. `CALL DOLT_BACKUP('sync', ...)` only ever adds new chunks to the destination — it never prunes ones that became unreachable on the source (history rewrites, superseded data), and Dolt exposes no supported way to GC a backup destination in place. Left uncapped, the destination can only grow until disk fills; this was the root cause of a 2026-06-19 outage where a 1.7GB store produced a 43GB backup directory. Once the cap is reached, auto-backup pauses — nothing is deleted, but no further syncs run until you raise `backup.size-cap-mb` or point `backup.git-repo` at a different git repository, whose `backup/` directory then becomes the destination. `bd backup init` does not end the pause: it configures the separate destination that manual `bd backup sync` pushes to. Set `size-cap-mb: 0` to disable the cap entirely.
|
||||
- If the destination is under its cap, a Dolt-native backup is synced to `.beads/backup/` (or to a `backup/` directory inside `backup.git-repo` when configured).
|
||||
- State is tracked in `backup_state.json` inside the backup directory. `bd backup status` prints `PAUSED (cap exceeded)` when the destination is over its cap, and its `--json` output reports the same state as `size_cap.exceeded: true` — so an agent/CI caller relying on `--json` or `--quiet` can see that auto-backup has stopped instead of reading a reassuring "Last backup" line while nothing further syncs.
|
||||
- The cap applies only to auto-backup; manual `bd backup` / `bd backup sync` are not capped.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue