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.16 or higher - Build system generator
C++ Compiler - GCC 8+, Clang 8+, or MSVC 2019+
Build tools - make, ninja, or equivalent
Development libraries - OpenSSL, ncurses, pkg-config, bison, and other MySQL dependencies

Install Dependencies

Ubuntu/Debian:

sudo apt install cmake libssl-dev libncurses5-dev pkg-config bison \
                 libtirpc-dev rpcsvc-proto build-essential 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 cmake openssl pkgconf bison libtirpc rpcsvc-proto

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). 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 only the server (recommended for development):

make -j10 mysqld

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 binary was built: Linux:

ls $HOME/build/villagesql/bin/mysqld

macOS:

ls ~/build/villagesql/bin/mysqld

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
~/build/villagesql/bin/mysqld --initialize --datadir=~/mysql-data/data --basedir=~/build/villagesql

Development (no password - optional):

mkdir -p ~/mysql-data/data
~/build/villagesql/bin/mysqld --initialize-insecure --datadir=~/mysql-data/data --basedir=~/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:

~/build/villagesql/bin/mysqld --gdb --datadir=~/mysql-data/data --basedir=~/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, use mysqld_safe with &.

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 include the git commit hash in the version string:

8.4.9-villagesql-0.0.4-dev

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 or .dll) 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.

Getting Started

Extensions

Using Extensions

Creating Extensions

Documentation Index

​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