lua-cassandra

A pure Lua client library for Apache Cassandra (2.0+), compatible with ngx_lua/OpenResty and plain Lua.

It is implemented following the example of the official Datastax drivers, and tries to offer the same behaviors, options and features.

Note: this project is currently undergoing a massive refactoring (see lua-cassandra#15), please be aware before proposing changes. Thank you!

Table of Contents

• Features
• Usage
• Installation
• Documentation and Examples
• Roadmap
• Test Suites
• Tools

Features

• Leverage the ngx_lua cosocket API (non-blocking, reusable sockets)
• Fallback on LuaSocket for plain Lua compatibility
• Simple, prepared and batch statements
• Cluster topology automatic discovery
• Configurable load balancing, reconnection and retry policies
• TLS client-to-node encryption
• Client authentication
• Highly configurable options per session/query
• Support Cassandra 2.0+
• Compatible with Lua 5.1, 5.2, 5.3, LuaJIT 2.x, and optimized for OpenResty/ngx_lua

Usage

With ngx_lua:

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 cassandra = require "cassandra"

        local session, err = cassandra.spawn_session {
          shm = "cassandra", -- defined by "lua_shared_dict"
          contact_points = {"127.0.0.1", "127.0.0.2"}
        }
        if err then
          ngx.log(ngx.ERR, "could not spawn session: ", err)
          return ngx.exit(500)
        end

        local res, err = session:execute("INSERT INTO users(id, name, age) VALUES(?, ?, ?)", {
          cassandra.uuid("1144bada-852c-11e3-89fb-e0b9a54a6d11"),
          "John O Reilly",
          42
        })
        if err then
          -- ...
        end

        local rows, err = session:execute "SELECT * FROM users"
        if err then
          -- ...
        end

        session:set_keep_alive()

        ngx.say("rows retrieved: ", #rows)
      }
    }
  }
}

With plain Lua:

local cassandra = require "cassandra"

local session, err = cassandra.spawn_session {
  shm = "cassandra",
  contact_points = {"127.0.0.1", "127.0.0.2"}
}
assert(err == nil)

local res, err = session:execute("INSERT INTO users(id, name, age) VALUES(?, ?, ?)", {
  cassandra.uuid("1144bada-852c-11e3-89fb-e0b9a54a6d11"),
  "John O'Reilly",
  42
})
assert(err == nil)

local rows, err = session:execute "SELECT * FROM users"
assert(err == nil)

print("rows retrieved: ", #rows)

session:shutdown()

Installation

With Luarocks:

$ luarocks install lua-cassandra

Manually:

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

/path/to/src/?.lua;/path/to/src/?/init.lua;

Note: When used outside of ngx_lua, this module requires:

• LuaSocket
• If you wish to use TLS client-to-node encryption, LuaSec

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.

Roadmap

CQL:

• Support for query tracing
• Support for native protocol v3's default timestamps and named parameters
• Support for native protocol v4

Documentation:

• Options
• Errors
• Type inference of binded parameters
• Type serialization example

Test Suites

This library relies on three test suites:

• Unit tests, with busted
• Integration tests, with busted and ccm
• ngx_lua integration tests with Test::Nginx::Socket and a running Cassandra cluster

The first can simply be run after installing busted and running:

$ busted spec/01-unit

The integration tests are located in another folder, and require ccm to be installed.

busted spec/02-integration

Finally, the ngx_lua integration tests can be run after installing the Test::Nginx::Socket module and require a Cassandra instance to be running on localhost:

$ prove t/

Tools

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

$ make dev

Code coverage is analyzed by luacov from the busted (unit and integration) tests:

$ busted --coverage
$ luacov cassandra
# or
$ make coverage

The code is linted with luacheck. It is easier to use the Makefile again to avoid analyzing Lua files that are not part of this module:

$ make lint

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

$ ldoc -c doc/config.ld src
# or
$ make doc