EVALSHA for cached scripts in Redis - Deep Dive

Overview - EVALSHA for cached scripts

What is it?

EVALSHA is a Redis command that runs a Lua script already stored in Redis by referencing its unique SHA1 hash. Instead of sending the whole script every time, you send just the hash, which makes execution faster. This helps Redis reuse scripts efficiently without resending the script code repeatedly. It is mainly used to improve performance when running the same script multiple times.

Why it matters

Without EVALSHA, every time you want to run a Lua script in Redis, you must send the entire script text, which wastes network bandwidth and slows down execution. EVALSHA solves this by caching the script on the server and running it by its hash, making repeated script calls much faster and reducing network load. This is crucial for high-performance applications that rely on Redis scripting for atomic operations.

Where it fits

Before learning EVALSHA, you should understand basic Redis commands and how Lua scripting works with Redis using the EVAL command. After mastering EVALSHA, you can explore advanced Redis scripting patterns, script caching strategies, and error handling for missing scripts.

Mental Model

Core Idea

EVALSHA runs a cached Lua script in Redis by using its unique hash, avoiding the need to resend the full script every time.

Think of it like...

Imagine you have a favorite recipe saved in a cookbook with a unique page number. Instead of rewriting the whole recipe each time you want to cook, you just tell someone the page number, and they find it instantly. EVALSHA is like giving the page number instead of the full recipe.

┌───────────────┐       ┌───────────────┐
│ Client sends  │       │ Redis server  │
│ SHA1 hash of  │──────▶│ Looks up Lua  │
│ cached script │       │ script by hash│
└───────────────┘       └───────────────┘
         │                       │
         │                       ▼
         │               ┌───────────────┐
         │               │ Executes Lua  │
         │               │ script atomically│
         │               └───────────────┘
         │                       │
         │                       ▼
         │               ┌───────────────┐
         │               │ Returns result│
         │               └───────────────┘
         ▼                       ▲
┌───────────────┐               │
│ Client receives│◀─────────────┘
│ script result  │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

What is Redis Lua scripting

Concept: Introduce the idea that Redis can run Lua scripts atomically on the server.

Redis allows you to write small programs in Lua that run inside the Redis server. These scripts can read and write data atomically, meaning all changes happen together without interference. You use the EVAL command to send and run these scripts.

Result

You can perform complex operations in Redis safely and efficiently using Lua scripts.

Understanding that Redis supports Lua scripting is the base for learning how to optimize script execution with caching.

2

Foundation

How EVAL runs Lua scripts

Concept: Explain how the EVAL command sends the full Lua script to Redis for execution.

When you want to run a Lua script, you send the entire script text with the EVAL command. Redis compiles and runs it immediately. This works well for occasional scripts but can be slow if you run the same script many times because the script text is sent every time.

Result

Scripts run correctly but with overhead from sending full script text repeatedly.

Knowing that EVAL sends the full script every time shows why caching scripts can improve performance.

3

Intermediate

What is script caching in Redis

Concept: Introduce the idea that Redis stores scripts by their SHA1 hash to reuse them.

Redis keeps a cache of Lua scripts identified by a SHA1 hash of their content. When you send a script with EVAL, Redis stores it and remembers its hash. Later, you can run the same script by just sending the hash instead of the full script.

Result

Scripts can be reused without resending the full code, saving bandwidth and time.

Understanding script caching is key to using EVALSHA effectively for performance gains.

4

Intermediate

How EVALSHA runs cached scripts

🤔Before reading on: do you think EVALSHA requires sending the full script or just the hash? Commit to your answer.

Concept: Explain that EVALSHA runs a cached script by sending only its SHA1 hash.

Instead of sending the whole Lua script, you send the EVALSHA command with the script's SHA1 hash. Redis looks up the script in its cache and runs it. If the script is not found, Redis returns an error.

Result

Scripts run faster because only the hash is sent, reducing network load.

Knowing that EVALSHA uses the hash alone helps you optimize repeated script execution.

5

Intermediate

Handling missing scripts with EVALSHA

🤔Before reading on: what do you think happens if the script hash is not in Redis? Commit to your answer.

Concept: Describe the error returned when a script is missing and how to handle it.

If you call EVALSHA with a hash Redis doesn't know, it returns a NOSCRIPT error. The usual fix is to send the full script with EVAL to load it again, then retry EVALSHA. This pattern ensures scripts are cached before running by hash.

Result

You learn to handle missing scripts gracefully to avoid runtime errors.

Understanding error handling with EVALSHA prevents bugs in production when scripts are evicted or Redis restarts.

6

Advanced

Benefits of EVALSHA in production

🤔Before reading on: do you think using EVALSHA always improves performance? Commit to your answer.

Concept: Explain the performance and network benefits of using EVALSHA in real systems.

Using EVALSHA reduces network traffic because only the hash is sent, not the full script. It also speeds up execution since Redis can skip parsing the script text again. This is especially important in high-throughput systems where scripts run many times per second.

Result

Applications become more efficient and scalable by using cached scripts.

Knowing when and why EVALSHA improves performance helps you design better Redis-based systems.

7

Expert

Script eviction and cache consistency surprises

🤔Before reading on: do you think cached scripts in Redis persist forever? Commit to your answer.

Concept: Reveal that Redis can evict cached scripts and how this affects EVALSHA usage.

Redis stores cached scripts in memory, but if Redis restarts or scripts are evicted (e.g., due to memory pressure), the cache is lost. Then EVALSHA calls fail with NOSCRIPT errors until scripts are reloaded. This means clients must handle these errors and reload scripts dynamically to maintain reliability.

Result

You understand the need for robust script loading and error recovery in production.

Knowing that script cache is volatile prevents hidden bugs and downtime in systems relying on EVALSHA.

Under the Hood

When you send EVAL with a Lua script, Redis compiles the script and stores it in an internal cache keyed by the SHA1 hash of the script text. EVALSHA uses this hash to find the compiled script quickly and execute it without recompiling. If the script is missing, Redis returns an error. The cache is stored in Redis memory and is lost on restart or eviction. This mechanism avoids repeated parsing and network overhead.

Why designed this way?

Redis was designed for speed and low latency. Sending full scripts repeatedly wastes bandwidth and CPU time parsing scripts. Caching scripts by hash allows Redis to run scripts faster and reduces network load. The SHA1 hash is a compact, unique identifier that avoids storing duplicate scripts. The design balances performance with simplicity, but requires clients to handle cache misses.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Client sends  │       │ Redis script  │       │ Redis script  │
│ EVAL + script │──────▶│ cache stores  │──────▶│ compiled Lua  │
│               │       │ script by SHA1│       │ script object │
└───────────────┘       └───────────────┘       └───────────────┘
         ▲                       │                       │
         │                       │                       ▼
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Client sends  │       │ Redis receives│       │ Redis looks   │
│ EVALSHA + SHA1│──────▶│ SHA1 hash     │──────▶│ up script by  │
│               │       │               │       │ SHA1 in cache │
└───────────────┘       └───────────────┘       └───────────────┘
                                         │
                                         ▼
                               ┌───────────────────┐
                               │ Executes cached    │
                               │ compiled script    │
                               └───────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does EVALSHA automatically load missing scripts? Commit yes or no.

Common Belief: EVALSHA will automatically load the script if it is missing in Redis.

Reality: EVALSHA returns a NOSCRIPT error if the script is not cached; it does not load scripts automatically.

Why it matters: Assuming automatic loading causes runtime errors and failed commands in production.

Quick: Do cached scripts persist after Redis restarts? Commit yes or no.

Common Belief: Cached scripts stay in Redis forever, even after restarts.

Reality: Cached scripts are stored in memory and are lost when Redis restarts or evicts them.

Why it matters: Not handling script cache loss leads to unexpected NOSCRIPT errors and downtime.

Quick: Does using EVALSHA always improve performance? Commit yes or no.

Common Belief: EVALSHA always makes script execution faster than EVAL.

Reality: EVALSHA improves performance only when scripts are cached; the first run still requires EVAL to load the script.

Why it matters: Misusing EVALSHA without loading scripts first causes errors and no performance gain.

Quick: Can you use EVALSHA with any arbitrary hash? Commit yes or no.

Common Belief: You can run any script by guessing or generating a SHA1 hash.

Reality: You must use the exact SHA1 hash of a script previously loaded in Redis; otherwise, EVALSHA fails.

Why it matters:

Expert Zone

1

Scripts cached by Redis are stored per instance; in clustered Redis setups, scripts must be loaded on each node separately.

2

The SHA1 hash is computed on the exact script text; even whitespace or comments changes the hash, so scripts must be identical to reuse the cache.

3

Redis does not provide a built-in way to list cached scripts, so clients must track script hashes themselves for reliable EVALSHA usage.

When NOT to use

Avoid EVALSHA when scripts are rarely reused or when script caching complexity outweighs benefits. For one-off scripts, use EVAL directly. Also, in environments where Redis restarts frequently without script preloading, EVALSHA can cause errors unless carefully managed.

Production Patterns

In production, clients often implement a script manager that loads scripts with EVAL, stores their SHA1 hashes, and retries EVALSHA calls on NOSCRIPT errors by reloading scripts. This pattern ensures reliability and performance. Also, scripts are versioned and updated carefully to avoid hash mismatches.

Connections

Content-Addressable Storage

EVALSHA uses a SHA1 hash to identify scripts, similar to how content-addressable storage identifies data by hash.

Understanding content-addressable storage helps grasp why Redis uses script hashes for caching and quick lookup.

HTTP Caching with ETags

Both use hashes to avoid resending full content when unchanged, improving efficiency.

Knowing HTTP ETags clarifies how EVALSHA reduces network load by sending only hashes instead of full scripts.

Compiler Caching in Programming Languages

Like Redis caches compiled Lua scripts, compilers cache compiled code to speed up repeated runs.

Recognizing this parallel helps understand the performance benefits of caching compiled scripts in Redis.

Common Pitfalls

#1 Calling EVALSHA before loading the script causes errors.

Wrong approach:

EVALSHA 1 key1

Correct approach:

EVAL 1 key1
EVALSHA 1 key1

Root cause:

The script was never loaded into Redis cache, so EVALSHA cannot find it.

#2 Assuming cached scripts survive Redis restarts.

Wrong approach:

Start Redis, load script, restart Redis, then call EVALSHA without reloading.

Correct approach:

After Redis restart, reload scripts with EVAL before calling EVALSHA.

Root cause:

Redis stores cached scripts in volatile memory, lost on restart.

#3 Using different script text with same logic but different formatting causes cache misses.

Wrong approach:

EVALSHA with hash of script A but sending script B with extra spaces or comments.

Correct approach:

Ensure script text is byte-for-byte identical to the cached version before using EVALSHA.

Root cause:

SHA1 hash depends on exact script text; any change alters the hash.

Key Takeaways

EVALSHA runs Lua scripts in Redis by referencing their cached SHA1 hash, avoiding resending full scripts.

Scripts must be loaded first with EVAL to cache them before EVALSHA can run them successfully.

Cached scripts live in Redis memory and are lost on restart, so clients must handle NOSCRIPT errors by reloading scripts.

Using EVALSHA reduces network traffic and speeds up script execution in high-performance Redis applications.

Proper script management and error handling are essential for reliable use of EVALSHA in production.