Xandra v0.10.0 Xandra.Cluster View Source

A DBConnection.Pool pool that implements clustering support.

This module implements a DBConnection.Pool pool that implements support for connecting to multiple nodes and executing queries on such nodes based on a given “strategy”.

Usage

To use this pool, the :pool option in Xandra.start_link/1 needs to be set to Xandra.Cluster. Xandra.Cluster is a “proxy” pool in the sense that it only proxies requests to other underlying pools of Xandra connections; the underlying pool can be specified with the :underlying_pool option. When you start a Xandra.Cluster connection, it will start one pool (:underlying_pool) of connections to each of the nodes specified in :nodes. The default :underlying_pool is DBConnection.Connection, which means by default only a single connection to each specified node will be established.

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, while using :poolboy for pooling the connections to each node:

Xandra.start_link([
  nodes: ["cassandra1.example.net", "cassandra2.example.net"],
  pool: Xandra.Cluster,
  underlying_pool: DBConnection.Poolboy,
  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.

Once a Xandra.Cluster pool is started, queries executed through such pool will be “routed” to nodes in the provided list of nodes; see the “Load balancing strategies” section below.

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.

Options

These are the options that Xandra.start_link/1 accepts when pool: Xandra.Cluster is passed to it:

  • :underlying_pool - (module) the DBConnection.Pool pool used to pool connections to each of the specified nodes.

  • :load_balancing - (atom) load balancing “strategy”. Defaults to :random.

To pass options to the underlying pool, you can just pass them alongside other options to Xandra.start_link/1.

Link to this section Summary

Functions

Checkin a connection’s state to the pool

Checkout a connection’s state from a pool

Returns a specification to start this module under a supervisor

Create a supervisor child specification for the pool with module module, options opts and child specification options child_opts

Checkin a connection’s state to the pool and disconnect it with an exception

Ensure all applications necessary to run the pool are started

Invoked when the server is started. start_link/3 or start/3 will block until it returns

Start and link to a pool of module connections with options opts

Link to this section Functions

Link to this function activate(cluster, node_ref, address, port) View Source
Link to this function checkin(arg, state, options) View Source

Checkin a connection’s state to the pool.

The pool_ref is from the return of checkout/2.

state is the lastest state of the connection.

Callback implementation for DBConnection.Pool.checkin/3.

Link to this function checkout(cluster, options) View Source

Checkout a connection’s state from a pool.

The returned pool_ref will be passed to checkin/3, disconnect/4 and stop/4.

module and state are the module and state of the connection.

Callback implementation for DBConnection.Pool.checkout/2.

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function child_spec(module, options, child_options) View Source

Create a supervisor child specification for the pool with module module, options opts and child specification options child_opts.

Callback implementation for DBConnection.Pool.child_spec/3.

Link to this function disconnect(arg, error, state, options) View Source

Checkin a connection’s state to the pool and disconnect it with an exception.

The pool_ref is from the return of checkout/2.

state is the lastest state of the connection.

Callback implementation for DBConnection.Pool.disconnect/4.

Link to this function ensure_all_started(options, type) View Source

Ensure all applications necessary to run the pool are started.

Callback implementation for DBConnection.Pool.ensure_all_started/2.

Invoked when the server is started. start_link/3 or start/3 will block until it returns.

args is the argument term (second argument) passed to start_link/3.

Returning {:ok, state} will cause start_link/3 to return {:ok, pid} and the process to enter its loop.

Returning {:ok, state, timeout} is similar to {:ok, state} except handle_info(:timeout, state) will be called after timeout milliseconds if no messages are received within the timeout.

Returning {:ok, state, :hibernate} is similar to {:ok, state} except the process is hibernated before entering the loop. See c:handle_call/3 for more information on hibernation.

Returning :ignore will cause start_link/3 to return :ignore and the process will exit normally without entering the loop or calling c:terminate/2. If used when part of a supervision tree the parent supervisor will not fail to start nor immediately try to restart the GenServer. The remainder of the supervision tree will be (re)started and so the GenServer should not be required by other processes. It can be started later with Supervisor.restart_child/2 as the child specification is saved in the parent supervisor. The main use cases for this are:

  • The GenServer is disabled by configuration but might be enabled later.
  • An error occurred and it will be handled by a different mechanism than the Supervisor. Likely this approach involves calling Supervisor.restart_child/2 after a delay to attempt a restart.

Returning {:stop, reason} will cause start_link/3 to return {:error, reason} and the process to exit with reason reason without entering the loop or calling c:terminate/2.

Callback implementation for GenServer.init/1.

Link to this function start_link(arg, options) View Source

Start and link to a pool of module connections with options opts.

Callback implementation for DBConnection.Pool.start_link/2.

Link to this function stop(arg, error, state, options) View Source

Stop a connection.

The pool_ref is from the return of checkout/2.

state is the lastest state of the connection.

Callback implementation for DBConnection.Pool.stop/4.

Link to this function update(cluster, status_change) View Source