Module resty.cassandra.cluster

Cassandra cluster client module.

Cluster module for OpenResty.

Info:

  • Release: 1.5.2
  • Author: thibaultcha

Functions

_Cluster.new (opts) Create a new Cluster client.
_Cluster:refresh (timeout) Refresh the list of nodes in the cluster.
_Cluster:execute (query, args, options, coordinator_options) Execute a query.
_Cluster:batch (queries, options, coordinator_options) Execute a batch.
_Cluster:iterate (query, args, options) Lua iterator for auto-pagination.

Tables

cluster_options New cluster options.
coordinator_options Coordinator options.


Functions

_Cluster.new (opts)
Create a new Cluster client. Takes a table of cluster_options. Does not connect automatically. On the first request to the cluster, the module will attempt to connect to one of the specified contact_points, and retrieve the full list of nodes belonging to this cluster. Once this list retrieved, the load balancing policy will start selecting nodes to act as coordinators for the future requests.

Parameters:

  • opts table Options for the created cluster client.

Returns:

  1. table cluster: A table holding clustering operations capabilities or nil if failure.
  2. string err: String describing the error if failure.

Usage:

    local Cluster = require "resty.cassandra.cluster"
local cluster = Cluster.new {
  shm = "cassandra_shared_dict",
  contact_points = {"10.0.0.1", "10.0.0.2"},
  keyspace = "my_keyspace",
  default_port = 9042,
  timeout_connect = 3000
}
_Cluster:refresh (timeout)
Refresh the list of nodes in the cluster. Queries one of the specified contact_points to retrieve the list of available nodes in the cluster, and update the configured policies. The query will use the timeout threshold specified in the read_timeout option of the new method. This method is safe be called at runtime, by multiple workers at the same time, which can be useful to refresh the cluster topology when nodes are added or removed from the cluster. This method is automatically called upon the first query made to the cluster (from execute, batch or iterate), but needs to be manually called if further updates are required.

Parameters:

  • timeout number Timeout threshold (in seconds) for a given worker when another worker is already refreshing the topology (defaults to the lock_timeout option of the new method).

Returns:

  1. boolean ok: true if success, nil if failure.
  2. string err: String describing the error if failure.
  3. table topology: A table containing the topology changes if any. This value will only be returned when the worker acquired the lock.
_Cluster:execute (query, args, options, coordinator_options)
Execute a query. Sends a request to the coordinator chosen by the configured load balancing policy. The policy always chooses nodes that are considered healthy, and eventually reconnects to unhealthy nodes as per the configured reconnection policy. Requests that fail because of timeouts can be retried on the next available node if retry_on_timeout is enabled, and failed requests can be retried as per defined in the configured retry policy.

Parameters:

  • query string CQL query to execute.
  • args table (optional) Arguments to bind to the query.
  • options table (optional) Options from query_options.
  • coordinator_options table (optional) Options from coordinator_options for this query.

Returns:

  1. table res: Table holding the query result if success, nil if failure.
  2. string err: String describing the error if failure.
  3. number cql_err: If a server-side error occurred, the CQL error code.

Usage:

    local Cluster = require "resty.cassandra.cluster"
local cluster, err = Cluster.new()
if not cluster then
  ngx.log(ngx.ERR, "could not create cluster: ", err)
  ngx.exit(500)
end

local rows, err = cluster:execute("SELECT * FROM users WHERE age = ?". {
  21
}, {
  page_size = 100
})
if not rows then
  ngx.log(ngx.ERR, "could not retrieve users: ", err)
  ngx.exit(500)
end

ngx.say("page size: ", #rows, " next page: ", rows.meta.paging_state)
_Cluster:batch (queries, options, coordinator_options)
Execute a batch. Sends a request to execute the given batch. Load balancing, reconnection, and retry policies act the same as described for execute.

Parameters:

  • queries table CQL queries to execute.
  • options table (optional) Options from query_options.
  • coordinator_options table (optional) Options from coordinator_options for this query.

Returns:

  1. table res: Table holding the query result if success, nil if failure.
  2. string err: String describing the error if failure.
  3. number cql_err: If a server-side error occurred, the CQL error code.

Usage:

    local Cluster = require "resty.cassandra.cluster"
local cluster, err = Cluster.new()
if not cluster then
  ngx.log(ngx.ERR, "could not create cluster: ", err)
  ngx.exit(500)
end

local res, err = cluster:batch({
  {"INSERT INTO things(id, n) VALUES(?, 1)", {123}},
  {"UPDATE things SET n = 2 WHERE id = ?", {123}},
  {"UPDATE things SET n = 3 WHERE id = ?", {123}}
}, {
  logged = false
})
if not res then
  ngx.log(ngx.ERR, "could not execute batch: ", err)
  ngx.exit(500)
end
_Cluster:iterate (query, args, options)
Lua iterator for auto-pagination. Perform auto-pagination for a query when used as a Lua iterator. Load balancing, reconnection, and retry policies act the same as described for execute.

Parameters:

  • query string CQL query to execute.
  • args table (optional) Arguments to bind to the query.
  • options table (optional) Options from query_options for this query.

Usage:

    local Cluster = require "resty.cassandra.cluster"
local cluster, err = Cluster.new()
if not cluster then
  ngx.log(ngx.ERR, "could not create cluster: ", err)
  ngx.exit(500)
end

for rows, err, page in cluster:iterate("SELECT * FROM users") do
  if err then
    ngx.log(ngx.ERR, "could not retrieve page: ", err)
    ngx.exit(500)
  end
  ngx.say("page ", page, " has ", #rows, " rows")
end

Tables

cluster_options
New cluster options. Options taken by new upon cluster creation.

Fields:

  • shm Name of the luashareddict to use for this cluster's information. (string, default: cassandra)
  • contact_points Array of addresses for this cluster's contact points. (table, default: {"127.0.0.1"})
  • default_port The port on which all nodes from the cluster are listening on. (number, default: 9042)
  • keyspace Keyspace to use for this cluster. (string, optional)
  • timeout_connect The timeout value when connecing to a node, in ms. (number, default: 1000)
  • timeout_read The timeout value when reading from a node, in ms. (number, default: 2000)
  • retry_on_timeout Specifies if the request should be retried on the next coordinator (as per the load balancing policy) if it timed out. (boolean, default: true)
  • max_schema_consensus_wait Maximum waiting time allowed when executing DDL queries before timing out, in ms. (number, default: 10000)
  • lock_timeout Timeout value of lua-resty-lock used for the refresh and prepared statement mutexes, in seconds. (number, optional)
  • silent Disables all logging (of any log_level) from this cluster. (boolean, default: false)
  • lb_policy A load balancing policy created from one of the modules under resty.cassandra.policies.lb.*. (lb policy, default: lb.rr round robin)
  • reconn_policy A reconnection policy created from one of the modules under resty.cassandra.policies.reconnection.*. (reconn policy, default: reconnection.exp (exponential) 1000ms base, 60000ms max)
  • retry_policy A retry policy created from one of the modules under resty.cassandra.policies.retry.*. (retry policy, default: retry.simple, 3 retries)
  • ssl Determines if the created cluster should connect using SSL. (boolean, default: false)
  • verify Enable server certificate validation if ssl is enabled. (boolean, default: false)
  • auth Authentication handler, created from the cassandra.auth_providers table. (optional)
coordinator_options
Coordinator options. Options to pass to coordinators chosen by the load balancing policy on execute/batch/iterate.

Fields:

  • keyspace Keyspace to use for the current request connection. (string, optional)
  • no_keyspace Does not set a keyspace for the current request connection. (boolean, default: false)
generated by LDoc 1.4.6 Last updated 2022-05-20 11:10:11