skaidb v0.234.0

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.234.0).

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 cgroup limit, so a container gets its own cap rather than the host's. 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. 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.

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

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.

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.