README.md

lua-cassandra

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

Table of Contents

• Features
• Usage
• Installation
• Documentation and Examples
• Roadmap
• Development

Features

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

Back to TOC

Usage

Single host module (Lua and OpenResty):

local cassandra = require "cassandra"

local peer = assert(cassandra.new {
  host = "127.0.0.1",
  port = 9042,
  keyspace = "my_keyspace"
})

peer:settimeout(1000)

assert(peer:connect())

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

local rows = assert(peer:execute "SELECT * FROM users")

local user = rows[1]
print(user.name) -- John O Reilly
print(user.age)  -- 42

peer:close()

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 = Cluster.new {
                    shm = 'cassandra', -- defined by the lua_shared_dict directive
                    contact_points = {'127.0.0.1', '127.0.0.2'},
                    keyspace = 'my_keyspace'
                }
                if not cluster then
                    ngx.log(ngx.ERR, 'could not create cluster: ', err)
                    return ngx.exit(500)
                end

                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)
                end

                ngx.say('users: ', #rows)
            }
        }
    }
}

Back to TOC

Installation

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):

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

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)

Back to TOC

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.

Back to TOC

Roadmap

Cluster:

• new load balancing policies (token-aware)

CQL:

• implement decimal data type
• v4: implement date and time data types
• v4: implement smallint and tinyint data types

Back to TOC

Development

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

Tools

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

Back to TOC