LiteStash (Elixir)

High-performance key-value store using SQLite static lock sharding.

This is the native Elixir client for the LiteStash database ecosystem. It acts as a high-performance Host that drives the litestash-engine storage appliance via a strictly typed MessagePack protocol.

⚠️ Status: Pre-Alpha / Namespace Reservation This package is currently being architected. The API below is provisional.

Architecture

LiteStash uses Application-Side Static Lock Sharding.

1. The Client (Elixir) determines the routing topology (hashing keys to specific shard files).
2. The Engine (Python/Native Binary) manages the ACID persistence via SQLAlchemy/SQLite.
3. The Bridge communicates via Standard I/O using binary MessagePack frames.

This architecture allows high-concurrency writes by distributing lock contention across multiple deterministic SQLite files.

Installation

Add litestash to your list of dependencies in mix.exs:

def deps do
  [
    {:litestash, "~> 0.1.0-alpha.1"}
  ]
end

System Requirements

This library requires the LiteStash Engine to be present in your system path.

# Install the engine 
pip install litestash-engine

Usage (Planned API)

# Start the connection (spawns the engine sidecar)
{:ok, pid} = LiteStash.start_link(data_dir: "./data")

# Write a value (Primitive, Map, List, or Vector)
# Routing and sharding happen automatically based on the key hash.
:ok = LiteStash.set("user:1001", %{name: "Alice", score: 99})

# Read a value
{:ok, val} = LiteStash.get("user:1001")
# => %{"name" => "Alice", "score" => 99}

# Vector Storage (Stored as Arrays)
:ok = LiteStash.set("vec:1", [0.1, 0.5, 0.9])

The Universal Data Contract

All data written by this client is byte-for-byte compatible with the Python and Rust implementations.

• Hashing: BLAKE2b-512 (Canonical/Raw).
• Protocol: MsgPack with 4-byte Big-Endian framing.
• Schema: Universal 5-column SQLite layout.

License

Apache 2.0