Getting Started With Lua UDFs

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

User Defined Functions are written in Lua. Lua is a powerful, fast, lightweight, embeddable scripting language. To learn more about Lua, see About Lua.

If this is your first foray into Lua programming, we suggest the following materials:

Lua Version

Starting with Database 7.0.0, Aerospike supports Lua 5.4. Previously, Aerospike used LuaJIT 2.1, which is compatible with Lua 5.1.

Lua Restrictions

Aerospike supports most of the Lua programming language, subject to sandbox restrictions described on this page.

Globals are restricted

Global variables are not allowed.
Global functions can only be called by Aerospike Database, and cannot be called by other Lua functions.
To call a custom Lua function from another Lua function, the called function must be declared as a “local” function. For example, external function sum() can call local function add(), provided it is defined as local.

    local function add(a,b)
          return a + b
    end

    function sum(a,b)
          return add(a,b)
    end

Restricted modules and functions

coroutines - Lua functions can call each other provided they are “forward declared” before their actual use. In this example, we forward-declare fun_B() and then we can use it inside the body of fun_B(). We don’t have to forward-declare fun_A() in this example because it is declared first.

    local fun_B

    local fun_A( foo )
        fun_B( foo.bar )
    end

    local fun_B( bar )
        fun_A( bar.foo )
    end

debug module – Not enabled due to not being able to support the debugging features in Lua.
os.exit() – Not enabled because it didn’t make sense for a Lua script to cause the database to process to exit.
io library – Calling functions from the Lua io library is not allowed.
os library – Only os.clock(), os.date(), os.difftime(), and os.time() are available in default mode.

Sandbox modes

The preceding restrictions describe the default sandbox. A stricter hardened mode is available by setting mod-lua.allow-unsafe-lua to false. Hardened mode removes the os, io, debug, dofile, loadfile, load, and loadstring globals entirely. It also blocks native .so UDF modules, blocks precompiled Lua bytecode, and requires the lowercase .lua extension at registration.

See UDF security and sandbox hardening for the full list and a migration checklist.