LeanXcale Quick Guide

LeanXcale is a distributed database built for scalability and performance. This quick guide provides an introduction to the basics.

1. Installation

LeanXcale provides a set of scripts based on Ansible to install, deploy and manage the cluster.

For everything to work all cluster machines must meet some prerequisites – which are almost defaults for any Linux installation:

1.1. SSH

The scripts provided, assume that SSH among all the servers is configured and proper keys are set for the user controlling the cluster (USER) to access any machine without any further authentication mechanism.

1.2. Simple setup

If you just want to start as easy as possible, you just have to follow the following steps:

  1. Create the base directory for the installation in all servers

    mkdir /basedir/lxs

    (The cluster user should have rwx permissions on that folder in all machines)

  2. Select one server to act as MASTER server (in terms of ansible operations)

  3. Unpack the TAR installation package in the base directory in the MASTER server

    cd /basedir/lxs
    tar xvf install-package-\{XXX}.tgz
  4. Configure the servers of the cluster in the inventory file

    vim conf/inventory

    Go to the [meta] section and fill in the hostname of the server that will have the metadata components (this is usually the server you are using as MASTER for the installation). Then fill in the [datastores] section with the hostnames of all servers in the cluster

    server1 ansible_connection=local
    #Datastore Servers. You can have multiple data store instances
    server1 ansible_connection=local

    (In this case server1 is supposed to be the MASTER server and will run both MetaData components and DataStore components which is pretty standard.)

  5. Run the configuration process

    bash install.sh
  6. Deploy the installation to the rest of the servers in the cluster

    admin/deploycluster.sh build
  7. Start the cluster

  8. If you just want to set up the cluster you should already have a working cluster,

1.3. Configuration

The default configuration is based on some workload assumptions that may not be met by your application so resources may not be making the most of your resources with this configuration.

If you know about your workload and want to have a better deployment to better use of the resources you may want to read the rest of the document and refine your inventory file before going to step 5.

There are also some basic options for using different filesystems covered in next section.

1.3.1. Some more Points about Installation

So far you have done a very simple installation. However, there are at least a couple of points you must consider to do a good use of your resources.

In the inventory, you may have noticed a line having:

sizing mem=- sockets=- ncores=- nthreadscore=- fsdata=. fslog=.

This tells the installation process to use all memory, all sockets, all cores and use the same filesystems as used for BASEDIR, but you can change those easily to fit your needs (mainly of you don’t want to allocate all resources to LeanXcale).

The most important part is the filesystem definition. For high performance It is highly recommended to isolate the IO for the transaction logging from the IO of the datastores, therefore you should have different filesystems in different disks.

  • mem: Memory available in the machine to run LeanXcale components (in GB)

  • sockets: Lists of sockets in the machine to be used to run the components. Values like "0-2" or "0,1,2" or "0,4" are allowed.

  • ncores: This is the number of physical cores to be used in each machine to run LeanXcale components. Take care that this is physical cores so hyperthreads should not be counted on.

  • fslog: Folder where the transaction logging files are located. These are not the components logs, but the transaction logging that guarantees database durability. If SUDO is not granted, the folder with RW permissions for USER should have been created by the administrator

  • fsdata: Parent Folder where database is storing data.

This might be a resulting configuration:

sizing mem=64G sockets=0,1 ncores=- nthreadscore=- fsdata=/disk1/lxdata

There are few more points you can fine tune to improve the allocation of resources and the performance of your distributed database. For full information on the installation options, please refer to the Installation and Configuration Guide.

2. Basic Operations

Once you have a running cluster these are some basic operations that you may need to do:

  • Start Cluster

$BASEDIR/admin> ./startcluster.sh
#start zookeeper in Metadata server
$BASEDIR/admin> ./startcluster.sh MS ZK
  • Stop Cluster. Current stopcluster.sh, uses lxConsole by default to do a graceful stop. Allows 3 modifiers which cannot be combined:

#stop gracefully all components except Zookeeper
$BASEDIR/admin> ./stopcluster.sh
#stop Zookeeper
$BASEDIR/admin> ./stopcluster.sh MS ZK
  • Check the Cluster: To check whether the components are really running and ports are bind.

$BASEDIR/admin> ./checkcluster.sh

checkcluster doesn’t check if zookeeper is running directly but It does check that zookeeper port is listening

  • Restart components: This will do the previous check and restart all components that are found not to be running.

$BASEDIR/admin> ./checkandrestart.sh
  • Backup. LeanXcale provides a hot backup for production environments. However, you may need to do backup for your testing environment. For this, you should have first stopped the cluster and then do the backup. Current backup doesn’t store transaction log files so If the system didn’t stop gracefully some information could be lost. The following sequence is recommended:

##First stop all the workload
$BASEDIR/admin> ./stopcluster.sh
$BASEDIR/admin> ./checkcluster.sh
##If any component didn't stop, force to kill it
$BASEDIR/admin> ./stopcluster.sh force
$BASEDIR/admin> ./backupcluster.sh
$BASEDIR/admin> ./startcluster.sh
  • Recover: To recover from a previous backup, there is a scripts but assumes you have first stopped the cluster. The recover, will start the cluster once files were recovered

##First stop all the workload
$BASEDIR/admin> ./stopcluster.sh force
$BASEDIR/admin> ./recovercluster.sh
$BASEDIR/admin> ./checkcluster.sh

3. SQL Clients

LeanXcale provides a simple command line client called lxClient, but we recommend you use your favorite JDBC/SQL client. We provide instructions on how to install and configure the SQuirreL SQL client with LeanXcale.

3.1. Creating the schema

Using SQL DDL commands, you can use the client of your choice to create a database and build your schema.

3.2. Monitoring

LeanXcale is usually distributed with a Prometheus and a Grafana instance with a standard dashboard so you can have a view on how your cluster is running.

You can access the dashboard at http://{Metaserver}:3000/

Default login:

user admin

password admin

Don’t forget to change the password