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.

Prerequisites

Before you begin, ensure you have the following installed:

Git - For cloning the repository
CMake 3.14.6 or higher - Build system generator (macOS requires 3.19 or higher)
C++ Compiler - GCC 10 or newer, or Clang 14 or newer
Build tools - make, ninja, or equivalent
Development libraries - OpenSSL, ncurses, pkg-config, bison, and other MySQL dependencies

Install Dependencies

Ubuntu/Debian:

sudo apt install bison build-essential cmake libaio-dev libncurses5-dev \
                 libssl-dev libtirpc-dev pkg-config zlib1g-dev

macOS (using Homebrew): First, install Homebrew if you haven’t already:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then install dependencies:

brew install bison cmake openssl@3 pkgconf

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

The repository is several GB due to the MySQL codebase.

Step 2: Configure with CMake

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

# 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

macOS:

# Create build directory (outside the repo)
mkdir -p ~/build/villagesql
cd ~/build/villagesql

# Configure with CMake
cmake ~/villagesql-server -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX=~/mysql -DWITH_SSL=system

Linux users: Use $HOME for absolute paths. macOS users: Use ~ (tilde) — except in the mysqld commands in Steps 4 and 5, which use quoted "$HOME/..." paths on both platforms. The shell does not expand a tilde that follows =, so --datadir=~/mysql-data/data reaches mysqld as a literal ~ directory name and it aborts; the quotes keep the path in one piece if your home directory name contains a space. cmake expands the tilde itself, so -DCMAKE_INSTALL_PREFIX=~/mysql above is fine. Replace the repository path with your actual clone location if different.

CMake Options Explained

<path-to-repo> - Path to the cloned VillageSQL repository (use $HOME on Linux, ~ on macOS)
-DWITH_DEBUG=1 - Enables debug symbols (recommended for development)
-DCMAKE_INSTALL_PREFIX=~/mysql - Sets installation directory
-DWITH_SSL=system - Uses system OpenSSL library (required on macOS)

Additional CMake Options

Production build without debug symbols: Linux:

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

macOS:

cmake ~/villagesql-server -DCMAKE_INSTALL_PREFIX=/usr/local/mysql

With custom compilation comment: Linux:

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

macOS:

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

Developer mode with stricter warnings: Linux:

cmake $HOME/villagesql-server -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1

macOS:

cmake ~/villagesql-server -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1

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

rm CMakeCache.txt

Step 3: Compile the Code

Build VillageSQL using make with parallel compilation. From within the build directory: Build the server and client (recommended for development):

make -j10 mysqld mysql

The mysql target builds the client used to connect in Step 6; make -j10 mysqld alone builds only the server, and Step 6 would then have no client to run. Build everything:

make -j10

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: Linux:

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

macOS:

ls ~/build/villagesql/bin/mysqld ~/build/villagesql/bin/mysql

Step 4: Initialize the Database

Before starting the server for the first time, initialize the data directory: Linux: 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"

macOS: Production (with generated password - recommended):

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

Development (no password - optional):

mkdir -p ~/mysql-data/data
"$HOME/build/villagesql/bin/mysqld" --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: Linux:

ls $HOME/mysql-data/data/mysql

macOS:

ls ~/mysql-data/data/mysql

Step 5: Start the Server

Start the VillageSQL server: Linux:

"$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"

macOS:

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

The --gdb flag installs a SIGINT handler so Ctrl-C stops the server cleanly — useful when running interactively from a terminal. To run in the background, add --daemonize to the mysqld command.

Step 6: Connect with MySQL Client

Open a new terminal and connect to the server using the MySQL client: Linux: 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

macOS: If using —initialize-insecure (no password):

~/build/villagesql/bin/mysql -u root

If using —initialize (with generated password):

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

You should see the MySQL prompt:

Welcome to the VillageSQL Server for MySQL monitor.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>

Verify Installation

Check that you’re running VillageSQL:

SELECT VERSION();

Development builds append the git commit hash to the version string:

8.4.10-villagesql-0.0.6-dev-9e0577bd0b6

Step 7: 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: Linux:

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

macOS:

# Ctrl-D to exit
~/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

For GDB debugging, running tests, and contributing to the server codebase, see the Server Development Guide.

Troubleshooting

Build Fails with Missing Dependencies

Install the required development packages for your platform. Check the error message for specific missing libraries.

Server Won’t Start

Verify the data directory was initialized: ls ~/mysql-data/data/
Check if another MySQL/VillageSQL instance is using port 3306
Review error logs in ~/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

​Install Dependencies

​Step 1: Clone the Repository

​Step 2: Configure with CMake

​CMake Options Explained

​Additional CMake Options

​Step 3: Compile the Code

​Step 4: Initialize the Database

​Step 5: Start the Server

​Step 6: Connect with MySQL Client

​Verify Installation

​Step 7: Set Up Users and Database

​Change Root Password

​Create a Development User

​Create a Database

​Troubleshooting

​Build Fails with Missing Dependencies

​Server Won’t Start

​Extension Installation Fails

​Next Steps

Using Extensions

Creating Extensions

Getting Started

Overview

Prerequisites

Install Dependencies

Step 1: Clone the Repository

Step 2: Configure with CMake

CMake Options Explained

Additional CMake Options

Step 3: Compile the Code

Step 4: Initialize the Database

Step 5: Start the Server

Step 6: Connect with MySQL Client

Verify Installation

Step 7: Set Up Users and Database

Change Root Password

Create a Development User

Create a Database

Troubleshooting

Build Fails with Missing Dependencies

Server Won’t Start

Extension Installation Fails

Next Steps