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

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/0 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().

the-data-directory-and-the-ra-system

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 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/0 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

Managing Ra cluster members

A Khepri/Ra cluster can be expanded by telling a node to join a remote cluster. Note 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().