Valkey

Valkey is an in-memory data structure server used for jobs such as caching, counters, queues, and ordered collections. Choose it from the data and failure behavior the application needs, then decide whether each value is disposable, rebuildable, or authoritative. The word cache does not make a missing value harmless if the rest of the system cannot cope with it.

For a Redis migration, inventory the exact source version, commands, client libraries, modules, persistence files, and operating topology. Compatibility is a set of boundaries to verify, not permission to point an existing production directory at a new executable.

TL;DR

Quick Example

This is a command-session example for an already running, isolated, authorized Valkey instance on loopback port 6379. Use valkey-cli to enter the commands. The disposable tekstache:demo: keys must not already be used. It creates a short-lived fictional cache value and a temporary counter, then deletes only that counter. It performs no flush, migration, persistence change, or server configuration change.

The first set should return OK for a new key; NX prevents replacing an existing value. Before expiry, the page value should be readable and its TTL positive or zero as it approaches expiration. The counter should reach 2 if the commands run promptly against fresh keys. If a key already existed, stop and select an unused prefix rather than assuming the initial state.

The SET reference documents conditional writes and expiry options. A normal replacement SET discards the previous TTL unless you deliberately preserve or replace it. That matters when a refresh path is meant to keep a cache entry bounded in time.

The expected output follows the command documentation. Run the session against a disposable Valkey instance before relying on it, because expiry timing, eviction, persistence, cluster routing, and recovery depend on configuration.

Core Concepts

Data structures carry the operation

Valkey offers strings, hashes, lists, sets, sorted sets, streams, and other structures; the data-type overview explains their purposes. A string can hold a cached document, a hash can hold field-value pairs, and a sorted set can support ordered membership. Choose the structure that makes required reads and updates clear instead of serializing everything into a giant opaque value.

Expiry is different from eviction

Expiry expresses a value's time boundary; memory-pressure eviction expresses a server policy under capacity limits. A proposed cache design needs both a miss path and a load budget for rebuilding. If many popular entries disappear together, a healthy datastore can still receive more rebuild work than it can handle.

Persistence and replication solve different failures

RDB persistence captures snapshots; AOF records write operations for reconstruction. The persistence guide describes their tradeoffs and combined use. Select the policy from acceptable loss and restart requirements, then test it with representative data. A configuration file does not demonstrate that a restart can recover the expected dataset.

Decide Which State May Be Lost

This table is an editorial review route. The same data structure can have different consequences in different applications. A session cache and a payment ledger should not inherit the same persistence choice merely because both fit in memory.

For a fictional cache pilot, stop reads from the cache temporarily and measure origin latency, connection pressure, and error rates. Bound concurrent rebuilds and test how stale values are handled if the product permits them. If the origin cannot survive a controlled miss burst, the cache is part of the availability design and needs corresponding operational ownership.

Replication and Cluster Behavior Need Failure Tests

Valkey uses asynchronous replication. The replication documentation explains that acknowledgment mechanisms such as WAIT do not turn the system into a strongly consistent CP system and that acknowledged writes can still be lost in failure scenarios. Do not equate a successful write response with an independently demonstrated zero-loss failover guarantee.

Cluster adds data distribution and routing requirements. The cluster specification describes hash slots and same-slot constraints for multi-key operations. Use a cluster-aware client and test redirects, reconnection, resharding behavior, and the application's actual multi-key operations. A client that works against one standalone endpoint has not passed a cluster migration.

Key design can support related-key placement, but placing too much work together can create a hotspot. Evaluate the intended operations and distribution before introducing hash tags broadly. If a single logical operation cannot be expressed within the selected cluster boundary, reconsider its data model or datastore rather than discovering the limitation at cutover.

A Redis Migration Needs an Exact Source Version

The official Redis-to-Valkey migration guide scopes straightforward compatibility to Redis OSS 7.2 and earlier and warns that Redis CE 7.4 and later data files are incompatible with Valkey. This is a file-format and version boundary; a familiar command interface does not remove it. Do not copy newer source persistence files and infer safety from a successful client connection.

Inventory source/target versions, commands and scripts, client behavior, modules, TLS/authentication settings, persistence mode, memory policy, and topology. Distinguish application-protocol compatibility from file compatibility and managed-service migration support. If a required module or command is absent, stop and choose an explicit alternative before planning the cutover.

Rehearse migration with copied nonproduction data or an isolated representative dataset. Verify key types, values, expirations, application invariants, and failure behavior. Check the supported migration method for the exact version pair rather than combining steps from standalone and cluster guides.

Plan the write boundary. Decide when writers pause or switch, how stale clients are detected, and what happens to writes made after cutover if you need to return to the old service. Retaining the old endpoint is not a complete rollback plan when the two sides have diverged. Keep recovery artifacts and credentials available without exposing them in runbooks or repository examples.

Best Practices

Test the miss path before capacity claims

Measure the system when a popular value is absent, expires, or is evicted. Include backend protection and user-visible behavior. A high hit rate under a warm synthetic load can hide the failure that matters during recovery.

Record the durability objective

Write down acceptable loss and recovery time for each state category. Rehearse restart and restore with the intended persistence configuration. Review resulting data and application behavior, not merely that the server process starts again.

Keep credentials and network scope explicit

Restrict access to the intended application and operator paths, with appropriate authentication and transport settings. A quick loopback demo is not a deployable security configuration. Verify the target client and managed-service requirements before exposing an endpoint.

Keep a versioned compatibility checklist

Exercise the actual command inventory, scripts, modules, expiry behavior, client reconnects, and cluster topology. Record failures and pending checks. A migration guide supplies prerequisites and methods; it does not certify your application.

Common Mistakes

Bad: Refresh a short-lived key with an ordinary SET and assume its old expiry survives.

Correct: Deliberately preserve or set the required TTL and test the refresh path.

Bad: Treat replicas as a historical backup before an accidental write.

Correct: Maintain suitable independent recovery artifacts and demonstrate a restore.

Bad: Copy Redis CE 7.4+ persistence files into Valkey because basic commands look compatible.

Correct: Use an explicitly supported method for the exact versions and validate it on isolated data.

FAQ

Is Valkey only a cache?

Its data structures support several roles. The application's durability, delivery, and correctness requirements determine whether a proposed use is appropriate and what recovery controls it needs.

Does a replica guarantee no lost writes?

No such guarantee follows from the default asynchronous replication model. Test failure behavior against the application's stated loss objective and review the relevant documented limits.

Can every Redis deployment migrate unchanged?

No. Source version, file format, modules, commands, client behavior, and topology all matter. Use the exact compatibility scope and record untested dependencies.

How do I verify expiry and persistence behavior?

Run the commands against a disposable Valkey instance configured like production, then observe key expiry, restarts with your persistence settings, and failover if you use replication. Command documentation describes behavior; only a live instance shows what your configuration does.

Related Topics

References