LLKV Runtime

Work in Progress

llkv-runtime coordinates the end-to-end execution of SQL statements for the LLKV stack. It bridges plans, storage, and MVCC so the higher-level SQL engine can remain stateless.

Responsibilities

• Execute all statement types (DDL, DML, transaction control, and queries) using the lower-layer crates.
• Inject and maintain MVCC columns (row_id, created_by, deleted_by) across every mutation.
• Manage session lifecycle, namespaces, and transaction snapshots for both auto-commit and explicit transactions.
• Orchestrate plan evaluation by invoking llkv-executor for streaming SELECT workloads while handling side effects elsewhere.

Transaction Model

• Built on llkv-transaction to allocate monotonic transaction IDs and track commit watermarks.
• Sessions capture a TransactionSnapshot at BEGIN; visibility rules follow MVCC snapshot isolation.
• Auto-commit statements run with TXN_ID_AUTO_COMMIT = 1, observing the latest committed snapshot without staging.
• Explicit transactions maintain a durable catalog snapshot and replay staging operations on commit after conflict checks.

Dual-Context Execution

• Each active transaction holds two runtime contexts:
  • Persistent context (RuntimeContext<BoxedPager>): Operates on existing tables directly, tagging all writes with MVCC metadata.
  • Staging context (RuntimeContext<MemPager>): Buffers tables created inside the transaction so they remain isolated until commit.
• On commit the runtime replays staged operations into the persistent context after [TxnIdManager] confirms the commit and advances the global watermark.
• Rollback drops the staging context and clears tracked operations, so uncommitted objects never leak.

Statement Dispatch

• The runtime routes statements produced by llkv-plan into subsystem-specific executors:
  • SELECT plans stream through llkv-executor, returning Arrow RecordBatches.
  • Mutations append Arrow batches via llkv-table which delegates to llkv-column-map.
  • Catalog updates leverage the system catalog (SysCatalog, table 0) to persist schema metadata alongside user data.
• Result reporting uses enums in llkv-result so callers receive structured responses (Select, Insert, CreateTable, etc.).

Integration Points

• Consumed by llkv-sql to power SqlEngine APIs.
• Supplies the session handle returned by SqlEngine::session() for advanced transaction control.
• Provides helper hooks used by the SLT harness to expose detailed query statistics when LLKV_SLT_STATS=1 is set.

License

Licensed under the Apache-2.0 License.