KeyDB Performance: Switching from Redis to a Multi-Threaded Drop-in Alternative

I just read a few pages with benchmarks about Redis vs. KeyDB, and my curiosity was piqued. KeyDB, a multi-threaded fork of Redis, promised significant performance and memory usage improvements. This guide shows how I switched three different Redis use cases to KeyDB.

A Note on Risks and Support

What I show here is not officially recommended by the developers of Nextcloud or Paperless-NGX. KeyDB is designed to be a drop-in replacement, but conflicts can occur. I highly recommend you know what you are doing, thoroughly test the migration, and expect potential operational challenges.

Part I: Installation and Preparation

The installation uses a dedicated repository to ensure the latest version is available.

# Add the KeyDB repository and key
echo "deb https://download.keydb.dev/open-source-dist $(lsb_release -sc) main" | tee /etc/apt/sources.list.d/keydb.list
wget -O /etc/apt/trusted.gpg.d/keydb.gpg https://download.keydb.dev/open-source-dist/keyring.gpg
apt-get update
apt-get install keydb

Part II: Switching Multi-Instance Services (systemd)

I previously configured my multi-instance system using systemd unit templates (redis@amavis.conf). I noticed that both Redis and KeyDB ship with similar scripts (redis-server@ and keydb-server@), making the switch simple.

Migration Procedure

The migration involves copying the old Redis configuration, adapting it for KeyDB, and switching the Systemd service.

Copy and Adapt Configuration: I copy the old Redis configuration and use sed (or a text editor) to change paths and database directories.

cp /etc/redis/redis-amavis.conf /etc/keydb/keydb-amavis.conf

# Example of the final KeyDB configuration
# cat /etc/keydb/keydb-amavis.conf 
include /etc/keydb/keydb.conf

port 6377

pidfile /var/run/keydb-amavis/keydb-server.pid
logfile /var/log/keydb/keydb-server-amavis.log
dbfilename amavis.rdb
dir /var/lib/keydb

maxmemory 300M

Switch Systemd Service: I stop the old service and enable the new keydb-server@ unit.

systemctl disable redis-server@amavis
systemctl stop redis-server@amavis
systemctl enable keydb-server@amavis
systemctl start keydb-server@amavis

This was a successful drop-in replacement for my Amavis and SpamAssassin instances.

Part III: Switching Application Backends

1. Nextcloud (Unix Socket Integration)

My Nextcloud setup relies on a local Unix Socket for communication, which is faster and safer than TCP over localhost. The switch requires changing the socket path in two places:

KeyDB Configuration: Set KeyDB to listen on the Unix socket and adjust permissions.

# /etc/keydb/keydb.conf
Port 0
unixsocket /var/run/keydb/keydb-server.sock
unixsocketperm 770

Application Configuration: Update config.php and php.ini to point to the new socket path.

# Nextcloud config.php excerpt
'host' => '/var/run/keydb/keydb-server.sock',

# PHP.ini for session storage
session.save_path = "unix:///var/run/keydb/keydb-server.sock"

2. Paperless-NGX (Docker Compose)

Switching the caching and broker service to KeyDB in the Docker Compose stack was the easiest migration.

Update docker-compose.yml: I changed the image: tag to the KeyDB image (eqalpha/keydb:latest) and renamed the volume.

# docker-compose.yml (Excerpt)

services:
  broker:
    image: eqalpha/keydb:latest
    restart: unless-stopped
    volumes:
      - keydbdata:/data

volumes:
  ...
  keydbdata: # Renamed from redisdata

Execute Update: Running docker compose down, pull, and up -d replaced the backend, which the stateless Paperless services accepted instantly.

Conclusion

KeyDB provided a successful drop-in replacement for Redis across all my use cases (Systemd, Nextcloud, Docker Compose). It’s a compelling alternative for users seeking multi-threaded performance gains without changing their application logic.

Sources / See Also

KeyDB Documentation. Official Installation and Configuration Guides. https://docs.keydb.dev/
KeyDB Documentation. KeyDB vs Redis Benchmarks (Multi-Threading). https://docs.keydb.dev/blog/2021/01/18/keydb-benchmarks
Redis Documentation. Redis persistence explained. https://redis.io/topics/persistence/
systemd Documentation. Using Templates and Instances (Service Management). https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Templates
EQ Alpha Labs. Technical blog posts on KeyDB’s architecture and multi-threading. https://docs.keydb.dev/blog/