Module khepri_clustering

Khepri service and cluster management API.

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.

Starting a Ra system

The default store is based on Ra's default system. You need to change the Ra application configuration if you want to set settings. That said, it is recommended to start your own Ra system. This way, even though Ra is already running, you can choose where the Khepri data should be stored. This is also required if you need to run multiple database instances in parallel.

Here is a quick start example:

%% We start Khepri. Ra is also started because Khepri depends on it.
{ok, _} = application:ensure_all_started(khepri),
 
%% We define the configuration of the Ra system for our database. Here, we
%% only care about the directory where data will be written.
RaSystem = my_ra_system,
RaSystemDataDir = "/path/to/storage/dir",
DefaultSystemConfig = ra_system:default_config(),
RaSystemConfig = DefaultSystemConfig#{name => RaSystem,
                                      data_dir => RaSystemDataDir,
                                      wal_data_dir => RaSystemDataDir,
                                      names => ra_system:derive_names(
                                                 RaSystem)},
 
%% The configuration is ready, let's start the Ra system.
{ok, _RaSystemPid} = ra_system:start(RaSystemConfig),
 
%% At last we can start Khepri! We need to choose a name for the Ra cluster
%% running in the Ra system started above. This must be an atom.
RaClusterName = my_khepri_db,
RaClusterFriendlyName = "My Khepri DB",
{ok, StoreId} = khepri:start(
                  RaSystem,
                  RaClusterName,
                  RaClusterFriendlyName),
 
%% The Ra cluster name is our <em>store ID</em> used everywhere in the
Khepri API.
khepri:insert(StoreId, [stock, wood], 156).

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

Managing Ra cluster members

To add a member to your Ra cluster:

khepri_clustering:add_member(
  RaSystem,
  RaClusterName,
  RaClusterFriendlyName,
  NewMemberErlangNodename).

To remove a member from your Ra cluster:

khepri_clustering:remove_member(
  RaClusterName,
  MemberErlangNodenameToRemove).

Function Index

start/0Starts a store on the default Ra system.
start/1Starts a store on the specified Ra system.
start/3Starts a store on the specified Ra system.
add_member/2
add_member/4
remove_member/1
remove_member/2
reset/2Resets the store on this Erlang node.
members/1
locally_known_members/1
nodes/1
locally_known_nodes/1
get_store_ids/0Returns the list of running stores.

Function Details

start/0

start() -> Ret

Starts a store on the default Ra system.

The store uses the default Ra cluster name and cluster friendly name.

start/1

start(RaSystem) -> Ret

RaSystem: the name of the Ra system.

Starts a store on the specified Ra system.

The store uses the default Ra cluster name and cluster friendly name.

start/3

start(RaSystem, ClusterName, FriendlyName) -> Ret

RaSystem: the name of the Ra system.
ClusterName: the name of the Ra cluster.
FriendlyName: the friendly name of the Ra cluster.

Starts a store on the specified Ra system.

add_member/2

add_member(RaSystem, NewNode) -> any()

add_member/4

add_member(RaSystem, ClusterName, FriendlyName, NewNode) -> any()

remove_member/1

remove_member(NodeToRemove) -> any()

remove_member/2

remove_member(ClusterName, NodeToRemove) -> any()

reset/2

reset(RaSystem, ClusterName) -> Ret

RaSystem: the name of the Ra system.
ClusterName: the name of the Ra cluster.

Resets the store on this Erlang node.

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

members/1

members(ClusterName) -> any()

locally_known_members/1

locally_known_members(ClusterName) -> any()

nodes/1

nodes(ClusterName) -> any()

locally_known_nodes/1

locally_known_nodes(ClusterName) -> any()

get_store_ids/0

get_store_ids() -> [StoreId]

Returns the list of running stores.


Generated by EDoc