TODO: describe goals :)

Update 3: new clustering module is only compatible with ngx_lua and LuaJIT but allows for very good performance in comparison to the old one.

Update 2: this branch is under daily, active development. https://github.com/thibaultCha/lua-cassandra/pull/45/commits

Update:

The main goal of this refactor is to separate the basic Cassandra session facility from the clustering capabilities. We don't want to force users to systematically have to deal with the clustering capability. Secondly, we want to follow a more friendly OpenResty pattern. And finally, we wish to fix some annoying leftovers such as the need to systematically specify an shm or contact_points, especially outside of ngx_lua.

A "host" or "peer" only has knowledge about a single Cassandra node:

local cassandra = require "cassandra"

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

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

-- ...

peer:setkeepalive()

A cluster maps an entire Cassandra cluster and coordinates queries. Under the hood, it uses the previously described hosts:

local Cluster = require "resty.cassandra.cluster"

local cluster = assert(Cluster.new {
  shm = "cassandra", -- this is now optional, "cassandra" by default, and not needed outside of ngx_lua
  contact_points = {"127.0.0.1", "127.0.0.2"}
})

-- takes load balancing, retry policies and such into account
local rows = assert(cluster:execute "SELECT * FROM users")

cluster:shutdown()

A cluster only refreshes the Cassandra nodes when needed (upon the first query) or when being asked (cluster:refresh()). Those clustering features allow for production usage of Cassandra in ngx_lua (as the current driver already offers).