thunderstrike

Python client for the thunderstrike key-value database: a pool of pipelined TLS 1.3 connections behind a small blocking API.

The wheel carries the compiled client library. Nothing to compile on install, and no dependencies beyond the standard library (it uses ctypes).

Install

pip install thunderstrike

Python 3.8 or newer, on Linux x86-64 / ARM64 (glibc 2.17 or newer) or Windows x86-64. macOS wheels come in a later release.

Quick start

The server speaks TLS 1.3 only. The client needs the CA certificate that issued the server's certificate (docker/tls/ca.crt in the server's kit) and a DNS name that certificate carries (localhost unless the server was set up with other THUNDERSTRIKE_TLS_NAMES).

from thunderstrike import Thunderstrike

with open("ca.crt", "rb") as f:
    ca = f.read()

with Thunderstrike("127.0.0.1:7380",
                   tls_server_name="localhost",
                   tls_ca_pem=ca) as db:
    db.set(b"user:1", b"ada")
    print(db.get(b"user:1"))   # b'ada'
    print(db.get(b"nope"))     # None

Give it one address. The client asks that server for the cluster layout and connects to every core (core c listens on port 7380 + c), so those ports must be reachable too.

tls_server_name is sent as SNI and checked against the certificate, so it is the name the certificate was issued for, not necessarily the host you dial. There is no way to turn verification off.

Operations

Keys and values are bytes. A key is at most 65,535 bytes; an empty value is refused. Keys do not expire: the server does not support expiry, and refuses a set with a non-zero ttl_ms as malformed.

db.set(b"k", b"v")
db.get(b"k")                 # b"v", or None when absent
db.get(b"k", b"fallback")    # a default for a miss
db.exists(b"k")              # True / False
db.append(b"k", b"-more")    # appends (creates if absent); returns the new length
db.delete(b"k")              # True if it was there
db.ping()

# Mapping-style access
db[b"k"] = b"v"
value = db[b"k"]             # raises NotFound on a miss
del db[b"k"]                 # raises NotFound on a miss
b"k" in db                   # exists()

Batches

For more than one key, use the batch calls. They put every request on the wire before waiting for any answer, so n keys cost one round trip instead of n.

db.mset({b"a": b"1", b"b": b"2"})           # or a list of (key, value) pairs
db.mget([b"a", b"b", b"missing"])            # [b"1", b"2", None]
db.mdelete([b"a", b"b", b"missing"])         # [True, True, False]

Threads

One Thunderstrike instance is safe to share across threads, and should be: it is a connection pool. The GIL is released during every call, so a thread waiting on the server does not block the others. The API is blocking; there is no asyncio interface in this release (run calls in a thread pool from async code).

Errors and retries

Every failure raises ThunderstrikeError (or a subclass) with:

• code: the numeric status (positive from the server, negative from the client).
• retry_class: whether sending the request again is sound.
• detail: the specific cause when there is one, e.g. the TLS reason.

The client has already retried Busy answers (every operation but delete) and dropped connections (idempotent operations) before it raises.

Subclasses: NotFound, Timeout, Disconnected, Closed, Busy, ServerOutOfMemory, StorageExhausted, ServerError, TlsError.

import thunderstrike

try:
    db.set(b"k", b"v")
except thunderstrike.Busy:
    ...  # not applied; safe to try again later
except thunderstrike.ThunderstrikeError as e:
    print(e.code, e.retry_class, e.detail)

Configuration

All keyword-only, all optional except the TLS pair:

db.stats() returns pool counters (connections, requests, bytes, reconnects). db.endpoints() is the number of server cores connected, db.shards() the number of shards.

The library loads from inside the package. To use another build, set THUNDERSTRIKE_CLIENT_LIB to its path.

Links

• Source and issues: https://github.com/TheManhattanProject/thunderstrike-client
• Server image: https://hub.docker.com/r/sbansal793/thunderstrike
• Clients for other languages: see the repository README.

License

Proprietary, free to use: see the LICENSE file shipped in the package. You may build this library into your own applications and ship it as part of them.

Copyright (c) 2026 SHORTSQUEEZE PRIVATE LIMITED.