Install on Debian / Ubuntu
Install KiviDB from its apt repository. apt upgrade then keeps it current like the rest of the system. The repository has every stable release from 1.2.1…
Install KiviDB from its apt repository. apt upgrade then keeps it current like the rest of the system. The repository has every stable release from 1.2.1 on, for amd64 and arm64.
Requirements: glibc 2.34 or newer, which means Debian 12, Ubuntu 22.04 or later. On an older system apt refuses the package; use Cargo there. The arm64 package needs an ARMv8.1 CPU or newer: Graviton2 and later and Ampere work, a Raspberry Pi 4 does not.
Install from the apt repository (recommended)
sudo apt update && sudo apt install -y ca-certificates curl
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://packages.kividb.io/kividb.gpg | sudo tee /etc/apt/keyrings/kividb.gpg > /dev/null
sudo tee /etc/apt/sources.list.d/kividb.sources > /dev/null <<'EOF'
Types: deb
URIs: https://packages.kividb.io/deb
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/kividb.gpg
EOF
sudo apt update && sudo apt install -y kividb
Check that the key you downloaded has the fingerprint below before you rely on it:
gpg --show-keys /etc/apt/keyrings/kividb.gpg
Fingerprint: 6492 17DE 0F7F D7DB 3D7B AC3A E21D 8F6E DDE5 F489 (KiviDB Packages <packages@kividb.io>). It is also published in the KiviDB repository, which the package site does not control. If the fingerprint differs, do not install from the repository.
The same source as a one-line .list file, for older apt and tools that only read those:
echo "deb [signed-by=/etc/apt/keyrings/kividb.gpg] https://packages.kividb.io/deb stable main" \
| sudo tee /etc/apt/sources.list.d/kividb.list > /dev/null
Use one or the other, not both.
What the package installs
/usr/bin/kividb- a systemd unit,
kividb.service, which runs the server as thekividbsystem user. Installing enables and starts it. /etc/kividb/kividb.conf, which listens on127.0.0.1:6380only. An upgrade keeps your changes to it./var/lib/kividb, where the snapshot (dump.kdb), the AOF andnodes.conflive.
Check that it is running:
systemctl status kividb
redis-cli -p 6380 PING
# PONG
journalctl -u kividb
KiviDB listens on port 6380, so it can run beside a Redis on 6379.
Configure it
Settings go in /etc/kividb/kividb.conf, one directive per line. Restart after changing it:
sudo systemctl restart kividb
- Accept clients from other machines: set a password with
requirepass, and change thebind 127.0.0.1line, for example tobind 0.0.0.0. - Keep the data across restarts: uncomment
appendonly yes. Every write is then appended toappendonly.aofin/var/lib/kividb. - Worker threads: add
threads N. The default,0, picks a count from the CPU cores.
Change the configuration file, not the systemd unit.
Upgrading, pinning and going back
An upgrade restarts the unit if it is running, and leaves it stopped or disabled if you stopped or disabled it.
sudo apt update && sudo apt upgrade
The newest 20 releases stay in the repository, so you can install a given one, or go back to it:
apt list -a kividb # the versions on offer
sudo apt install --allow-downgrades kividb=1.2.1 # that version
sudo apt-mark hold kividb # and stay on it
Before going back across a minor release, read that release's upgrade notes: a newer server may have written files an older one cannot read.
Removing
sudo apt remove kividb
This stops and disables the unit and removes the binary and the unit. The kividb user, /var/lib/kividb (your data) and the configuration stay. sudo apt purge kividb removes the configuration too. Delete /var/lib/kividb yourself if you no longer want the data.
Install with Cargo
KiviDB is published on crates.io, in every variant. cargo install builds it on the machine, so it also works where the apt package does not, on a system with glibc older than 2.34:
cargo install --locked kividb # default variant
cargo install --locked kividb --features lua,tls # full (or lua, or tls)
cargo binstall kividb # the release's binary
cargo installbuilds from source and needs Rust 1.89 or newer.--lockedbuilds with the dependency versions the release was built and tested with. The release profile uses fat LTO, so the build takes several minutes.cargo binstalldownloads the release's own binary of the Default build instead of compiling. That binary has the package's requirements: glibc 2.34 or newer, and an ARMv8.1 CPU on arm64.- Cargo installs only the
kividbbinary, in~/.cargo/bin. There is no systemd unit, configuration file orkividbuser: start it as a release binary is started, for examplekividb --threads "$(nproc)".
Lua scripting or TLS
The package is the Default build, without Lua or TLS. It is the fastest build, and the benchmark results are from it.
| Variant | When to use | Get it as |
|---|---|---|
| Default | No Lua scripting or TLS needed | the apt package, cargo install kividb, kividb-linux-… tarball, image v1.2.2 |
| Lua | You need EVAL / EVALSHA | Cargo with --features lua, kividb-lua-linux-… tarball, image v1.2.2-lua |
| TLS | You need TLS-encrypted connections | Cargo with --features tls, kividb-tls-linux-… tarball, image v1.2.2-tls |
| Full | You need both | Cargo with --features lua,tls, kividb-full-linux-… tarball, image v1.2.2-full |
See Install with Cargo, Release binaries below, or Install with Docker.
.deb from GitHub Releases (air-gapped hosts)
For a host that can't reach the repository, download the .deb attached to each GitHub Release and copy it over. It is the same package: it installs the binary, the unit and the configuration above, and enables and starts the unit.
# amd64 (on arm64, kividb_arm64.deb)
curl -LO https://github.com/kividbio/kividb/releases/download/v1.2.2/kividb_amd64.deb
sudo apt install ./kividb_amd64.deb
redis-cli -p 6380 PING
It doesn't update itself: install the next release's .deb the same way.
Release binaries
For systems without a package manager, or to run a Lua, TLS or Full build: each release has tarballs for x86_64 and aarch64. Each unpacks to a kividb/ directory holding the kividb binary, LICENSE and NOTICE.
# x86_64 (on aarch64, kividb-linux-aarch64.tar.gz)
curl -LO https://github.com/kividbio/kividb/releases/download/v1.2.2/kividb-linux-x86_64.tar.gz
tar xzf kividb-linux-x86_64.tar.gz
./kividb/kividb --version
# Lua (swap "lua" for "tls" or "full" as needed)
curl -LO https://github.com/kividbio/kividb/releases/download/v1.2.2/kividb-lua-linux-x86_64.tar.gz
tar xzf kividb-lua-linux-x86_64.tar.gz
Run it from the directory where it should keep its data, or name one with --dir:
./kividb/kividb # default settings, port 6380
./kividb/kividb --threads "$(nproc)" # one worker thread per core
./kividb/kividb --requirepass "change-me" # with a password
./kividb/kividb --aof # with AOF persistence
Every file in a release is listed, with links, on the Downloads page.
Command-line flags
A flag on the command line wins over the same directive in the configuration file. When it exists, the server reads /etc/kividb/kividb.conf on startup; --configfile names another file.
| Flag | Default | Description |
|---|---|---|
--port | 6380 | Port to listen on |
--bind | 0.0.0.0 | Address to listen on |
--requirepass | none | Password clients must AUTH with |
--threads | 0 (auto) | Worker threads. 0 uses cores − 2 (all cores below 4). |
--databases | 16 | Number of databases |
--aof | off | Append-only file persistence |
--dir | the current directory | Where dump.kdb, appendonly.aof and nodes.conf are kept |
--maxmemory | 0 | Memory limit in bytes, or with a unit (512mb, 3gb). 0 = unlimited. |
--loglevel | info | debug, verbose, notice (or info), warning, nothing |
--io-model | auto | I/O model: auto, uring, tokio |
--configfile | /etc/kividb/kividb.conf | Configuration file to read |
While there is no password and bind is not set, the server accepts clients from the same machine only (protected mode). Set --requirepass before you open it to other machines.
Cluster mode (optional)
| Flag | Default | Description |
|---|---|---|
--cluster-enabled <yes|no> | no | Enable cluster mode and open a cluster bus on port + 10000. |
--cluster-node-timeout <ms> | 15000 | Failure detection timeout (lower for faster failover testing). |
See Set up a cluster for forming a multi-node cluster.
Run kividb --help for the full list.