Skip to content

Configuration Basics#

RonDB supports two different configuration files:

  • Cluster Configuration (config.ini): Required file that is read by the management server

  • MySQL Configuration (my.cnf): Optional file that can be replaced by CLI parameters for MySQL servers

Both configuration files are written in the .ini format. Whilst the cluster configuration file has case-insensitive section names and parameters, these are case-sensitive for the MySQL configuration file.

The following describes the sections of these files and their most important parameters.

Cluster Configuration File#

The following section headers are valid for the cluster configuration file:

  • [ndb_mgmd] (equivalent to [mgm])

  • [ndbd] (equivalent to [db])

  • [api] (equivalent to [mysqld])

  • [tcp]

  • [shm]

The sections ndbd, ndb_mgmd and mysqld each represent nodes in the cluster. Each of these can be specified multiple times. To avoid repetition, one can specify default sections like this:

[ndbd default]

The communication between two nodes can be configured using either the tcp (TCP/IP) section or the shm (shared memory) section. These are the two options for nodes to communicate with each other.

An example of a cluster configuration file (config.ini) has already been shown in the Local Quickstart Tutorial. In the following, we will explain several more parameters that can be used for a basic setup.

Node IDs#

The node IDs are identifiers for the node slots in the configuration file. They use the parameter NodeId such as follows:

[ndbd]
NodeId=1
NodeGroup=0
Hostname=ndbd1_hostname

Since a distributed cluster may end up containing many nodes, we will briefly discuss some properties of node IDs:

  • Range of node IDs: [1-255]; hence max number of nodes: 255

  • Usage of node IDs is optional, but helpful for debugging

  • Data nodes can only use node IDs [1-144]

  • We recommend using node IDs [65-66] for management servers and [67-255] for MySQL servers / API nodes

Hostnames#

Depending on the node type, setting hostnames/IPs to the slots’ Hostname parameter may be required or optional:

  • Management servers: Required

  • Data nodes: Required (defaults to localhost)

  • MySQL servers / API nodes: Optional, but recommended for security reasons

Regarding API nodes, the Hostname parameter acts as an internal firewall and therefore can block unwanted access to the cluster.

Since RonDB claims to have higher availability than DNS servers, it is recommended to use IP addresses over hostnames. However, using hostnames can be very convenient in environments such as Kubernetes, where network IDs can be static for services.

Note that the Hostname parameter will also be used as a binding address for the corresponding service. If the service should listen to a different network address, one can use the --bind-address argument when starting the service.

As an example, we have the following data node slot, where the hostname ndbd1_hostname resolves to the given IP address:

[ndbd]
NodeId=1
Hostname=192.158.1.38

Then we could start the data node as follows:

ndbmtd \
    --ndb-connectstring=<string> \
    --ndb-nodeid=1 \
    --bind-address=ndbd1_hostname

Ports#

The management server will listen to the port set by PortNumber. It defaults to 1186, so setting it is optional. The data nodes’ ServerPort on the other hand defaults to a dynamic port number. Relying on this can be tricky in environments with firewalls.

Defining Disk Space#

For RonDB data nodes, defining disk space is important for both how much data the database can store and for certain performance characteristics. RonDB has the following larger read/write operations to disk for data nodes:

  • REDO logs: Persisting transaction logs every 1-2s

  • Local checkpoints: Compressing REDO logs when full - e.g. 5 updates on same key ➡ 1 insert

  • Disk column data: Storing disk-based columns

  • UNDO logs: Needed to revert disk-based columns to the start of a local checkpoint

The following table shows how these different storage types are impacted by their available size:

Impact of larger size Minimum Recommended
REDO logs

  • Less frequent local checkpoints (more efficient)

  • Slower recovery

  • Lower likelihood of running out of REDO logs with high write load

 2GiB 64GiB (default)
Local checkpoints 1.6 x in-memory data 1.6 x in-memory data
Disk column data More available disk data 1GiB Expected disk-column data (default is 0)
UNDO logs Better performance for disk column writes 100 MiB 64GiB

The following shows how the sizes of these different types of data can be configured:

REDO Log#

The size of the REDO log is equal to:

NoOfFragmentLogParts x NoOfFragmentLogFiles x FragmentLogFileSize

when trying to minimise this size, one can use the following configuration (2GiB):

[ndbd default]
NoOfFragmentLogParts=2
NoOfFragmentLogFiles=8
FragmentLogFileSize=128MiB

Local Checkpoints#

The local checkpoint size will simply grow with the amount of data stored in memory. The maximum amount of in-memory data is either all available RAM per data node or the value of TotalMemoryConfig if configured.

Disk Column Data#

The disk column data is stored in tablespaces. Each tablespace can contain multiple data files. Usually, one defines a single large data file at cluster start using the following notation:

[ndbd default]
InitialTablespace=name=ts_1;extent_size=16M;<data_file_name.dat>:<size>

However, it is also possible to define multiple data files and place them into different directories. This will then allow for parallel disk column reads.

UNDO Log#

The UNDO log works similarly to the disk column data - one log file group can contain multiple log files. Once again, this is usually initialized with one large log file at cluster start:

[ndbd default]
InitialLogFileGroup=name=name=lg_1;undo_buffer_size=128M;<undo-log-filename.log>:<size>

MySQL Configuration File#

[mysqld]
ndbcluster
ndb-connectstring=192.168.1.100

[ndbd]
connect-string=192.168.1.100
nodeid=1

[ndb_mgmd]
connect-string=192.168.1.100
config-file=/path/to/config/file
nodeid=65

[ndb_mgm]
connect-string=192.168.1.100

The MySQL configuration file (my.cnf) contains parameters to the various programs executed in RonDB. The [mysqld] section contains parameters to be used by mysqld when starting. The ndbcluster and ndb-connectstring are mandatory here so they are good candidates to place into my.cnf.

The [ndbd] is used by ndbmtd. The connect-string parameter is good to place here. If only one data node is used per host it makes sense to place the data node id here as well.

The same reasoning applies to the [ndb_mgmd] section, here the placement of the configuration files config-file is a useful parameter to place in my.cnf.

There is a section for the ndb_mgm program and here it makes sense to specify the connect-string.

One of the complexities of the my.cnf is that it can execute several my.cnf files before using the command run-time parameters.

This is the order that the search for my.cnf is done.

  1. /etc/my.cnf

  2. /etc/mysql/my.cnf

  3. $MYSQL_HOME/my.cnf

  4. defaults-extra-file

  5. ./my.cnf

  6. ./mylogin.cnf (only MySQL clients)

The --defaults-extra-file is specified as a command parameter. This means that potentially up to 6 different configurations files are processed and only after that the run-time parameters are processed. As is clear it is easy to forget about one of those instances of the MySQL configuration file. The complexity here comes from that a distribution might have preinstalled some of those configuration files with values that you don’t want to have there.

The --defaults-file command option can be used to specify the one and only my.cnf file to read. To start without any configuration file at all one uses the option --no-defaults-file.