Migrating from Redis to Valkey

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
• Set Up Valkey Locally with SpinDB
• Migrating Your Data
• What to Test
• The One Gotcha: Redis Stack Modules
• Cloud Migration

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 SpinDB

Before migrating production, run Valkey locally and verify everything works. The fastest way is SpinDB. One CLI, no Docker, no manual compilation. (What is SpinDB?)

Install SpinDB:

npm i -g spindb    # npm
pnpm add -g spindb # pnpm

Create a Valkey instance:

spindb create myvalkey -e valkey --start

Check the connection URL:

spindb url myvalkey

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:

spindb connect myvalkey

You're now talking to Valkey using the same commands you've always used with Redis. Try it:

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:

# 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:

redis-cli -h your-redis-host -p 6379 BGSAVE

Wait for the save to complete:

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:

spindb stop myvalkey
cp dump.rdb $(spindb info myvalkey --data-dir)/dump.rdb
spindb 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:

spindb 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:

valkey-cli -h your-valkey-host REPLICAOF your-redis-host 6379

Once the sync is complete, promote Valkey to primary:

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:

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, create a new Valkey instance, grab the connection string from Quick Connect, and update your application config. If you need to migrate data from an existing Redis instance, use the RDB method described 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.

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 SpinDB:

spindb stop myvalkey    # Stop Valkey
spindb start myvalkey   # Start Valkey again
spindb list             # See all your instances

SpinDB 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 macOS GUI if you prefer a visual interface.