VALKEY-MODULES-INTRO(7)

📦
version 9.0.6 · 2 versions
, in fedora 44

🎀 NAME 🎀

okay so bestie, this is valkey-modules-intro — Modules Introduction. It’s the main character of the Valkey modules docs, and it’s here to give you the whole vibe. 💖

🌈 DESCRIPTION 🌈

The modules documentation is composed of the following pages:

  • Introduction to Valkey modules (this file). An overview about Valkey Modules system and API. It’s a good idea to start your reading here. 💅
  • valkey-modules-native-types(7) — Implementing native data types covers the implementation of native data types into modules. 🦋
  • valkey-modules-blocking-ops(7) — Blocking operations shows how to write blocking commands that will not reply immediately, but will block the client, without blocking the Valkey server, and will provide a reply whenever will be possible. ✨
  • valkey-modules-api-ref(7) — Valkey modules API reference is generated from module.c top comments of ValkeyModule functions. It is a good reference in order to understand how each function works. 📚

Valkey modules make it possible to extend Valkey functionality using external modules, rapidly implementing new Valkey commands with features similar to what can be done inside the core itself. Lowkey iconic, fr fr. 👑

Valkey modules are dynamic libraries that can be loaded into Valkey at startup, or using the MODULE LOAD command. Valkey exports a C API, in the form of a single C header file called valkeymodule.h. Modules are meant to be written in C, however it will be possible to use C++ or other languages that have C binding functionalities. 🫶

Modules are designed in order to be loaded into different versions of Valkey, so a given module does not need to be designed, or recompiled, in order to run with a specific version of Valkey. For this reason, the module will register to the Valkey core using a specific API version. The current API version is “1”. ⭐

🚀 Loading modules 🚀

In order to test the module you are developing, you can load the module using the following valkey.conf configuration directive:

loadmodule /path/to/mymodule.so

It is also possible to load a module at runtime using the following command:

MODULE LOAD /path/to/mymodule.so

In order to list all loaded modules, use:

MODULE LIST

Finally, you can unload (and later reload if you wish) a module using the following command:

MODULE UNLOAD mymodule

Note that mymodule above is not the filename without the .so suffix, but instead, the name the module used to register itself into the Valkey core. The name can be obtained using MODULE LIST. However it is good practice that the filename of the dynamic library is the same as the name the module uses to register itself into the Valkey core. 🧚

🧁 The simplest module you can write 🧁

In order to show the different parts of a module, here we’ll show a very simple module that implements a command that outputs a random number.

#include "valkeymodule.h"

#include <stdlib.h>

int HelloworldRand_ValkeyCommand(ValkeyModuleCtx *ctx, ValkeyModuleString **argv, int argc) {
    ValkeyModule_ReplyWithLongLong(ctx,rand());
    return VALKEYMODULE_OK;
}

int ValkeyModule_OnLoad(ValkeyModuleCtx *ctx, ValkeyModuleString **argv, int argc) {
    if (ValkeyModule_Init(ctx,"helloworld",1,VALKEYMODULE_APIVER_1)
        == VALKEYMODULE_ERR) return VALKEYMODULE_ERR;

    if (ValkeyModule_CreateCommand(ctx,"helloworld.rand",
        HelloworldRand_ValkeyCommand, "fast random",
        0, 0, 0) == VALKEYMODULE_ERR)
        return VALKEYMODULE_ERR;

    return VALKEYMODULE_OK;
}

The example module has two functions. One implements a command called HELLOWORLD.RAND. This function is specific of that module. However the other function called ValkeyModule_OnLoad() must be present in each Valkey module. It is the entry point for the module to be initialized, register its commands, and potentially other private data structures it uses. 💫

Note that it is a good idea for modules to call commands with the name of the module followed by a dot, and finally the command name, like in the case of HELLOWORLD.RAND. This way it is less likely to have collisions.

Note that if different modules have colliding commands, they’ll not be able to work in Valkey at the same time, since the function ValkeyModule_CreateCommand will fail in one of the modules, so the module loading will abort returning an error condition. 😭

🌟 Module initialization 🌟

The above example shows the usage of the function ValkeyModule_Init(). It should be the first function called by the module OnLoad function. The following is the function prototype:

int ValkeyModule_Init(ValkeyModuleCtx *ctx, const char *modulename,
                     int module_version, int api_version);

The Init function announces the Valkey core that the module has a given name, its version (that is reported by MODULE LIST), and that is willing to use a specific version of the API.

If the API version is wrong, the name is already taken, or there are other similar errors, the function will return VALKEYMODULE_ERR, and the module OnLoad function should return ASAP with an error.

⚠️ Before the Init function is called, no other API function can be called, otherwise the module will segfault and the Valkey instance will crash. Not dramatic, just facts. 💀

The second function called, ValkeyModule_CreateCommand, is used in order to register commands into the Valkey core. The following is the prototype:

int ValkeyModule_CreateCommand(ValkeyModuleCtx *ctx, const char *name,
                              ValkeyModuleCmdFunc cmdfunc, const char *strflags,
                              int firstkey, int lastkey, int keystep);

As you can see, most Valkey modules API calls all take as first argument the context of the module, so that they have a reference to the module calling it, to the command and client executing a given command, and so forth. 💅

To create a new command, the above function needs the context, the command’s name, a pointer to the function implementing the command, the command’s flags and the positions of key names in the command’s arguments.

The function that implements the command must have the following prototype:

int mycommand(ValkeyModuleCtx *ctx, ValkeyModuleString **argv, int argc);

The command function arguments are just the context, that will be passed to all the other API calls, the command argument vector, and total number of arguments, as passed by the user.

As you can see, the arguments are provided as pointers to a specific data type, the ValkeyModuleString. This is an opaque data type you have API functions to access and use, direct access to its fields is never needed. 🦋

Zooming into the example command implementation, we can find another call:

int ValkeyModule_ReplyWithLongLong(ValkeyModuleCtx *ctx, long long integer);

This function returns an integer to the client that invoked the command, exactly like other Valkey commands do, like for example INCR or SCARD. ✨

🧼 Module cleanup 🧼

In most cases, there is no need for special cleanup. When a module is unloaded, Valkey will automatically unregister commands and unsubscribe from notifications. However in the case where a module contains some persistent memory or configuration, a module may include an optional ValkeyModule_OnUnload function. If a module provides this function, it will be invoked during the module unload process. The following is the function prototype:

int ValkeyModule_OnUnload(ValkeyModuleCtx *ctx);

The OnUnload function may prevent module unloading by returning VALKEYMODULE_ERR. Otherwise, VALKEYMODULE_OK should be returned. 🫶

🛠️ Setup and dependencies of a Valkey module 🛠️

Valkey modules don’t depend on Valkey or some other library, nor they need to be compiled with a specific valkeymodule.h file. In order to create a new module, just copy a recent version of valkeymodule.h in your source tree, link all the libraries you want, and create a dynamic library having the ValkeyModule_OnLoad() function symbol exported. 🌈

The module will be able to load into different versions of Valkey.

A module can be designed to support both newer and older Redis OSS versions where certain API functions are not available in all versions. If an API function is not implemented in the currently running Redis OSS version, the function pointer is set to NULL. This allows the module to check if a function exists before using it:

if (ValkeyModule_SetCommandInfo != NULL) {
    ValkeyModule_SetCommandInfo(cmd, &info);
}

In recent versions of valkeymodule.h, a convenience macro RMAPI_FUNC_SUPPORTED(funcname) is defined. Using the macro or just comparing with NULL is a matter of personal preference. 💜

🌈 PASSING CONFIGURATION PARAMETERS TO VALKEY MODULES 🌈

When the module is loaded with the MODULE LOAD command, or using the loadmodule directive in the valkey.conf file, the user is able to pass configuration parameters to the module by adding arguments after the module file name:

loadmodule mymodule.so foo bar 1234

In the above example the strings foo, bar and 1234 will be passed to the module OnLoad() function in the argv argument as an array of ValkeyModuleString pointers. The number of arguments passed is into argc. 👑

The way you can access those strings will be explained in the rest of this document. Normally the module will store the module configuration parameters in some static global variable that can be accessed module wide, so that the configuration can change the behavior of different commands.

💖 Working with ValkeyModuleString objects 💖

The command argument vector argv passed to module commands, and the return value of other module APIs functions, are of type ValkeyModuleString.

Usually you directly pass module strings to other API calls, however sometimes you may need to directly access the string object.

There are a few functions in order to work with string objects:

const char *ValkeyModule_StringPtrLen(ValkeyModuleString *string, size_t *len);

The above function accesses a string by returning its pointer and setting its length in len. You should never write to a string object pointer, as you can see from the const pointer qualifier.

However, if you want, you can create new string objects using the following API:

ValkeyModuleString *ValkeyModule_CreateString(ValkeyModuleCtx *ctx, const char *ptr, size_t len);

The string returned by the above command must be freed using a corresponding call to ValkeyModule_FreeString():

void ValkeyModule_FreeString(ValkeyModuleString *str);

However if you want to avoid having to free strings, the automatic memory management, covered later in this document, can be a good alternative, by doing it for you. 🎀

okay quick lil note before we move on, bestie, because this trips people up — the strings you get handed through the argument vector argv? you never need to free those. Ever. Not once. 💅 The only strings you're responsible for freeing are the new ones you create yourself, or new ones that come back from other APIs where the docs specifically tell you "yeah, this one's yours, go free it". That's the whole rule, no cap.

🌸 Creating strings from numbers or parsing strings as numbers 🌸

Making a brand new string out of an integer is like, the most common thing ever, so obviously there's a function for it:

ValkeyModuleString *mystr = ValkeyModule_CreateStringFromLongLong(ctx,10);

And same energy in reverse — if you wanna parse a string as a number:

long long myval;
if (ValkeyModule_StringToLongLong(ctx,argv[1],&myval) == VALKEYMODULE_OK) {
    /* Do something with 'myval' */
}

👑 Accessing Valkey keys from modules 👑

Okay so real talk: most Valkey modules, to actually be useful, gotta talk to the Valkey data space. (Not always tho — like an ID generator might literally never touch a single Valkey key, and that's valid.) So Valkey modules get two different APIs for reaching into the data space:

  • One is a low level API — it's giving very fast access, plus a whole set of functions for manipulating Valkey data structures directly.
  • The other is more high level — it lets you call Valkey commands and fetch the result, basically the same way Lua scripts access Valkey.

The high level API is also super useful when you need to reach Valkey functionality that just... isn't exposed as an API otherwise. iykyk.

Generally, module devs should prefer the low level API, because commands built with it run at a speed comparable to native Valkey commands. ✨ But the higher level API absolutely has its use cases — sometimes the actual bottleneck is processing the data, not accessing it.

Also, lowkey important: sometimes using the low level API is not harder than the higher level one. Fr fr.

💖 Calling Valkey commands 💖

The high level API for accessing Valkey is literally just the sum of the ValkeyModule_Call() function, plus all the functions you need to access the reply object that Call() hands back.

ValkeyModule_Call uses a special calling convention with a format specifier, which tells it what kind of objects you're passing as arguments.

Valkey commands get invoked with just a command name and a list of arguments. But here's the thing — when you call commands, those arguments can come from all different kinds of strings: null-terminated C strings, ValkeyModuleString objects like the ones you get from the argv parameter in a command implementation, binary safe C buffers with a pointer and a length, and so on and so forth. 🦋

So say I wanna call INCRBY where the first argument (the key) is a string I got from the argument vector argv (which is an array of ValkeyModuleString object pointers), and the second argument (the increment) is a C string representing the number "10". Here's the call:

ValkeyModuleCallReply *reply;
reply = ValkeyModule_Call(ctx,"INCRBY","sc",argv[1],"10");

Break it down, bestie:

  • The first argument is the context.
  • The second is always a null terminated C string holding the command name.
  • The third is the format specifier, where every single character corresponds to the type of the argument that follows it. In the case above, "sc" means a ValkeyModuleString object, then a null terminated C string.
  • The rest are just the arguments, as specified. So argv[1] is a ValkeyModuleString and "10" is a null terminated C string. 🎀

Here's the full list of format specifiers:

  • c — Null terminated C string pointer.
  • b — C buffer, two arguments needed: C string pointer and size_t length.
  • s — ValkeyModuleString as received in argv or from other Valkey module APIs returning a ValkeyModuleString object.
  • l — Long long integer.
  • v — Array of ValkeyModuleString objects.
  • ! — This modifier just tells the function to replicate the command to replicas and AOF. It's ignored from the point of view of arguments parsing.
  • A — This modifier, when ! is given, tells it to suppress AOF propagation: the command will be propagated only to replicas.
  • R — This modifier, when ! is given, tells it to suppress replicas propagation: the command will be propagated only to the AOF, if enabled.

The function returns a ValkeyModuleCallReply object on success. On error, NULL is returned.

And NULL comes back in these situations, so listen up:

  • when the command name is invalid,
  • when the format specifier uses characters that aren't recognized,
  • or when the command is called with the wrong number of arguments.

In all of those cases, the errno var is set to EINVAL. 👀

NULL is also returned when — on an instance with Cluster enabled — the target keys are about non local hash slots. In that case errno is set to EPERM.

🌈 Working with ValkeyModuleCallReply objects. 🌈

ValkeyModule_Call returns reply objects that you access with the ValkeyModule_CallReply* family of functions. 🫶

To get the type of a reply (corresponding to one of the data types supported by the Valkey protocol), you use ValkeyModule_CallReplyType():

reply = ValkeyModule_Call(ctx,"INCRBY","sc",argv[1],"10");
if (ValkeyModule_CallReplyType(reply) == VALKEYMODULE_REPLY_INTEGER) {
    long long myval = ValkeyModule_CallReplyInteger(reply);
    /* Do something with myval. */
}

The valid reply types are:

  • VALKEYMODULE_REPLY_STRING — Bulk string or status replies.
  • VALKEYMODULE_REPLY_ERROR — Errors.
  • VALKEYMODULE_REPLY_INTEGER — Signed 64 bit integers.
  • VALKEYMODULE_REPLY_ARRAY — Array of replies.
  • VALKEYMODULE_REPLY_NULL — NULL reply.

Strings, errors and arrays all have an associated length. For strings and errors, that length is the length of the string. For arrays, it's the number of elements. Grab the reply length with:

size_t reply_len = ValkeyModule_CallReplyLength(reply);

To get the value of an integer reply, use this one (already saw it in the example above, but here it is again):

long long reply_integer_val = ValkeyModule_CallReplyInteger(reply);
Called with a reply object of the wrong type, that function always returns LLONG_MIN. So like... don't do that. 💀

Sub elements of array replies are accessed like this:

ValkeyModuleCallReply *subreply;
subreply = ValkeyModule_CallReplyArrayElement(reply,idx);

That function returns NULL if you try to access out of range elements. 🙈

Strings and errors (which are like strings but with a different type) are accessed like this — and make sure you never write to the resulting pointer (it comes back as a const pointer, so misusing it has to be pretty explicit on your part):

size_t len;
char *ptr = ValkeyModule_CallReplyStringPtr(reply,&len);

If the reply type is not a string or an error, NULL is returned.

Now, ValkeyCallReply objects are not the same as module string objects (ValkeyModuleString types). But sometimes you'll need to pass a reply of type string or integer into an API function that's expecting a module string. 😭

When that happens, you might wanna evaluate whether the low level API would just be a simpler way to implement your command — or you can use this function to create a new string object from a call reply of type string, error or integer:

ValkeyModuleString *mystr = ValkeyModule_CreateStringFromCallReply(myreply);

If the reply isn't of the right type, NULL is returned. The returned string object should be released with ValkeyModule_FreeString() like usual — or by enabling automatic memory management (see the corresponding section). ✨

🎀 Releasing call reply objects 🎀

Reply objects must be freed using ValkeyModule_FreeCallReply. For arrays, you only free the top level reply — not the nested replies.

Currently the module implementation provides a protection in order to avoid crashing if you free a nested reply object for error, HOWEVER this feature is not guaranteed to be here forever, so it should not be considered part of the API. Don't get comfy with it, bestie. 💅

If you use automatic memory management (explained later in this document), you don't need to free replies — but you still could if you wanna release memory ASAP. Your call. 🦋

⭐ Returning values from Valkey commands ⭐

Like normal Valkey commands, new commands implemented via modules have to be able to return values to the caller. The API exports a whole set of functions for this, so you can return the usual types of the Valkey protocol, plus arrays of those types as elements. Errors can be returned too, with any error string and code (the error code is the initial uppercase letters in the error message — like the "BUSY" string in the "BUSY the sever is busy" error message). 👑

All the functions that send a reply to the client are called ValkeyModule_ReplyWith<something>.

To return an error, use:

ValkeyModule_ReplyWithError(ValkeyModuleCtx *ctx, const char *err);

There's a predefined error string for key of wrong type errors:

VALKEYMODULE_ERRORMSG_WRONGTYPE

Example usage:

ValkeyModule_ReplyWithError(ctx,"ERR invalid arguments");

We already saw how to reply with a long long up in the examples above:

ValkeyModule_ReplyWithLongLong(ctx,12345);

To reply with a simple string — which can't contain binary values or newlines, so it's suitable for sending small words like "OK" — we use:

ValkeyModule_ReplyWithSimpleString(ctx,"OK");

It's possible to reply with "bulk strings" that are binary safe, using two different functions:

int ValkeyModule_ReplyWithStringBuffer(ValkeyModuleCtx *ctx, const char *buf, size_t len);

int ValkeyModule_ReplyWithString(ValkeyModuleCtx *ctx, ValkeyModuleString *str);

The first one gets a C pointer and length. The second one gets a ValkeyModuleString object. Use whichever one matches the source type you've got at hand. 🫶

To reply with an array, you just use a function to emit the array length, followed by as many calls to the functions above as there are elements in the array:

ValkeyModule_ReplyWithArray(ctx,2);
ValkeyModule_ReplyWithStringBuffer(ctx,"age",3);
ValkeyModule_ReplyWithLongLong(ctx,22);

And returning nested arrays? So easy. Your nested array element just uses another call to ValkeyModule_ReplyWithArray() followed by the calls to emit the sub array elements. 🌈

💫 Returning arrays with dynamic length 💫

Okay bestie, sometimes you literally cannot know ahead of time how many items an array reply is gonna have. Picture a Valkey module that implements a FACTOR command — you give it a number, it spits out the prime factors. Instead of factorizing the whole number, shoving the prime factors into an array, and then producing the reply (so much extra work, not the vibe), the better move is to start an array reply where the length is unknown and set it later. This is giving ✨ deferred commitment ✨ and it's done with a special argument to ValkeyModule_ReplyWithArray():

ValkeyModule_ReplyWithArray(ctx, VALKEYMODULE_POSTPONED_LEN);

That call starts an array reply, so now you can use other ReplyWith calls to produce the array items. Then finally, to set the length, you call:

ValkeyModule_ReplySetArrayLength(ctx, number_of_items);

For the FACTOR command, that translates into code kinda like this:

ValkeyModule_ReplyWithArray(ctx, VALKEYMODULE_POSTPONED_LEN);
number_of_factors = 0;
while(still_factors) {
    ValkeyModule_ReplyWithLongLong(ctx, some_factor);
    number_of_factors++;
}
ValkeyModule_ReplySetArrayLength(ctx, number_of_factors);

Another super common use case for this feature: iterating over the arrays of some collection and only returning the ones that pass some kind of filtering. Filtered, curated, iconic. 🎀

And yes, you can have multiple nested arrays with postponed reply. Each call to SetArray() sets the length of the latest corresponding call to ReplyWithArray():

ValkeyModule_ReplyWithArray(ctx, VALKEYMODULE_POSTPONED_LEN);
// ... generate 100 elements ...
ValkeyModule_ReplyWithArray(ctx, VALKEYMODULE_POSTPONED_LEN);
// ... generate 10 elements ...
ValkeyModule_ReplySetArrayLength(ctx, 10);
ValkeyModule_ReplySetArrayLength(ctx, 100);

This creates a 100 items array having as last element a 10 items array. Nesting queen behavior fr fr. 🪆

🔍 Arity and type checks 🔍

Often commands need to check that the number of arguments and the type of the key are correct. To report a wrong arity, there's a specific function called ValkeyModule_WrongArity(). The usage is trivial:

if (argc != 2) return ValkeyModule_WrongArity(ctx);

Checking for the wrong type means opening the key and checking the type:

ValkeyModuleKey *key = ValkeyModule_OpenKey(ctx,argv[1],
    VALKEYMODULE_READ|VALKEYMODULE_WRITE);

int keytype = ValkeyModule_KeyType(key);
if (keytype != VALKEYMODULE_KEYTYPE_STRING &&
    keytype != VALKEYMODULE_KEYTYPE_EMPTY)
{
    ValkeyModule_CloseKey(key);
    return ValkeyModule_ReplyWithError(ctx,VALKEYMODULE_ERRORMSG_WRONGTYPE);
}
Little note bestie: you often want to proceed with a command both if the key is of the expected type, or if it's empty. Don't gatekeep the empty keys. 🫶

🔑 Low level access to keys 🔑

Low level access to keys lets you perform operations on value objects associated to keys directly, with a speed similar to what Valkey uses internally to implement the built-in commands. Like, internal-employee speed. No cap. 🔥

Once a key is opened, a key pointer is returned that will be used with all the other low level API calls to perform operations on the key or its associated value.

Because the API is meant to be very fast, it cannot do too many run-time checks, so the user must be aware of certain rules to follow:

  • Opening the same key multiple times where at least one instance is opened for writing, is undefined and may lead to crashes. 💀
  • While a key is open, it should only be accessed via the low level key API. For example opening a key, then calling DEL on the same key using the ValkeyModule_Call() API will result into a crash. However it is safe to open a key, perform some operation with the low level API, closing it, then using other APIs to manage the same key, and later opening it again to do some more work. So: close the door behind you before you redecorate the room. 🚪

In order to open a key the ValkeyModule_OpenKey function is used. It returns a key pointer, that we'll use with all the next calls to access and modify the value:

ValkeyModuleKey *key;
key = ValkeyModule_OpenKey(ctx,argv[1],VALKEYMODULE_READ);

The second argument is the key name, that must be a ValkeyModuleString object. The third argument is the mode: VALKEYMODULE_READ or VALKEYMODULE_WRITE. It is possible to use | to bitwise OR the two modes to open the key in both modes. Currently a key opened for writing can also be accessed for reading but this is to be considered an implementation detail. The right mode should be used in sane modules. (Be a sane module. Use the right mode. 💅)

You can open non existing keys for writing, since the keys will be created when an attempt to write to the key is performed. However when opening keys just for reading, ValkeyModule_OpenKey will return NULL if the key does not exist.

Once you are done using a key, you can close it with:

ValkeyModule_CloseKey(key);
Good news: if automatic memory management is enabled, you are not forced to close keys. When the module function returns, Valkey will take care to close all the keys which are still open. Valkey is your cleanup crew bestie. ✨

🏷️ Getting the key type 🏷️

In order to obtain the value of a key, use the ValkeyModule_KeyType() function:

int keytype = ValkeyModule_KeyType(key);

It returns one of the following values:

VALKEYMODULE_KEYTYPE_EMPTY
VALKEYMODULE_KEYTYPE_STRING
VALKEYMODULE_KEYTYPE_LIST
VALKEYMODULE_KEYTYPE_HASH
VALKEYMODULE_KEYTYPE_SET
VALKEYMODULE_KEYTYPE_ZSET

The above are just the usual Valkey key types, with the addition of an empty type, that signals the key pointer is associated with an empty key that does not yet exists. It's giving "placeholder era". 🙈

🌱 Creating new keys 🌱

To create a new key, open it for writing and then write to it using one of the key writing functions. Example:

ValkeyModuleKey *key;
key = ValkeyModule_OpenKey(ctx,argv[1],VALKEYMODULE_WRITE);
if (ValkeyModule_KeyType(key) == VALKEYMODULE_KEYTYPE_EMPTY) {
    ValkeyModule_StringSet(key,argv[2]);
}

Manifesting that key into existence. 🦋

🗑️ Deleting keys 🗑️

Just use:

ValkeyModule_DeleteKey(key);

The function returns VALKEYMODULE_ERR if the key is not open for writing. Note that after a key gets deleted, it is setup in order to be targeted by new key commands. For example ValkeyModule_KeyType() will return it is an empty key, and writing to it will create a new key, possibly of another type (depending on the API used). Glow up transformation, honestly. ✨

⏳ Managing key expires (TTLs) ⏳

To control key expires two functions are provided, that are able to set, modify, get, and unset the time to live associated with a key. The full TTL package deal. 🎁

One function is used in order to query the current expire of an open key:

mstime_t ValkeyModule_GetExpire(ValkeyModuleKey *key);

The function returns the time to live of the key in milliseconds, or VALKEYMODULE_NO_EXPIRE as a special value to signal the key has no associated expire or does not exist at all (you can differentiate the two cases checking if the key type is VALKEYMODULE_KEYTYPE_EMPTY). Two very different problems, one very same answer. 😭

In order to change the expire of a key the following function is used instead:

int ValkeyModule_SetExpire(ValkeyModuleKey *key, mstime_t expire);

When called on a non existing key, VALKEYMODULE_ERR is returned, because the function can only associate expires to existing open keys (non existing open keys are only useful in order to create new values with data type specific write operations). Can't expire something that isn't there, bestie. 🙅

Again the expire time is specified in milliseconds. If the key has currently no expire, a new expire is set. If the key already have an expire, it is replaced with the new value. Overwrite energy. 💅

If the key has an expire, and the special value VALKEYMODULE_NO_EXPIRE is used as a new expire, the expire is removed, similarly to the Valkey PERSIST command. In case the key was already persistent, no operation is performed. Nothing to do, so we simply do nothing. Periodt. 🌸

📏 Obtaining the length of values 📏

There is a single function in order to retrieve the length of the value associated to an open key. The returned length is value-specific, and is the string length for strings, and the number of elements for the aggregated data types (how many elements there is in a list, set, sorted set, hash).

size_t len = ValkeyModule_ValueLength(key);

If the key does not exist, 0 is returned by the function:

🧵 String type API 🧵

Setting a new string value, like the Valkey SET command does, is performed using:

int ValkeyModule_StringSet(ValkeyModuleKey *key, ValkeyModuleString *str);

The function works exactly like the Valkey SET command itself, that is, if there is a prior value (of any type) it will be deleted. Old value? Gone. Not invited to the function. 💀

Accessing existing string values is performed using DMA (direct memory access) for speed. The API will return a pointer and a length, so that's possible to access and, if needed, modify the string directly.

size_t len, j;
char *myptr = ValkeyModule_StringDMA(key,&len,VALKEYMODULE_WRITE);
for (j = 0; j < len; j++) myptr[j] = 'A';

In the above example we write directly on the string. Note that if you want to write, you must be sure to ask for WRITE mode. No sneaking writes in read mode, that's not the move. 👑

Important: DMA pointers are only valid if no other operations are performed with the key before using the pointer, after the DMA call.

Sometimes when we want to manipulate strings directly, we need to change their size as well. For this scope, the ValkeyModule_StringTruncate function is used. Example:

ValkeyModule_StringTruncate(mykey,1024);

The function truncates, or enlarges the string as needed, padding it with zero bytes if the previous length is smaller than the new length we request. If the string does not exist since key is associated to an open empty key, a string value is created and associated to the key.

Heads up: every time StringTruncate() is called, we need to re-obtain the DMA pointer again, since the old may be invalid. The old pointer is stale, expired, blocked. 🚫

For a complete list of string type functions, see Key API for String type in the Modules API reference.

🍓 List type API 🍓

It's possible to push and pop values from list values:

int ValkeyModule_ListPush(ValkeyModuleKey *key, int where, ValkeyModuleString *ele);
ValkeyModuleString *ValkeyModule_ListPop(ValkeyModuleKey *key, int where);

In both the APIs the where argument specifies if to push or pop from tail or head, using the following macros:

VALKEYMODULE_LIST_HEAD
VALKEYMODULE_LIST_TAIL

Elements returned by ValkeyModule_ListPop() are like strings created with ValkeyModule_CreateString(), they must be released with ValkeyModule_FreeString() or by enabling automatic memory management. Free your strings bestie, don't leak them, that's not cute. 🎀

For a complete list of set type functions, see Key API for List type in the Modules API reference.

💅 Set type API

Okay so bestie, listen — a direct API for set type keys? Not implemented yet. Nope, doesn't exist. 😭 If you wanna poke at keys of type set, you gotta slide through the ValkeyModule_Call API and use set commands like SADD. That's the move. 🫶

🎀 Sorted set type API

Head over to the Key API for Sorted Set type section in the Modules API reference. It's all there, iykyk. ✨

🌸 Hash type API

Same energy, different type — check valkey-modules-api-ref(7) Key API for Hash type in the Modules API reference. 💜

🔥 Replicating commands

So if you want your module commands to act exactly like normal Valkey commands — like, in the context of replicated Valkey instances, or when using the AOF file for persistence — it's important for module commands to handle their replication in a consistent way. No cap.

When you're using the higher level APIs to invoke commands, replication just happens automatically if you use the "!" modifier in the format string of ValkeyModule_Call(), like this:

reply = ValkeyModule_Call(ctx,"INCRBY","!sc",argv[1],"10");

See how the format specifier is "!sc"? The bang is not parsed as a format specifier — instead it internally flags the command as “must replicate”. Iconic behavior honestly.

If you use that programming style, you're chilling. No problems. 🧘‍♀️

But sometimes things are more complex than that, and you're out here using the low level API. In that case: if there are no side effects in the command execution, and it consistently always performs the same work, what you can do is replicate the command verbatim, exactly as the user executed it. To do that, you just call:

ValkeyModule_ReplicateVerbatim(ctx);
⚠️ When you use the above API, you should not use any other replication function, since they are not guaranteed to mix well. Periodt.

But wait, that's not the only option bestie. 👀 It's also possible to exactly tell Valkey what commands to replicate as the effect of the command execution, using an API similar to ValkeyModule_Call() — except instead of calling the command, it sends it to the AOF / replicas stream. Like so:

ValkeyModule_Replicate(ctx,"INCRBY","cl","foo",my_increment);

You can call ValkeyModule_Replicate multiple times, and each one will emit a command. And all the sequence emitted gets wrapped between a MULTI/EXEC transaction, so that the AOF and replication effects are the same as executing a single command. Slay. 💅

Now, a lil note: Call() replication and Replicate() replication have a rule, in case you want to mix both forms of replication (which is not necessarily a good idea if there are simpler approaches). The rule is: commands replicated with Call() are always the first emitted in the final MULTI/EXEC block, while all the commands emitted with Replicate() will follow after. 🌈

💖 Automatic memory management

Normally when you're writing programs in the C language, you as the programmer have to manage memory manually. That's literally why the Valkey modules API has functions to release strings, close open keys, free replies, and so forth. 😮‍💨

BUT — given that commands are executed in a contained environment with a set of strict APIs, Valkey is able to provide automatic memory management to modules, at the cost of some performance (most of the time, a very low cost). Bestie, that's a deal.

When automatic memory management is enabled:

  1. You don't need to close open keys. 🎀
  2. You don't need to free replies. ✨
  3. You don't need to free ValkeyModuleString objects. 💜

However, you can still do it if you want. Like, automatic memory management may be active, but if you're inside a loop allocating a lot of strings, you may still want to free strings that are no longer used. Totally valid.

To enable automatic memory management, just call this function at the start of the command implementation:

ValkeyModule_AutoMemory(ctx);

Automatic memory management is usually the way to go — however, experienced C programmers may not use it in order to gain some speed and memory usage benefit. Main character choices, honestly. 👑

🦋 Allocating memory into modules

Normal C programs use malloc() and free() to allocate and release memory dynamically. And while in Valkey modules the use of malloc is not technically forbidden, it's a lot better to use the Valkey Modules specific functions — they're exact replacements for malloc, free, realloc and strdup. Those functions are:

void *ValkeyModule_Alloc(size_t bytes);
void* ValkeyModule_Realloc(void *ptr, size_t bytes);
void ValkeyModule_Free(void *ptr);
void ValkeyModule_Calloc(size_t nmemb, size_t size);
char *ValkeyModule_Strdup(const char *str);

They work exactly like their libc equivalent calls — except they use the same allocator Valkey uses. And the memory allocated using these functions gets reported by the INFO command in the memory section, is accounted when enforcing the maxmemory policy, and in general is a first citizen of the Valkey executable. Meanwhile, the method allocated inside modules with libc malloc() is transparent to Valkey. 💀

Another reason to use the modules functions to allocate memory: when you're creating native data types inside modules, the RDB loading functions can return deserialized strings (from the RDB file) directly as ValkeyModule_Alloc() allocations. So they can be used directly to populate data structures after loading, instead of having to copy them to the data structure. Efficiency queen. 🧚

🍓 Pool allocator

Sometimes in command implementations, it's required to perform many small allocations that will not be retained at the end of the command execution — they're just functional to execute the command itself.

This work can be more easily accomplished using the Valkey pool allocator:

void *ValkeyModule_PoolAlloc(ValkeyModuleCtx *ctx, size_t bytes);

It works similarly to malloc(), and returns memory aligned to the next power of two of greater or equal to bytes (for a maximum alignment of 8 bytes). However, it allocates memory in blocks, so the overhead of the allocations is small — and more importantly, the memory allocated is automatically released when the command returns. 😌

So in general, short living allocations are good candidates for the pool allocator. 💖

🌈 Writing commands compatible with Valkey Cluster

See the Modules API reference for the following commands:

And that's a wrap on this whole page, bestie! 🎉 This one is from 9.0.0, dated 2025-10-21, and it's VALKEY-MODULES-INTRO(7) — go forth and write modules, you absolute icon. 👑💅✨

📦 where this page comes from