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 the kividb system user. Installing enables and starts it.
  • /etc/kividb/kividb.conf, which listens on 127.0.0.1:6380 only. An upgrade keeps your changes to it.
  • /var/lib/kividb, where the snapshot (dump.kdb), the AOF and nodes.conf live.

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 the bind 127.0.0.1 line, for example to bind 0.0.0.0.
  • Keep the data across restarts: uncomment appendonly yes. Every write is then appended to appendonly.aof in /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 install builds from source and needs Rust 1.89 or newer. --locked builds with the dependency versions the release was built and tested with. The release profile uses fat LTO, so the build takes several minutes.
  • cargo binstall downloads 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 kividb binary, in ~/.cargo/bin. There is no systemd unit, configuration file or kividb user: start it as a release binary is started, for example kividb --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.

VariantWhen to useGet it as
DefaultNo Lua scripting or TLS neededthe apt package, cargo install kividb, kividb-linux-… tarball, image v1.2.2
LuaYou need EVAL / EVALSHACargo with --features lua, kividb-lua-linux-… tarball, image v1.2.2-lua
TLSYou need TLS-encrypted connectionsCargo with --features tls, kividb-tls-linux-… tarball, image v1.2.2-tls
FullYou need bothCargo 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.

FlagDefaultDescription
--port6380Port to listen on
--bind0.0.0.0Address to listen on
--requirepassnonePassword clients must AUTH with
--threads0 (auto)Worker threads. 0 uses cores − 2 (all cores below 4).
--databases16Number of databases
--aofoffAppend-only file persistence
--dirthe current directoryWhere dump.kdb, appendonly.aof and nodes.conf are kept
--maxmemory0Memory limit in bytes, or with a unit (512mb, 3gb). 0 = unlimited.
--loglevelinfodebug, verbose, notice (or info), warning, nothing
--io-modelautoI/O model: auto, uring, tokio
--configfile/etc/kividb/kividb.confConfiguration 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)

FlagDefaultDescription
--cluster-enabled <yes|no>noEnable cluster mode and open a cluster bus on port + 10000.
--cluster-node-timeout <ms>15000Failure 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.