# Migrating from Redis to Valkey > A step-by-step guide to migrating from Redis to Valkey, covering data transfer, application changes, and the one gotcha worth knowing about. Published: 2026-06-20 Canonical: https://layerbase.com/blog/migrating-from-redis-to-valkey Short version: this is an engine swap, not a platform migration. Valkey is a fork of Redis 7.2.4 that speaks the same wire protocol, so your application code, client library, commands, Lua scripts, and `redis://` connection scheme all stay exactly as they are, and the change is which server the URL points at. If the data is a cache, point at Valkey and let it refill. If it has to come along, check your Redis version first: Valkey loads an RDB written by Redis 7.2 or earlier, but not one written by Redis 7.4 or later, which bumped the format. Above 7.2 the routes are replication with `REPLICAOF`, or a key-by-key copy. [Redis vs Valkey](/blog/redis-vs-valkey) has the format details. The one thing that does not carry over is Redis Stack: RedisJSON, RediSearch, RedisTimeSeries, RedisBloom, and RedisGraph are proprietary modules with no Valkey equivalent, so those workloads move to a purpose-built service or into your own code. If you are not running any of them, there is nothing else to plan. This might be the easiest database migration you'll ever do. Valkey is a fork of Redis 7.2.4 that kept the BSD 3-Clause license when Redis moved to SSPL + RSALv2. It's wire-compatible with Redis. Same protocol, same commands. The data format matched at the fork and has since diverged, which is the one thing to check before you plan the copy. Your application code doesn't change. Your client libraries don't change. You change where the server lives and that's about it. Whether you're switching for licensing reasons, because your cloud provider moved to Valkey, or because your legal team flagged Redis's new license, the migration path is the same. Let's walk through it. ## Contents - [What Actually Changes](#what-actually-changes) - [Set Up Valkey Locally with the Layerbase CLI](#set-up-valkey-locally-with-the-layerbase-cli) - [Migrating Your Data](#migrating-your-data) - [What to Test](#what-to-test) - [The One Gotcha: Redis Stack Modules](#the-one-gotcha-redis-stack-modules) - [Cloud Migration](#cloud-migration) - [FAQ](#faq) ## What Actually Changes Not much. Here's the full list: - **Server binary**: `redis-server` becomes `valkey-server`. If you're using a managed service, you don't even see this. - **CLI tool**: `redis-cli` still works with Valkey. You can also use `valkey-cli` if you prefer. They're functionally identical. - **Connection string**: Your `redis://` URL points to Valkey instead of Redis. The URI scheme stays `redis://` (or `rediss://` for TLS) because Valkey speaks the same protocol. - **Client libraries**: No change. The `redis` npm package, `redis-py`, `Jedis`, `StackExchange.Redis`, and every other Redis client work with Valkey out of the box. - **Configuration files**: `redis.conf` syntax works in `valkey.conf`. You can copy your existing config and it will work. What does not change: your application code, your queries, your data structures, your pub/sub channels, your Lua scripts, your cluster topology. All of it transfers over as-is. ## Set Up Valkey Locally with the Layerbase CLI Before migrating production, run Valkey locally and verify everything works. The fastest way is [the Layerbase CLI](https://layerbase.com/docs/cli) (formerly SpinDB). One CLI, no Docker, no manual compilation. ([What is the Layerbase CLI?](https://layerbase.com/docs/cli)) Install the Layerbase CLI: ```bash npm i -g layerbase # npm pnpm add -g layerbase # pnpm ``` Create a Valkey instance: ```bash lbase create myvalkey -e valkey --start ``` Check the connection URL: ```bash lbase url myvalkey ``` ```text redis://127.0.0.1:6380 ``` That URL uses the `redis://` scheme. This is correct. Valkey uses the same protocol, so the same URI format applies. Connect with `redis-cli` or `valkey-cli`: ```bash lbase connect myvalkey ``` You're now talking to Valkey using the same commands you've always used with Redis. Try it: ```bash SET test "hello from valkey" GET test DEL test ``` ## Migrating Your Data You have two paths depending on whether you need to bring existing data along. ### Option A: Fresh Start (No Data to Migrate) If your Redis instance is used for caching or ephemeral data, skip the data migration entirely. Point your application at Valkey, let the cache rebuild, and you're done. Update your environment variable: ```bash # Before REDIS_URL=redis://your-redis-host:6379 # After REDIS_URL=redis://your-valkey-host:6380 ``` Your code that reads `REDIS_URL` doesn't need to know or care that it's talking to Valkey now. ### Option B: Migrate Existing Data with RDB If you have data that needs to come along (session store, job queues, persistent state), and your source is **Redis 7.2 or earlier**, use Redis's built-in RDB snapshot. On Redis 7.4 or later the file will not load in Valkey and you want the replication route below instead. **1. Create an RDB dump from your Redis instance:** ```bash redis-cli -h your-redis-host -p 6379 BGSAVE ``` Wait for the save to complete: ```bash redis-cli -h your-redis-host -p 6379 LASTSAVE ``` Copy the `dump.rdb` file from your Redis data directory. **2. Stop your Valkey instance, copy the RDB file into its data directory, and restart:** ```bash lbase stop myvalkey cp dump.rdb $(lbase info myvalkey --data-dir)/dump.rdb lbase start myvalkey ``` Valkey reads the RDB format as it stood at Redis 7.2. On startup, it loads the dump and your data is available immediately. If Valkey refuses the file, check the Redis version that wrote it: 7.4 and later write a format Valkey does not accept, and the fix is replication rather than a flag. **3. Verify the data loaded:** ```bash lbase connect myvalkey DBSIZE KEYS * ``` ### Option C: Live Sync with Replication For zero-downtime migrations, you can configure Valkey as a replica of your Redis primary. Valkey supports the same replication protocol: ```bash valkey-cli -h your-valkey-host REPLICAOF your-redis-host 6379 ``` Once the sync is complete, promote Valkey to primary: ```bash valkey-cli -h your-valkey-host REPLICAOF NO ONE ``` Then update your application's connection string to point to Valkey. Clean cutover, no data loss. ## What to Test Valkey supports every Redis command from 7.2.4 and has maintained compatibility since. That said, verify before you ship. **Run your test suite against Valkey.** If you have integration tests that hit Redis, point them at your local Valkey instance and run the suite. Everything should pass. **Check your commands.** Core data structures (strings, lists, sets, sorted sets, hashes, streams), pub/sub, transactions (`MULTI`/`EXEC`), Lua scripting, and pipelining all work identically. If you're using standard Redis commands, you're fine. **Check your client library version.** Older client library versions work because the protocol hasn't changed. But newer versions of some libraries (like `node-redis` 5.x or `redis-py` 5.x) have added explicit Valkey support and testing. Updating to a recent version is good practice. **Check your connection configuration.** If you're using TLS, authentication (`requirepass` or ACLs), or clustering, verify those settings carry over to your Valkey config. The configuration format is the same, but double-check that credentials and certificates are in place. ## The One Gotcha: Redis Stack Modules Here's the one area where migration gets complicated. Redis Stack includes proprietary modules that are not available in Valkey: | Redis Stack Module | What It Does | Valkey Alternative | |---|---|---| | **RedisJSON** | Native JSON document storage | Store JSON as strings and parse in your application, or use [ReJSON](https://github.com/RedisJSON/RedisJSON) (source-available builds may work) | | **RediSearch** | Full-text search and secondary indexing | Use a dedicated search engine like [Meilisearch](https://layerbase.com/blog/getting-started-with-meilisearch) or Elasticsearch alongside Valkey | | **RedisGraph** | Graph database on top of Redis | Discontinued by Redis Ltd. in early 2024. Consider [FalkorDB](https://www.falkordb.com/) (community fork) or a standalone graph database | | **RedisTimeSeries** | Time-series data structures | Use [InfluxDB](https://layerbase.com/blog/getting-started-with-influxdb) or [QuestDB](https://layerbase.com/blog/getting-started-with-questdb) for time-series workloads | | **RedisBloom** | Probabilistic data structures (Bloom filters, etc.) | Valkey has discussed adding probabilistic data structures natively. For now, use application-level implementations | If you use any of these modules, check whether you can replace them with a standalone service or application-level logic. For most teams, the modules in question were handling a workload that a purpose-built tool does better anyway. A dedicated search engine outperforms RediSearch. A dedicated time-series database outperforms RedisTimeSeries. If you're not using any Redis Stack modules, this section doesn't apply to you. Move on, you're in the clear. ## Cloud Migration ### AWS ElastiCache If you're on AWS, you might already be running Valkey without knowing it. AWS switched ElastiCache's default engine to Valkey in late 2024. Check your cluster's engine version in the AWS console. If it says "Valkey," your migration is already done. If you're still on a Redis-engine ElastiCache cluster, AWS provides an in-place engine migration path. Check the [ElastiCache documentation](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/WhatIs.html) for the current migration procedure. ### Layerbase Cloud On [Layerbase Cloud](https://cloud.layerbase.com), the migration flow does the copy for you. Create a new database, choose **Migrating from another platform**, and paste your existing Redis or Valkey connection string. Upstash has an API-key path instead: paste your account email and a management API key and it lists your databases. A Vercel KV store moved to Upstash when KV was sunset, so for those you paste the `rediss://` endpoint from the Upstash dashboard. It reads the source once with a non-blocking scan and copies every key, type, and TTL into a fresh Valkey instance, so there is no manual RDB step. If you would rather start empty and copy by hand, create a [Valkey instance](https://cloud.layerbase.com/create?engine=valkey), grab the connection string from Quick Connect, and use the RDB method above. ### Other Providers Google Cloud Memorystore, DigitalOcean Managed Databases, and several other providers now offer Valkey alongside or instead of Redis. Check your provider's documentation for their specific migration path. ## FAQ ### Do I have to change any application code? No. Valkey is wire-compatible with Redis, so the `redis` npm package, `redis-py`, `Jedis`, `StackExchange.Redis`, and the rest connect to it without knowing the difference, and the URI scheme stays `redis://` or `rediss://`. Your commands, data structures, pub/sub channels, transactions, and Lua scripts all behave the same. The `redis.conf` you already have works as a `valkey.conf`. Updating to a recent client release is still worth doing, since newer versions test against Valkey explicitly. ### Does my existing data come across, TTLs included? Yes, by whichever route suits the workload, though the RDB route has a version limit. Valkey reads an RDB written by Redis 7.2 or earlier, so on those versions a `BGSAVE` on the Redis side and a copy into the Valkey data directory is enough, and keys come back with their types and expirations. Redis 7.4 and later write a newer format that Valkey will not load, so use replication instead. Replication works too, since the protocol is the same. If you migrate through Layerbase Cloud instead, the copy runs as a non-blocking scan that carries every key, type, and TTL. ### Can I do this without downtime? Yes, with replication. Point Valkey at the Redis primary with `REPLICAOF`, wait for the sync to finish, then promote it with `REPLICAOF NO ONE` and switch your application's connection string. If the instance is a pure cache, the simpler answer is to skip the data entirely: repoint the URL and let the cache warm back up. ### What happens to RediSearch, RedisJSON, and the other Redis Stack modules? They do not exist in Valkey, and this is the part of the move that needs real work. RedisJSON, RediSearch, RedisTimeSeries, and RedisBloom are proprietary modules; RedisGraph was discontinued by Redis Ltd. in early 2024 regardless of which side you are on. The table above lists the practical replacements, and in most cases a purpose-built service does the job better than the module did: a real search engine beats RediSearch, a real time-series database beats RedisTimeSeries. ### How do I know I am not already running Valkey? Check the engine on your managed cluster before doing anything. AWS switched ElastiCache's default engine to Valkey in late 2024, so a cluster created since then may already say Valkey in the console, in which case there is nothing to migrate. Google Cloud Memorystore, DigitalOcean, and several other providers now offer it as well. ## Wrapping Up The migration from Redis to Valkey is about as painless as database migrations get. Same protocol, same commands. The only things that change are the server binary and your connection string, plus a decision about how the data travels if you are above Redis 7.2. Unless you depend on Redis Stack modules, the whole process is: stand up Valkey, copy your data over (if any), update your connection URL, run your tests, and deploy. Manage your local Valkey instance with the Layerbase CLI: ```bash lbase stop myvalkey # Stop Valkey lbase start myvalkey # Start Valkey again lbase list # See all your instances ``` The Layerbase CLI supports [20+ engines](https://layerbase.com/docs/cli) including both Redis and [Valkey](/db/valkey), so you can run them side by side while you verify your migration. [Layerbase Desktop](https://layerbase.com/desktop/download) provides a desktop GUI if you prefer a visual interface.