EVALSHA

Execute a cached Lua script by its SHA-1 hash

Usage

await redis.evalsha(sha1, keys, args);

Executes a Lua script that has been previously loaded into Redis. Instead of sending the entire script, you only send the SHA-1 hash of the script, which is more efficient for frequently executed scripts.

Parameters

sha1 · string · required

The SHA-1 hash of the script to execute. Obtain this by using SCRIPT LOAD or by computing the SHA-1 hash of your script.

keys · string[] · required

Array of key names that the script will access. These are available in the script as KEYS[1], KEYS[2], etc.

args · unknown[]

Array of arguments to pass to the script. These are available in the script as ARGV[1], ARGV[2], etc.

Response

result · unknown

The value returned by the Lua script. The type depends on what the script returns.

Examples

Load and Execute a Script

const script = `
  local current = redis.call('GET', KEYS[1]) or 0
  local next = current + tonumber(ARGV[1])
  redis.call('SET', KEYS[1], next)
  return next
`;

// First, load the script and get its SHA-1 hash
const sha1 = await redis.scriptLoad(script);
console.log(sha1); // e.g., "a42059b356c875f0717db19a51f6aaca9ae659ea"

// Now execute it using the hash
const result = await redis.evalsha(
  sha1,
  ["counter"],
  ["5"]
);
console.log(result); // 5 (or current value + 5)

// Subsequent calls are more efficient
const result2 = await redis.evalsha(sha1, ["counter"], ["3"]);
console.log(result2); // previous value + 3

Handling Missing Scripts

If the script isn’t loaded, EVALSHA will fail with a NOSCRIPT error:

try {
  const result = await redis.evalsha(
    "nonexistent_sha",
    ["key"],
    ["arg"]
  );
} catch (error) {
  if (error.message.includes("NOSCRIPT")) {
    // Script not loaded, use EVAL instead or load it first
    const sha1 = await redis.scriptLoad(script);
    const result = await redis.evalsha(sha1, ["key"], ["arg"]);
  }
}

Conditional Operations

const compareAndSetScript = `
  local current = redis.call('GET', KEYS[1])
  if current == ARGV[1] then
    redis.call('SET', KEYS[1], ARGV[2])
    return 1
  else
    return 0
  end
`;

const sha1 = await redis.scriptLoad(compareAndSetScript);

// Try to update if current value matches
const updated = await redis.evalsha(
  sha1,
  ["mykey"],
  ["expected_value", "new_value"]
);

if (updated === 1) {
  console.log("Successfully updated");
} else {
  console.log("Value didn't match, not updated");
}

EVALSHA vs EVALSHA_RO

EVALSHA

The evalsha command can execute scripts that modify data:

const script = `
  redis.call('SET', KEYS[1], ARGV[1])
  return 'OK'
`;

const sha1 = await redis.scriptLoad(script);
const result = await redis.evalsha(
  sha1,
  ["mykey"],
  ["myvalue"]
);

EVALSHA_RO (Read-Only)

Use evalshaRo for read-only scripts that don’t modify data:

const script = `
  return redis.call('GET', KEYS[1])
`;

const sha1 = await redis.scriptLoad(script);
const result = await redis.evalshaRo(
  sha1,
  ["mykey"],
  []
);

Read-only scripts:

• Can be executed on read replicas
• Are optimized for read-heavy workloads
• Will error if they attempt to modify data

Using the Script Class

The SDK provides a Script class that automatically handles SHA-1 computation and caching:

const script = redis.createScript<number>(`
  local current = redis.call('GET', KEYS[1]) or 0
  local next = current + tonumber(ARGV[1])
  redis.call('SET', KEYS[1], next)
  return next
`);

// Use evalsha method - assumes script is loaded
const result = await script.evalsha(["counter"], ["1"]);

// Or use exec method - optimistically tries EVALSHA, falls back to EVAL
const result2 = await script.exec(["counter"], ["1"]);

The exec method is recommended as it:

1. First tries EVALSHA (fast, using cached script)
2. If script not found, falls back to EVAL
3. Subsequent calls will use EVALSHA

For read-only scripts:

const script = redis.createScript<string>(
  "return redis.call('GET', KEYS[1])",
  { readOnly: true }
);

// Uses EVALSHA_RO
const result = await script.evalshaRo(["mykey"], []);

Benefits of EVALSHA

1. Reduced bandwidth: Only the SHA-1 hash is sent instead of the entire script
2. Better performance: Script is pre-compiled and cached on the server
3. Ideal for frequently executed scripts: Especially beneficial for scripts executed many times

See Also

• EVAL - Execute a Lua script
• SCRIPT LOAD - Load a script into the server cache