A pure Lua client library for Apache Cassandra

$ opm get thibaultcha/lua-cassandra


![Module Version][badge-version-image] [![Build Status][badge-travis-image]][badge-travis-url] [![Coverage Status][badge-coveralls-image]][badge-coveralls-url]

A pure Lua client library for Apache Cassandra (2.x/3.x), compatible with [OpenResty].


This library offers 2 modules: a "single host" module, compatible with PUC Lua 5.1/5.2, LuaJIT and OpenResty, which allows your application to connect itself to a given Cassandra node, and a "cluster" module, only compatible with OpenResty which adds support for multi-node Cassandra datacenters.

  • Single host cassandra module:

    • no dependencies

    • support for Cassandra 2.x and 3.x

    • simple, prepared, and batch statements

    • pagination (manual and automatic via Lua iterators)

    • SSL client-to-node connections

    • client authentication

    • leverage the non-blocking, reusable cosocket API in ngx_lua (with automatic fallback to LuaSocket in non-supported contexts)

  • Cluster resty.cassandra.cluster module:

    • all features from the cassandra module

    • cluster topology discovery

    • advanced querying options

    • configurable policies (load balancing, retry, reconnection)

    • optimized performance for OpenResty


Single host module (Lua and OpenResty):

    local cassandra = require "cassandra"
    local peer = assert( {
      host = "",
      port = 9042,
      keyspace = "my_keyspace"
    assert(peer:execute("INSERT INTO users(id, name, age) VALUES(?, ?, ?)", {
      "John O Reilly",
    local rows = assert(peer:execute "SELECT * FROM users")
    local user = rows[1]
    print( -- John O Reilly
    print(user.age)  -- 42

Cluster module (OpenResty only):

    http {
        # you do not need the following line if you are using luarocks
        lua_package_path "/path/to/src/?.lua;/path/to/src/?/init.lua;;";
        # all cluster informations will be stored here
        lua_shared_dict cassandra 1m;
        server {
            location / {
                content_by_lua_block {
                    local Cluster = require 'resty.cassandra.cluster'
                    -- For performance reasons, the cluster variable
                    -- should live in an upvalue at the main chunk level of your
                    -- modules to avoid creating it on every request.
                    -- see the 'intro' example in the online documentation.
                    local cluster, err = {
                        shm = 'cassandra', -- defined by the lua_shared_dict directive
                        contact_points = {'', ''},
                        keyspace = 'my_keyspace'
                    if not cluster then
                        ngx.log(ngx.ERR, 'could not create cluster: ', err)
                        return ngx.exit(500)
                    local rows, err = cluster:execute "SELECT * FROM users"
                    if not rows then
                        ngx.log(ngx.ERR, 'could not retrieve users: ', err)
                        return ngx.exit(500)
                    ngx.say('users: ', #rows)


With [Luarocks]:

    $ luarocks install lua-cassandra

Or via opm:

    $ opm get thibaultcha/lua-cassandra

Or manually:

Once you have a local copy of this module's lib/ directory, add it to your LUA_PATH (or lua_package_path directive for OpenResty):


Note: When used outside of OpenResty, or in the init_by_lua context, this module requires additional dependencies:

  • LuaSocket

  • If you wish to use SSL client-to-node connections, LuaSec

  • When used in PUC-Lua, Lua BitOp (installed by Luarocks)

Documentation and Examples

Refer to the online [manual] and detailed [documentation]. You will also find [examples] there and you can browse the test suites for in-depth ones.



  • new load balancing policies (token-aware)


  • implement decimal data type

  • v4: implement date and time data types

  • v4: implement smallint and tinyint data types


Test Suites

The single host tests require [busted] and [ccm] to be installed. They can be run with:

    $ make busted

The cluster module tests require Test::Nginx::Socket in addition to ccm. They can be run with:

    $ make prove


This module uses various tools for documentation and code quality, they can easily be installed from Luarocks by running:

    $ make dev

Code coverage is analyzed with luacov from the busted tests:

    $ make coverage

The code is linted with luacheck:

    $ make lint

The documentation is generated with ldoc and can be generated with:

    $ make doc

[Luarocks]: [OpenResty]: [ccm]: [busted]:

[documentation]: [manual]: [examples]:

[badge-travis-url]: [badge-travis-image]:

[badge-coveralls-url]: [badge-coveralls-image]:



Thibault Charbonnier (thibaultcha)