Lua Scripting Reference

Use KVdb's embedded Lua scripting engine to run your own scripts for working with keys and values.

In KVdb, each bucket can contain one or more scripts that can be executed over HTTP. The server provides a simple API to access the underlying keys and values in the bucket. For security, scripts are isolated from other buckets and can only access keys and values in the same bucket.

The scripting API is inspired and loosely modeled after OpenResty, the Nginx and Lua embedded web server framework.

HTTP Request

Request Variables

The kvdb.var table is populated with the HTTP request parameters, such as query parameters or POST body.

kvdb.say("Hello " ..

Now, if you access the script using a ?name=foo URL parameter (or POST to it), the output of the script will be:

Hello foo

The client's IP address can be accessed using kvdb.var.remote_addr.

HTTP Response


Write data to the HTTP resonse.

kvdb.print("Hello, world!\n")


Like kvdb.print, but writes a newline (\n) at the end.

kvdb.say("Hello, world!")

kvdb.redirect(url, [code])

Send an HTTP redirect response to the given URL. If code is not provided, 302 is used. Script execution stops after this statement.

return kvdb.redirect("")


Set the HTTP response status code, if different from the default 200 OK. Note that if data has already been written to the HTTP response, setting this value has no effect.

kvdb.status = 500


Terminate the script and set code to the HTTP status. Note that if data has already been written to the HTTP response, the code will be ignored. If code is omitted, the value from kvdb.status is used, otherwise the default of 200 is used. Script execution stops after this statement.

return kvdb.exit(403) -- forbidden

KVdb Query Interface

A simple Lua API lets you easily work with keys and values from scripts. By leveraging the built-in scripting engine in KVdb, you can significantly reduce latency for queries that depend on results from a previous query.


Get a value.

local value, info, err = kvdb.get("key")
if err then
  kvdb.say("error getting: " .. err)
  return kvdb.exit(500)

kvdb.say("value: " .. value)

kvdb.set(key, value)

Set a value.

local err = kvdb.set("key", "my value")
if err then
  kvdb.say("error setting: " .. err)
  return kvdb.exit(500)

kvdb.delete(key, value)

Delete a key-value pair.

local err = kvdb.delete("key", "my value")
if err then
  kvdb.say("error deleting key: " .. err)
  return kvdb.exit(500)


List keys by prefix.

local keys, err = kvdb.list("msg:")
if err then
  kvdb.say("error listing keys: " .. err)
  return kvdb.exit(500)

for _, key in ipairs(keys) do
  local val = kvdb.get(key)
  if val ~= nil then
    kvdb.say(key .. "=" .. val)

As you can see, scripting enables you to build almost any kind of server-side application using KVdb without requiring you to deploy any additional database!

Check out API reference guides and more code samples at the documentation portal.