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
Functions
Returns a specification to start this module under a supervisor.
Starts a cluster connection.
Link to this section Types
cluster()
View Source
cluster() :: GenServer.server()
cluster() :: GenServer.server()
Link to this section Functions
child_spec(init_arg) View Source
Returns a specification to start this module under a supervisor.
See Supervisor
.
execute(cluster, query, params_or_options \\ [])
View Source
execute(cluster(), Xandra.statement() | Xandra.Prepared.t(), Xandra.values()) ::
{:ok, Xandra.result()} | {:error, Xandra.error()}
execute(cluster(), Xandra.Batch.t(), keyword()) ::
{:ok, Xandra.Void.t()} | {:error, Xandra.error()}
execute(cluster(), Xandra.statement() | Xandra.Prepared.t(), Xandra.values()) ::
Xandra.result() | no_return()
execute(cluster(), Xandra.Batch.t(), keyword()) :: Xandra.Void.t() | no_return()
execute(cluster(), Xandra.statement() | Xandra.Prepared.t(), Xandra.values()) :: {:ok, Xandra.result()} | {:error, Xandra.error()}
execute(cluster(), Xandra.Batch.t(), keyword()) :: {:ok, Xandra.Void.t()} | {:error, Xandra.error()}
execute(cluster(), Xandra.statement() | Xandra.Prepared.t(), Xandra.values()) :: Xandra.result() | no_return()
execute(cluster(), Xandra.Batch.t(), keyword()) :: Xandra.Void.t() | no_return()
Same as Xandra.execute/3
.
execute(cluster, query, params, options)
View Source
execute(
cluster(),
Xandra.statement() | Xandra.Prepared.t(),
Xandra.values(),
keyword()
) :: {:ok, Xandra.result()} | {:error, Xandra.error()}
execute(
cluster(),
Xandra.statement() | Xandra.Prepared.t(),
Xandra.values(),
keyword()
) :: Xandra.result() | no_return()
execute( cluster(), Xandra.statement() | Xandra.Prepared.t(), Xandra.values(), keyword() ) :: {:ok, Xandra.result()} | {:error, Xandra.error()}
execute( cluster(), Xandra.statement() | Xandra.Prepared.t(), Xandra.values(), keyword() ) :: Xandra.result() | no_return()
Same as Xandra.execute/4
.
execute!(cluster, query, params_or_options \\ []) View Source
Same as Xandra.execute!/3
.
execute!(cluster, query, params, options) View Source
Same as Xandra.execute!/4
.
prepare(cluster, statement, options \\ [])
View Source
prepare(cluster(), Xandra.statement(), keyword()) ::
{:ok, Xandra.Prepared.t()} | {:error, Xandra.error()}
prepare(cluster(), Xandra.statement(), keyword()) :: {:ok, Xandra.Prepared.t()} | {:error, Xandra.error()}
Same as Xandra.prepare/3
.
prepare!(cluster, statement, options \\ [])
View Source
prepare!(cluster(), Xandra.statement(), keyword()) ::
Xandra.Prepared.t() | no_return()
prepare!(cluster(), Xandra.statement(), keyword()) :: Xandra.Prepared.t() | no_return()
Same as Xandra.prepare!/3
.
run(cluster, options \\ [], fun)
View Source
run(cluster(), keyword(), (Xandra.conn() -> result)) :: result when result: var
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)
start_link(options)
View Source
start_link([Xandra.start_option() | {:load_balancing, atom()}]) ::
GenServer.on_start()
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")
)
stream_pages!(conn, query, params, options \\ [])
View Source
stream_pages!(
cluster(),
Xandra.statement() | Xandra.Prepared.t(),
Xandra.values(),
keyword()
) :: Enumerable.t()
stream_pages!( cluster(), Xandra.statement() | Xandra.Prepared.t(), Xandra.values(), keyword() ) :: Enumerable.t()
Same as Xandra.stream_pages!/4
.