thibaultcha / lua-cassandra

Pure Lua driver for Apache Cassandra
https://thibaultcha.github.io/lua-cassandra
Other
98 stars 35 forks source link
cassandra lua lua-resty luajit ngx-lua openresty

lua-cassandra

Module Version Build Status Coverage Status

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

Table of Contents

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.

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:

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:

CQL:

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