Repository navigation
#Tellstone v1.3.0
This release adds WAL encryption, snapshot compaction, and transparent plaintext-to-encrypted migration — bringing full at-rest encryption to the persistence layer with zero-downtime upgrades.
Highlights
- Encrypted WAL: Every write-ahead log record is encrypted with ChaCha20-Poly1305 when
--enable-encryptionis active. Encrypted WALs carry a 4-byteTSW\x01magic header and use counter-based nonces with a durable sidecar file (shard_NNN.nonce) for crash-safe nonce management. - Snapshot compaction: Fork-based background snapshots capture the full in-memory engine state to a compact binary file, then truncate the WAL. Configurable via
--snapshot-interval(time-based) and--snapshot-bytes(size-based). On startup, snapshots are loaded first, then only the post-snapshot WAL is replayed — dramatically reducing warm-up time. - Encrypted snapshots: Snapshot files store encrypted values when at-rest encryption is active. A 16-byte key fingerprint in the snapshot header prevents restoring a snapshot taken with a different encryption key.
- Plaintext-to-encrypted migration: Existing plaintext WALs are automatically migrated to encrypted format on startup when
--enable-encryptionis enabled. The migration replays all plaintext records, rewrites them as encrypted entries in an atomic temp-file swap, and resumes normal encrypted operation. No manual intervention required. - Zero-copy replay: New
SetFromBufferandSetRawengine methods eliminate allocations during WAL replay and encrypted snapshot restore, reducing GC pressure on cold start.
Install
APT (Debian/Ubuntu)
curl -fsSL https://saxy.github.io/tellstone-apt/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/tellstone.gpg
echo "deb [signed-by=/usr/share/keyrings/tellstone.gpg] https://saxy.github.io/tellstone-apt stable main" \
| sudo tee /etc/apt/sources.list.d/tellstone.list
sudo apt update && sudo apt install tellstoneHomebrew (macOS/Linux)
brew tap Saxy/tellstone-tap
brew install --cask tellstoneContainer images
# Production (distroless, single listener)
docker pull ghcr.io/saxy/tellstone:1.3.0
docker run -d -p 9988:9988 ghcr.io/saxy/tellstone:1.3.0
# Development (multi-stage, binary + RESP)
docker pull ghcr.io/saxy/tellstone:1.3.0-dev
docker run -d -p 9988:9988 -p 6379:6379 ghcr.io/saxy/tellstone:1.3.0-devBinary downloads
Pre-built binaries for Linux, macOS, and Windows (amd64/arm64) are available on the GitHub Releases page.
Build from source
git clone https://github.com/Saxy/Tellstone
cd Tellstone
task build # -> ./bin/tellstoneWhat's included
Binaries
| OS | Arch | Archive |
|---|---|---|
| Linux | amd64 | tellstone_v1.3.0_linux_amd64.tar.gz |
| Linux | arm64 | tellstone_v1.3.0_linux_arm64.tar.gz |
| macOS | amd64 | tellstone_v1.3.0_darwin_amd64.tar.gz |
| macOS | arm64 | tellstone_v1.3.0_darwin_arm64.tar.gz |
| Windows | amd64 | tellstone_v1.3.0_windows_amd64.zip |
Packages
.debfor Debian/Ubuntu (amd64, arm64)
Container images
ghcr.io/saxy/tellstone:1.3.0— production (distroless)ghcr.io/saxy/tellstone:1.3.0-dev— development (multi-stage)- Platforms:
linux/amd64,linux/arm64
Checksums
SHA-256 checksums are provided in checksums.txt.
Configuration
New flags and settings in v1.3.0 (all previous flags remain unchanged):
| Flag | Env | Default | Description |
|---|---|---|---|
--snapshot-interval |
TSD_SNAPSHOT_INTERVAL |
0 (disabled) |
Time between periodic snapshots (e.g. 5m) |
--snapshot-bytes |
TSD_SNAPSHOT_BYTES |
64MiB |
WAL size threshold that triggers a snapshot |
Both flags require --enable-persistence. Setting both to zero disables snapshot compaction entirely (the default).
Upgrading from v1.2.0
v1.3.0 is fully backward-compatible with v1.2.0 data files:
- Plaintext WALs (written by v1.2.0 without
--enable-encryption) are automatically migrated to encrypted format when--enable-encryptionis enabled. No manual steps required. - Snapshot files from v1.2.0 do not exist (snapshots are new in v1.3.0). On first startup, the full WAL is replayed into memory, and the first snapshot is created automatically if snapshots are configured.
- Encrypted WALs are not affected by the snapshot feature and continue to work as before.
- Nonce sidecar files (
shard_NNN.nonce) are created automatically on first encrypted write. Existing encrypted WALs recover the nonce counter from WAL replay.
If you are upgrading from a version earlier than v1.2.0, upgrade to v1.2.0 first.
Changelog
Features
- Encrypted WAL: ChaCha20-Poly1305 encryption for all WAL records (
TSW\x01magic header, counter-based nonces) - Nonce counter sidecar files (
shard_NNN.nonce) for crash-safe nonce durability - Snapshot compaction: fork-based background snapshots with atomic writes and WAL truncation
- Encrypted snapshots with key fingerprint header to prevent cross-key restores
- Automatic plaintext-to-encrypted WAL migration on startup (atomic temp-file swap, crash-safe)
- Time-based snapshot trigger (
--snapshot-interval) - Size-based snapshot trigger (
--snapshot-bytes) - Zero-copy
SetFromBufferfor WAL replay andSetRawfor encrypted snapshot restore - Two-phase startup: load snapshot first, then replay post-snapshot WAL
Bug fixes
CloseShardonly removes from shard map if the caller holds the current handle, preserving replacement handles during migration
Infrastructure
- Backward-compatibility unit tests for v1.2.0 plaintext WALs
- Manual backward-compatibility test script (8 phases, 26 assertions): v1.2.0→dev upgrade, crash recovery, plaintext-to-encrypted migration
Links
License
Apache-2.0