# SQLite Storage Schema for Runtime State Persistence in Apache Maka

> Explore the SQLite storage schema Apache Maka uses for runtime state persistence. Discover how it manages events, journal entries, and workspace versions with WAL mode and incremental migrations.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-08-27

---

**Apache Maka persists all runtime state—including events, tool journal entries, and workspace versions—in a single SQLite database managed by the runtime schema defined in [`sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-schema.ts), using Write-Ahead Logging (WAL) mode, foreign-key constraints, and incremental migrations to version 12.**

Apache Maka is an open-source framework for building reliable AI-native applications that require durable execution state. To guarantee crash-safe persistence of session data, tool invocations, and workspace history, Maka implements a comprehensive **SQLite storage schema for runtime state persistence** that enforces strict data integrity through foreign-key constraints, unique indexes, and ACID-compliant transactions configured for maximum durability.

## Core Database Architecture

The runtime schema organizes state into specialized tables that separate canonical events from operational metadata. All tables are defined in [`packages/storage/src/sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-runtime-schema.ts) and enforced with foreign-key constraints and CHECK clauses to prevent data corruption.

### Event and Tool Journal Storage

Three primary tables manage the execution history:

- **`runtime_events`** — Stores canonical, ordered events for sessions, runs, and turns. Contains `event_id`, `session_id`, `invocation_id`, `run_id`, `turn_id`, `event_seq`, `event_kind`, `payload_json`, and `committed_at` timestamps. This table serves as the immutable ledger of execution history.
- **`tool_journal_events`** — Records every tool call with its state, arguments hash, recovery mode flags, and a foreign key linking to the resulting entry in `runtime_events`.
- **`tool_operations`** — Provides a high-level view of tool operations, linking call and result events while maintaining uniqueness constraints on the combination of `invocation_id` and `provider_tool_call_id`.

### Workspace Versioning Tables

Maka implements immutable workspace history through three interconnected tables:

- **`runtime_workspace_epochs`** — Represents immutable workspace epochs that define points in history.
- **`runtime_workspace_versions`** — Stores version objects containing workspace state snapshots.
- **`runtime_workspace_heads`** — Maintains the current head pointer for each workspace, referencing the active `workspace_version_id`.

These tables enable **time-travel debugging** and deterministic replay by maintaining complete version lineage.

### Runtime Capabilities and Continuation

Supporting infrastructure tables enable advanced features:

- **`runtime_capabilities`** — Declares enabled capabilities (recovery, continuation, workspace versioning) and their schema versions.
- **`runtime_continuation_claims`** — Tracks continuation claims that allow one session to safely resume another’s execution state.
- **`runtime_storage_root_binding`** — Binds the database to a unique storage-root identifier (64 hexadecimal characters) to prevent cross-contamination of data roots.
- **`runtime_partial_snapshots`** and **`runtime_partial_segments`** — Store streamed or partial UI state incrementally, referenced by `stream_key` for efficient updates.
- **`runtime_session_event_ordinals`** — Provides fast lookup of the global ordinal position for each `event_id` within a session, optimizing event ordering queries.

**Note:** The legacy `headless_task_run_events` table was removed in schema version 12 during migration.

## Schema Versioning and Migration Strategy

The schema is strictly versioned with `SQLITE_RUNTIME_SCHEMA_VERSION = 12`. Maka applies changes incrementally through the **`migrateSqliteRuntimeDatabase()`** function located in [`packages/storage/src/sqlite-runtime-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-runtime-store.ts).

The migration system iterates through a versioned map of schema changes and updates the `PRAGMA user_version` after each successful step. This approach ensures that existing databases upgrade automatically when new application versions start, without manual intervention.

## Data Integrity and Durability Configuration

Maka configures SQLite for production-grade reliability through specific pragmas applied in `configureSqliteRuntimeDatabase()`:

**Write-Ahead Logging (WAL) Mode** — The database opens with WAL journal mode, allowing readers to operate concurrently with writers without blocking.

**Synchronous Full** — Setting `PRAGMA synchronous = FULL` ensures that SQLite waits for data to reach physical storage before reporting successful commits, preventing data loss during power failures or crashes.

**Foreign Key Enforcement** — All relationships between tables enforce referential integrity. For example, `tool_journal_events` maintains foreign keys to `runtime_events`, and workspace heads reference valid version IDs.

**Constraints and Indexes** — UNIQUE indexes prevent duplicate entries for tool operations and storage root bindings, while CHECK clauses validate data invariants at the database level.

## Working with the Runtime Schema

### Initializing the Database

To open or create the runtime database, use the utilities exported from [`sqlite-runtime-store.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-store.ts):

```typescript
import { open } from 'node:sqlite';
import { 
  configureSqliteRuntimeDatabase, 
  migrateSqliteRuntimeDatabase 
} from './sqlite-runtime-store';

const db = await open({
  filename: '/home/you/.local/share/maka/maka.db',
  driver: require('sqlite3').Database,
});

configureSqliteRuntimeDatabase(db);
migrateSqliteRuntimeDatabase(db);

```

### Recording Runtime Events

Insert canonical events into the `runtime_events` table to persist tool results or state changes:

```typescript
const eventId = crypto.randomUUID();

db.exec(`
  INSERT INTO runtime_events (
    event_id, session_id, invocation_id, run_id, turn_id,
    event_seq, event_kind, payload_json, committed_at
  ) VALUES (
    '${eventId}', 'sess-1', 'inv-1', 'run-1', 'turn-1',
    1, 'tool_result', '{"output":"Hello"}', ${Date.now()}
  );
`);

```

### Querying Workspace Versions

Retrieve the current workspace state by joining the heads table with version metadata:

```typescript
const row = db.prepare(`
  SELECT wv.*
  FROM runtime_workspace_heads wh
  JOIN runtime_workspace_versions wv
    ON wh.workspace_version_id = wv.workspace_version_id
  WHERE wh.workspace_id = ?
`).get('my-workspace');

console.log('Current version ID:', row.workspace_version_id);

```

### Graceful Shutdown

Always close the database connection to ensure all WAL checkpoints complete:

```typescript
await db.close();

```

## Summary

- Apache Maka uses a **versioned SQLite schema** (current version 12) defined in [`sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-schema.ts) to persist runtime state.
- The schema separates concerns into **event storage** (`runtime_events`), **tool journaling** (`tool_journal_events`), and **workspace versioning** (`runtime_workspace_versions`).
- **Foreign-key constraints**, UNIQUE indexes, and CHECK clauses ensure referential integrity across all tables.
- The database operates in **WAL mode** with `synchronous = FULL` for crash-safe durability.
- Migrations are handled automatically by **`migrateSqliteRuntimeDatabase()`** in [`sqlite-runtime-store.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-store.ts), incrementally upgrading schemas from older versions.

## Frequently Asked Questions

### What is the current schema version for Maka's SQLite runtime database?

The current schema version is **12**, defined as `SQLITE_RUNTIME_SCHEMA_VERSION` in [`sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-schema.ts). This version removed the legacy `headless_task_run_events` table and represents the latest incremental migration applied by `migrateSqliteRuntimeDatabase()`.

### How does Maka ensure data durability across application crashes?

Maka configures SQLite with **Write-Ahead Logging (WAL) mode** and **`PRAGMA synchronous = FULL`**, ensuring commits reach physical storage before acknowledgment. Combined with foreign-key constraints and ACID transactions, this prevents data corruption during unexpected terminations.

### What is the difference between `runtime_events` and `tool_journal_events`?

The `runtime_events` table stores the **canonical execution history** for all sessions and turns, while `tool_journal_events` specifically tracks **tool invocations** with additional metadata like arguments hashes and recovery modes. The tool journal references runtime events via foreign keys but focuses on operational details required for deterministic replay and debugging.

### How does the workspace versioning system work in the SQLite schema?

Workspace versioning uses three tables: `runtime_workspace_epochs` define immutable historical points, `runtime_workspace_versions` store actual state snapshots, and `runtime_workspace_heads` point to the current active version. This design enables Maka to maintain **immutable history** while supporting efficient queries for the latest workspace state through indexed joins.