Welcome to this new series about extending MariaDB. This series covers the addition of a new data type using the Type_handler.

The goal of the entire series is to create a new plugin data type MONEY to store and display amounts with currency.

Something like:

MariaDB [test]> select * from t1;
+----+-------------+
| id | amount      |
+----+-------------+
|  1 | $2,000.00   |
|  2 | $100,000.56 |
+----+-------------+
2 rows in set (0.002 sec)

Of course, the ultimate goal is to teach how to add data types in MariaDB, and we expect to see how creative our community developers are!

This is Part 0 – Build MariaDB from the GitHub repository

We will see how to clone the source tree and compile the server.

---

Opening

Before you can experiment with a custom data type, you need a server you built, one that you control.

In this article, we cover the 5 steps to have our build environment ready.

We will see two types of build modes:

• Debug is the best mode for development.
• RelWithDebInfo is what we ship when we want optimization without losing debug symbols.

MariaDB’s manual includes instructions for compiling MariaDB Server. For this series, we will focus on building it for Linux. Take a look at the documentation if you want to compile it for another Operating System.

Step 1: clone the MariaDB server source tree

$ git clone https://github.com/MariaDB/server.git
$ cd server

Before building the server, we also need several tools and libraries. These are the dependencies.

The best way to get all the dependency packages for your environment is to run the following commands:

On RPM environments (Red Hat, CentOS, Fedora, Oracle Linux, Rocky Linux, …):

$ sudo dnf builddep mariadb-server

On APT environments (Debian, Ubuntu, …):

$ sudo apt-get build-dep mariadb-11.8

Step 2: create an out-of-source build

Keep the source tree clean and make it easy to switch between build modes:

$ mkdir -p ../build-mariadb-debug
$ mkdir -p ../build-mariadb-relwithdebinfo

Build types determine whether MariaDB is compiled for debugging, release performance, or a mix of optimization and debug information.

Some info can be found in the documentation.

The accepted values are:

• Debug
• Release
• MinSizeRel
• RelWithDebInfo

Step 3: configure your environments

Configure a true debug build

I recommend using a separate build directory (out-of-source directory), so you won’t pollute the source directory. This allows you to have multiple build directories, and you can rebuild it from a fresh start by just removing it.

For the most introspection-friendly configuration, I suggest using:

$ cd ../build-mariadb-debug
$ cmake ../server -DCMAKE_BUILD_TYPE=Debug 

Use this build when you want:

• maximum visibility into server behavior
• assertions enabled
• easy single-stepping in gdb or lldb

If you are missing some packages to build the server, the CMake process will stop and let you know which package or library is missing.

At the end of the cmake command, you will see something similar to this:

-- The following OPTIONAL packages have been found:

 * ZLIB
 * LibXml2
 * Java (required version >= 1.6)
   Required for the CONNECT_JDBC feature
 * JNI
   Required for the CONNECT_JDBC feature
 * Boost (required version >= 1.40.0)
   Required for the OQGraph storage engine
 * GSSAPI
 * BZip2
 * LZ4 (required version >= 1.6)
 * LibLZMA
 * LZO 
 * Snappy
 * BISON (required version >= 2.4)

-- The following RECOMMENDED packages have been found:

 * OpenSSL

-- The following REQUIRED packages have been found:

 * Curses
 * Threads
 * CURL

-- The following features have been disabled:

 * LIBWRAP, Support for tcp wrappers
 * COLUMNSTORE, Storage Engine 
 * CONNECT_ODBC, Support for ODBC in the CONNECT storage engine
 * CONNECT_MONGODB, Support for MongoDB in the CONNECT storage engine
 * INNODB_EXTRA_DEBUG, Extra InnoDB debug checks
 * AWS_KEY_MANAGEMENT, AWS Encryption Key Management Plugin
 * EMBEDDED_SERVER, Embedded MariaDB Server Library

-- The following OPTIONAL packages have not been found:

 * Judy
   Required for the OQGraph storage engine

-- Configuring done (52.2s)
-- Generating done (0.4s)

Configure a production-like build

For information purposes, we now configure a faster build that still preserves symbols:

$ cd ../build-mariadb-relwithdebinfo
$ cmake ../server -DCMAKE_BUILD_TYPE=RelWithDebInfo

This is the build I would recommend for most of your development once the basics are working.

Step 4: compile

Build the server in whichever tree you want to use:

$ cmake --build . --parallel

This command will use all the cores of your machine. If you compile on your daily machine, such as your laptop, I recommend limiting the number of parallel threads used for compilation:

$ cmake --build . --parallel 4

In MariaDB Server’s source tree, there are also several helper scripts to build the server. Most of the contributors are already familiar with them. Those scripts are located in the BUILD directory.

Pay attention that the size of your build directory will also vary:

$ du -sh *
9.9G	build-mariadb-debug
5.7G	build-mariadb-relwithdebinfo
3.6G	server                           # the source tree

Step 5: testing the server

To test the freshly compiled server, the easiest way is to use MTR.

MTR (MariaDB/MySQL Test Run) is the test framework for running the server’s regression test suite. It can deploy, initialize, and start the server. Of course, we usually use it to automate tests, but we can also use it to start the server, then connect to it and test things manually.

At the end, we will have to create automatic tests for your code anyway.

$ ./mtr --start

My colleague Joro is always using mtr 1st to test if the server was built correctly

If you want, you can specify a vardir location using --vardir=<your-temp-data-dir>.

And finally, it’s the --start option that will let the MariaDB Server run for us to use.

It’s also possible to use --start-and-exit but then you will need to send the shutdown command instead of a simple CTRL+C

The output provides you with the socket and the port to use to connect to your MariaDB Server:

=========================================================================

TEST                                      RESULT   TIME (ms) or COMMENT
-------------------------------------------------------------------------

worker[01] Using MTR_BUILD_THREAD 300, with reserved ports 19000..19029
worker[01] 
Started [mysqld.1 - pid: 88563, winpid: 88563]
worker[01] Using config for test innodb.innodb
worker[01] Port and socket path for server(s):
worker[01] mysqld.1  19000  /run/media/fred/DATA/vardir/tmp/mysqld.1.sock
worker[01] Waiting for server(s) to exit...

In another shell, you can connect easily using the mariadb client:

$ client/mariadb -u root -S /run/media/fred/DATA/vardir/tmp/mysqld.1.sock 
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 3
Server version: 13.0.1-MariaDB-log Source distribution

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Help others discover MariaDB. Star it on GitHub: https://github.com/MariaDB/server

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> 

Conclusion

We now have everything we need to begin developing our new data type, since we have a separate development server that won’t interfere with the system installation.

See you very soon for the next part of this series.