Module eredis_cluster

Description
Data Types
Function Index
Function Details

.

Behaviours: application.

Description

This module provides the API of eredis_cluster.

The eredis_cluster application is a Redis Cluster client. For each of the nodes in a connected Redis cluster, a connection pool is maintained. In this manual, the words "pool" and "node" are used interchangeably when referring to the connection pool to a particular Redis node.

Some functions accept a Cluster parameter. For those which don't, they operate on a default cluster. If you only need to connect to one cluster, there is no need to use the functions with an explicit Cluster parameter.

Data Types

anystring()


anystring() = string() | binary()

optimistic_locking_error_result()


optimistic_locking_error_result() = {error, resource_busy} | {error, redis_error_result()}

optimistic_locking_result()


optimistic_locking_result() = optimistic_locking_error_result() | {{ok, undefined}, any()} | {{ok, redis_success_result()}, any()} | {{ok, [redis_success_result()]}, any()}

options()


options() = [{term(), term()}]

redis_command()


redis_command() = redis_simple_command() | redis_pipeline_command()

redis_error_result()


redis_error_result() = binary() | no_connection | invalid_cluster_command | tcp_closed

redis_pipeline_command()


redis_pipeline_command() = [redis_simple_command()]

redis_pipeline_result()


redis_pipeline_result() = [redis_simple_result()] | {error, redis_error_result()}

redis_result()


redis_result() = redis_simple_result() | redis_pipeline_result() | optimistic_locking_result()

redis_simple_command()


redis_simple_command() = [anystring() | integer()]

redis_simple_result()


redis_simple_result() = {ok, redis_success_result()} | {error, redis_error_result()}

redis_success_result()


redis_success_result() = binary() | [binary()] | undefined

redis_transaction_result()


redis_transaction_result() = {ok, [redis_success_result()]} | {ok, undefined} | {error, redis_error_result()}

Function Index

connect/1	Connect to a Redis cluster using a set of init nodes.
connect/2	Connects to a Redis cluster using a set of init nodes, with options.
connect/3	Connects to a Redis cluster using a set of init nodes, with options and cluster name.
disconnect/1	Disconnects a cluster by name or a set of nodes in the default cluster.
eval/4	Eval command helper, to optimize the query, it will try to execute the script using its hashed value.
flushdb/0	Perform flushdb command on each node of the redis cluster.
get_all_pools/0	Returns the connection pools for all Redis nodes in the default cluster.
get_all_pools/1	Returns the connection pools for all Redis nodes in a named cluster.
get_pool_by_command/1	Returns the connection pool for the Redis node in the default cluster where a command should be executed.
get_pool_by_command/2	Like get_pool_by_command/1 for a named cluster.
get_pool_by_key/1	Returns the connection pool for the Redis node responsible for the key in the default cluster.
get_pool_by_key/2	Like get_pool_by_key/1 for a named cluster.
load_script/1	Load LUA script to all master nodes in the Redis cluster.
optimistic_locking_transaction/3	Optimistic locking transaction, based on Redis documentation: https://redis.io/topics/transactions.
q/1	This function executes simple or pipelined command on a single redis node, which is selected according to the first key in the command.
q/2	Simple or pipelined command on a named cluster.
q_noreply/1	Executes a simple or pipeline of commands on a single Redis node, but ignoring any response from Redis.
qa/1	Performs a query on all nodes in the default cluster.
qa/2	Performs a query on all nodes in a cluster.
qa2/1	Perform a given query on all master nodes of a redis cluster and return result with master node reference in result.
qa2/2	Like qa2/1 but for a named cluster rather than the default cluster.
qk/2	Executes a simple or pipeline of command on the Redis node where the provided key resides on the default cluster.
qk/3	Executes a simple or pipeline of command on the Redis node where the provided key resides on a named cluster.
qmn/1	Multi node query.
qmn/2	Like qmn/1, but for a named cluster rather than the default cluster.
qn/2	Execute a simple or pipelined command on a specific node.
qp/1	Executes a pipeline of commands.
qw/2	Function to be used for direct calls to an `eredis` connection instance (a worker) in the function passed to the `transaction/2` function.
scan/4	Performs a SCAN on a specific node in the Redis cluster.
start/0	Start application.
stop/0	Stop application.
transaction/1	(Deprecated.) Function to execute a pipeline of commands as a transaction command, by wrapping it in MULTI and EXEC.
transaction/2	Execute a function on a single connection in the default cluster.
transaction/3	Execute a function on a single connection in a named cluster.
update_hash_field/3	Update the value of a field stored in a hash by applying the function passed in the argument.
update_key/2	Update the value of a key by applying the function passed in the argument.

Function Details

connect/1


connect(InitServers) -> ok

InitServers = [{Address::string(), Port::inet:port_number()}]

Connect to a Redis cluster using a set of init nodes.

This is useful if the cluster configuration is not known when the application is started.

Not all Redis nodes need to be provided. The addresses and port of the nodes in the cluster are retrieved from one of the init nodes.

connect/2


connect(InitServers, Options) -> ok

InitServers = [{Address::string(), Port::inet:port_number()}]
Options = options()

Connects to a Redis cluster using a set of init nodes, with options.

Useful if the cluster configuration is not known at startup. The options, if provided, can be used to override options set using application:set_env/3.

connect/3


connect(Cluster, InitServers, Options) -> ok

Cluster = atom()
InitServers = [{Address::string(), Port::inet:port_number()}]
Options = options()

Connects to a Redis cluster using a set of init nodes, with options and cluster name.

Failes with error badarg if the cluster name is already in use as a registered name of some other process.

disconnect/1


disconnect(Nodes::(Nodes::[atom()]) | (Cluster::atom())) -> ok

Disconnects a cluster by name or a set of nodes in the default cluster.

Note: Unused nodes are disconnected automatically when the slot mapping is updated.

eval/4


eval(Script, ScriptHash, Keys, Args) -> redis_result()

Script = anystring()
ScriptHash = anystring()
Keys = [anystring()]
Args = [anystring()]

Eval command helper, to optimize the query, it will try to execute the script using its hashed value. If no script is found, it will load it and try again.

The ScriptHash is provided by load_script/1, which can be used to pre-load the script on all nodes.

The first key in Keys is used for selecting the Redis node where the script is executed. If Keys is an empty list, the script is executed on an arbitrary Redis node.

See also: load_script/1.

flushdb/0


flushdb() -> ok | {error, redis_error_result()}

Perform flushdb command on each node of the redis cluster

This is equivalent to calling qa(["FLUSHDB"]) except for the return value.

get_all_pools/0


get_all_pools() -> [atom()]

Returns the connection pools for all Redis nodes in the default cluster.

This is usedful for commands to a specific node using qn/2 and transaction/2.

See also: qn/2, transaction/2.

get_all_pools/1


get_all_pools(Cluster::atom()) -> [atom()]

Returns the connection pools for all Redis nodes in a named cluster.

get_pool_by_command/1


get_pool_by_command(Command::redis_command()) -> atom() | undefined

Returns the connection pool for the Redis node in the default cluster where a command should be executed.

The node is selected based on the first key in the command.

See also: get_pool_by_key/1.

get_pool_by_command/2


get_pool_by_command(Cluster::atom(), Command::redis_command()) -> atom() | undefined

Like get_pool_by_command/1 for a named cluster.

get_pool_by_key/1


get_pool_by_key(Key::anystring()) -> atom() | undefined

Returns the connection pool for the Redis node responsible for the key in the default cluster.

get_pool_by_key/2


get_pool_by_key(Cluster::atom(), Key::anystring()) -> atom() | undefined

Like get_pool_by_key/1 for a named cluster.

load_script/1


load_script(Script::string()) -> redis_result()

Load LUA script to all master nodes in the Redis cluster.

Returns {ok, SHA1} on success and an error otherwise.

This is equivalent to calling qa(["SCRIPT", "LOAD", Script]) except for the return value.

A script loaded in this way can be executed using eval/4.

See also: eval/4.

optimistic_locking_transaction/3


optimistic_locking_transaction(WatchedKey, GetCommand, UpdateFunction) -> Result

WatchedKey = anystring()
GetCommand = redis_command()
UpdateFunction = fun((redis_result()) -> redis_pipeline_command())
Result = {ok, {redis_success_result(), any()}} | {ok, {[redis_success_result()], any()}} | optimistic_locking_error_result()

Optimistic locking transaction, based on Redis documentation: https://redis.io/topics/transactions

The function operates like the following pseudo-code:


  WATCH WatchedKey
  value = GetCommand
  MULTI
  UpdateFunction(value)
  EXEC

If the value associated with WatchedKey has changed between GetCommand and EXEC, the sequence is retried.

q/1


q(Command::redis_command()) -> redis_result()

This function executes simple or pipelined command on a single redis node, which is selected according to the first key in the command.

q/2


q(Cluster::atom(), Command::redis_command()) -> redis_result()

Simple or pipelined command on a named cluster.

q_noreply/1


q_noreply(Command::redis_command()) -> ok

Executes a simple or pipeline of commands on a single Redis node, but ignoring any response from Redis. (Fire and forget)

Errors are ignored and there are no automatic retries.

qa/1


qa(Command) -> Result

Command = redis_command()
Result = [redis_result()] | {error, no_connection}

Performs a query on all nodes in the default cluster. When a query to a master fails, the mapping is refreshed and the query is retried.

qa/2


qa(Cluster, Command) -> Result

Cluster = atom()
Command = redis_command()
Result = [redis_result()] | {error, no_connection}

Performs a query on all nodes in a cluster. When a query to a master fails, the mapping is refreshed and the query is retried.

qa2/1


qa2(Command) -> Result

Command = redis_command()
Result = [{Node::atom(), redis_result()}] | {error, no_connection}

Perform a given query on all master nodes of a redis cluster and return result with master node reference in result. When a query to the master fail refresh the mapping and try again.

qa2/2


qa2(Cluster, Command) -> Result

Cluster = atom()
Command = redis_command()
Result = [{Node::atom(), redis_result()}] | {error, no_connection}

Like qa2/1 but for a named cluster rather than the default cluster.

qk/2


qk(Command::redis_command(), Key::anystring()) -> redis_result()

Executes a simple or pipeline of command on the Redis node where the provided key resides on the default cluster.

qk/3


qk(Cluster::atom(), Command::redis_command(), Key::anystring()) -> redis_result()

Executes a simple or pipeline of command on the Redis node where the provided key resides on a named cluster.

qmn/1


qmn(Commands::redis_pipeline_command()) -> redis_pipeline_result()

Multi node query. Each command in a list of commands is sent to the Redis node responsible for the key affected by that command. Only simple commands operating on a single key are supported.

qmn/2


qmn(Cluster::atom(), Commands::redis_pipeline_command()) -> redis_pipeline_result()

Like qmn/1, but for a named cluster rather than the default cluster.

qn/2


qn(Command, Node) -> redis_result()

Command = redis_command()
Node = atom()

Execute a simple or pipelined command on a specific node.

The node is identified by the name of the connection pool for the node.

See also: get_all_pools/0, qk/2.

qp/1


qp(Commands::redis_pipeline_command()) -> redis_pipeline_result()

Executes a pipeline of commands.

This function is identical to q(Commands).

See also: q/1.

qw/2


qw(Connection::pid(), Commands::redis_command()) -> redis_result()

Function to be used for direct calls to an eredis connection instance (a worker) in the function passed to the transaction/2 function.

This function calls eredis:qp/2 for pipelines of commands and eredis:q/1 for single commands. It is also possible to use eredis directly.

See also: transaction/2.

scan/4


scan(Node, Cursor, Pattern, Count) -> Result

Node = atom()
Cursor = integer()
Pattern = anystring()
Count = integer()
Result = redis_result() | {error, Reason::binary() | atom()}

Performs a SCAN on a specific node in the Redis cluster.

This is equivalent to calling qn(["SCAN", Cursor, "MATCH", Pattern, "COUNT", Count], Node).

See also: get_all_pools/0, qn/1.

start/0


start() -> ok | {error, Reason::term()}

Start application.

If eredis_cluster is configured with init nodes using the application environment, using a config file or by explicitly by calling application:set_env(eredis_cluster, init_nodes, InitNodes), the cluster is connected when the application is started. Otherwise, it can be connected later using connect/1,2.

stop/0


stop() -> ok | {error, Reason::term()}

Stop application.

The same as application:stop(eredis_cluster).

transaction/1


transaction(Commands::redis_pipeline_command()) -> redis_transaction_result()

This function is deprecated: This function can be confused with transaction/2 which works in a very different way. Please use q/1 instead.

Function to execute a pipeline of commands as a transaction command, by wrapping it in MULTI and EXEC. Returns the result of EXEC, which is the list of responses for each of the commands.

transaction(Commands) is equivalent to calling q([["MULTI"]] ++ Commands ++ [["EXEC"]]) and taking the last element in the resulting list.

transaction/2


transaction(Transaction, KeyOrPool::Key | Pool) -> redis_result()

Key = anystring()
Pool = atom()
Transaction = fun((Connection::pid()) -> redis_result())

Execute a function on a single connection in the default cluster.

This should be used when a transaction command such as WATCH or DISCARD must be used. The node is selected by giving a key that this node is containing or by giving the node directly. Note that this function does not add MULTI or EXEC, so it can be used also for sequences of commands which are not Redis transactions.

The Transaction fun shall use qw/2 to execute commands on the selected connection pid passed to it.

A transaction can be retried automatically, so the Transaction fun should not have side effects.

See also: qw/2.

transaction/3


transaction(Transaction, Cluster, Key::Key | Pool) -> redis_result()

Transaction = fun((Connection::pid()) -> redis_result())
Cluster = atom()
Key = anystring()
Pool = atom()

Execute a function on a single connection in a named cluster.