Xandra v0.11.0 Xandra.Cluster View Source

Connection to a Cassandra cluster.

This module is a "proxy" connection with support for connecting to multiple nodes in a Cassandra cluster and executing queries on such nodes based on a given strategy.

Usage

This module manages connections to different nodes in a Cassandra cluster. Each connection to a node is a Xandra connection (so it can also be a pool of connections). When a Xandra.Cluster connection is started, one Xandra connection or pool of connections will be started for each node specified in the :nodes option.

The API provided by this module mirrors the API provided by the Xandra module. Queries executed through this module will be "routed" to nodes in the provided list of nodes based on a strategy. See the "Load balancing strategies" section below

Note that regardless of the underlying pool, Xandra.Cluster will establish one extra connection to each node in the specified list of nodes (used for internal purposes).

Here is an example of how one could use Xandra.Cluster to connect to multiple nodes:

Xandra.Cluster.start_link(
  nodes: ["cassandra1.example.net", "cassandra2.example.net"],
  pool_size: 10,
)

The code above will establish a pool of ten connections to each of the nodes specified in :nodes, for a total of twenty connections going out of the current machine, plus two extra connections (one per node) used for internal purposes.

Load balancing strategies

For now, there are two load balancing "strategies" implemented:

  • :random - it will choose one of the connected nodes at random and execute the query on that node.

  • :priority - it will choose a node to execute the query according to the order nodes appear in :nodes.

Disconnections and reconnections

Xandra.Cluster also supports nodes disconnecting and reconnecting: if Xandra detects one of the nodes in :nodes going down, it will not execute queries against it anymore, but will start executing queries on it as soon as it detects such node is back up.

If all specified nodes happen to be down when a query is executed, a Xandra.ConnectionError with reason {:cluster, :not_connected} will be returned.

Link to this section Summary

Link to this section Types

Link to this section Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

execute(cluster, query, params_or_options \\ []) View Source

Same as Xandra.execute/3.

Link to this function

execute(cluster, query, params, options) View Source

Same as Xandra.execute/4.

Link to this function

execute!(cluster, query, params_or_options \\ []) View Source

Same as Xandra.execute!/3.

Link to this function

execute!(cluster, query, params, options) View Source

Same as Xandra.execute!/4.

Link to this function

prepare(cluster, statement, options \\ []) View Source
prepare(cluster(), Xandra.statement(), keyword()) ::
  {:ok, Xandra.Prepared.t()} | {:error, Xandra.error()}

Same as Xandra.prepare/3.

Link to this function

prepare!(cluster, statement, options \\ []) View Source

Same as Xandra.prepare!/3.

Link to this function

run(cluster, options \\ [], fun) View Source
run(cluster(), keyword(), (Xandra.conn() -> result)) :: result when result: var

Same as Xandra.run/3.

The connection that is passed to fun is a Xandra connection, not a cluster. This means that you should call Xandra functions on it.

Examples

query = "SELECT * FROM system_schema.keyspaces"

Xandra.Cluster.run(cluster, fn conn ->
  prepared = Xandra.prepare!(conn, query)
  Xandra.execute!(conn, prepared, _params = [])
end)
Link to this function

start_link(options) View Source
start_link([Xandra.start_option() | {:load_balancing, atom()}]) ::
  GenServer.on_start()

Starts a cluster connection.

Note that a cluster connection starts an additional connection for each node in the cluster that is used for monitoring cluster updates.

Options

This function accepts all options accepted by Xandra.start_link/1 and and forwards them to each connection or pool of connections. The following options are specific to this function:

  • :load_balancing - (atom) load balancing "strategy". Either :random or :priority. See the "Load balancing strategies" section above. Defaults to :random.

Examples

Starting a cluster connection and executing a query:

{:ok, cluster} =
  Xandra.Cluster.start_link(
    nodes: ["cassandra1.example.net", "cassandra2.example.net"]
  )

Passing options down to each connection:

{:ok, cluster} =
  Xandra.Cluster.start_link(
    nodes: ["cassandra1.example.net", "cassandra2.example.net"],
    after_connect: &Xandra.execute!(&1, "USE my_keyspace")
  )
Link to this function

stream_pages!(conn, query, params, options \\ []) View Source

Same as Xandra.stream_pages!/4.