Migrate from Redis

KiviDB speaks the Redis protocol (RESP2 and RESP3) and implements the Redis command set, so moving from Redis, Valkey or another Redis-compatible server is mostly a matter of moving the data and changing the address your clients connect to. This guide covers both, and what to check first.

Before you start: what differs

Check these against the commands your application sends:

	Redis	KiviDB
Protocol	RESP2, RESP3	RESP2, RESP3
Commands run on	One thread	Every core
Lua (EVAL, EVALSHA, FUNCTION)	Built in	The lua and full builds (a switch on KiviDB Cloud); the default build answers with an error
TLS	Built in	The tls and full builds; always available on KiviDB Cloud
Search, vectors, JSON, time series	Modules, or built into Redis 8	Built in
Redis modules (MODULE LOAD)	Supported	Not supported
Sentinel	Supported	Not implemented: use cluster mode, the Kubernetes operator or KiviDB Cloud for failover
Cluster	16,384 hash slots	16,384 hash slots, the same CLUSTER commands
Search text matching	Stemming, phonetic	Whole words, prefixes, suffixes, infixes and fuzzy; no stemming or phonetic matching
Default port	6379	6380

The command reference has the syntax and behaviour of every command, and Redis compatibility summarises the differences.

Which build

KiviDB ships four builds of each release:

Build	Includes	Use it when
default	the server	you use no Lua scripts and no TLS
lua	Lua scripting	you use EVAL, EVALSHA or FUNCTION (BullMQ, Sidekiq and many locking libraries do)
tls	TLS	clients connect over TLS
full	Lua and TLS	you are not sure; this is the general-purpose build

The Docker image tags follow the same names, e.g. kividb/kividb:v1.1.2-full.

Clients

Your Redis client library connects unchanged: redis-cli, ioredis, node-redis, redis-py, go-redis, Jedis, Lettuce and redis-rs all work as they do against Redis. Change the host, the port (6380 unless you set --port), and the password if there is one.

# Before
REDIS_URL=redis://redis.internal:6379
# After
REDIS_URL=redis://kividb.internal:6380

Moving the data

Pick the way that fits how much downtime you can take. All of them carry strings, lists, sets, sorted sets, hashes (with per-field expiry), streams with their consumer groups, and RedisJSON documents, from Redis 6.2 to 8.10 (KiviDB 1.1.2 or later).

1. Replicate, then switch (least downtime)

Start KiviDB as a replica of your Redis primary. It takes a full copy, then follows every write until you switch.

kividb --replicaof redis.internal 6379 --masterauth "$REDIS_PASSWORD"

When INFO replication on KiviDB shows the link up and the offset caught up, stop writes to Redis (or put the application in maintenance), let the last writes arrive, then promote KiviDB and point your clients at it:

redis-cli -p 6380 REPLICAOF NO ONE

2. Load a dump.rdb (simplest)

Take a snapshot in Redis (SAVE or BGSAVE), and give KiviDB the file:

# Either put it in KiviDB's data directory; it is read at startup when there is no dump.kdb
cp /var/lib/redis/dump.rdb /var/lib/kividb/dump.rdb
kividb --dir /var/lib/kividb

# Or name it explicitly
kividb --preload-file rdb:/backups/dump.rdb

Writes made to Redis after the snapshot are not in the file, so stop writes first or replay them.

3. Copy keys with MIGRATE

To move some keys rather than the whole dataset, run MIGRATE on the Redis server with KiviDB as the target:

redis-cli -h redis.internal MIGRATE kividb.internal 6380 "" 0 5000 AUTH "$KIVIDB_PASSWORD" KEYS user:1 user:2 user:3

KiviDB accepts the RESTORE payloads Redis sends.

4. KiviDB Cloud

Under Snapshots → Import a snapshot, upload the Redis dump.rdb (a .kdb file works too). It appears in your snapshots, and you can create a database from it. Stop writes to Redis before you take the snapshot, or replay the writes made since.

What does not come across

• Search indexes. Index definitions from the Redis search module are not rebuilt from a Redis file; the keys are loaded. Run FT.CREATE again, and it indexes the keys already there. The same for FT.DICTADD dictionaries.
• Other modules' data. Keys of a module type KiviDB does not read stop the load with an error naming the type. Move those keys another way, or remove them in Redis first.
• Function libraries without Lua. A file with FUNCTION libraries loads them in a lua or full build; the default build loads the data and leaves the libraries out.

After the switch

• Run your test suite against KiviDB before moving production traffic.
• Watch the log for warnings: each one says what to do, and the errors page explains them.
• Keep the old Redis running, read-only, until you are sure.

To compare throughput on your own hardware first, the benchmark guide runs the same tests we publish.