Get the code, build it, test it

MariaDB Server is hosted on GitHub. The official repository can be found at https://github.com/MariaDB/server.

Prerequisites

For getting started as a developer and to make your debugging process easier, make sure that your hardware has at least 2GB RAM, 10GB HD and at least 4 cores. We are working with git and cmake, so you will need to have git installed and cmake.

Having a GitHub account will make the contribution process easier.

Get the source code and decide which branch to target

It is recommended that everything you do with development you do as a regular user, not as a super user.

If you are developing a new feature, or refactoring code, use the current development version. As of September 2024, this is 11.7.
If you are fixing a bug, including any malfunctioning build or feature, use the earliest maintained branch where the bug applies. If this bug is from our JIRA bug tracker, the earliest Fix Version/s in JIRA that is maintained applies. As of May 2024, the earliest maintained branch is 10.5 (end-of-life in June 2025).
If the upcoming release is due to be the final release for that series, to avoid fixes introducing permanent regressions, only critical and safe bugfixes will be applied to that release. The final 10.5 release is scheduled for the second quarter of 2025. If in doubt, check with a developer on Zulip.

The recommended way to get the source is to fork it and clone it. A --branch {version} argument can be appended to this for the non-default branch.

git clone https://github.com/YOUR-USERNAME/server

Build the server

Before you can build the server, you must install build dependencies. Windows users should follow the link How to build MariaDB on Windows.

On a Debian based distribution:

apt-get build-dep mariadb-server
apt-get install build-essential libncurses5-dev gnutls-dev bison zlib1g-dev ccache

On RPM based distributions:

dnf builddep mariadb

A few extra packages may be required to build other components. Extra packages may also apply if dependencies have been added since the OS version you are using.

Please note that on some MacOS systems, the default bison version is a bit older than what we need to build MariaDB. Please try to install bison from Homebrew if you encounter grammar errors during the build process.

Configure the build

MariaDB uses cmake to generate Makefiles (or Ninja build files) used to compile the server.

To check if cmake is installed run cmake --version. CMake has a CMAKE_BUILD_TYPE option for predefined build types, which affects optimization and whether the result of the build can be instrumented. One of the build types is the Debug type, for which optimizations are off and debug instrumentation is generated. This option is used for creating the trace files which are useful if mariadbd is crashing. Running without specifying CMAKE_BUILD_TYPE uses default (RelWithDebugInfo). All CMake configuration options for MariaDB can be displayed with:

cmake . -LH

where L stands for short form, LH short form plus description, LA lists internal and advanced ones options. For more options see cmake documentation.

Recommend always doing an out-of-tree build so that your source code doesn’t get build artifacts mixed with the source files. This also allow different build directories with different cmake options from the same source.

If you have accidentally built an in-tree build, make sure to clean out old object files and cached information before reconfiguring and rebuilding:

make clean

rm CMakeCache.txt

or (preferred) nothing this will remove any uncommitted changes:

git clean -dffx

git reset --hard HEAD

git submodule update --init --recursive

The last command is needed because fresh git clone doesn’t automatically clone everything (examples are modules libmariadb and storage/rocksdb/rocksdb folder which is upstream submodule). After git submodule update run again git status. To configure a Debug build, useful for development, create a build directory beside the source tree and change to this directory:

mkdir build-mariadb-server-debug
cd build-mariadb-server-debug

Then configure MariaDB by running:

cmake ../server -DCMAKE_BUILD_TYPE=Debug

Debugging builds provide additional tests.

CMake will now check to see which libraries are available, which compiler is installed and if everything checks out, it will finish with a “Configure successful” message. If there are failures, check to see which libraries you need to install. You probably need to install the development versions of them.

Configuration with CMake produces files under the CMakeFiles directory:
CMakeFiles/CMakeError.log and CMakeFiles/CMakeOutput.log.

After the initial configuration has been performed you can add more options to cmake. Options are remembered in the CMake cache (the CMakeCache.txt file in the build directory (build-mariadb-server-debug)).

If the configuring or building doesn’t succeed, you can install the required packages and re-run cmake. Alternately if the error is confined to a plugin, those can be disabled with a cmake option like -DPLUGIN_MROONGA=NO.

Build with embedded server is not set by default in the build since it increase the compilation time. In order to use it, compile the server with cmake . -DWITH_EMBEDDED_SERVER=1. Note the . here is the current build directory and not the source directory.

As an alternative you can also use ninja build system in order to run builds faster. To do so make sure you have installed ninja.

apt-get install ninja-build

If you have successfully installed build system with ninja --version you will obtain installed version.

Make sure that you cleaned old object files and run again cmake but this time with Ninja flag and with prefix -G.

cmake ../server -DCMAKE_BUILD_TYPE=Debug -G Ninja

Now you are ready to compile server (with make or ninja), invoke cmake --build . inside the build directory.

For the faster build you can exclude storage engines that you don’t need in your development. Here is an example of excluding some of storage engines (uses shell expansion) plus other configuration options for a faster build:

cmake ../server -DCONC_WITH_{UNITTEST,SSL}=OFF -DWITH_UNIT_TESTS=OFF -DCMAKE_BUILD_TYPE=Debug -DWITHOUT_DYNAMIC_PLUGIN=ON -DWITH_SAFEMALLOC=OFF -DWITH_SSL=bundled -DMYSQL_MAINTAINER_MODE=OFF -G Ninja

To see the full list of options used by cmake or to change them through GUI, from build folder run ccmake .(you will have to install cmake-curses-gui).

Compile

To build with cmake, regardless of if using make or ninja:

 cmake --build . --parallel 5

Substitute 5 with the number of cores you have available for faster builds. Option --parallel works for cmake version 3.20+, alternatively pass options to native tool like cmake --build . -- -j5. Ninja automatically does builds in parallel.

Testing the server

Now that the server is built, we should test that everything is working properly.

To find out if your mariadbd binary has debugging support, run from the build directory sql/mariadbd -V on the command line. If the version number ends in -debug then your mariadbd binary was compiled with debugging support.

MariaDB has a testing framework defined in mysql-test folder. To run all tests:

mysql-test/mtr --parallel=5 --mem --force --max-test-fail=40

Note: if you are using MacOS omit the --mem flag. To run only unit tests:

mysql-test/mtr --suite=unit --mem --parallel=5

Each of the above is run from build directory. mysql-test-run uses its own --defaults-file overriding any default one.

You can see logs for your test in

mysql-test/var/log

There are lots of useful flags for mtr.

--parallel=#number-of-parallel-tasks will run multiple tests in parallel, thus speeding up tests. The process can easily take over an hour, even if parallelization is used.
--mem is used to force the tests to be run on a virtual ramdisk. This will speed things up as long as RAM is sufficient (not working in MacOS).
--force is used to continue to run the suit after failure.
--max-test-fail is used to limit the number of test failures before aborting the current test run. Defaults to 10. Set it’s default with the environment variable MTR_MAX_TEST_FAIL. (requires --force)
--embedded is used to run with the embedded server.
--big-test(or just --big) is used to run the big tests (tests which can use lots of memory and/or disk. In tests these tests have --source include/big_test.inc. If you want only to run big test use the flag two times --big --big.
--help is used to show options to control what engine/variation to run.

Starting mariadbd after build

You can run mariadbd directly from the build directory (without executing sudo cmake --install .).

If you are running MariaDB for first time you will need to run mariadb-install-db to install the needed system tables. But before that create a directory for your data (this directory will be used for the datadir system variable in the config file). Copy following in ~/mariadb.cnf file.

Note: if you are using MacOS you will need to use the path to your home directory instead of ~ for all the subsequent steps in this document.

The path of these locations should exist and be writable by the current OS user.

[client-server]
socket = /path/to/mariadb.sock

[mariadb]
datadir = path/to/your/data/dir

If you need to change something, read more about setting mariadbd configuration files and groups.

Now that you have created your own config file you can call it with flag --defaults-file while installing the system tables. To install the system tables call following from the build folder:

./scripts/mariadb-install-db --srcdir=../server --defaults-file=~/mariadb.cnf

After that you can start mariadbd, which by default looks for option file. If --defaults-file is given mariadbd will read only from this file. Run like:

sql/mariadbd --defaults-file=~/mariadb.cnf

After starting up mariadbd you can launch the client as root:

client/mariadb

What is next?

If you are complete in the feature/bug fix see Submitting a Pull Request to contribute your change to the next server release.

As a new contributor we encourage you to look more in beginner friendly jira tasks where you can find appropriate task that you can work on. In order to work on this task just write a comment in the ticket, stating that you re interested in working on it.