Skip to main content
This guide covers the essentials of developing for VillageSQL, with a focus on running the comprehensive test suite to ensure code quality and feature correctness.

​
Setting Up Your Environment

To develop VillageSQL, you first need to build the server from source. Follow the Clone and Build from Source guide to clone the repository and compile the binaries. Once you have a build directory (e.g., build/), you are ready to run the regression tests.

​
Running Regression Tests

VillageSQL uses the MySQL Test Framework (mysql-test-run.pl or mtr) for regression testing. The test suite is located in the mysql-test directory.

​
Running the Full Suite

To run the complete set of VillageSQL-specific tests, including all sub-suites (Insert, Select, Stored Procedures, etc.), use the --do-suite option: 
cd build
./mysql-test/mysql-test-run.pl --do-suite=villagesql --parallel=auto
Using --suite=villagesql (without do-) typically only runs the top-level tests in the villagesql directory and skips the sub-directories. Always use --do-suite=villagesql for full coverage.

​
Running Specific Sub-Suites

VillageSQL tests are organized into sub-suites based on functionality (e.g., insert, select, update). You can run a specific sub-suite to focus on a particular area: 
# Run only INSERT tests
./mysql-test/mysql-test-run.pl --suite=villagesql/insert

# Run only SELECT tests
./mysql-test/mysql-test-run.pl --suite=villagesql/select

# Run only Stored Procedure tests
./mysql-test/mysql-test-run.pl --suite=villagesql/stored_procedure
Available sub-suites include:
  • villagesql/insert
  • villagesql/select
  • villagesql/update
  • villagesql/delete
  • villagesql/replace
  • villagesql/table_dml
  • villagesql/values
  • villagesql/handler
  • villagesql/load_data
  • villagesql/load_xml
  • villagesql/stored_procedure
  • villagesql/prepared_statement
  • villagesql/trigger
  • villagesql/view
  • villagesql/expression

​
Running Individual Tests

To run a single test case, specify the suite path and test name: 
# Run a specific insert test
./mysql-test/mysql-test-run.pl villagesql/insert.insert_values_complex

​
Creating New Tests

When adding new features or fixing bugs, you should add corresponding regression tests.

​
Test Location

Tests are located in mysql-test/suite/villagesql/. Choose the appropriate sub-directory based on the SQL statement or feature being tested.
  • Test files end with .test and go in the t/ directory.
  • Expected result files end with .result and go in the r/ directory.

​
Test File Conventions

VillageSQL tests often involve the custom COMPLEX type. We follow a specific pattern to ensure tests are skipped gracefully if the feature is not yet fully implemented: 
# Description of the test
# Grammar: (Optional) SQL syntax reference

--source include/villagesql/not_implemented_complex_type.inc

--source include/villagesql/install_complex_extension.inc

# ... Your Test Code Here ...
CREATE TABLE t1 (val COMPLEX);
INSERT INTO t1 VALUES ('(1.0,2.0)');
SELECT * FROM t1;
DROP TABLE t1;

--source include/villagesql/uninstall_complex_extension.inc

​
Steps to Add a Test

  1. Create the .test file in the appropriate t/ directory (e.g., mysql-test/suite/villagesql/select/t/my_new_test.test).
  2. Create an empty .result file in the corresponding r/ directory (e.g., mysql-test/suite/villagesql/select/r/my_new_test.result).
  3. Run the test with --record to generate the expected output: 
    ./mysql-test/mysql-test-run.pl --suite=villagesql/select --record my_new_test
  4. Verify the output in the generated .result file to ensure it matches your expectations.

​
Debugging Tests

If a test fails, mtr provides detailed logs.
  • Test output: Check build/mysql-test/var/log/my_new_test.log.
  • Server error log: Check build/mysql-test/var/log/mysqld.1.err.
  • Diff: mtr usually outputs a diff between the actual output and the expected .result file.
To run a test with extra debug information: 
./mysql-test/mysql-test-run.pl --verbose villagesql/select.my_new_test