Valkey Migration Guide · Amazon Elasticache · aws/agent-toolkit-for-aws · Skills Docs

Valkey Migration Guide · Amazon Elasticache · aws/agent-toolkit-for-aws · Skills Docs

Is your cluster running Redis OSS on ElastiCache?
├── No (self-managed Redis) --> See "Self-Hosted Redis to ElastiCache" in instructions.md
└── Yes
    ├── Running Redis OSS 4.x or 5.x?
    │   └── Yes --> URGENT: These versions are past EOL. You are paying Extended Support fees.
    │       └── Direct upgrade to Valkey is supported (e.g., --engine valkey --engine-version 7.2).
    │           Optionally upgrade to Valkey 8.0, 8.1, or 8.2 for new features (Valkey 9.0 is the recommended target).
    ├── Running Redis OSS 6.x?
    │   └── Yes --> Extended Support fees begin after EOL (check lifecycle calendar).
    │       └── Direct upgrade to Valkey is supported (e.g., --engine valkey --engine-version 7.2).
    │           Optionally upgrade to Valkey 8.0, 8.1, or 8.2 for new features (Valkey 9.0 is the recommended target).
    └── Running Redis OSS 7.x?
        └── Yes --> Direct switch to Valkey 7.2 available (in-place, zero downtime).
            └── After switch: optionally upgrade to Valkey 8.0, 8.1, or 8.2 for new features (Valkey 9.0 is the recommended target).

Valkey 7.2
├── Valkey 8.0 (in-place upgrade, adds performance improvements)
├── Valkey 8.1 (in-place upgrade, hash table memory improvements: up to 20% less overhead for common key/value patterns; suitable bridge between 8.0 and 8.2)
├── Valkey 8.2 (in-place upgrade, adds vector search)
└── Valkey 9.0 (in-place upgrade, recommended target version)

Current Version	Target	Steps	Estimated Time
Redis OSS 4.x	Valkey 7.2	Direct: `--engine valkey --engine-version 7.2`	1 operation
Redis OSS 5.x	Valkey 7.2	Direct: `--engine valkey --engine-version 7.2`	1 operation
Redis OSS 6.x	Valkey 7.2	Direct: `--engine valkey --engine-version 7.2`	1 operation
Redis OSS 7.x	Valkey 7.2	Direct: `--engine valkey --engine-version 7.2`	1 operation (minutes)
Redis OSS (any)	Valkey 8.0	Direct: `--engine valkey --engine-version 8.0`	1 operation
Redis OSS (any)	Valkey 8.2	Direct: `--engine valkey --engine-version 8.2`	1 operation
Valkey 7.2	Valkey 8.1	Valkey 7.2 -> 8.1 (direct)	1 operation (minutes)
Valkey 7.2	Valkey 8.2	Valkey 7.2 -> 8.2 (direct)	1 operation (minutes)
Valkey 8.0	Valkey 8.2	Valkey 8.0 -> 8.2 (direct)	1 operation (minutes)
Valkey 8.1	Valkey 8.2	Valkey 8.1 -> 8.2 (direct)	1 operation (minutes)

# Extended Support surcharge for a 6-node Redis cluster
python3 scripts/price_calculator.py --engine redis --extended-support --nodes 6 --region <region>

# Serverless cost estimate
python3 scripts/price_calculator.py --engine redis --mode serverless --data-gb <your-data-size> --ops-per-sec <N> --region <region>

Client	Min Version for Valkey	Code Changes Required	Notes
Jedis	4.0+ (recommended: 5.0+)	None	Works out of the box. 5.0+ has dedicated Valkey support.
Lettuce	6.2+ (recommended: 6.3+)	None	Connection URI stays `redis://` or `rediss://` (TLS).
Redisson	Check Redisson compatibility matrix (opens in a new tab) (recommended: 3.30+)	None for basic use	Cluster-mode-enabled with Redisson requires testing: verify `ClusterServersConfig` compatibility. Redisson’s distributed objects (locks, maps, queues) work unchanged.
Valkey GLIDE (Java)	1.0+	New client	Official Valkey client. Consider for new projects building on the Valkey ecosystem. Existing projects can stay on Jedis/Lettuce with no compatibility issues.

Client	Min Version for Valkey	Code Changes Required	Notes
redis-py	4.5+ (recommended: 5.0+)	None	`redis.Redis()` and `redis.cluster.RedisCluster()` work unchanged.
valkey-py	6.0+	Import change	`from valkey import Valkey` instead of `from redis import Redis`. API is identical.
Valkey GLIDE (Python)	1.0+	New client	Official Valkey client. Consider for new projects building on the Valkey ecosystem. Existing projects can stay on redis-py/valkey-py.

Client	Min Version for Valkey	Code Changes Required	Notes
ioredis	5.0+	None	Works out of the box. Connection URL stays `rediss://` for TLS.
node-redis	4.5+	None	`createClient()` works unchanged with Valkey endpoints.
Valkey GLIDE (Node.js)	1.0+	New client	Official Valkey client. Consider for new projects building on the Valkey ecosystem. Existing projects can stay on ioredis/node-redis.

Client	Min Version for Valkey	Code Changes Required	Notes
go-redis/redis	v9.0+	None	`redis.NewClusterClient()` and `redis.NewClient()` work unchanged.
valkey-go	v2.0+	Import change	`github.com/valkey-io/valkey-go` instead of `github.com/redis/go-redis`.
Valkey GLIDE (Go)	2.0+	New client	Official Valkey client. Go support added in GLIDE 2.0. Consider for new projects building on the Valkey ecosystem.

# Take pre-migration snapshot
aws elasticache create-snapshot \
  --replication-group-id <cluster-id> \
  --snapshot-name pre-valkey-migration-$(date +%Y%m%d) \
  --region <region>

# Switch engine (zero downtime from Redis OSS 5.0.6+)
# Note: Single-node Redis OSS (cluster mode disabled) clusters must first be
# added to a replication group before cross-engine upgrading.
# If using a custom parameter group, add --cache-parameter-group-name <valkey-param-group>
# The Valkey custom parameter group must have the same Redis OSS static parameter values.
aws elasticache modify-replication-group \
  --replication-group-id <cluster-id> \
  --engine valkey \
  --engine-version 8.0 \
  --apply-immediately \
  --region <region>