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 " .. kvdb.var.name)

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

kvdb.print(chunk)

Write data to the HTTP response.

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

kvdb.say(chunk)

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.

kvdb.redirect("https://www.example.com/")

kvdb.status

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

kvdb.header

Set HTTP response headers, namely the Content-Type. Note that if data has already been written to the HTTP response, setting headers has no effect. Only content-type is allowed to be set at this time, the default being text/plain.

kvdb.header["content-type"] = "text/html"

kvdb.exit([code])

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.

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.

kvdb.get(key)

Get a value.

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

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)
  kvdb.exit(500)
end

kvdb.incr(key, increment)

Increment the value stored at key by the increment amount, which can be positive or negative. The data type of the value stored in the key must be either an integer or a float. If the key does not exist, it will be created.

local key = os.date("visitors:%Y-%m-%d")
local err = kvdb.incr(key, 1)
if err then
  kvdb.say("error incrementing: " .. err)
  kvdb.exit(500)
end

local value = kvdb.get(key)
kvdb.say(value)

kvdb.delete(key)

Delete a key-value pair.

local err = kvdb.delete("key")
if err then
  kvdb.say("error deleting key: " .. err)
  kvdb.exit(500)
end

kvdb.list(prefix)

List keys by prefix.

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

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

kvdb.scope

Get or set the database scope to restrict queries to a subset of the database denoted by a prefix or restirct the kinds of queries that can be made. If an access token is supplied (in the URL or in the HTTP Authorization header), the kvdb.scope table already reflects the granted scope (prefix and permissions) contained in the token.

Note that the prefix and permissions for the scope must be set separately; assigning a table to the kvdb.scope field will not work.

kvdb.say("scope prefix: " .. kvdb.scope.prefix)

kvdb.print("scope permissions: ")
for i, p in ipairs(kvdb.scope.permissions) do
  kvdb.print(p .. " ")
end
kvdb.say()

-- only allow read-write operations to a subset of the database
kvdb.scope.prefix = "users:1:"
kvdb.scope.permissions = {"read", "write"}

kvdb.set("users:1:name", "bob")
kvdb.set("users:2:name", "kim") -- this will return an error

The scoped database feature of the scripting engine makes it possible to implement complex server-side access control logic by the use of permissioned and prefixed access tokens. KVdb automatically sets the appropriate scope from the access token when provided.

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

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