Server Development Guide

This guide covers debugging, running the server test suite, and contributing to VillageSQL. It assumes a working source build — see Build from Source if you haven’t done that yet.

Debugging

VillageSQL server debugging uses GDB on Linux and lldb on macOS. GDB on macOS requires code signing, which is painful to set up — lldb is the standard macOS debugger and works out of the box.

Linux (GDB)

Run VillageSQL under GDB:

gdb --args "$HOME/build/villagesql/bin/mysqld" --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/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:

# 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

macOS (lldb)

Run VillageSQL under lldb:

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

Inside lldb:

(lldb) run                         # Start the server
(lldb) breakpoint set -n function_name  # Set breakpoints
(lldb) continue                    # Resume execution
(lldb) bt                          # Show backtrace on crash

Common lldb commands:

# Break on specific SQL command execution
(lldb) breakpoint set -n mysql_execute_command

# Break on extension loading
(lldb) breakpoint set -n Sql_cmd_install_extension::execute

# Print variable values
(lldb) print variable_name

# Step through code
(lldb) step      # Step into functions
(lldb) 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 --nounit-tests --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.)
--nounit-tests skips the unit tests MTR would otherwise run alongside the suite. Those are upstream MySQL unit tests and include known failures; run the VillageSQL ones on their own with the Unit Tests commands above.

Running Individual Tests

Run a specific test by name:

./mysql-test-run.pl villagesql/startup.recovery_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/startup.recovery_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.

Test Portability

When test output includes paths from the test runner’s temp directory, add this directive inside your .test file so recorded results don’t contain absolute paths that break on other machines:

--replace_result $MYSQLTEST_VARDIR MYSQLTEST_VARDIR

Debugging Test Failures

VillageSQL-specific log messages (emitted via LogVSQL()) are suppressed by default. To surface them in the error log during a test run:

./mysql-test-run.pl --mysqld=--log-error-verbosity=3 villagesql/startup.recovery_complex_index

The full error log is at mysql-test/var/log/mysqld.1.err for a single-worker run. Under --parallel, each worker writes to mysql-test/var/<N>/log/mysqld.1.err instead. For writing extension regression tests, 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

Contributing

If you’re contributing to VillageSQL, please see the contributing guidelines for coding standards and development workflows.

Getting Started