Xandra v0.10.1 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) theDBConnection.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
.
Stop a connection.
Link to this section Functions
activate(cluster, node_ref, address, port) View Source
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
.
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
.
child_spec(init_arg) View Source
Returns a specification to start this module under a supervisor.
See Supervisor
.
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
.
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
.
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
.
init(arg) View Source
Invoked when the server is started. start_link/3
or start/3
will
block until it returns.
init_arg
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 {:ok, state, {:continue, continue}}
is similar to
{:ok, state}
except that immediately after entering the loop
the c:handle_continue/2
callback will be invoked with the value
continue
as first argument.
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 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 callingSupervisor.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
.
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
.
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
.