# Migrate from Redis or Valkey > Move data and configuration from Redis or Valkey to HotKV, what your applications need to change, and the differences to check first. URL: https://docs.hotkv.com/get-started/migrate-from-redis/ 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](https://docs.hotkv.com/data-types/probabilistic/index.md), [Time series](https://docs.hotkv.com/data-types/time-series/index.md) and [Vector search](https://docs.hotkv.com/data-types/vector-search/index.md). Keys that hold a module's value cannot be migrated as they are. | | Sentinel | Not available. Use [cluster mode](https://docs.hotkv.com/clustering/index.md) with automatic failover, or replication with manual promotion; see [High availability](https://docs.hotkv.com/operate/high-availability/index.md). | | `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](https://docs.hotkv.com/operate/replication/index.md). `REPLICAOF NO ONE` promotes a replica. | | `rename-command` | Not supported. Deny the command with an [ACL rule](https://docs.hotkv.com/operate/acl/index.md) (`-flushall`) instead. | | `user` lines in `redis.conf` | Move them to an ACL file (`aclfile`); see [ACL](https://docs.hotkv.com/operate/acl/index.md#the-acl-file). | | 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](#copy-keys-from-a-running-server)). ```bash # 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](https://docs.hotkv.com/persistence/index.md) 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. ```bash # 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_.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: ```bash 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](https://docs.hotkv.com/reference/configuration/index.md). HotKV also reads an equivalent TOML file; see [Quick start: On-Premise](https://docs.hotkv.com/quickstart-onpremise/index.md#2-configuration-file-basics). ## Switch over 1. Install HotKV ([Install](https://docs.hotkv.com/get-started/install/index.md)) 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](https://docs.hotkv.com/persistence/index.md): snapshots and the AOF in HotKV. - [ACL](https://docs.hotkv.com/operate/acl/index.md) and [Security](https://docs.hotkv.com/security/index.md): users, passwords and protected mode. - [Compatibility](https://docs.hotkv.com/reference/compatibility/index.md): command-level differences from Redis and Valkey.