Migrate to KiviDB

KiviDB speaks the Redis protocol (RESP2 and RESP3) and implements the Redis command set. For any source that speaks the same protocol, the move comes down to two jobs: copying the data, and pointing your clients at a new address. For Memcached, Aerospike and Hazelcast, it also means changing the client code. This page helps you choose a method, explains each method once, and links to a guide for every source.

Choose your guide

The second and third columns give the method to try first. The guide for each source explains when to use the others, and gives the exact steps.

Source	Into self-hosted KiviDB	Into KiviDB Cloud	Guide
Redis (6.2 to 8.x, standalone, Sentinel or Cluster)	Replicate	Copy tool (RedisShake)	Redis
Valkey (7.2 to 9.x)	Replicate (9.x: an RDB file fetched with valkey-cli --rdb, or a copy tool)	Copy tool, or RDB import	Valkey
KeyDB	Replicate from a server that is not an active replica	Copy tool	KeyDB
Dragonfly	RDB file (SAVE RDB)	RDB file import, or copy tool in scan mode	Dragonfly
Amazon ElastiCache / MemoryDB	Copy tool, or a backup exported as RDB	Copy tool, or RDB import	ElastiCache
Redis Cloud	Copy tool, or an RDB backup	Copy tool, or RDB import	Redis Cloud
Azure Cache for Redis / Azure Managed Redis	Copy tool, or an RDB export where your tier allows it	Copy tool, or RDB import	Azure Cache
Google Cloud Memorystore	Copy tool, or an RDB export where your product allows it	Copy tool, or RDB import	Memorystore
Aiven for Valkey / Redis	Copy tool	Copy tool	Aiven
Upstash	Copy tool	Copy tool	Upstash
DigitalOcean Managed Caching	Copy tool	Copy tool	DigitalOcean
Memcached	Dual-write (a cache usually needs no copy)	Dual-write	Memcached
Aerospike	Export and load script, then dual-write	Export and load script, then dual-write	Aerospike
Hazelcast	Export and load script, then dual-write	Export and load script, then dual-write	Hazelcast

Managed services usually block the replication commands (SYNC, PSYNC), so replicating straight from them is rarely possible. What each provider allows, and on which plans, is in its guide.

The four methods

1. Replicate

KiviDB connects to the source as a replica, takes a full copy, then follows every write until you switch:

kividb --replicaof source.internal 6379 --masterauth "$SOURCE_PASSWORD"

When it has caught up, stop writes to the source, let the last ones arrive, and promote KiviDB with REPLICAOF NO ONE. Downtime is the few seconds that takes.

• Works with: self-hosted Redis 6.2 to 8.x, Valkey 7.2 to 8.x, and KeyDB (not in active-replica mode).
• Does not work with: most managed services, which block PSYNC; Valkey 9, whose snapshot format KiviDB does not read; Dragonfly, which does not serve Redis-protocol replicas; and KiviDB Cloud as the target, which cannot be made a replica of an outside server.

2. File (RDB snapshot)

The source writes a snapshot (SAVE, BGSAVE, or a backup exported by the provider), and KiviDB loads it:

# Self-hosted: load at startup
kividb --preload-file rdb:/backups/dump.rdb

On KiviDB Cloud, upload the file under Snapshots → Import a snapshot and create a database from it, or restore it into an existing database. A new database can also be seeded from an https:// link to the file, such as a presigned S3 URL. The file can't be larger than the database's data size.

KiviDB reads Redis RDB files from Redis 6.2 to 8.10, and the RDB files that Valkey 7.2 to 8.x, KeyDB and Dragonfly (SAVE RDB) write. It does not read Valkey 9's own format (VALKEY080) or Dragonfly's .dfs files; the Valkey and Dragonfly guides show how to get a Redis-format file from them. Writes made after the snapshot are not in it, so stop writes first, or accept losing them, or replay them.

• Works with: any self-hosted source, and managed services that let you export or download an RDB backup, where your plan allows it.
• Downtime: from the snapshot until clients have switched.

3. Copy tool

A copy tool reads from the source like a client and writes to KiviDB like a client, so it works where the replication commands are blocked and into KiviDB Cloud. Two open-source tools work with KiviDB:

Tool	Modes	Notes
RedisShake (MIT)	sync (acts as a replica, needs PSYNC on the source), scan (SCAN + DUMP/RESTORE, optionally following keyspace notifications), rdb (replays a file)	One binary, a TOML config file. Writes with RESTORE, so it keeps TTLs, field expiry and stream consumer groups.
RIOT (Apache 2.0)	scan, live (follows keyspace notifications); --struct copies with ordinary commands instead of DUMP/RESTORE	One command line. Copies one logical database per run.

Where the source's DUMP payloads are not Redis's (KeyDB, Valkey 9), the DUMP-based modes fail; each guide says which mode to use instead.

A minimal RedisShake scan copy into KiviDB Cloud:

[scan_reader]
address = "source.example.com:6379"
password = "source-password"
tls = true

[redis_writer]
address = "your-name.cloud.kividb.io:6380"
username = "kividbapp"
password = "kividb-password"
tls = true

./redis-shake shake.toml

The Redis guide has the full configuration for each mode and for clusters.

• Works with: every Redis-protocol source and target.
• Downtime: with sync, or scan with keyspace notifications, seconds; with a one-off scan, from the start of the copy until clients have switched.

4. Dual-write

The application writes to both the old store and KiviDB for a while, reads from the old one, and then switches reads. Data the application doesn't write during that time is copied by a one-off job, or, for a cache, simply expires and is filled again from the database behind it.

• Works with: any source, and is the only way for stores that don't speak the Redis protocol (Memcached, Aerospike, Hazelcast).
• Downtime: none, at the cost of changing the application twice.

Before any move

Check these on the source first. Each guide says how for that source.

Check	Why
Lua scripts (EVAL, EVALSHA, FUNCTION): INFO commandstats	Self-hosted: use the lua or full build. KiviDB Cloud: turn Lua on when you create the database; default and free-tier databases have no Lua. Job queues such as BullMQ and Sidekiq need it.
Modules (MODULE LIST)	MODULE LOAD is not supported. Search, JSON, time series and vectors are built in. Module data other than JSON is not read from an RDB file, so move it another way. Search indexes are not in the file: run FT.CREATE again.
TLS	Self-hosted: the tls or full build. KiviDB Cloud: on or required, chosen per database.
Users and ACLs (ACL LIST)	Self-hosted: copy the ACL file or the ACL SETUSER lines. KiviDB Cloud: create users in the console.
Cluster mode	Into a self-hosted KiviDB cluster, or a sharded KiviDB Cloud database, use a copy tool with cluster mode on both sides.
Size (INFO memory, used_memory)	Size the KiviDB server or Cloud database for the data plus headroom.
Key names that are not valid UTF-8	KiviDB refuses them (ERR key must be valid UTF-8), and copy tools stop or skip them. The Redis guide has a script that lists them; rename them at the source first.

KiviDB listens on port 6380 by default; KiviDB Cloud uses 6379, or 6380 with TLS.

After any move

Every guide ends with a verify step that compares key counts and spot-checks random keys, their values and their TTLs between the source and KiviDB. The script is in the Redis guide, and works for every Redis-protocol source.

Keep the source running, without writes, until you are sure. Switching back is then a change of address.

Rolling back

Copying data back out of KiviDB is harder than copying it in. KiviDB 1.2.0's replication stream and DUMP payloads are in its own format, so a Redis or Valkey replica of KiviDB, RedisShake, and RIOT's default mode don't work in that direction. RIOT with --struct does, from a KiviDB build with Lua, but leaves stream consumer groups and hash field expiry behind. Until you are confident, keep the source intact and able to take writes again: switch reads first, or dual-write. The Redis guide has the details.