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 repositoryCMake 3.16 or higher - Build system generatorC++ Compiler - GCC 8+, Clang 8+, or MSVC 2019+Build tools - make, ninja, or equivalentDevelopment 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:
git clone --depth 1 https://github.com/villagesql/villagesql-server.git cd villagesql-server
The repository is several GB due to the MySQL codebase.
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: Step 3: Compile the Code Build VillageSQL using make with parallel compilation. From within the build directory:
Build only the server (recommended for development): Build everything: 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, binaries will be available in the build/bin/ and build/runtime_output_directory/ directories.
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>
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 enables Ctrl-C to quit gracefully. To run in 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:
Development builds include the git commit hash in the version string:
8.4.6-villagesql-0.0.3-dev-7df91cf796b
Release builds show the version without the git hash:
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
Debugging with GDB For development and troubleshooting, you can run VillageSQL under GDB:
Linux: gdb --args $HOME /build/villagesql/bin/mysqld --gdb --datadir= $HOME /mysql-data/data --basedir= $HOME /build/villagesql
macOS: gdb --args ~/build/villagesql/bin/mysqld --gdb --datadir= ~ /mysql-data/data --basedir= ~ /build/villagesql
Inside GDB: (gdb) run # Start the server (gdb) break function_name # Set breakpoints (gdb) continue # Resume execution (gdb) bt # Show backtrace on crash
Common GDB commands for MySQL debugging: # Break on specific SQL command execution (gdb) break mysql_execute_command # Break on extension loading (gdb) break Sql_cmd_install_extension::execute # Print variable values (gdb) print variable_name # Step through code (gdb) step # Step into functions (gdb) next # Step over functions
Running Tests VillageSQL includes both unit tests and regression tests to verify functionality.
Unit Tests Run VillageSQL-specific unit tests (from within your build directory):
make -j10 villagesql-unit-tests && ctest -L villagesql
Or run all unit tests:
ctest --output-on-failure
Regression Tests Change to the mysql-test directory:
Run the full MySQL test suite (slow): ./mysql-test-run.pl --parallel=auto
Run VillageSQL-specific tests only: ./mysql-test-run.pl --suite=villagesql
Run VillageSQL tests including all sub-suites: ./mysql-test-run.pl --do-suite=villagesql --parallel=auto
—suite vs —do-suite:
--suite=villagesql runs only top-level villagesql tests--do-suite=villagesql runs all tests including sub-suites (insert, select, stored_procedure, etc.) Running Individual Tests Run a specific test by name:
./mysql-test-run.pl villagesql.complex_index
Run a test from a sub-suite:
./mysql-test-run.pl --suite=villagesql/insert
Updating Test Results If you’ve changed functionality and need to update expected test output:
./mysql-test-run.pl --record villagesql.complex_index
Test Recording: Always review changes to .result files to ensure they reflect intended behavior, not bugs. The --record flag blindly overwrites expected output.
For more detailed information on writing your own tests, debugging failures, and test file syntax, see the Development Guide .
Installing Binaries To install VillageSQL system-wide (requires appropriate permissions):
cmake --build build --target install
This installs binaries to /usr/local/mysql/ by default. You can customize the installation prefix:
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/villagesql cmake --build build --target install
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.
Contributing If you’re building from source to contribute to VillageSQL, please see our contributing guidelines for coding standards and development workflows. 
