Migrate from Redis or Valkey

HotKV speaks the Redis protocol and runs the Redis command set, so moving an application usually means pointing it at a new host and port. This page covers the three parts of a move: your data, your configuration, and the differences to check before you switch.

Before you start

Check the parts of your setup that HotKV handles differently:

You use	In HotKV
Redis modules or Redis Stack data types (JSON, search, time series, Bloom, vector sets)	Modules cannot be loaded. HotKV has its own Bloom filters, Count-Min Sketch, Top-K, time series and vector search with their own commands, see Probabilistic data types, Time series and Vector search. Keys that hold a module’s value cannot be migrated as they are.
Sentinel	Not available. Use cluster mode with automatic failover, or replication with manual promotion; see High availability.
REPLICAOF / replicaof	Replication is set up with the replication.* settings, not REPLICAOF host port, and needs the replication license feature on On-Premise; see Replication. REPLICAOF NO ONE promotes a replica.
rename-command	Not supported. Deny the command with an ACL rule (-flushall) instead.
user lines in redis.conf	Move them to an ACL file (aclfile); see ACL.
Unix sockets (unixsocket)	Not available. Connect over TCP (127.0.0.1 for local clients).
io-threads	Ignored. HotKV uses every core by default; threads sets how many.
CONFIG GET requirepass	Answers (hidden) when a password is set, never the password.

Applications that only send commands need no code changes: every Redis-compatible client library works against HotKV. HotKV reports redis_version:8.4.0 in INFO and HELLO, the Redis version whose command set it follows, so libraries that choose commands by version treat it as Redis 8.4.

Move the data

Pick one of three ways:

1. Start HotKV on Redis’s files. Stop Redis, and start HotKV with dir pointing at Redis’s data directory. Fastest for a full copy; needs downtime from the moment Redis stops until HotKV has loaded the data.
2. Copy keys from a running server with the migration tools in the package, or with MIGRATE. Works across machines and from managed services; writes made during the copy need care.
3. Copy the files to the HotKV machine, then start HotKV on them as in option 1.

HotKV does not replicate from a Redis or Valkey primary: its replication links run between HotKV nodes only, so a live replica cannot be used to switch over.

Start HotKV on Redis’s files

With no snapshot or AOF of its own in dir yet, HotKV loads Redis’s at startup:

• The snapshot, dump.rdb, when dbfilename is HotKV’s default.
• The AOF, when appendonly yes is set: the appendonlydir directory of Redis 7 and later (with its manifest; appenddirname names a different directory), or the single appendonly.aof file of earlier versions, including one that begins with a snapshot. With the AOF on, HotKV loads it instead of the snapshot, as Redis does.

HotKV reads snapshots that begin with the REDIS header, up to RDB version 15 (written by Redis 8.10). That covers every data type with its TTLs and databases, hash field TTLs, stream consumer groups, and function libraries (loaded as if by FUNCTION LOAD). Newer Valkey releases write a different file format, with a VALKEY header, which HotKV does not read; for those, copy the keys by command instead (see below).

# Stop Redis so its files are complete
sudo systemctl stop redis

# Redis saved snapshots only:
hotkv --dir /var/lib/redis

# Redis ran with the AOF:
hotkv --dir /var/lib/redis --appendonly yes

The log names the Redis file that was loaded. Redis’s files are left as they are; HotKV writes its own format beside them (dump.hkv and appendonly.hkv), which Redis cannot read. Keep Redis’s files until you no longer need a way back.

If your configuration gives HotKV Redis’s file names (dbfilename dump.rdb or appendfilename appendonly.aof, as a copied redis.conf does), HotKV first keeps the Redis file as dump.rdb.redis (or appendonly.aof.redis) and then saves its own format under the original name. To go back to Redis, move the .redis file back.

Caution

A file HotKV cannot read stops the start, so that the next save does not overwrite it: a damaged or truncated file, a newer format, or a key that holds a module’s value. The log names the key or byte where reading stopped. Delete module keys in Redis (or move them another way) and take a new snapshot first.

See Persistence for how HotKV saves data once it runs.

Copy keys from a running server

The HotKV packages include three migration tools: hotkv-migrate-elasticache, hotkv-migrate-azure-cache and hotkv-migrate-memorystore. They work the same way and differ only in the name they print; despite the names, each copies from any Redis-compatible server. They walk the source with SCAN, and copy each key with DUMP and RESTORE ... REPLACE, keeping its remaining TTL.

# See what would be copied
hotkv-migrate-elasticache --source-host redis.internal --source-password "$SRC_PW" \
  --target-host 127.0.0.1 --target-password "$HOTKV_PW" --dry-run

# Copy keys that match a pattern
hotkv-migrate-elasticache --source-host redis.internal --source-password "$SRC_PW" \
  --target-host 127.0.0.1 --target-password "$HOTKV_PW" --filter 'user:*'

Option	Default	Description
--source-host, -sh	127.0.0.1	Server to copy from
--source-port, -sp	6379	Its port
--source-password, -sa		Its password
--source-db, -sd	0	Database to copy from
--target-host, -th	127.0.0.1	HotKV server to copy to
--target-port, -tp	6379	Its port
--target-password, -ta		Its password
--filter, -f	*	Copy only keys matching this pattern
--batch-size, -b	1000	SCAN count per batch
--dry-run		List keys, types and TTLs without writing
--no-verify		Skip the check at the end

After copying, the tool compares the key counts of both servers and checks the types of up to 100 random keys (and the values of string keys). It writes a summary to migration_report_<source>.json in the current directory and exits with status 2 if some keys could not be copied.

Limits of the tools:

• They authenticate with a password only (the default user), not an ACL user name.
• They connect without TLS, so the source and target must accept plain connections from the machine you run them on.
• They copy one database per run, into database 0 of the target.
• They copy keys one by one while the source keeps serving: a key written after it was copied keeps its old value in HotKV. Stop writes to the source, or copy again just before you switch.
• A value HotKV cannot restore (a module’s type, or a DUMP payload in a newer Valkey format) fails; strings are then copied with GET and SET instead, and other keys are counted as failed.

MIGRATE on the source server is another way to move keys from a running Redis: HotKV accepts the RESTORE it sends.

Bring your configuration

HotKV reads redis.conf syntax: the same directive names, include, values of several words, units such as 4gb, and quoted strings. You can start it with your existing file and adjust from there:

hotkv /etc/redis/redis.conf

• Settings HotKV implements are applied as in Redis: bind, port, requirepass, maxmemory and the eviction policies, save, appendonly, appendfsync, the TLS and cluster directives, and the rest.
• Settings of Redis 7 and 8 and Valkey 8 and 9 that HotKV does not use (io-threads, lazyfree-*, unixsocket, supervised, rdbcompression and others) are logged as ignored and the server starts.
• Directives HotKV refuses (rename-command, user, loadmodule, sentinel, replicaof/slaveof) and names it does not know stop the start, with the reason in the log. Remove them, or set ignore-unknown-directives yes to start with them skipped.

On the command line (hotkv --setting value), an unknown setting always stops the start. HotKV’s own settings and enterprise settings are listed in the configuration reference. HotKV also reads an equivalent TOML file; see Quick start: On-Premise.

Switch over

1. Install HotKV (Install) and copy your configuration and ACL users across.
2. Move the data with one of the methods above, and compare DBSIZE (or INFO keyspace) on both servers.
3. Run your application’s tests against HotKV.
4. Point your clients at the HotKV host and port. With the same password, ACL users, and TLS settings, nothing else in the client changes.
5. Keep the Redis files or server until you are sure you will not go back.

Next steps

• Persistence: snapshots and the AOF in HotKV.
• ACL and Security: users, passwords and protected mode.
• Compatibility: command-level differences from Redis and Valkey.