VALKEY-PROGRAMMABILITY(7)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ VALKEY-PROGRAMMABILITY ✨

okay bestie, welcome to valkey-programmability(7) — the programmability page, aka the one where Valkey lets you run your own lil' logic right on the server itself. 💅

🌸 DESCRIPTION 🌸

So here's the tea: Valkey ships a programming interface that lets you execute custom scripts on the server itself. You've got two whole flavors of this:

💭 Background 💭

Valkey is literally a "domain-specific language for abstract data types". No cap. The language Valkey speaks is made up of its valkey-commands(7). Most of those commands specialize in manipulating the core valkey-data-types(7) in all kinds of different ways. And honestly? In many cases these commands already give developers everything they need to manage application data in Valkey. Ate. 👑

But the term programmability in Valkey means something specific: it's the ability to execute arbitrary user-defined logic by the server. We call those pieces of logic scripts. In our case, scripts let you process the data where it lives — a.k.a. data locality 🦋. And on top of that, responsibly embedding programmatic workflows in the Valkey server can help reduce network traffic and improve overall performance. Developers can use this capability for implementing robust, application-specific APIs. Those APIs can encapsulate business logic and maintain a data model across multiple keys and different data structures. It's giving architecture. 💀✨

User scripts get executed in Valkey by an embedded, sandboxed scripting engine. Right now, Valkey supports a single scripting engine: the Lua 5.1 interpreter. That's the whole lineup, bestie.

For the complete documentation, go read valkey-lua-api(7) — the Valkey Lua API Reference page. 🎀

🏃 Running scripts 🏃

Valkey gives you two ways to run scripts. Two! Iconic.

First up: the EVAL command, which runs server-side scripts. Eval scripts are the quick-and-straightforward route to having Valkey run your scripts ad-hoc. BUT — and this is the catch — using them means the scripted logic is a part of your application, not an extension of the Valkey server. Every applicative instance that runs a script must have the script's source code readily available for loading at any time. Why? Because scripts are only cached by the server and are volatile 😭. As your application grows, this approach can become harder to develop and maintain. It's giving maintenance nightmare.

Second up: added in v7.0, Valkey Functions are essentially scripts that are first-class database elements. As such, functions decouple scripting from application logic and enable independent development, testing, and deployment of scripts. To use functions, they need to be loaded first, and then they're available for use by all connected clients. In this case, loading a function to the database becomes an administrative deployment task (such as loading a Valkey module, for example), which separates the script from the application. Slay. 💅

Peep these pages for more info:

When running a script or a function, Valkey guarantees its atomic execution. The script's execution blocks all server activities during its entire time, similarly to the semantics of valkey-transactions(7). These semantics mean that all of the script's effects either have yet to happen or had already happened. The blocking semantics of an executed script apply to all connected clients at all times. Periodt.

⚠️ Heads up bestie: the potential downside of this blocking approach is that executing slow scripts is not a good idea. It is not hard to create fast scripts because scripting's overhead is very low. However, if you intend to use a slow script in your application, be aware that all other clients are blocked and can't execute any command while it is running. Not the vibe. 🙈

📖 Read-only scripts 📖

A read-only script is a script that only executes commands that don't modify any keys within Valkey. You can run these either by adding the no-writes valkey-lua-api(7) flag to the script, or by executing the script with one of the read-only script command variants: EVAL_RO, EVALSHA_RO, or FCALL_RO.

They have the following properties:

  • They can always be executed on replicas.
  • They can always be killed by the SCRIPT KILL command.
  • They never fail with OOM error when Valkey is over the memory limit.
  • They are not blocked during write pauses, such as those that occur during coordinated failovers.
  • They cannot execute any command that may modify the data set.
  • Currently PUBLISH, SPUBLISH and PFCOUNT are also considered write commands in scripts, because they could attempt to propagate commands to replicas and AOF file.

And in addition to the benefits provided by all read-only scripts, the read-only script commands have these extra advantages:

  • They can be used to configure an ACL user to only be able to execute read-only scripts.
  • Many clients also better support routing the read-only script commands to replicas for applications that want to use replicas for read scaling.

🕰️ Read-only script history 🕰️

Read-only scripts and read-only script commands were introduced in Redis OSS 7.0. Let's do a lil' lore recap:

  • Before Redis OSS 7.0.1 PUBLISH, SPUBLISH and PFCOUNT were not considered write commands in scripts
  • Before Redis OSS 7.0.1 the no-writes valkey-lua-api(7) flag did not imply allow-oom
  • Before Redis OSS 7.0.1 the no-writes flag did not permit the script to run during write pauses.

The recommended approach is to use the standard scripting commands with the no-writes flag unless you need one of the previously mentioned features. iykyk 💜

🧸 Sandboxed script context 🧸

Valkey places the engine that executes user scripts inside a sandbox. The sandbox attempts to prevent accidental misuse and reduce potential threats from the server's environment. It's protective, we love that for us.

🚫 Scripts should never try to access the Valkey server's underlying host systems, such as the file system, network, or attempt to perform any other system call other than those supported by the API.

Scripts should operate solely on data stored in Valkey and data provided as arguments to their execution. That's the boundary, bestie. Respect it. 🌸

⏰ Maximum execution time ⏰

Scripts are subject to a maximum execution time (set by default to five seconds). This default timeout is enormous since a script usually runs in less than a millisecond. The limit is in place to handle accidental infinite loops created during development. (We've all been there. 😭)

It is possible to modify the maximum time a script can be executed with millisecond precision, either via valkey.conf or by using the CONFIG SET command. The configuration parameter affecting max execution time is called busy-reply-threshold.

When a script reaches the timeout threshold, it isn't terminated by Valkey automatically. Doing so would violate the contract between Valkey and the scripting engine that ensures that scripts are atomic. Interrupting the execution of a script has the potential of leaving the dataset with half-written changes. So no, we're not doing that.

Therefore, when a script executes longer than the configured timeout, here's what goes down:

  • Valkey logs that a script is running for too long.
  • It starts accepting commands again from other clients but will reply with a BUSY error to all the clients sending normal commands. The only commands allowed in this state are SCRIPT KILL, FUNCTION KILL, and SHUTDOWN NOSAVE.
  • It is possible to terminate a script that only executes read-only commands using the SCRIPT KILL and FUNCTION KILL commands. These commands do not violate the scripting semantic as no data was written to the dataset by the script yet.
  • If the script had already performed even a single write operation, the only command allowed is SHUTDOWN NOSAVE that stops the server without saving the current data set on disk (basically, the server is aborted). 💀

and that's the whole page, bestie — no notes, you ate this 🎀

this was Valkey Manual version 9.0.0, dated 2025-10-21 — mwah, go run some scripts (the fast ones) 💖✨🦋

📦 where this page comes from