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.

Data Types

anystring()

anystring() = string() | bitstring()

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() = bitstring() | 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()]

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() = bitstring() | 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.
disconnect/1	Disconnects a set of nodes.
eval/4	Eval command helper, to optimize the query, it will try to execute thescript 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.
get_pool_by_command/1	Returns the connection pool for the Redis node where a command should beexecuted.
get_pool_by_key/1	Returns the connection pool for the Redis node responsible for the key.
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 redisnode, which is selected according to the first key in the command.
q_noreply/1	Executes a simple or pipeline of commands on a single Redis node, butignoring any response from Redis.
qa/1	Performs a query on all nodes in the cluster.
qa2/1	Perform a given query on all master nodes of a redis cluster andreturn result with master node reference in result.
qk/2	Executes a simple or pipeline of command on the Redis node where theprovided key resides.
qmn/1	Multi node query.
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	Function to execute a pipeline of commands as a transaction command, bywrapping it in MULTI and EXEC.
transaction/2	Execute a function on a single connection.
update_hash_field/3	Update the value of a field stored in a hash by applying the functionpassed in the argument.
update_key/2	Update the value of a key by applying the function passed in theargument.

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.

disconnect/1

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

Disconnects a set of nodes.

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, Reason::bitstring()}

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.

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

See also: qn/2, transaction/2.

get_pool_by_command/1

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

Returns the connection pool for the Redis node 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_key/1

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

Returns the connection pool for the Redis node responsible for the key.

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_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_transaction_result()] | {error, no_connection}

Performs a query on all nodes in the 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.

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.

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.

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.

The same as application:start(eredis_cluster).

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()

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, Key::Key | Pool) -> redis_result()

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

Execute a function on a single connection. 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. 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.

update_hash_field/3

update_hash_field(Key, Field, UpdateFunction) -> Result

• Key = anystring()
• Field = anystring()
• UpdateFunction = fun((any()) -> any())
• Result = {ok, {[any()], any()}} | {error, redis_error_result()}

Update the value of a field stored in a hash by applying the function passed in the argument. The operation is done atomically using an optimistic locking transaction.

See also: optimistic_locking_transaction/3.

update_key/2

update_key(Key, UpdateFunction) -> Result

• Key = anystring()
• UpdateFunction = fun((any()) -> any())
• Result = redis_transaction_result()

Update the value of a key by applying the function passed in the argument. The operation is done atomically, using an optimistic locking transaction.

See also: optimistic_locking_transaction/3.