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

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"

On macOS, add -DWITH_SSL=system so CMake finds the Homebrew OpenSSL:

cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX="$HOME/mysql" -DWITH_SSL=system

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 - Enables debug symbols (recommended for development)
-DCMAKE_INSTALL_PREFIX="$HOME/mysql" - Sets installation directory
-DWITH_SSL=system - Uses system OpenSSL library (required on macOS)

Additional CMake Options

Production build without debug symbols:

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"

Developer mode with stricter warnings:

cmake "$HOME/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 4: 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 7; make -j10 mysqld alone builds only the server, and Step 7 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:

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

9.7.2-villagesql-0.0.6-dev-5a64e122090

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

For GDB debugging, running tests, 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

​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

Troubleshooting

Build Fails with Missing Dependencies

Server Won’t Start

Extension Installation Fails

Next Steps