Skip to main content

​
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
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
GitHub Authentication: For easier repository access, install GitHub CLI and authenticate once:
# Install gh CLI (macOS)
brew install gh

# Or on Ubuntu/Debian
sudo apt install gh

# Authenticate
gh auth login
This avoids needing personal access tokens for private repositories.

​
Step 1: Clone the Repository

Clone the VillageSQL Server repository from GitHub: 
git clone 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: 
# Create build directory (outside the repo)
mkdir -p ~/build
cd ~/build
Linux: 
cmake ~/villagesql-server -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX=$HOME/mysql
macOS: 
cmake ~/villagesql-server -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX=$HOME/mysql -DWITH_SSL=system
Replace ~/villagesql-server with the actual path to your cloned repository.

​
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 ~/villagesql-server -DCMAKE_INSTALL_PREFIX=/usr/local/mysql
With custom compilation comment: 
cmake ~/villagesql-server -DWITH_DEBUG=1 \
      -DCMAKE_INSTALL_PREFIX=$HOME/mysql \
      -DCOMPILATION_COMMENT="VillageSQL Version of MySQL"
Developer mode with stricter warnings: 
cmake ~/villagesql-server -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1
If you need to reconfigure, clear the CMake cache first:
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, 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: Production (with generated password - recommended): 
mkdir -p ~/mysql-data
~/build/bin/mysqld --initialize --datadir=$HOME/mysql-data/data --basedir=$HOME/build
This will generate a temporary password and print it to the console: 
A temporary password is generated for root@localhost: <password>
Development (no password - optional): 
mkdir -p ~/mysql-data
~/build/bin/mysqld --initialize-insecure --datadir=$HOME/mysql-data/data --basedir=$HOME/build
Use --initialize (with password) for production-like setups. Use --initialize-insecure (no password) only for local development and testing. Note: Skip password setup if using --initialize-insecure.

​
Step 5: Start the Server

Start the VillageSQL server: 
~/build/bin/mysqld --gdb --datadir=$HOME/mysql-data/data --basedir=$HOME/build
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: If using —initialize-insecure (no password): 
~/build/bin/mysql -u root
If using —initialize (with generated password): 
~/build/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>

​
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'@'%';

-- Apply changes
FLUSH PRIVILEGES;
Exit and reconnect as your new user: 
# Ctrl-D to exit
~/build/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: 
gdb --args ~/build/bin/mysqld --gdb --datadir=$HOME/mysql-data/data --basedir=$HOME/build
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: 
cd mysql-test
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 build/data/
  • Check if another MySQL/VillageSQL instance is using port 3306
  • Review error logs in build/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 SONAME 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.