Making the Switch to Valkey: A Step-by-Step Migration Checklist
If you're considering moving from Redis to Valkey, you're facing a decision many teams are working through right now. With Redis 7.4 and later moving to restrictive licenses, organizations that value open source, predictability, and freedom from vendor lock-in are taking a hard look at Valkey.
Valkey is a Linux Foundation–governed, BSD-licensed fork of Redis 7.2.4, created and supported by the same community of experts who know this technology inside and out. It delivers the performance and reliability you expect from Redis, with the confidence that it will remain open and community-driven.
This checklist is designed to help you plan, execute, and validate your migration so you can make the switch smoothly and with confidence.
Phase 1: Planning your migration
The key to a successful migration is thorough preparation, so start by taking inventory of your current setup.
Check your version compatibility
- Valkey originated as a fork of Redis 7.2.4.
- Supported: Redis OSS ≤ 7.2 can migrate directly to Valkey 7.2.x or 8.0.x.
- Not supported: Redis 7.4 or later. These releases use different licensing and data formats that don’t work seamlessly with Valkey.
Validate client libraries
Most Redis clients will connect to Valkey without changes. In most cases, you only need to update the server endpoint. Still, test your specific libraries if you rely on less common features or edge-case commands.
Assess your feature requirements
While Valkey and Redis started from the same codebase, they're evolving in different directions. Make sure to verify that Valkey supports all the commands and data structures your applications depend on. If you're using specialized features like JSON handling or Time Series data, confirm these work as expected in your test environment.
Prepare your environment
Before touching production, you need a clear picture of your current setup and a safe way to rehearse the migration. This step is about more than just grabbing a backup; it’s about documenting everything, testing in conditions that mirror reality, and being honest about your downtime tolerance. Doing the groundwork now will make the actual cutover far smoother.
1. Back up first.
Create a full, point-in-time copy with an RDB snapshot using BGSAVE. Record the LASTSAVE time so you know exactly what you captured, and keep the snapshot somewhere safe.
2. Document your current state.
Note your Redis version, persistence settings (RDB and AOF), memory limits, security options, and deployment type (standalone, Sentinel, or Cluster). Save copies of your configuration files.
3. Stand up a like-for-like test environment.
Mirror production as closely as possible, including CPU, memory, storage class, and network. This is where you’ll practice the migration steps without risking your live systems.
4. Decide your cutover model early.
If a short maintenance window is acceptable, plan for a snapshot-based seed. If you need near-zero downtime, plan for replication-based migration and confirm connectivity between the source and Valkey.
5. Prep Valkey for seeding.
When starting Valkey from an RDB snapshot, make sure AOF is disabled on the first run so the snapshot imports cleanly. Review valkey.conf to confirm persistence paths and permissions are correct.
6. Check feature and client compatibility.
List any modules or advanced features you rely on, and confirm they behave in Valkey. Test your client libraries by pointing a staging app at the Valkey endpoint.
7. Plan connection changes and secrets.
Identify every application, job, and service that connects to Redis. Prepare updated connection strings, credentials, and TLS materials so the cutover is a configuration change, not a code change.
8. Define success and monitoring.
Decide which metrics matter most—latency, ops per second, memory usage, replication lag—and have dashboards ready.
9. Rehearse and set a rollback.
Run through the migration in your test environment, document every step, and write down how you would revert to Redis if needed. Keep backups until you’re fully confident.
Phase 2: Executing the migration
With your prep work done, it’s time to actually move your data. The right method depends on how much downtime you can tolerate and how complex your current setup is. Below are the main approaches, with practical steps for each.
Snapshot-based migration (fastest, requires downtime)
The simplest way to migrate is by seeding Valkey from a Redis snapshot.
- Run BGSAVE on Redis to generate an RDB file.
- Copy the .rdb file into Valkey’s data directory.
- Make sure AOF is disabled when you start Valkey for the first time, otherwise it won’t load the snapshot.
- Start Valkey and run INFO keyspace to confirm the data loaded correctly.
This method is fast and reliable, but requires stopping writes while you capture the snapshot and bring Valkey online. It works well if your applications can handle a short maintenance window.
Replication-based migration (minimal downtime)
If you need to keep your apps online, you can sync Valkey as a replica of Redis, then promote it.
1. Start Valkey and point it at your Redis instance: REPLICAOF <redis-host> <port>
2. Monitor progress with INFO replication until Valkey has fully synchronized.
3. Promote Valkey to primary with: REPLICAOF NO ONE
4. Update your applications to connect to Valkey instead of Redis.
This approach requires more coordination and careful timing during the switchover, but it can reduce downtime to just a few seconds.
Migrating specific keys only
If you don’t want to move everything, you can migrate a subset of keys.
- Use DUMP on Redis to serialize a key and RESTORE it into Valkey. You’ll need to set the TTL manually.
- Or use the MIGRATE command with flags like COPY, REPLACE, and KEYS for an atomic transfer of selected keys.
This approach is helpful for partial migrations, testing, or gradually moving workloads.
Cluster migrations (for complex deployments)
Migrating a Redis Cluster to Valkey requires more coordination but follows similar principles.
- Add Valkey nodes as replicas to your existing Redis cluster and let them sync.
- Gradually promote Valkey nodes to primaries while retiring the Redis nodes.
- For more advanced needs, tools like RIOT, Redis-Shake, or Redis-Migrate-Tool can simplify large or phased migrations.
With careful planning, cluster migrations can be done without jeopardizing availability.
Phase 3: Verifying and optimizing
Once Valkey is live, don’t declare victory until you’ve proven everything is stable and performing as expected. This phase is about validating data, checking performance, and fine-tuning your new setup so it’s production-ready.
Validate your data
- Run INFO keyspace on Valkey to confirm that your key distribution matches what you had on Redis.
- Use application-level tests or your CI test suite to ensure critical features still behave correctly.
- For selective migrations, spot-check with DUMP on Redis and RESTORE results in Valkey to verify consistency.
Benchmark performance
- Compare Valkey against your Redis baseline using tools like redis-benchmark or production-style load tests.
- Look for improvements in latency, throughput, or memory usage. Valkey introduces features like multi-threaded I/O, dual-channel replication, and memory-efficient slot dictionaries, which can show measurable gains.
- Track replication lag if you used a replication-based migration, to ensure Valkey is caught up.
Fine-tune configuration
- Start with your old Redis config, but review valkey.conf defaults. Some settings may differ (persistence, memory management, threading).
- Confirm persistence settings: if you loaded from a snapshot, enable or tune AOF or RDB to match your durability needs.
- Adjust maxmemory, eviction policies, and threading parameters (io-threads, replica-threads) for your workload.
Update your applications
- Update connection strings, secrets, and TLS certificates across all clients so they point to Valkey.
- Monitor logs for errors or mismatches immediately after cutover.
Monitor and clean up safely
- Put monitoring in place from day one: watch latency, throughput, ops/sec, replication health, and memory fragmentation.
- Keep your Redis backup (and even the Redis cluster itself) available until you’re completely satisfied with Valkey’s performance.
- When you’re confident, decommission Redis cleanly to avoid resource waste.
Moving forward with confidence
Yes, the migration takes some planning and careful execution, but that effort pays off. You end up with a data store that performs just as well (often better) while giving you the freedom to build and scale without worrying about licensing surprises or vendor lock-in.
Every migration scenario is different, though. Your configuration, applications, performance requirements, and uptime constraints all create a unique puzzle that affects how you should approach the migration.
If you're not sure about the best path forward for your specific situation, it might help to have a professional look at your current Redis environment. Sometimes, an outside perspective can spot potential issues you might miss and recommend the smoothest migration approach for your particular setup.