skaidb v0.320.9

Installing skaidb

Every release is published as compiled, signed packages at repo.dsys.org. Every bundle ships two binaries:

  • skaidb — the database server (binary + REST endpoints, clustering).
  • skaidbsh — the unified shell and admin client: an interactive SQL shell that connects over the network (with nearest-node selection and failover), plus cluster membership and configuration commands (cluster, config, status, metrics) — see CLUSTERING.md. It can also open a data directory directly with --local for offline use.

skaidb-mcp ships separately, as its own package and its own archive (skaidb-mcp_X.Y.Z_amd64.deb, skaidb-mcp-X.Y.Z-<target>.tar.gz, and a raw .exe on Windows). It is the MCP server that exposes a database to an LLM, and it belongs on the machine running the LLM client — a laptop or workstation — which is usually not a database host. Installing it does not install a server, and installing a server does not install it.

Replace X.Y.Z below with the release you want (e.g. 0.320.9).

Contents

System requirements

Minimum Recommended
CPU 1 core (x86-64 or ARM64) 2+ cores
RAM 512 MB 2 GB+
Disk 1 GB free beyond your data SSD/NVMe, 2–3× your expected data size
  • RAM: the default memtable alone budgets 256 MB. On boxes at or near the minimum, set storage.memory_target ("auto", or an explicit "256MB"/"2GB") so the memtable, read cache, search-index writer heaps and the per-statement scan ceilings share one budget sized to this node instead of assuming a bigger machine. "auto" reads the smallest memory limit that applies to the process — its own cgroup (a MemoryMax= on the unit counts), every parent cgroup, the container — so a service gets its own cap rather than its container's or the host's; an explicit target above that limit is clamped to half of it and logged with both numbers. That cap is only honest if the host can actually give it: a container limit above the host's free memory makes the host reclaim from the node. The node then releases its caches when it sees a memory stall (PSI) and logs memory pressure from outside this process, but on an over-committed host set an explicit memory_target below what the host can really spare. A 3-node test cluster runs comfortably in 1 GB per node.
  • Disk: LSM compaction needs transient headroom (it rewrites overlapping sstables before deleting the old ones), the WAL adds its own footprint, and a full-text SEARCH INDEX typically adds another 0.5–1× the size of the text it indexes — hence 2–3× your expected live data. Watch real usage with SHOW STATUS (disk_bytes, wal_bytes, search.*.disk_bytes).
  • Cluster: the same figures apply per node; total storage scales with the replication factor (default 3 — every row is stored RF times).

When the disk fills up

skaidb keeps running on a full volume; it stops taking new data. Below the iwm.disk_low_watermark of free space (default min(5%, 2GB)) — or the moment any write actually fails with No space left on device — the node enters IWM state 3: /ready answers 503, /status shows iwm.disk_write_block: true, and INSERT/UPDATE/remote-write get the retryable error disk full: node is blocking writes, retry (drivers treat it like memory shedding: back off and retry, or fail over on a cluster). Reads, DELETE, DDL, retention and compaction keep working: the node gives back a reserve file it keeps for exactly this (iwm.disk_reserve, 64 MB by default) so tombstones and compaction output have somewhere to go. A write that had already committed is never lost to a full disk — it is in the WAL and the memtable, and the flush it triggered is retried once space exists. Restarting on a full disk is safe.

To recover, free space and wait ~10 s: drop or truncate a table you can spare, lower a partitioned table's ttl so whole partitions drop, delete files that are not skaidb's, or grow the volume. Once free space is back above iwm.disk_resume_watermark (default twice the low watermark) plus the reserve, the node logs writes resumed, /ready returns 200 and blocked clients' retries succeed. Metrics to watch: skaidb_iwm_state, skaidb_iwm_disk_enospc_trips_total (non-zero = the watermark was too low for this node's compaction outputs; raise it) and skaidb_storage_build_failures_total.

Which download do I want?

Platform CPU Recommended Also available
Debian, Ubuntu, Mint, … x86-64 skaidb_X.Y.Z_amd64.deb tarball
Debian, Ubuntu, … ARM64 skaidb_X.Y.Z_arm64.deb tarball
Fedora, RHEL, Rocky, Alma, openSUSE x86-64 skaidb-X.Y.Z-1.x86_64.rpm tarball
Fedora, RHEL, … ARM64 skaidb-X.Y.Z-1.aarch64.rpm tarball
Alpine / "any Linux, no deps" x86-64 skaidb-X.Y.Z-x86_64-unknown-linux-musl.tar.gz (static) —
Alpine / "any Linux, no deps" ARM64 skaidb-X.Y.Z-aarch64-unknown-linux-musl.tar.gz (static) —
Any Linux (glibc) x86-64 skaidb-X.Y.Z-x86_64-unknown-linux-gnu.tar.gz .deb/.rpm
Any Linux (glibc) ARM64 skaidb-X.Y.Z-aarch64-unknown-linux-gnu.tar.gz .deb/.rpm
macOS Apple Silicon (M-series) skaidb-X.Y.Z-aarch64-apple-darwin.dmg .tar.gz
macOS Intel skaidb-X.Y.Z-x86_64-apple-darwin.dmg .tar.gz
Windows x86-64 skaidb-X.Y.Z-x86_64-pc-windows-msvc.zip standalone .exe
Docker / compose any build from docker/ (DOCKER.md) — every config key as a SKAIDB_* env var —

What releases actually publish today: the .deb and .rpm for x86-64 and ARM64 (from the package repository), and the static musl tarball for x86-64 (from repo.dsys.org/dl/skaidb). The glibc tarballs, the macOS builds and the Windows build are not currently produced — on those platforms build from source, or run the server under Docker.

Not sure of your CPU? uname -m on Linux/macOS (x86_64 → amd64/x86_64, aarch64/arm64 → ARM64). On Apple Silicon Macs uname -m prints arm64.

Package repository (apt / dnf)

Every release is also published to a signed package repository at repo.dsys.org, so apt/dnf handle installs and upgrades (no manual downloads):

# Debian / Ubuntu
curl -fsSL https://repo.dsys.org/pubkey.gpg \
  | sudo tee /etc/apt/keyrings/repo-dsys.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/repo-dsys.gpg] https://repo.dsys.org/deb stable main" \
  | sudo tee /etc/apt/sources.list.d/repo-dsys.list
sudo apt update && sudo apt install skaidb

# Fedora / RHEL / Rocky / Alma
sudo tee /etc/yum.repos.d/repo-dsys.repo <<'EOF'
[repo-dsys]
name=repo.dsys.org
baseurl=https://repo.dsys.org/rpm
enabled=1
gpgcheck=0
repo_gpgcheck=1
gpgkey=https://repo.dsys.org/pubkey.gpg
EOF
sudo dnf install skaidb

Upgrades are then just apt upgrade / dnf upgrade (in a cluster, upgrade one node at a time). The sections below cover installing directly from downloaded package files instead.

Each release includes SHA256SUMS covering every asset, and SHA256SUMS.minisig — a minisign signature over it. Verifying the signature and then the checksums authenticates every asset. The skaidb release public key:

RWRy23pp77/D3ct8mR6AjZBwdpha5AveYo3tvqcZf+ls9JeMRODnm92C

# 1. The signature (minisign, or rsign2 — same key/signature format).
minisign -Vm SHA256SUMS -P RWRy23pp77/D3ct8mR6AjZBwdpha5AveYo3tvqcZf+ls9JeMRODnm92C

# 2. The checksums.
# Linux
sha256sum -c SHA256SUMS --ignore-missing

# macOS
shasum -a 256 -c SHA256SUMS --ignore-missing

The trusted comment inside the signature names the release tag it was made for — minisign -Vm prints it on success.

# Windows (PowerShell): compare the printed hash to the matching line in SHA256SUMS
Get-FileHash .\skaidb-X.Y.Z-x86_64-pc-windows-msvc.zip -Algorithm SHA256
Select-String skaidb-X.Y.Z-x86_64-pc-windows-msvc.zip .\SHA256SUMS

A ... : OK line (Linux/macOS) means the file is intact. (Releases are not GPG-signed; verify over HTTPS from the official repo.)

Linux

The .deb/.rpm install skaidb and skaidbsh to /usr/bin and drop the license + README under /usr/share/doc/skaidb/.

Debian / Ubuntu (.deb)

# x86-64
sudo apt install ./skaidb_X.Y.Z_amd64.deb
# ARM64
sudo apt install ./skaidb_X.Y.Z_arm64.deb

apt install ./file.deb resolves dependencies. On older systems without that syntax, use sudo dpkg -i skaidb_X.Y.Z_amd64.deb (then sudo apt -f install if it reports missing deps).

Fedora / RHEL / CentOS / Rocky / Alma (.rpm)

# x86-64
sudo dnf install ./skaidb-X.Y.Z-1.x86_64.rpm
# ARM64
sudo dnf install ./skaidb-X.Y.Z-1.aarch64.rpm

On older systems use sudo yum install ./skaidb-X.Y.Z-1.x86_64.rpm, or sudo rpm -i skaidb-X.Y.Z-1.x86_64.rpm for a dependency-free install.

openSUSE (.rpm)

sudo zypper install ./skaidb-X.Y.Z-1.x86_64.rpm

Any distro — tarball (glibc)

For distros where you'd rather not use a package, or to install without root:

tar xzf skaidb-X.Y.Z-x86_64-unknown-linux-gnu.tar.gz   # → skaidb, skaidbsh, LICENSE, README.md
sudo install -m 0755 skaidb skaidbsh /usr/local/bin/
# …or, no root, into your user path:
mkdir -p ~/.local/bin && install -m 0755 skaidb skaidbsh ~/.local/bin/

Use the aarch64-unknown-linux-gnu tarball on ARM64. The glibc build needs a reasonably recent glibc; if you hit a GLIBC_… error, use the musl build below.

Any distro / Alpine — static musl tarball

A fully static build with no libc dependency — works on Alpine and anywhere the glibc build won't. Tarballs are published at repo.dsys.org/dl/skaidb — one directory per version, plus latest/, each with a SHA256SUMS signed by the same key that signs the apt/dnf metadata:

V=X.Y.Z
base="https://repo.dsys.org/dl/skaidb/$V"
curl -fLO "$base/skaidb-$V-x86_64-unknown-linux-musl.tar.gz"
curl -fLO "$base/SHA256SUMS"
sha256sum -c --ignore-missing SHA256SUMS

tar xzf "skaidb-$V-x86_64-unknown-linux-musl.tar.gz"
sudo install -m 0755 skaidb skaidbsh /usr/local/bin/

To check the signature too, import the repo key (curl -fsSL https://repo.dsys.org/pubkey.asc | gpg --import) and run gpg --verify SHA256SUMS.asc SHA256SUMS.

Run as a service (systemd)

The .deb / .rpm install a systemd unit and a default config, and create an unprivileged skaidb system account that owns the data directory:

Path Purpose
/lib/systemd/system/skaidb.service the service unit
/etc/skaidb/skaidb.toml main configuration (not overwritten on upgrade)
/etc/default/skaidb optional SKAIDB_* env overrides (win over the file)
/var/lib/skaidb data directory, owned by the skaidb user

Installing does not auto-start the server, so you can configure it first:

sudoedit /etc/skaidb/skaidb.toml          # set bind_addr, cluster seeds, etc.
sudo systemctl enable --now skaidb        # start now and on boot
systemctl status skaidb
journalctl -u skaidb -f                    # follow the logs

For a cluster, the per-host bits are easiest as env overrides in /etc/default/skaidb (consistency levels are case-insensitive):

SKAIDB_BIND_ADDR=192.168.7.3
SKAIDB_SEEDS=192.168.7.3:7100,192.168.7.4:7100
SKAIDB_REPLICATION_FACTOR=2
SKAIDB_DEFAULT_READ_CONSISTENCY=ALL
SKAIDB_DEFAULT_WRITE_CONSISTENCY=ALL

Then sudo systemctl restart skaidb — after a package upgrade, run skaidb --config /etc/skaidb/skaidb.toml --check-config first: the new binary validates the live file (unknown keys warn, out-of-range values and bad addresses refuse) without touching the data directory. Health is at http://<bind_addr>:7080/health and metrics at :9090/metrics (see METRICS.md). Uninstalling leaves /var/lib/skaidb and the skaidb account in place so data is never destroyed by a package removal.

Memory limits. Memory protection is in-process: memory_target sizes the caches against the limit the process runs under (the smallest memory.max from the service's cgroup up to the container, else system RAM), and the memory guard releases caches at 75% and sheds client writes at 85% of that limit (see CLUSTER_OPERATIONS.md, "Memory-pressure release and load shedding"). The package sets no kernel memory.high on the service — the unit says MemoryHigh=infinity and ships no drop-in — because memory.high is charged with page cache: on a node whose data exceeds its RAM a value below the container's limit holds the service at the line permanently, the kernel reclaims in the allocating thread and can put it to sleep while it holds a lock. systemctl show skaidb -p MemoryHigh prints infinity and the service cgroup's memory.high reads max. An upgrade removes the /etc/systemd/system/skaidb.service.d/50-memory-high.conf an older package generated (only that generated file; other drop-ins are left alone) and reloads systemd before it restarts the service, so the one restart of the upgrade runs without the limit. To add a kernel-side limit of your own, put MemoryMax= (or MemoryHigh=) in a drop-in (systemctl edit skaidb): the guard measures usage and stall pressure on the container unless the service, or a slice above it, carries its own memory.max — then on that cgroup — and a memory_target above such a limit is clamped to it at start.

Thread stacks (RUST_MIN_STACK). Every connection, request and maintenance thread is a plain Rust thread, and the server starts them with 8 MiB stacks (address space only; pages are committed as they are touched) so that a statement at the SQL nesting cap, its evaluation and the frames below them never run out of stack. Setting RUST_MIN_STACK (bytes) in /etc/default/skaidb or the unit overrides that default; the server only fills it in when it is unset.

Log rotation. The package installs /etc/logrotate.d/skaidb (copytruncate, daily, maxsize 256M, rotate 140, maxage 14, compressed) for every file under /var/log/skaidb — skaidb.log, and query.log, slow.log, error.log, login.log when [observability] splits them out. The server keeps its log files open in append mode and reopens nothing on a signal, which is why the policy copies and truncates in place; no restart or reload is involved. Because the distro's logrotate timer runs only daily, the package also enables skaidb-logrotate.timer, which runs skaidb's policy hourly so maxsize acts within the hour (query logging is on by default and a busy node writes 100+ MB of query.log an hour). The policy keeps 14 days of every log: a quiet log rotates daily and maxage 14 drops rotations older than that; a busy one rotates each time it passes 256 MB, and 140 rotations cover 14 days at 100 MB an hour. Disk budget: about 5 GB per log at worst — 140 compressed rotations (masked SQL compresses 8:1 or better, ≤ 32 MB each) plus two uncompressed files, the live one and the newest rotation — which in practice only query.log approaches. A log written faster than 256 MB an hour rotates once per hourly run, so its rotations are larger and 140 of them span fewer than 14 days; where /var/log cannot hold that, lower rotate in the policy file (a conffile: your edit survives upgrades) or reduce query logging. logrotate is a recommended, not required, package; without it the files grow until you rotate them.

For the tarball installs above there is no service unit; either run skaidb under your own process manager or copy the unit from the repo's packaging/skaidb.service and adjust paths.

macOS

Builds are provided for both Apple Silicon (aarch64-apple-darwin) and Intel (x86_64-apple-darwin). The binaries are not notarized, so macOS Gatekeeper will warn the first time — clear the quarantine flag (shown below) or right-click the binary in Finder and choose Open.

Disk image (.dmg)

# Mount, copy the binaries to a directory on your PATH, unmount.
hdiutil attach skaidb-X.Y.Z-aarch64-apple-darwin.dmg
vol="/Volumes/skaidb X.Y.Z"
sudo cp "$vol/skaidb" "$vol/skaidbsh" /usr/local/bin/
hdiutil detach "$vol"

# Clear the quarantine flag so Gatekeeper allows them to run.
sudo xattr -d com.apple.quarantine /usr/local/bin/skaidb /usr/local/bin/skaidbsh

(Use the x86_64-apple-darwin dmg on Intel Macs.) There is no Homebrew tap.

Tarball (macOS)

tar xzf skaidb-X.Y.Z-aarch64-apple-darwin.tar.gz
sudo install -m 0755 skaidb skaidbsh /usr/local/bin/
sudo xattr -d com.apple.quarantine /usr/local/bin/skaidb /usr/local/bin/skaidbsh

Windows

The binaries are not code-signed, so SmartScreen may warn on first run ("More info" → "Run anyway").

Zip archive

  1. Download skaidb-X.Y.Z-x86_64-pc-windows-msvc.zip and extract it (it contains skaidb.exe, skaidbsh.exe, LICENSE, README.md).
  2. Move the folder somewhere stable (e.g. C:\Program Files\skaidb) and add it to your PATH:
# Unblock the downloaded zip, extract, and add to PATH (per-user).
Unblock-File .\skaidb-X.Y.Z-x86_64-pc-windows-msvc.zip
Expand-Archive .\skaidb-X.Y.Z-x86_64-pc-windows-msvc.zip -DestinationPath "$env:LOCALAPPDATA\skaidb"
[Environment]::SetEnvironmentVariable(
  "Path", $env:Path + ";$env:LOCALAPPDATA\skaidb", "User")

Open a new terminal so the PATH change takes effect.

Standalone .exe

If you only want one binary, download skaidb-X.Y.Z-x86_64-pc-windows-msvc.exe (server) and/or skaidbsh-X.Y.Z-x86_64-pc-windows-msvc.exe, rename to skaidb.exe / skaidbsh.exe, and put them on your PATH.

Binary-only (no package, no build)

If you just want the executable and nothing else (no system package, no system files), grab the tarball/zip for your platform and extract only the binary you need:

# Linux/macOS — extract just the server binary into the current directory.
tar xzf skaidb-X.Y.Z-x86_64-unknown-linux-gnu.tar.gz skaidb
./skaidb --version

# Windows — the standalone .exe is already binary-only; just run it.
.\skaidb-X.Y.Z-x86_64-pc-windows-msvc.exe --version

The binaries are self-contained: they create and manage their own data directory and have no runtime dependencies beyond the OS (the musl build has none at all).

Run it / verify the install

skaidb --version
skaidbsh --version

Start the server (creates the data dir if missing):

skaidb --data-dir ./data --bind-addr 127.0.0.1 --rest-port 7080
# Every option is also a flag/env var; print the effective config and exit:
skaidb --print-config
# Validate a config (file + env + flags) exactly as a start would, without
# starting: exit 0 = it would start, 1 = the fatal issues printed on stderr.
skaidb --config /etc/skaidb/skaidb.toml --check-config

Query it over REST:

curl -X POST 127.0.0.1:7080/query -d "CREATE TABLE users (PRIMARY KEY (id))"
curl -X POST 127.0.0.1:7080/query -d "INSERT INTO users (id, name) VALUES (1, 'ada')"
curl -X POST 127.0.0.1:7080/query -d '{"sql":"SELECT * FROM users"}'
curl 127.0.0.1:7080/metrics

Or use the shell. It connects over the network by default (picking the nearest reachable node, with failover); --local opens a data directory directly with no server:

skaidbsh --host 127.0.0.1 -e "SELECT COUNT(*) FROM users"
skaidbsh --host 127.0.0.1          # interactive REPL
skaidbsh --local ./data            # offline, against the data dir

Optional listeners: enabling [mqtt] binds 1883 (plain/WebSocket) and, with client TLS on, 8883 — open them in the firewall only if IoT clients connect from outside the host (see MQTT.md).

To run multiple nodes, see CLUSTERING.md (seeds, ports, replication factor, consistency, adding/removing nodes). For the SQL surface, see QUERY_SYNTAX.md.

Upgrading

  • .deb / .rpm: install the newer package the same way — it replaces the old one (sudo apt install ./skaidb_NEW_amd64.deb, sudo dnf install ./skaidb-NEW…rpm). If the skaidb service is running, the package restarts it automatically so the new binary takes over (a stopped or never-enabled service is left untouched). In a multi-node cluster, upgrade one host at a time so the nodes don't all restart at once.
  • Tarball / zip / source: overwrite the binaries in place. The on-disk data format is forward-compatible within a release line; stop the server before swapping the binary.

Downgrades. Nothing checks versions at start, so an older binary opens whatever data directory it is pointed at. What is supported: a patch downgrade within a minor line (0.311.4 → 0.311.3) — the data format is unchanged within the line — and a minor downgrade to the previous minor line (0.311 → 0.310), provided no newer-only format was switched on. The formats that are opt-in and rollback-sensitive are documented as such on their key; today that is cluster.cas_paxos_compress: a binary without the compressed layout reads a compressed CAS state as empty (it forgets that key's promise and accepted value), so set it to false on every member and let CAS traffic settle BEFORE rolling any member back, and turn it on again only once no member will be rolled back. Downgrade the same way you upgrade: one node at a time, keeping the previous package at hand (apt install skaidb=<version> / dnf downgrade skaidb-<version>), waiting for /ready?strict=1 between nodes; the mixed-version window is the one a rolling upgrade produces and is supported. A downgrade across a major version is not supported; restore a backup taken under the older version instead. Markers and lock files newer binaries leave behind (<data_dir>/.lock, a backup's BACKUP_COMPLETE) are ignored by older ones.

skaidb uses SemVer.

Uninstalling

# Debian/Ubuntu
sudo apt remove skaidb
# Fedora/RHEL/openSUSE
sudo dnf remove skaidb        # or: sudo rpm -e skaidb / sudo zypper remove skaidb
# Tarball install
sudo rm /usr/local/bin/skaidb /usr/local/bin/skaidbsh
# cargo install
cargo uninstall skaidb-server skaidb-cli

Your data directory (e.g. ./data) is never touched by uninstalling — remove it manually if you want to delete the database.