Skip to content

Local Quickstart#

image

In this quickstart, we will run a RonDB cluster on a local machine. We will verify that it is running and run some MySQL queries against it.

Requirements#

The following requirements must be fulfilled to run this quickstart:

  • Linux machine (tested on Ubuntu 20.04, 22.04 & Red Hat-compatible 8+)

  • RonDB installed (22.10 recommended)

  • 8-10GiB of free memory (only 5GiB if using a single data node)

  • 3-4 CPU cores

Create a Configuration File#

We will first define our cluster configuration. We want a cluster with the following setup:

  • 1 management server

  • 2 data nodes (1 node group and replication factor 2)

  • 1 MySQL server

The management server will be used to load the cluster configuration file. When running a production cluster on a single machine, using both multiple replicas or multiple node groups does not make sense. In our case, we are simply demoing the usage of replicas. In a distributed cluster, we recommend using 2 or 3 replicas per node group. Node groups can be added later on to grow database storage capacity.

Since RonDB is an in-memory database, which is usually run with one data node (and only a data node) per host, we will have to be more careful with the memory and CPU configuration. By default, a data node will allocate all available memory and apply adaptive spinning to all available CPUs. To restrict allocated resources, we can use the parameters TotalMemoryConfig and NumCPUs.

In accordance with the requirements mentioned earlier, we will therefore run a minimal cluster setup, which allocates the following resources per node type:

  • Management Server: 10MiB memory, 0.1 CPU

  • Data Node: 3-4GiB memory, 1 CPU

  • MySQL Server: 1GiB memory, 2 CPU

For the sake of simplicity, we will use a single directory for all data files of all RonDB services. In production, this can be subject to many optimizations, especially when using local NVMe drives.

mkdir -p /usr/local/rondb_data

The cluster configuration file, i.e. our config.ini, is shown in the following. The notation for the management server is ndb_mgmd, for data nodes it is ndbd and for MySQL servers it is mysqld. The appended d stands for daemon, i.e., a process that runs in the background.

[ndb_mgmd]
NodeId=65
Hostname=127.0.0.1
DataDir=/usr/local/rondb_data

[ndbd default]
NoOfReplicas=2
DataDir=/usr/local/rondb_data

# Restricting CPU usage
NumCPUs=1

# Minimising memory allocation
TotalMemoryConfig=3G
RedoBuffer=16M
ReplicationMemory=50M
SchemaMemory=200M
TransactionMemory=150M
SharedGlobalMemory=150M

[ndbd]
NodeId=1

[ndbd]
NodeId=2

[mysqld]
NodeId=67

[mysqld]
NodeId=68

[api]
NodeId=69

Note that the parameter Hostname is only used for the management server. For data nodes, the default is localhost and for API nodes (RonDB clients) the default is empty. Empty hostnames for API nodes are generally considered an unsafe practice since they allow anybody with network access to connect to the cluster. Data nodes and management servers will also use Hostname as the binding address of their server.

For any type of API slots (including MySQL servers), each slot specifies one connection. Our configuration will allow our MySQL server to use two connections. It can therefore scale to a higher number of CPUs.

Start Cluster#

First, we start the management server, which loads the cluster configuration file.

ndb_mgmd --config-file=</path/to/config.ini> \
         --configdir=/usr/local/rondb_data

In contrast to the previously specified DataDir, the --configdir flag is used to specify the directory in which the management server will store its configuration database. This is essentially the config.ini file in a binary format. If other management client commands were used to alter the cluster configuration, these changes would also be reflected in this file.

If any configuration parameter is incorrect, the management server will fail to start. If this happens, check the node log file /usr/local/rondb_data/ndb_65_out.log.

Next, we’ll be starting the data nodes. This works as follows:

ndbmtd --ndb-connectstring=127.0.0.1 --ndb-nodeid=1
ndbmtd --ndb-connectstring=127.0.0.1 --ndb-nodeid=2

Note that this should be done in parallel since a cluster will not start until at least a partial cluster can be run. This means that every node group must have at least one data node running and at least one node group must have all data nodes running.

Once again, the node log files /usr/local/rondb_data/ndb_1_out.log and /usr/local/rondb_data/ndb_2_out.log can be checked for errors.

Since we are now already running cluster interactions, further errors can also be detected in the management’s cluster log: /usr/local/rondb_data/ndb_65_cluster.log

Checking Cluster Status#

Now, we technically already have a running cluster. This can be verified by running the show command via the management client. This will use the api slot which was specified in the config.ini file earlier to connect.

ndb_mgm --ndb-connectstring=127.0.0.1 -e show

This will output something like the following:

Connected to Management Server at: localhost:1186
Cluster Configuration
---------------------
[ndbd(NDB)] 2 node(s)
id=1    @127.0.0.1  (RonDB-22.10.1, Nodegroup: 0, *)
id=2    @127.0.0.1  (RonDB-22.10.1, Nodegroup: 0)

[ndb_mgmd(MGM)] 1 node(s)
id=65   @127.0.0.1  (RonDB-22.10.1)

[mysqld(API)]   3 node(s)
id=67 (not connected, accepting connect from any host)
id=68 (not connected, accepting connect from any host)
id=69 (not connected, accepting connect from any host)

As one can see, we have 2 data nodes and 1 management server running. However, what one can also see, is that we do not have a MySQL server running yet. This is what we will do next.

Starting MySQL Server#

MySQL servers can be configured extensively using an ini configuration file. There are a handful of books and an extensive MySQL reference manual which can be consulted for more details. For the sake of brevity, we will only use a few CLI commands:

mysqld --ndbcluster \
    --ndb-connectstring=127.0.0.1:1186 \
    --datadir=/usr/local/rondb_data/mysql_data \
    --log-error=/usr/local/rondb_data/mysql-error.log \
    --socket=/usr/local/rondb_data/mysql.sock \
    --ndb-cluster-connection-pool=2 \
    --initialize-insecure

This will bootstrap the MySQL server as a foreground process and exit once finished. When this is done, we can start the MySQL server as a background process. The following assumes that we are running with the Unix root user.

mysqld --ndbcluster \
    --ndb-connectstring=127.0.0.1:1186 \
    --datadir=/usr/local/rondb_data/mysql_data \
    --socket=/usr/local/rondb_data/mysql.sock \
    --log-error=/usr/local/rondb_data/mysql-error.log \
    --ndb-cluster-connection-pool=2 \
    --user=root \
    --daemonize

This will start a MySQL server using the two connections to the cluster that we had specified in the config.ini file. Both these two commands should take less than a minute to initialize.

Error messages can be checked in the log file /usr/local/rondb_data/mysql-error.log.

Checking MySQL Status#

The created MySQL server will be initialized passwordless for the default MySQL user root. Therefore, we can connect to it using the MySQL client with the following command:

mysql --socket=/usr/local/rondb_data/mysql.sock -uroot

If everything is working, we will then be able to access the ndbinfo database, which provides information about the RonDB cluster:

mysql> USE ndbinfo;
mysql> SHOW TABLES;
mysql> SELECT * from cpustat;
+---------+--------+---------+-----------+---------+-------------+-----------------+-----------------+-------------+--------------------+--------------+
| node_id | thr_no | OS_user | OS_system | OS_idle | thread_exec | thread_sleeping | thread_spinning | thread_send | thread_buffer_full | elapsed_time |
+---------+--------+---------+-----------+---------+-------------+-----------------+-----------------+-------------+--------------------+--------------+
|       1 |      0 |       2 |         2 |      96 |           3 |              97 |               0 |           0 |                  0 |      1032096 |
|       2 |      0 |       2 |         2 |      96 |           3 |              97 |               0 |           0 |                  0 |      1006971 |
+---------+--------+---------+-----------+---------+-------------+-----------------+-----------------+-------------+--------------------+--------------+
2 rows in set (0.01 sec)

The MySQL server is now connected to the RonDB cluster and can access information about the data nodes. The cluster is now fully set up!