Skip to content
LayerbaseLayerbase

Migrating from Redis to Valkey

9 min readRedisValkeyDatabases

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, Valkey reads Redis's RDB file directly, or you can attach it as a replica with REPLICAOF and promote it for a cutover with no data loss. 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, same data format. 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

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 (formerly SpinDB). One CLI, no Docker, no manual compilation. (What is the Layerbase 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), use Redis's built-in RDB snapshot.

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 same RDB format. On startup, it loads the dump and your data is available immediately.

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 ModuleWhat It DoesValkey Alternative
RedisJSONNative JSON document storageStore JSON as strings and parse in your application, or use ReJSON (source-available builds may work)
RediSearchFull-text search and secondary indexingUse a dedicated search engine like Meilisearch or Elasticsearch alongside Valkey
RedisGraphGraph database on top of RedisDiscontinued by Redis Ltd. in early 2024. Consider FalkorDB (community fork) or a standalone graph database
RedisTimeSeriesTime-series data structuresUse InfluxDB or QuestDB for time-series workloads
RedisBloomProbabilistic 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 for the current migration procedure.

Layerbase Cloud

On Layerbase Cloud, 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, 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. Valkey reads Redis's RDB file format, so 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. 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, same data format. The only things that change are the server binary and your connection string. 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 including both Redis and Valkey, so you can run them side by side while you verify your migration. Layerbase Desktop provides a desktop GUI if you prefer a visual interface.

Keep reading