diff --git a/CHANGELOG.md b/CHANGELOG.md index 89e60d86f..e38cae372 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 ` 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 diff --git a/cmd/bd/backup_cap.go b/cmd/bd/backup_cap.go index 64854731f..77f0101fd 100644 --- a/cmd/bd/backup_cap.go +++ b/cmd/bd/backup_cap.go @@ -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 ` 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 `.\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 diff --git a/cmd/bd/backup_cap_test.go b/cmd/bd/backup_cap_test.go index d44ac0438..837a10592 100644 --- a/cmd/bd/backup_cap_test.go +++ b/cmd/bd/backup_cap_test.go @@ -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 ` 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 `, 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 diff --git a/cmd/bd/backup_status_test.go b/cmd/bd/backup_status_test.go index 513603cc8..86348c185 100644 --- a/cmd/bd/backup_status_test.go +++ b/cmd/bd/backup_status_test.go @@ -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) } }) } diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 33803808c..39c60a394 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -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 --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 `. 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.