Skip to main content

Install from Binary

Download and unzip EloqKV tarball​

EloqKV on EloqStore requires Ubuntu 24.04. Download tarball.

After successfully downloading the proper binary, untar it in a directory.

cd ${HOME}
tar -zxvf eloqkv-1.0.1-ubuntu24-amd64.tar.gz

Prepare EloqKV config file​

EloqKV uses a configuration file to customize settings. An example is provided in conf/eloqkv.ini under the installation directory. EloqKV will automatically set reasonable default values for its parameters if no user specified value is provided in the configuration file. Check configuration for advanced setting.

Below is an example of how to configure EloqKV to run on a local machine.

[local]
# It is recommended to set the IP to the actual server IP for external access
ip=127.0.0.1
port=6379

[store]
# It is recommended to set eloq_store_data_path_list to NVMe SSD.
# Shard data directories separated by ',' when multiple. By default under eloq_data_path.
# eloq_store_data_path_list=

Start EloqKV server​

The EloqKV eloqkv executable binary is installed in the EloqKV/bin directory. Start the server on the local machine using the commands below.

cd ${HOME}/EloqKV
./bin/eloqkv --config=conf/eloqkv.ini

Connect to EloqKV server​

EloqKV is compatible with the Redis protocol. We have included a eloq-cli for your convinence, but any redis client can connect to EloqKV. You can obtain official redis-cli by e.g. execute sudo apt-get install redis-tools on Ubuntu. Please use the same ip and port in config file eloqkv.ini to connect to EloqKV.

redis-cli -h 127.0.0.1 -p 6379

Enable Persistent Data Store​

EloqKV supports the integration with pluggable data stores, enabling data persistence even when the EloqKV service is stopped. This capability facilitates the implementation of tiered storage strategies, allowing hot data to reside in memory for quick access, while cold data can be offloaded to disks.

[local]
# set it to `on` to turn on persistent storage. Default value: 'on'
enable_data_store=on

# Checkpoint_interval determines the period of flushing records into persistent store
# so that data in persistent store will not lag too much behind. Default value: 10
checkpointer_interval=10

Enable WAL for Durability​

By enabling the Write-Ahead Logging (WAL), EloqKV can achieve Durability, i.e. all writes will be logged and data won't get lost in the event of a system crash. WAL need to be combined with persistent data store to work properly.

Edit eloqkv.ini and restart EloqKV to enable WAL.

[local]
# set it to `on` to turn on WAL
enable_wal=on

Setting Up a Cluster​

It is very simple to set up a cluster of EloqKV. Just start several EloqKV instances on different machines, each provided with a configuration file with nodes listed in the cluster section.

For example, assuming we are setting up a cluster with 3 servers, on 192.168.1.20, 192.168.1.21 and 192.168.1.22:

[cluster]
# ip_port_list should include all eloqkv nodes in the cluster.
# Make sure to set them to match the ip:port specified in the [local]
# section of the configuration file on each node.
ip_port_list=192.168.1.20:6379,192.168.1.21:6379,192.168.1.22:6379

Now you can connect your client to any one of the servers in the cluster and enjoy the increased capacity. Data will be automatically sharded.

Note that Distributed transactions are supported in EloqKV clusters. For example, MULTI commands and Lua scritpts will behave the same in a cluster just as on a single node. To enable this feature, you need to enable auto-redirect.

[local]
auto_redirect=true