---
title: "Getting Started With Lua UDFs"
description: "Guide to implementing Lua UDFs in Aerospike, covering supported versions and programming restrictions."
---

# Getting Started With Lua UDFs

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/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](https://www.lua.org/about.html).

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

-   [Programming in Lua](https://www.lua.org/pil/)
-   [Lua Reference Manual](https://www.lua.org/manual/5.4/)
-   [Lua Tutorials](http://lua-users.org/wiki/TutorialDirectory)
-   [Lua Unofficial FAQ (uFAQ)](https://www.luafaq.org/)

## 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.

```lua
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.

```lua
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`](https://aerospike.com/docs/database/reference/config#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](https://aerospike.com/docs/database/advanced/udf/security) for the full list and a migration checklist.