Skip to content
CQLite CQLite

Compaction & Maintenance

Compaction & Maintenance

Section titled “Compaction & Maintenance”

Status: Proposed direction.

The compaction enhancement issues have enough design depth to stand as public proposal pages. The direction is an offline, deterministic maintenance plane: Cassandra still owns live data directories, while CQLite can compact snapshots, backups, and CQLite-native table directories with explicit inputs and testable parity.

Public summary

Section titled “Public summary”

Standalone manager

The manager schedules compaction work over snapshots, backups, or CQLite-native tables without modifying live Cassandra-owned directories.

Deterministic inputs

Compaction should receive explicit time inputs such as gc-before and now-sec, instead of depending on ambient wall-clock behavior.

Parity first

The executor remains a k-way merge path with Cassandra-compatible output and byte/semantic parity checks.

Maintenance model

Section titled “Maintenance model”
flowchart LR
  Snapshot["Offline snapshot / CQLite-native table"]
  Planner["Pure compaction planner"]
  Executor["K-way merge executor"]
  Manager["Standalone manager"]
  Output["Valid Cassandra 5 SSTables"]

  Snapshot --> Planner --> Executor --> Output
  Planner --> Manager
  Manager --> Executor
The documented design separates planning, execution, and long-running management so each layer can be tested independently.
Mermaid source for the compaction maintenance model 
flowchart LR
  Snapshot["Offline snapshot / CQLite-native table"]
  Planner["Pure compaction planner"]
  Executor["K-way merge executor"]
  Manager["Standalone manager"]
  Output["Valid Cassandra 5 SSTables"]

  Snapshot --> Planner --> Executor --> Output
  Planner --> Manager
  Manager --> Executor

Deterministic merge inputs

Section titled “Deterministic merge inputs”
flowchart LR
  Schema["schema.cql gc_grace"]
  GcBefore["explicit gc-before"]
  NowSec["explicit now-sec"]
  Merge["deterministic merge"]
  Tests["parity harness"]

  Schema --> Merge
  GcBefore --> Merge
  NowSec --> Merge
  Merge --> Tests
Compaction correctness depends on explicit schema and time inputs that can be replayed in the parity harness.
Mermaid source for deterministic compaction inputs 
flowchart LR
  Schema["schema.cql gc_grace"]
  GcBefore["explicit gc-before"]
  NowSec["explicit now-sec"]
  Merge["deterministic merge"]
  Tests["parity harness"]

  Schema --> Merge
  GcBefore --> Merge
  NowSec --> Merge
  Merge --> Tests
IssueCoveragePublic interpretation
#905 compaction managerDirectBuild a standalone manager around a pure planner and bounded executor.
#1536 cqlite compact --now-sec defaultDirectKeep TTL expiry behavior explicit and deterministic for compaction parity.

Research sources

Section titled “Research sources”
Compaction manager design The main design for the standalone planner, executor, manager, crash-safety, and GC policy.
Compaction parity harness design The design trail for explicit gc-before and now-sec inputs in the compact command.
Read-path performance audit Related audit notes on merge inputs, gc-before, now-sec, and documentation honesty.

Primary issue links: