Lua SDK reference

Read time: 3 minutes

Last edited: Jun 14, 2024

Version 2 of the Lua (server-side) SDK replaces users with contexts

A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users."

Code samples on this page are from the two most recent SDK versions where they differ. To learn more about upgrading, read Lua (server-side) SDK 1.x to 2.0 migration guide and Best practices for upgrading users to contexts.

Overview

This topic documents how to get started with the Lua SDK, and links to reference information on all of the supported features. We also provide documentation for running the SDK in NGINX and HAProxy.

SDK quick links

LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications:

Resource	Location
SDK API documentation	SDK API docs
GitHub repository	lua-server-sdk
Sample applications	Lua Lua with HAProxy Lua with OpenResty NGINX
Published module	LuaRocks

Get started

After you complete the Getting Started process, follow these steps to get started using the LaunchDarkly SDK in your Lua application.

The Lua server-side SDK is implemented using a foreign function interface that calls the C++ server-side SDK. You need to install the C++ server-side SDK dynamic library somewhere accessible by the linker.

To learn more, read C++ SDK reference (server-side).

Install the SDK

First, include the library:

local ld = require("launchdarkly_server_sdk")

The Lua SDK uses an SDK key

The Lua SDK uses an SDK key. Keys are specific to each project and environment. They are available from the Environments list for each project. To learn more about key types, read Keys.

Initialize the client

After you install and import the SDK, create a single, shared instance of LDClient. Specify your SDK key here to authorize your application to connect to a particular environment within LaunchDarkly.

LDClient must be a singleton

It's important to make LDClient a singleton for each LaunchDarkly project. The client instance maintains internal state that allows LaunchDarkly to serve feature flags without making any remote requests. Do not instantiate a new client with every request.

If you have multiple LaunchDarkly projects, you can create one LDClient for each. In this situation, the clients operate independently. For example, they do not share a single connection to LaunchDarkly.

Calling clientInit initiates a remote call to the LaunchDarkly service to fetch feature flags. This call blocks up for the time that you provide in milliseconds. If you request a feature flag before the client completes initialization, you will receive the default flag value.

Here is an example:

-- This will block for 1 second
local client = ld.clientInit("sdk-key-123abc", 1000, config)

To learn more about the specific configuration properties that are available in this SDK, read clientInit.

Evaluate a context

You can use client to check which variation a particular context will receive for a given feature flag.

Here's how:

if client:boolVariation(context, "flag-key-123abc", false) then
    print "feature is enabled"
else
    print "feature is disabled"
end

Supported features

This SDK supports the following features: