Build from Source - VillageSQL Server for MySQL

Overview

Building VillageSQL from source gives you the latest features and allows you to customize the build for your specific environment. These steps build VillageSQL on upstream MySQL 8.4. VillageSQL also builds on Percona Server as an alternative codebase — see the Percona Build page.

Prerequisites

Before you begin, ensure you have the following installed:

Git - For cloning the repository
A supported platform - Debian or Ubuntu Linux, or macOS with Homebrew

The repository ships a script that installs the compiler, CMake, and the development libraries the build needs. Step 2 runs that script, so you do not have to install those packages yourself.

Step 1: Clone the Repository

Clone the VillageSQL Server repository from GitHub. Clone into your home directory so the CMake steps below work without modification:

cd "$HOME"
git clone --depth 1 https://github.com/villagesql/villagesql-server.git
cd villagesql-server

To build the exact code a release shipped, clone the tag that marks it instead of the branch: -b publish/mysql-8.4_0.0.6.

The repository is several GB due to the MySQL codebase.

Step 2: Install Build Dependencies

Run the setup script from the repository you just cloned. The script detects your operating system and installs the packages the build needs:

cd "$HOME/villagesql-server"
villagesql/bld_tools/setup_build_env.sh

On Linux the script uses apt-get and asks for sudo. On macOS it uses Homebrew. VillageSQL CI installs its build dependencies with the same script, so the package list stays current with the build.

The script supports Debian or Ubuntu Linux and macOS. On another Linux distribution, read villagesql/bld_tools/setup_linux_build_env.sh and install the equivalent packages with your own package manager.

Step 3: Configure with CMake

Create a build directory outside the repository and configure the project:

# Create build directory (outside the repo)
mkdir -p "$HOME/build/villagesql"
cd "$HOME/build/villagesql"

# Configure with CMake
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX="$HOME/mysql"

Paths use $HOME rather than ~ throughout, on both platforms. The shell only expands ~ at the start of a word, so --datadir=~/mysql-data/data reaches mysqld as a directory literally named ~ and the server aborts. Quoting "$HOME/..." also keeps the path in one piece if your home directory name contains a space. Replace the repository path with your actual clone location if different.

CMake Options Explained

<path-to-repo> - Path to the cloned VillageSQL repository
-DWITH_DEBUG=1 - Builds with the DBUG facility and assertions, unoptimized (recommended for development)
-DCMAKE_INSTALL_PREFIX="$HOME/mysql" - Sets installation directory

Additional CMake Options

Production build:

cmake "$HOME/villagesql-server" -DCMAKE_INSTALL_PREFIX=/usr/local/mysql

With custom compilation comment:

cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
      -DCMAKE_INSTALL_PREFIX="$HOME/mysql" \
      -DCOMPILATION_COMMENT="VillageSQL Version of MySQL"

If you need to reconfigure, clear the CMake cache first (run from within the build directory):

rm CMakeCache.txt

Step 4: Compile the Code

Build VillageSQL using make with parallel compilation. From within the build directory: Build everything (recommended):

make -j10

This builds the server, the mysql client that Step 7 uses, the extension SDK, and the example extensions’ .veb files. Build the server and client only:

make -j10 mysqld mysql

This pair is faster and builds neither the extension SDK nor the example .veb files, so INSTALL EXTENSION vsql_complex finds no bundle to install and an extension build that passes -DVillageSQL_BUILD_DIR finds no SDK.

Adjust the parallelism (-j10) based on your CPU cores. Subtract 2-4 from your total core count to keep your system responsive. For example, on a 12-core machine, use -j10.

When complete, verify the server and client binaries were built:

ls "$HOME/build/villagesql/bin/mysqld" "$HOME/build/villagesql/bin/mysql"

Step 5: Initialize the Database

Before starting the server for the first time, initialize the data directory: Production (with generated password - recommended):

mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

Development (no password - optional):

mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize-insecure --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

Running as root (Docker or sudo): If running as root (e.g., in Docker), MySQL requires the --user=root flag:

# Initialize as root
"$HOME/build/villagesql/bin/mysqld" --user=root --initialize-insecure --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

Use --initialize (with password) for production-like setups. Use --initialize-insecure (no password) only for local development and testing. When using --initialize, a temporary password will be generated and printed to the console: A temporary password is generated for root@localhost: <password>

Verify initialization succeeded by checking that the system databases were created:

ls "$HOME/mysql-data/data/mysql"

Step 6: Start the Server

Start the VillageSQL server:

"$HOME/build/villagesql/bin/mysqld" --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

Running as root (Docker or sudo):

"$HOME/build/villagesql/bin/mysqld" --user=root --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

The --gdb flag unblocks SIGINT, so Ctrl-C stops the server when you run it from a terminal. It also suppresses the crash backtrace and cancels --core-file, so leave it out when you want a crash report. To run in the background, add --daemonize to the mysqld command.

Step 7: Connect with MySQL Client

Open a new terminal and connect to the server using the MySQL client: If using —initialize-insecure (no password):

"$HOME/build/villagesql/bin/mysql" -u root

If using —initialize (with generated password):

"$HOME/build/villagesql/bin/mysql" -u root -p
# Enter the temporary password printed during initialization

You should see the MySQL prompt:

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 8
Server version: <version> Source distribution

mysql>

Verify Installation

Check that you’re running VillageSQL:

SELECT VERSION();

Development builds include the git commit hash in the version string:

8.4.11-villagesql-0.0.6-dev-eac70667eb6

Step 8: Set Up Users and Database

Change Root Password

If you used --initialize, change the temporary password:

SET PASSWORD = 'your-secure-password';

Create a Development User

For daily development, create a non-root user:

-- Create user
CREATE USER developer IDENTIFIED BY 'dev-password';

-- Grant all privileges
GRANT ALL PRIVILEGES ON *.* TO developer;

Exit and reconnect as your new user:

# Ctrl-D to exit
"$HOME/build/villagesql/bin/mysql" -u developer -p

Create a Database

CREATE DATABASE my_database;
USE my_database;

Connect to a specific database: mysql -u developer -p -D my_database

Step 9: Run the Tests

Verify the build with the VillageSQL test suite, from the build directory:

cd "$HOME/build/villagesql"
mysql-test/mysql-test-run.pl --do-suite=villagesql --nounit-tests --parallel=auto

--nounit-tests skips the upstream MySQL unit tests, which include known failures. Run the VillageSQL unit tests separately:

make -j10 villagesql-unit-tests && ctest -L villagesql

A failing test makes either command exit non-zero. For GDB debugging, running individual tests, re-recording expected results, and contributing to the server codebase, see the Server Development Guide.

Troubleshooting

Build Fails with Missing Dependencies

Run the setup script again. Step 3 leaves you in the build directory, so give the script its absolute path:

"$HOME/villagesql-server/villagesql/bld_tools/setup_build_env.sh"

Check the error message for the specific missing library.

Server Won’t Start

Verify the data directory was initialized: ls "$HOME/mysql-data/data/"
Check if another MySQL/VillageSQL instance is using port 3306
Review error logs in $HOME/mysql-data/data/*.err

Extension Installation Fails

Ensure the extension library (.so on Linux, .dylib on macOS) exists in the build output
Check that VillageSQL has the necessary permissions to load extensions
Verify the extension name and .veb filename are correct

Next Steps

Using Extensions

Learn how to install, update, and manage VillageSQL extensions.

Creating Extensions

Build your own custom extensions for VillageSQL.

Getting Started

Quick start guide for VillageSQL.

​Overview

​Prerequisites

​Step 1: Clone the Repository

​Step 2: Install Build Dependencies

​Step 3: Configure with CMake

​CMake Options Explained

​Additional CMake Options

​Step 4: Compile the Code

​Step 5: Initialize the Database

​Step 6: Start the Server

​Step 7: Connect with MySQL Client

​Verify Installation

​Step 8: Set Up Users and Database

​Change Root Password

​Create a Development User

​Create a Database

​Step 9: Run the Tests

​Troubleshooting

​Build Fails with Missing Dependencies

​Server Won’t Start

​Extension Installation Fails

​Next Steps

Using Extensions

Creating Extensions

Getting Started

Overview

Prerequisites

Step 1: Clone the Repository

Step 2: Install Build Dependencies

Step 3: Configure with CMake

CMake Options Explained

Additional CMake Options

Step 4: Compile the Code

Step 5: Initialize the Database

Step 6: Start the Server

Step 7: Connect with MySQL Client

Verify Installation

Step 8: Set Up Users and Database

Change Root Password

Create a Development User

Create a Database

Step 9: Run the Tests

Troubleshooting

Build Fails with Missing Dependencies

Server Won’t Start

Extension Installation Fails

Next Steps