> ## 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](/mysql-8.4/0.0.5/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:

```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 VillageSQL-specific tests only:**

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

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

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

<Note>
  **--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.)
</Note>

### Running Individual Tests

Run a specific test by name:

```bash theme={null}
./mysql-test-run.pl villagesql.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.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.
</Warning>

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

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

```bash theme={null}
./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](/mysql-8.4/0.0.5/development).

## Installing Binaries

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

```bash theme={null}
cmake --build build --target install
```

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

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