Xandra v0.7.0 Xandra.Cluster
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, the only load balancing “strategy” implemented is random choice of
nodes: when you execute a query against a Xandra.Cluster connection, it will
choose one of connected nodes at random and execute the query on that node.
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) theDBConnection.Poolpool used to pool connections to each of the specified nodes.
To pass options to the underlying pool, you can just pass them alongside other
options to Xandra.start_link/1.
Summary
Functions
Checkin a connection’s state to the pool
Checkout a connection’s state from a pool
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
Start and link to a pool of module connections with options opts
Stop a connection
Functions
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.
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.
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.
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.
Ensure all applications necessary to run the pool are started.
Callback implementation for DBConnection.Pool.ensure_all_started/2.
Start and link to a pool of module connections with options opts.
Callback implementation for DBConnection.Pool.start_link/2.
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.