> ## 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.

# Server Development Guide

> Debugging, testing, and contributing to the VillageSQL server codebase.

This guide covers debugging, running the server test suite, and contributing to VillageSQL. It assumes a working source build — see [Build from Source](https://villagesql.com/docs/en/8.4/dev/source.md) 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:

```bash theme={null}
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:

```bash theme={null}
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):

```bash theme={null}
make -j10 villagesql-unit-tests && ctest -L villagesql
```

Or run all unit tests:

```bash theme={null}
ctest --output-on-failure
```

### Regression Tests

Change to the mysql-test directory:

```bash theme={null}
cd mysql-test
```

**Run the full MySQL test suite (slow):**

```bash theme={null}
./mysql-test-run.pl --parallel=auto
```

**Run one VillageSQL sub-suite:**

```bash theme={null}
./mysql-test-run.pl --suite=villagesql/insert
```

**Run VillageSQL tests including all sub-suites:**

```bash theme={null}
./mysql-test-run.pl --do-suite=villagesql --nounit-tests --parallel=auto
```

Run the tests as an ordinary user, not root: the test runner skips some tests and one of them fails.

> [!NOTE]
>
> **--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](#unit-tests) commands above.

### Running Individual Tests

Run a specific test by name:

```bash theme={null}
./mysql-test-run.pl villagesql/startup.recovery_complex_index
```

Run a test from a sub-suite:

```bash theme={null}
./mysql-test-run.pl --suite=villagesql/insert
```

### Updating Test Results

If you've changed functionality and need to update expected test output:

```bash theme={null}
./mysql-test-run.pl --record villagesql/startup.recovery_complex_index
```

> [!WARNING]
>
> **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:

```sql theme={null}
--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:

```bash theme={null}
./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](https://villagesql.com/docs/en/sdk/cpp/testing.md).

## Installing Binaries

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

```bash theme={null}
cmake --build "$HOME/build/villagesql" --target install
```

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

```bash theme={null}
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](https://github.com/villagesql/villagesql-server/blob/main/CONTRIBUTING.md) for coding standards and development workflows.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.