Lua

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

Note

This extension has not been released to community extensions yet. That is Coming Soon™, pending the release of DuckDB 1.4.0. In the mean time, build this extension with latest duckdb/duckdb.

Install via community extensions:

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

Evaluate a Lua expression in SQL:

SELECT lua('return "aa" .. context', "bb");

Returns "aabb".

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 an error is encountered, the error message will be returned instead. 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, use the following option:

SET lua_context_name = 'ctx';
SELECT lua('return ctx', 'abc');

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
./vcpkg/bootstrap-vcpkg.sh
export VCPKG_TOOLCHAIN_PATH=`pwd`/vcpkg/scripts/buildsystems/vcpkg.cmake

Note: VCPKG is only required for extensions that want to rely on it for dependency management. If you want to develop an extension without dependencies, or want to do your own dependency management, just skip this step. Note that the example extension uses VCPKG to build with a dependency for instructive purposes, so when skipping this step the build may not work without removing the dependency.

Build steps

Now to build the extension, run:

make

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)

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

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