Package com.tnsai.reliability

Class SqliteCheckpointStore

java.lang.Object
com.tnsai.reliability.SqliteCheckpointStore
All Implemented Interfaces:
CheckpointStore, AutoCloseable
public final class SqliteCheckpointStore extends Object implements CheckpointStore, AutoCloseable
Single-file SQLite-backed CheckpointStore (TNS-299). Aimed at personal-fleet workloads where one binary running on a laptop / NAS needs durable checkpoints without standing up Postgres.

File layout

One SQLite file at the configured path. Single table: 

 CREATE TABLE checkpoint (
   run_id        TEXT NOT NULL,
   step_index    INTEGER NOT NULL,
   captured_at   TEXT NOT NULL,
   state         BLOB NOT NULL,
   metadata_json TEXT NOT NULL,
   prev_id       TEXT,
   PRIMARY KEY (run_id, step_index)
 );

Concurrency

SQLite serialises writes at the file level; this class uses one connection per call (open/close per operation) so concurrent threads do not share a connection. Acceptable for personal-fleet throughput; a connection-pool variant is a follow-up if a workload demands it.

Optional dep

Requires org.xerial:sqlite-jdbc on the classpath. The dependency is declared optional=true in tnsai-core, so consumers that don't use this store don't pay for the JDBC driver.
Since:
0.10.0 (TNS-299)

  • Constructor Details

    • SqliteCheckpointStore

      public SqliteCheckpointStore(Path dbFile)

  • Method Details

    • save

      public void save(Checkpoint cp)
      Description copied from interface: CheckpointStore
      Persist a checkpoint. Returns when the entry is durable — see "Durability" in the type-level javadoc. Overwrites any prior checkpoint with the same (runId, stepIndex) pair so a step that retries can replace its earlier snapshot.
      Specified by:
      save in interface CheckpointStore

    • latest

      public Optional<Checkpoint> latest(String runId)
      Specified by:
      latest in interface CheckpointStore
      Returns:
      the highest-stepIndex checkpoint known for runId, or empty when the store has none.

    • history

      public List<Checkpoint> history(String runId)
      Specified by:
      history in interface CheckpointStore
      Returns:
      all checkpoints for runId, ordered by ascending stepIndex. Empty list when no checkpoints exist. Implementations may impose a soft cap when histories grow unbounded; document the cap in their javadoc when they do.

    • truncate

      public void truncate(String runId, Instant before)
      Description copied from interface: CheckpointStore
      Drop every checkpoint for runId captured strictly before before. Leaves the latest entry if it falls on or after the cutoff so resume continues to work. Used by retention jobs; not on the run's hot path.
      Specified by:
      truncate in interface CheckpointStore

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable