Admin CLI: check / rebuild-rollups / inspect-segment / verify-period / export-parquet

[pbudzik]

Summary

The usagedb binary doubles as an admin tool. The HTTP server behavior moves under usagedb serve (still the default when no subcommand is given, so prior invocations work unchanged).

Subcommands

usagedb check [--deep]
  Manifest summary (generation, segment counts, watermark).
  --deep additionally opens every segment file and verifies
  checksum + structural validity. Fails non-zero on any corruption.

usagedb rebuild-rollups --from <RFC3339> --to <RFC3339>
  Drops rollup segments overlapping the range + rewinds the
  watermark to `from`. Next server tick refills from raw segments.

usagedb inspect-segment <segment_id>
  SegmentMeta fields (bucket, time range, ID sets, checksum,
  input_segment_ids for rollups) + first 5 rows as a sample.

usagedb verify-period --account <id> --from <RFC3339> --to <RFC3339>
  Same logic as the /verify HTTP endpoint. Prints raw_total,
  rollup_total, drift, and `period_sealed`.

usagedb export-parquet <output.parquet>
  Calls export_raw_segments() — every raw segment to one Parquet
  file, zstd-compressed.

All commands accept --db-root <path> (global, default ./data) and operate on the on-disk state without needing a running server. Assumes the server is not running concurrently — file locking to prevent that is on the backlog.

Implementation

• src/admin.rs — cmd_* async functions take AppState + args and return Result<String>. Each command formats its own output; main.rs just prints.
• open_state_for_admin() — loads the manifest directly via Manifest::load() (no full Recovery, no segment-scan dedupe rebuild, no WAL replay). One-shot commands don't need the full startup cost.
• main.rs uses clap derive macros. The old server logic moves into run_server() — same code path, just behind a Command::Serve match arm.

Tests

10 new tests in tests/admin.rs, calling cmd_* directly (no subprocess):

• check_reports_manifest_summary
• check_deep_passes_for_valid_segments
• check_deep_fails_for_corrupt_segment — flips a byte mid-segment-file
• check_on_fresh_db_errors_with_clear_message
• inspect_segment_prints_meta_and_sample_rows
• inspect_segment_errors_for_unknown_id
• rebuild_rollups_drops_and_rewinds — tick → rebuild → verify state
• rebuild_rollups_rejects_invalid_dates
• verify_period_reports_match_for_sealed_rollup
• export_parquet_writes_file

Smoke test

$ cargo run --release -- --help
Embedded append-only usage database for AI billing

Usage: usagedb [OPTIONS] [COMMAND]

Commands:
  serve            Run the HTTP server (default)
  check            Print manifest summary
  rebuild-rollups  Drop rollup segments overlapping [from, to)
  inspect-segment  Read a specific segment
  verify-period    Compute raw vs rollup totals + drift
  export-parquet   Export every raw segment to a Parquet file
  ...

Test plan

• cargo build --all-targets clean with -D warnings
• cargo test --all-targets — 106 tests pass (was 96; +10)
• CLI smoke test (--help, all subcommands resolve)
• CI green

Dependency

clap = "4" with derive feature, ~1 MB compiled.

🤖 Generated with Claude Code