Skip to main content
Version: 2.x

Scripting

Redis can run Lua scripts on the server. A script runs atomically, so no other command executes while it runs. This page covers the seven scripting commands on Redis.

The library has no MULTI, EXEC, DISCARD or WATCH commands and no transaction API, so atomic multi-step logic is written as a Lua script and run with Redis#eval or Redis#evalSha.

Running Scriptsโ€‹

Redis#eval sends the script text, a Chunk of keys that the script reads through KEYS, and a Chunk of arguments that it reads through ARGV. The following table lists the commands that run scripts:

CommandPurpose
Redis#evalRuns a script sent as text
Redis#evalShaRuns a script already cached on the server, by its SHA1

Both commands finish with returning[R], but unlike the other commands they do not use a ZIO Schema Schema. They require an Input[K] for the keys, an Input[A] for the arguments and an Output[R] for the result, and the library provides no implicit instances of these. We define them ourselves from the public building blocks in Input and Output, such as StringInput, LongInput, LongOutput, MultiStringOutput and ChunkOutput.

The following example defines the instances in an object and increments a counter only when it is below a limit. The script runs atomically, so concurrent callers cannot exceed the limit:

import zio._
import zio.redis._

object ScriptCodecs {
implicit val stringInput: Input[String] = Input.StringInput
implicit val longInput: Input[Long] = Input.LongInput
implicit val longOutput: Output[Long] = Output.LongOutput
}

import ScriptCodecs._

val incrementBelowLimit: String =
"""local current = tonumber(redis.call('GET', KEYS[1]) or '0')
|if current < tonumber(ARGV[1]) then
| return redis.call('INCR', KEYS[1])
|end
|return -1""".stripMargin

def increment(redis: Redis, limit: Long): IO[RedisError, Long] =
redis.eval(incrementBelowLimit, Chunk("counter"), Chunk(limit)).returning[Long]

The script's return value is converted by the Output you choose, so it must match the Lua type: a number needs LongOutput, a string MultiStringOutput, and a table ChunkOutput of an element output. A mismatch fails with a RedisError.

Caching Scriptsโ€‹

Sending the whole script on every call wastes bandwidth. Redis#scriptLoad stores the script in the server's script cache and returns its SHA1 digest, which Redis#evalSha accepts in place of the text. The following example loads a script once and then runs it by digest:

import zio._
import zio.redis._

object ShaCodecs {
implicit val stringInput: Input[String] = Input.StringInput
implicit val stringOutput: Output[String] = Output.MultiStringOutput
}

import ShaCodecs._

def runCached(redis: Redis): IO[RedisError, String] =
for {
sha <- redis.scriptLoad("return ARGV[1]")
result <- redis.evalSha(sha, Chunk.empty[String], Chunk("hello")).returning[String]
} yield result

The cache is not persistent. After a server restart or Redis#scriptFlush, Redis#evalSha fails with a NOSCRIPT error, so a program that relies on it should load the script again and retry.

Managing the Script Cacheโ€‹

The following table lists the commands that manage the cache and running scripts:

CommandParametersReturns
Redis#scriptLoadscript: StringThe SHA1 digest
Redis#scriptExistssha1: String, sha1s: String*Chunk[Boolean]
Redis#scriptFlushmode: Option[FlushMode] = NoneUnit
Redis#scriptKillnoneUnit
Redis#scriptDebugmode: DebugModeUnit

Redis#scriptExists returns one Boolean per digest, in the order given. Redis#scriptKill stops the running script, and Redis refuses when the script has already written data. The following example flushes the cache only when a script is missing:

import zio._
import zio.redis._

def flushIfMissing(redis: Redis, sha: String): IO[RedisError, Unit] =
redis.scriptExists(sha).flatMap { found =>
ZIO.unless(found.forall(identity))(redis.scriptFlush(Some(FlushMode.Async))).unit
}

Option Typesโ€‹

FlushMode selects how Redis#scriptFlush clears the cache. When no mode is given, the server uses its default, which is synchronous:

ValueBehavior
FlushMode.AsyncFlushes the cache in the background
FlushMode.SyncFlushes the cache and waits

DebugMode configures the Lua debugger for scripts run afterwards with Redis#eval:

ValueBehavior
DebugMode.YesNon-blocking debugging; changes made by the script are discarded
DebugMode.SyncBlocking debugging; changes made by the script are saved
DebugMode.NoTurns debugging off

The following example turns the debugger off:

import zio._
import zio.redis._

def stopDebugging(redis: Redis): IO[RedisError, Unit] =
redis.scriptDebug(DebugMode.No)

ZIO Chat

Hi there! ๐Ÿ‘‹ I'm ZIO Chat, your friendly neighborhood ZIO expert. I'm here to help you navigate the world of ZIO. Whether you're a seasoned pro or just starting out, fire away with your ZIO questions. I will hit you back with the best insights I've got. Let's dive into the world of ZIO together!