GET / READ
Return the value.
A cached value can be returned directly. On a cache miss, the engine looks up the value and reads it from storage.
A value read from disk is decrypted and may be admitted to the cache.
ARCHITECTURE
Local execution. Room for large values. Writes that survive a restart.
See how Thunder brings CPU, memory, and persistent storage together.
Each reactor handles its own shard range.
Dedicated arenas hold working data and cached values.
The journal reaches disk before success is returned.
01 / THE WHOLE ENGINE
Shard 0892 → reactor R06 → port 7386
YOUR APPLICATION
Starts with one address. Discovers shard ranges and their serving ports.
THE OWNING REACTOR
Port 7386
Handles requests for its shard range.
Request space + cached values
Stored values and index
On disk before write acknowledgement
Owns logical shards 768–895
One mark per shard. The highlighted mark belongs to the selected key. Changing the allocation moves ownership; it does not change the key’s shard.
A local illustration using Thunder’s key hash and uniform CPU topology. Changing the allocation changes ownership; the key’s logical shard stays fixed. No database connection is made.
02 / EXECUTION
Keep the request with the reactor responsible for its data. Its foreground execution, local arena, and asynchronous I/O form the working path.
Requests for the owned shard range
Shared by maintenance and journal work
GET / READ
A cached value can be returned directly. On a cache miss, the engine looks up the value and reads it from storage.
A value read from disk is decrypted and may be admitted to the cache.
SET / WRITE
The owning reactor handles the write using its arena and storage. Its journal record reaches disk before success is returned.
The official client starts with one address, obtains ranges, ports, and a routing epoch through DISCOVER, then connects directly to the owners. Every discovered port must be reachable on the same host and port number.
03 / LARGE VALUES
Store a complete application object under one key, including values of 512 MiB and more. Size each reactor’s arena for the objects and concurrent requests it will handle.
This arena serves the reactor’s requests and cached values. The example below shows the value copies needed by one 512 MiB write within it.
MEMORY
Arenas are fully resident. Budget arena bytes × reactor count, then add process overhead. The documented setting for 512 MiB values is THUNDERSTRIKE_ARENA_BYTES=4294967296.
NETWORK + DISK
The official client pipelines requests and multiplexes large values. Plan disk capacity at peak live bytes / 0.75, plus one 4 GiB chunk for workloads with values of 512 MiB or more.
04 / DURABILITY
Every acknowledged write has a journal record on disk. The documented durability contract covers acknowledged writes surviving a crash or power cut.
The owning reactor handles the request.
The journal record is durable before success is returned.
Your application receives the successful response.
AFTER A RESTART
Start from the durable checkpoint.
Replay journal records beyond it.
Accept connections after recovery.
A clean stop drains in-flight requests and checkpoints the index. After a crash, recover with the previous reactor count before changing the allocation.
Recovery and operating procedures05 / OPERATING REFERENCE
A self-hosted database with an explicit CPU allocation, resident arenas, and persistent storage on your host.
Linux kernel 6.8+, Docker Compose v2, and ext4 or XFS. Use AVX2-capable x86-64 hardware or ARMv8.2 with Crypto Extensions.
Host requirementsSet an even physical-core budget from 2 through 1,024. The server derives the reactor count from the actual usable topology, affinity, and CPU quota.
| Physical cores | Threads / core | Reactors | Ports |
|---|---|---|---|
| 2 | 1 | 1 | 7380 |
| 2 | 2 | 2 | 7380–7381 |
| 8 | 1 | 4 | 7380–7383 |
| 8 | 2 | 8 | 7380–7387 |
On mixed CPU sets, complete sibling pairs are used first, then single-threaded cores are paired. Reactor counts can be odd. Shard ranges divide as evenly as possible; the shard count stays fixed at 1,024.
The automatic arena is 4 GiB for one reactor, or 2 GiB per reactor for multiple reactors. Allow additional process overhead. Explicitly use 4 GiB per reactor for 512 MiB values.
Calculate resident arena RAMTLS 1.3 protects every client connection. Clients verify the server’s CA-issued Ed25519 identity; mutual TLS can be configured. Values are encrypted at rest, with a passphrase-protected keystore.
Certificates and encryptionStop the server or take a filesystem snapshot, then back up the whole data volume, including its keystore. Retain the passphrase securely. A live file copy is not a consistent backup.
Backup and restore guidanceProvision space beyond live values and plan backups separately. When the volume fills, writes return StorageExhausted; the server continues serving reads.
CHANGING THE ALLOCATION
After a clean stop, change the core budget or starting port, regenerate the port mapping, then restart. The routing epoch advances when ownership or ports change.
FROM THE ENGINE TO YOUR APPLICATION
Set up Thunder, verify your first write and read, then test the payloads and concurrency your application needs.