Overview

Module khepri_cluster

• Description
• Data Types
• Function Index
• Function Details

Description

Khepri service and cluster management API.

This module provides the public API for the service and cluster management. For convenience, some functions of this API are repeated in the khepri module for easier access.

The Khepri store and the Ra cluster

A Khepri store is a Ra server inside a Ra cluster. The Khepri store and the Ra cluster share the same name in fact. The only constraint is that the name must be an atom, even though Ra accepts other Erlang types as cluster names.

By default, Khepri uses khepri as the store ID (and thus Ra cluster name). This default can be overridden using an argument to the start() functions or the default_store_id application environment variable.

• Use the default Khepri store ID:

  {ok, khepri} = khepri:start().

• Override the default store ID using an argument:

  {ok, my_store} = khepri:start("/var/lib/khepri", my_store).

• Override the default store ID using an application environment variable:

  ok = application:set_env(
         khepri, default_store_id, my_store, [{persistent, true}]),
   
  {ok, my_store} = khepri:start("/var/lib/khepri", my_store).

The data directory and the Ra system

A Ra server relies on a Ra system to provide various functions and to configure the directory where the data should be stored on disk.

By default, Khepri will configure its own Ra system to write data under khepri#Nodename in the current working directory, where Nodename is the name of the Erlang node.

{ok, StoreId} = khepri:start().
 
%% If the Erlang node was started without distribution (the default), the
%% statement above will start a Ra system called like the store (`khepri')
%% and will use the `khepri#nonode@nohost' directory.

The default data directory or Ra system name can be overridden using an argument to the start() or the default_ra_system application environment variable. Both a directory (string or binary) or the name of an already running Ra system are accepted.

• Override the default with the name of a running Ra system using an argument:

  {ok, StoreId} = khepri:start(my_ra_system).

• Override the default data directory using an application environment variable:

  ok = application:set_env(
         khepri, default_ra_system, "/var/lib/khepri", [{persistent, true}]),
   
  {ok, StoreId} = khepri:start().

Please refer to Ra documentation to learn more about Ra systems and Ra clusters.

Managing Ra cluster members

A Khepri/Ra cluster can be expanded by telling a node to join a remote cluster. Node that the Khepri store/Ra server to add to the cluster must run before it can join.

%% Start the local Khepri store.
{ok, StoreId} = khepri:start().
 
%% Join a remote cluster.
ok = khepri_cluster:join(RemoteNode).

To remove the local Khepri store node from the cluster, it must be reset.

%% Start the local Khepri store.
ok = khepri_cluster:reset().

Data Types

incomplete_ra_server_config()

incomplete_ra_server_config() = map()

A Ra server config map.

Function Index

Function Details

start/0

Starts a store.

See also: start/1, ra_server:ra_server_config/0.

start/1

Starts a store.

See also: start/2.

start/2

Starts a store.

See also: start/3.

start/3

Starts a store.

It accepts either a Ra system name (atom) or a data directory (string or binary) as its first argument. If a Ra system name is given, that Ra system must be running when this function is called. If a data directory is given, a new Ra system will be started, using this directory. The directory will be created automatically if it doesn't exist. The Ra system will use the same name as the Khepri store.

It accepts a Khepri store ID or a Ra server configuration as its second argument. If a store ID is given, a Ra server configuration will be created based on it. If a Ra server configuration is given, the name of the Khepri store will be derived from it.

If this is a new store, the Ra server is started and an election is triggered so that it becomes its own leader and is ready to process commands and queries.

stop/0

Stops a store.

See also: stop/1.

stop/1

Stops a store.

join/1

Adds the local running Khepri store to a remote cluster.

• join(RemoteNode). Calling it is the same as calling join(DefaultStoreId, RemoteNode) where DefaultStoreId is returned by get_default_store_id/0.
• join(RemoteMember). Calling it is the same as calling join(StoreId, RemoteNode) where StoreId and RemoteNode are derived from RemoteMember.

See also: join/2.

join/2

Adds the local running Khepri store to a remote cluster.

• join(RemoteNode, Timeout). Calling it is the same as calling join(DefaultStoreId, RemoteNode, Timeout) where DefaultStoreId is returned by get_default_store_id/0.
• join(StoreId, RemoteNode). Calling it is the same as calling join(StoreId, RemoteNode, DefaultTimeout) where DefaultTimeout is returned by khepri_app:get_default_timeout/0.
• join(RemoteMember, Timeout). Calling it is the same as calling join(StoreId, RemoteNode, Timeout) where StoreId and RemoteNode are derived from RemoteMember.

See also: join/3.

reset/0

Resets the store on this Erlang node.

reset/1

Resets the store on this Erlang node.

reset/2

Resets the store on this Erlang node.

It does that by force-deleting the Ra local server.

get_default_ra_system_or_data_dir/0

Returns the default Ra system name or data directory.

This is based on Khepri's default_ra_system` application environment variable. The variable can be set to: <ul> <li>A directory (a string or binary) where data should be stored. A new Ra system called `khepri` will be initialized with this directory.</li> <li>A Ra system name (an atom). In this case, the user is expected to configure and start the Ra system before starting Khepri.</li> </ul> If this application environment variable is unset, the default is to configure a Ra system called `khepri which will write data in "khepri-$NODE" in the current working directory where $NODE is the Erlang node name.

{khepri, [{default_ra_system, "/var/db/khepri"}]}.

get_default_store_id/0

Returns the default Khepri store ID.

members/1

members/2

locally_known_members/1

locally_known_members/2

nodes/1

locally_known_nodes/1

get_store_ids/0

Returns the list of running stores.

get_cached_leader/1

cache_leader/2

cache_leader_if_changed/3

clear_cached_leader/1

Overview

Generated by EDoc