Skip to main content

Documentation Index

Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers GDB debugging, running the server test suite, and contributing to VillageSQL. Start with Build from Source to get a working build before using this guide.

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

​
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.complex_index
The full error log is at mysql-test/var/log/mysqld.1.err. 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.