Skip to content
Percona Software for MySQL Documentation

Rate this page
☆ ☆ ☆ ☆ ☆
Thanks for your feedback
Thank you! The feedback has been submitted.

For help, click the link below to get free database assistance or contact our experts for personalized support.

Get help from Percona

Compile Percona Server for MySQL from source

The following instructions install Percona Server for MySQL 8.4.

When to use this guide

Compiling from source is an advanced installation method. Prefer repository packages (APT or DNF) or binary tarballs unless you need a custom or debug build.

Use this guide when you need a custom or debug build from source (for example, to test patches or build with non-default options).

For creating packages (RPM, DEB) or repeatable production builds, Percona provides automated build and packaging tooling that installs dependencies and produces installable packages; see Build APT packages and the Percona Server source repository for those workflows.

Warning: A manual source build does not match the performance or security profile of official Percona binaries. Release builds use Profile-Guided Optimization (PGO), Link-Time Optimization (LTO), and hardened compiler flags.

Treat a custom-compiled binary as suitable for development or testing, not as a drop-in production replacement for official packages.

Installation prerequisites

The build requires a fixed set of dependencies. Install the packages for your platform before running CMake so that configuration and compilation succeed without discovering missing libraries one at a time.

Toolchain: Percona Server 8.4 uses modern C++ and requires a minimum glibc version and a modern linker (binutils). Do not assume that a modern GCC (for example, 11+) implies a modern binutils; the linker is what handles C++20 symbol resolution, and an old system linker can cause a build failure in the final link phase after hours of compilation. On many systems a newer GCC is installed from a side-repo (for example, Software Collections) while the system linker stays old—check both.

Glibc: Run ldd --version. If the version is less than 2.28, this build will fail. Upgrade your OS or use a Docker container with a modern base.

Linker: Run ld -v (or ld.bfd -v). If the version is less than 2.30, C++20 symbol resolution will fail. You must install a newer binutils package.

On older LTS distros (for example, RHEL ⅞ with default or SCL toolchain), a late failure is often glibc or linker; use a distribution and full toolchain that Percona documents as supported.

RHEL, Rocky, Alma (package manager: dnf or yum):

dnf install cmake gcc gcc-c++ ncurses-devel openssl-devel libudev-devel libaio-devel bison wget curl

Debian, Ubuntu (package manager: apt):

apt install cmake gcc g++ libncurses-dev libssl-dev libudev-dev libaio-dev bison wget curl

If you will use -DDOWNLOAD_BOOST=1, you must have wget or curl installed and network access during configuration; otherwise the configure step can fail with a network or download error unrelated to C++. The lists below include both so a minimal environment has at least one.

Additional packages may be required depending on optional features (for example, PAM, zlib, MyRocks). For a Percona-specific list that extends the MySQL 8.4 baseline with requirements for XtraDB, MyRocks, and other components, see Percona Server for MySQL 8.4 source installation prerequisites. The MySQL 8.4 Source Installation Prerequisites page remains the upstream baseline reference.

If CMake reports a “library not found” or similar error for a dependency not listed in the prerequisites doc, check the Percona Server source repository or CMake configuration for that component.

Install location and overwrite risk

The default install prefix is /usr/local/mysql (CMAKE_INSTALL_PREFIX). Installing to the default prefix can overwrite or conflict with a package-managed Percona Server or MySQL installation.

To avoid overwriting package-managed installations, set a custom prefix at configure time and use that prefix consistently for make install:

cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_CONFIG=mysql_release -DCMAKE_INSTALL_PREFIX=/opt/percona-server-8.4

For staged installs (for example, into a package root), set DESTDIR when installing. The install layout replicates the full prefix under DESTDIR. If your prefix is /opt/ps and your DESTDIR is /tmp/stage, your binary is not at /tmp/stage/bin/mysqld. The binary is at /tmp/stage/opt/ps/bin/mysqld. If you look only under /tmp/stage/ you will not find it and may assume the build failed; the build did not fail—the files are under DESTDIR plus your prefix. Plan packaging and copy steps around that path.

make -j<N> install DESTDIR=/path/to/package/root

Obtain the source

You can build from a Git clone (when the build machine has network access to GitHub) or from a source tarball (the standard way on air-gapped or proxy-restricted build servers).

Build from a source tarball (offline or restricted network)

Many enterprise build servers cannot run git clone (proxy restrictions, no outbound access, or no git). In that case, obtain a source tarball on a machine that can download or build the tarball, transfer the tarball to the build machine, then configure and build there.

  • Download a Percona Server source tarball from Percona downloads, or

  • On a machine with a full clone, generate a tarball: from the repo root run cmake . && make dist and use the resulting tarball.

On the build machine, extract the tarball and use the same out-of-source configure and build steps as below (create a build directory inside the extracted tree, run cmake .. from there, then make and make install).

No git is required on the build machine.

Build from the Git source tree

Percona uses the Github revision control system for development. To build from git you need git installed and the build machine able to reach GitHub (or a mirror).

Fetch the latest Percona Server for MySQL 8.4 sources. To avoid pulling the full repository history (which is large in size and bandwidth), clone only the 8.4 branch with a shallow clone:

git clone --branch 8.4 --depth 1 https://github.com/percona/percona-server.git
cd percona-server
git submodule update --init

If you need full history (for example, to generate a source tarball or inspect past commits), use a normal clone and then checkout the branch:

git clone https://github.com/percona/percona-server.git
cd percona-server
git checkout 8.4
git submodule update --init

If you are going to be making changes to Percona Server for MySQL 8.4 and wanting to distribute the resulting work, you can generate a new source tarball (exactly the same way as we do for release):

cmake .
make dist

After either fetching the source repository or extracting a source tarball (from Percona or one you generated yourself), you will now need to configure and build Percona Server for MySQL.

First, run CMake to configure the build. You can specify build options as for a normal MySQL build.

Note: -DFEATURE_SET=community is not supported in 8.4. If you use -DFEATURE_SET=community, CMake will report: Manually-specified variables were not used by the project: FEATURE_SET.

Boost: Percona Server 8.4 requires a specific Boost version (defined in the source tree). If the system Boost is different (for example, 1.8x when the tree expects 1.77), CMake will fail or produce an incompatible build.

To avoid version mismatches, use one of:

  • Let CMake download the correct Boost: add -DDOWNLOAD_BOOST=1 to the cmake command. The DOWNLOAD_BOOST option requires wget or curl installed and working network access during configuration. In restricted or containerized environments (no network, or no wget/curl), the configure step can fail with a network or download error; in that case use a local Boost (next bullet) or install the required Boost via the system package manager.

  • Use a local Boost tree: add -DWITH_BOOST=/path/to/boost (must be the version required by the source).

Do not rely on a single hardcoded Boost path or version in documentation; check the source or CMake output for the exact version required.

Out-of-source build — the only supported approach. To avoid poisoning your environment, visualize the separation between your source code and your build artifacts:

  • Source tree — The “holy” directory. Never touch it with cmake; keep the source tree pristine and free of CMake or build artifacts.

  • Build directory — The “scrap heap.” This is where the configuration and objects live; delete the build directory to reset.

  • Install prefix — The “final product.” Where your binaries actually live and run (for example, /opt/percona-server-8.4).

From the repository root, use the following exact sequence:

mkdir build && cd build && cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_CONFIG=mysql_release

Do not run cmake . in the source root; that writes generated files into the source tree and is hard to undo safely.

If CMake reports a Boost version mismatch, add -DDOWNLOAD_BOOST=1 to the cmake command so the correct Boost is downloaded automatically.

On newer platforms or distros, if you hit compilation errors that are Linux-distro dependent, add -DWITH_PACKAGE_FLAGS=OFF:

cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_CONFIG=mysql_release -DWITH_PACKAGE_FLAGS=OFF

Recovery from a poisoned source tree: If you ran cmake . in the source root by mistake, CMake and build artifacts are now in the source tree; make clean does not fully reset CMake state.

Safest recovery: remove only the known generated files so you do not touch local patches or config. From the repository root, remove (for example) CMakeCache.txt, the CMakeFiles/ directory, cmake_install.cmake, and Makefile (and any other files or directories CMake created in the root). After that you can run the out-of-source sequence from a clean state.

Only if you are certain there are no untracked local changes, you can instead run git clean -xfd to remove all untracked and ignored files—but the command permanently deletes every file not tracked by git, including uncommitted work; the command is as destructive as the problem the command fixes.

With an out-of-source build, recovery is simple: delete the build directory (for example, rm -rf build) and run the mkdir build && cd build && cmake .. sequence again; the source tree is unchanged.

Compile from source

Compile using make from the build directory. Do not use make -j$(nproc).

Compilation can use 2 GB or more of RAM per job, and the final link of mysqld—the last few percent of the build—can spike to 4 GB or more in a single job, regardless of core count. On a 32-core machine with 16 GB RAM, -j32 would direct 32 compile jobs plus the link; that combination commonly causes swap storms or OOM.

Use a fixed cap instead: at most N jobs where N is the smaller of (physical RAM in GB ÷ 2) and 8. With 8 GB RAM use make -j4 or lower; with 16 GB or more, make -j8 is a safe upper bound. When in doubt use make -j2 or plain make (single job).

make -j4

If the build is killed by the OOM killer or the system thrashes, reduce the job count (for example, make -j2) or run make with no -j and try again.

Install (use the same -j value as for the build, or a lower one if install fails due to memory):

make -j4 install

Step 6: Initialize and start

The guide does not end at make install. For a beginner, the job is not done until the database is running. You have built the binary; you must initialize the data directory and start the server, then use the temporary root password to log in.

Initialize the data directory

Create a data directory and give ownership to the user that will run the server (for example, mysql). Then run mysqld --initialize with --basedir and --datadir set to your install prefix and chosen datadir path. Example (adjust the datadir path and user to match your system):

mkdir -p /var/lib/mysql-custom
chown mysql:mysql /var/lib/mysql-custom
/opt/percona-server-8.4/bin/mysqld --initialize --user=mysql --basedir=/opt/percona-server-8.4 --datadir=/var/lib/mysql-custom

You must find the temporary root password after initialization. mysqld --initialize generates a one-time password for root@localhost and writes it to the error log. The error log is usually in the datadir (for example, /var/lib/mysql-custom/hostname.err) or shown in the command output. Without this temporary password, you are locked out of the server you just built. Open the error log, search for a line containing “temporary password” or “root@localhost”, and use that password to connect and change it. See Post-installation for full steps.

To skip the temporary password (less secure), use --initialize-insecure instead of --initialize; then root@localhost has no password until you set one.

Start the server

Package installations provide a systemd unit (or init script) that starts mysqld from the default path. A custom-prefix install (for example, /opt/percona-server-8.4) is not managed by that unit. You must create or adapt a systemd unit file (or init script) so that ExecStart (or the equivalent) points to the actual binary path—for example, /opt/percona-server-8.4/bin/mysqld—and so that basedir and datadir match your layout. Without that, the system service manager will not start your custom-built server. See your distribution’s documentation for creating a systemd service and Post-installation for running and testing the server.

Maintaining a source build

By building from source you opt out of package-manager updates (dnf update / apt upgrade). You become the release engineer and your own security officer: you must track Percona security and release announcements and re-pull, re-patch, and re-compile when CVEs or releases affect your version.

A source build is a snapshot in time; without that discipline, a “quickstart” becomes a long-term liability. If you forget to re-pull and re-patch when CVEs are released, you are running known-vulnerable software; official packages receive security updates automatically. Treat maintenance as a responsibility: use the checklist below to stay on top of security and updates.

Maintenance checklist

  • Monthly: Check Percona Security Advisories.

  • Security patching: From the repository root, pull the latest changes and rebuild. Then reinstall (adjust -j if needed for your system):

git pull && git submodule update && cd build && cmake .. && make -j4 && make install

Applying updates: Obtain fresh source (for example, git pull and git submodule update in a clone, or a new source tarball). Then:

  • Incremental build: If you only pulled new commits and did not change CMake options or switch major versions, re-run make (and make install) from the existing build directory. No need to delete the build dir or re-run CMake; the incremental build is the normal path for security and minor updates.

  • Full reconfigure: If you changed CMake options, switched branch or major version, or see odd build errors after pulling, remove the build directory (rm -rf build), run the mkdir build && cd build && cmake .. sequence again with the same options, then make and make install.

Keep configuration files (for example, my.cnf) and data directories outside the install prefix; reinstalling then overwrites only the binaries and leaves your config and data intact.

Use a stable custom prefix and config/datadir paths so upgrades are predictable.