Lua

This extension adds the embedded scripting language Lua to DuckDB. Lua is a powerful, small, embedded, and free scripting language.

Install via community extensions:

INSTALL lua FROM community; -- First time only
LOAD loa;

Evaluate a Lua expression in SQL:

SELECT lua('return "a" .. context', 'b');

Returns "ab".

For JSON input/output:

SELECT lua_json('return "a" .. context', '"json"'::json);

Returns "ajson".

For the context parameter, you can pass in strings, integers, floats, booleans, and so on. Except for JSON input, the return type will be VARCHAR.

If a Lua error is encountered, the statement will be errored.

If you pass in JSON type data, it will be deserialized for you on the Lua side and the Lua return value will also be JSON serialized.

If you wish to rename the context variable, provide a third argument:

SELECT lua('return ctx', 'abc', 'ctx');

Building

Managing dependencies

DuckDB extensions uses VCPKG for dependency management. Enabling VCPKG is very simple: follow the installation instructions or just run the following:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
git checkout cd61e1e26a038e82d6550a3ebbe0fbbfe7da78e3
cd ..
./vcpkg/bootstrap-vcpkg.sh
export VCPKG_TOOLCHAIN_PATH=`pwd`/vcpkg/scripts/buildsystems/vcpkg.cmake

Build steps

Now to build the extension, run:

GEN=ninja make release

The main binaries that will be built are:

./build/release/duckdb
./build/release/test/unittest
./build/release/extension/lua/lua.duckdb_extension

• duckdb is the binary for the duckdb shell with the extension code automatically loaded.
• unittest is the test runner of duckdb. Again, the extension is already linked into the binary.
• lua.duckdb_extension is the loadable binary as it would be distributed.

Running the extension

To run the extension code, simply start the shell with ./build/release/duckdb.

Now we can use the features from the extension directly in DuckDB. The template contains a scalar function lua() that takes a string arguments and returns a string:

D select lua('return "aa" .. "bb"') as result;
┌───────────────┐
│    result     │
│    varchar    │
├───────────────┤
│ aabb          │
└───────────────┘

Running the tests

Different tests can be created for DuckDB extensions. The primary way of testing DuckDB extensions should be the SQL tests in ./test/sql. These SQL tests can be run using:

make test

License

duckdb-lua Copyright 2025 Isaac Brodsky. Licensed under the MIT License.

DuckDB Copyright 2018-2022 Stichting DuckDB Foundation (MIT License)

DuckDB extension-template Copyright 2018-2022 DuckDB Labs BV (MIT License)

DuckDB extension-template-c

Lua Copyright © 1994–2025 Lua.org, PUC-Rio. (MIT License)

dkjson Copyright (C) 2010-2024 David Heiko Kolf (MIT License)