engine

Documentation

Overview

Package engine provides the public API for the StrataKV storage engine. It exposes a clean, thread-safe interface for key-value operations while encapsulating the underlying Log-Structured Merge (LSM) tree mechanics, MemTables, and Write-Ahead Logging (WAL).

Index

• type DB
  • func Open(dataDir string) (*DB, error)
  • func (db *DB) Close() error
  • func (db *DB) Compact() error
  • func (db *DB) Delete(key []byte) error
  • func (db *DB) Get(key []byte) ([]byte, bool)
  • func (db *DB) Put(key, val []byte) error

Types

type DB

type DB struct {
	// contains filtered or unexported fields
}

DB represents an active instance of the StrataKV storage engine. It manages the active MemTable, Write-Ahead Log, and orchestrates disk flushes. DB is thread-safe and safe for concurrent use across multiple goroutines.

func Open

func Open(dataDir string) (*DB, error)

Open initializes and mounts the StrataKV engine at the specified directory. If the directory does not exist, it will be created. During initialization, Open will automatically recover any un-flushed data by replaying the Write-Ahead Log (WAL) and reconstruct the in-memory Bloom filters for fast reads.

func (*DB) Close

func (db *DB) Close() error

Close safely shuts down the database. It ensures that the Write-Ahead Log (WAL) is properly synchronized and closed, preventing data corruption. This should always be called (usually via defer) before an application exits.

func (*DB) Compact

func (db *DB) Compact() error

Compact triggers a manual background compaction process. It scans all immutable segment files on disk, merges them, and purges stale data (overwritten keys and tombstones). This reclaims disk space and reduces read amplification by consolidating fragmented segments into a single file.

func (*DB) Delete

func (db *DB) Delete(key []byte) error

Delete marks a key as deleted using a tombstone. The key is not immediately removed from disk; instead, a tombstone record is appended to the WAL and MemTable. The physical deletion occurs during the next Compaction cycle.

func (*DB) Get

func (db *DB) Get(key []byte) ([]byte, bool)

Get retrieves the value associated with a given key. It follows a hierarchy of reads: checking the MemTable first, then probing the in-memory Bloom filters to prune disk I/O, and finally searching the immutable segment files on disk. Returns false if the key does not exist or was deleted.

func (*DB) Put

func (db *DB) Put(key, val []byte) error

Put inserts or updates a key-value pair in the database. The operation is synchronous; it first appends the entry to the WAL for strict durability before mutating the in-memory MemTable.