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 one VillageSQL sub-suite:

./mysql-test-run.pl --suite=villagesql/insert

Run VillageSQL tests including all sub-suites:

./mysql-test-run.pl --do-suite=villagesql --nounit-tests --parallel=auto

—suite vs —do-suite:

--suite=villagesql/insert runs one sub-suite
--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 before each statement that prints one, 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 written to the error log at --log-error-verbosity=3, which MTR sets by default. To set the level for one 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 C++ Testing.

Installing Binaries

To install VillageSQL system-wide (requires appropriate permissions):

cmake --build "$HOME/build/villagesql" --target install

This installs binaries to /usr/local/mysql/ by default. You can customize the installation prefix:

cmake -S "$HOME/villagesql-server" -B "$HOME/build/villagesql" -DCMAKE_INSTALL_PREFIX=/opt/villagesql
cmake --build "$HOME/build/villagesql" --target install

Contributing

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

Getting Started