fix(server): compact superseded history and reclaim database space
Remove superseded events automatically. New databases shrink in background batches; existing databases can enable this with t3 doctor --fix. Reconnects fall back to snapshots after history cleanup.
| Command | Behavior |
|---|---|
t3 doctor | Choose repairs; recommended set preselected |
t3 doctor --dry-run | Preview repairs; overrides --fix |
t3 doctor --fix | Apply recommended repairs without prompting |
Web/desktop Storage settings and mobile Maintenance show a dismissible notice when an older database has at least 1 GiB to reclaim. The copied command includes that environment's data directory. The CLI shows a stage bar and elapsed time during repairs. Doctor restores a service it paused even after repair failure/cancellation, leaves already-stopped and other environments' services alone, and documents the workflow in a dedicated user guide. Desktop/manual servers must be closed first.
Measured on a copy of the maintainer's database
| Metric | Before | After compaction + VACUUM | Improvement |
|---|---|---|---|
| Database file | 114.46 GB | 19.67 GB | 94.79 GB reclaimed |
| Stored events | 2,922,807 | 2,023,882 | 31% fewer |
| Event JSON | 98.72 GB | 7.13 GB | 93% less |
| Full-history replay-stat scan | 6.66 s | 1.01 s | 6.6× faster |
| Recent 1,000-sequence replay-stat scan | 0.393 ms | 0.048 ms | 8.1× faster |
| Event-count index scan | 10.89 ms | 3.55 ms | 3.1× faster |
| Event-index ANALYZE | 1.97 s | 0.95 s | 2.1× faster |
| One-time maintenance | Duration |
|---|---|
| Delete 898,925 obsolete events | 6 min 12 s |
| VACUUM + checkpoint | 4 min 6 s |
Deletion alone reduced the full-history scan to 2.08 s; VACUUM reduced it further to 1.01 s. Automatic deletion starts after one minute and repeats every six hours, in 50-row batches. Full VACUUM is explicit and offline. Converted/new databases reclaim up to 1,024 pages per minute while running.
Method: Node 24.21.0 / SQLite 3.53.4, Apple M4 Max, 64 GB RAM. Medians of 3 scan/ANALYZE runs, 5 count runs, and 11 recent-range runs. Cache state was not controlled. Full-history scanning is a diagnostic upper bound; normal reconnects are capped. The same recent range returned 1,000 rows before and 331 after deletion. Startup optimize took 7.4 ms before and 1.2 ms after; the original 30-second delay was not reproduced.
Limitation: The guarded CLI refused one pre-existing unreadable thread projection. Benchmarks therefore invoked the underlying compactor and VACUUM directly on the disposable copy. The live database was untouched.
Validation: original 146 focused tests; 45 focused tests for doctor, database maintenance, storage status, scheduling, authorization and instrumentation. Server/web/mobile typechecks and targeted lint pass. 77 focused CLI/service/database tests cover selection, automatic service handling, dry-run isolation and progress. Isolated CLI dry run confirmed while the server was running.
UI verification is pending: the built-in browser timed out twice on snapshots. No screenshots are claimed.
Implemented with GPT-6.1 Sol via Codex.
Doctor recording
Throwaway database: 769.59 → 257.40 MiB, reclaiming 512.19 MiB. Recommended repair selected by default; colors, headings and stage progress shown below. Retained data verified. No installed service in this fixture; the recording harness stops the CLI after the completion summary.
CLI styling: 9 focused tests, server typecheck and targeted lint pass.