Develop

Notes about development process of nanodbc.

Contributing

nanodbc is an Open Source Software and very accepting of bug fixes and new features.

Please consider contributing any changes you make via pull requests or reporting any issues you might have.

Cheers!

Guidelines

Style

clang-format handles all C++ code formatting for nanodbc.

See our .clang-format configuration file for the style, and for the major version of clang-format it is written against, which is named in the comment at the top of the file. A different major version will reformat code that is already correct, so match the one named there. The development container carries it, and pip install clang-format==<major>.* supplies it on a host.

To run clang-format against the whole nanodbc codebase:

clang-format -i $(git ls-files '*.h' '*.cpp')

.clang-format-ignore lists what to leave alone, so vendored code is skipped even when it is named on the command line.

To run clang-format on a single file use the following.

clang-format -i /path/to/file

Important

Please auto-format all code submitted in Pull Requests.

.editorconfig file is provided to automatically tell popular code editors about the preferred basic style settings like indentation, whitespace, end of line and such for distinguished types of plain text files.

Environments

To get up and running with nanodbc as fast as possible, use the containers the repository provides. Every database nanodbc is tested against runs as a container, so none of them has to be installed on your machine. README.md covers the whole setup under Quick Setup for Testing or Development Environments.

Docker

docker compose brings up the database servers and a development container that carries the compiler toolchain, CMake, and the ODBC driver managers, drivers and client tools for all of them:

$ cd /path/to/nanodbc
$ docker compose up -d
$ docker compose run --rm nanodbc /bin/bash
root@hash:/opt/nanodbc# cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
root@hash:/opt/nanodbc# cmake --build build --parallel
root@hash:/opt/nanodbc# ctest --test-dir build --output-on-failure -E vertica_tests

The development container presets the NANODBC_TEST_CONNSTR_* variables the test programs read, so a build and a test run inside it need no arguments.

To build the development image on its own, without the database services, pass the file to docker build with -f, since it is not named Dockerfile:

$ docker build -f Dockerfile.dev -t nanodbc .
$ docker run -v "$(pwd)":/opt/nanodbc -it nanodbc /bin/bash

Test

Keeping nanodbc covered with tests is one of the important objectives, so new contributions submitted via pull requests must include corresponding tests.

The tests are built with the tests target and run with ctest. They are laid out as:

• test/base_test_fixture.h provides the helpers the fixtures share, such as connecting, creating and dropping tables, and reporting which backend is under test.

• test/test_case_fixture.h holds the test cases that run against every backend.

• test/<database>_test.cpp is the source for an independent test program that includes both the common and the database-specific test cases. test/main.cpp supplies the main() each of them links against, and test/CMakeLists.txt lists the databases a program is built for.

To add a new test case, add a method to test_case_fixture in test/test_case_fixture.h, then copy the TEST_CASE_METHOD boilerplate into each test/<database>_test.cpp, updating name and tags. A test that only makes sense for one database goes straight into that database’s source file instead.

The SQLite and utility tests need no server, so they are the quickest way to check a change. The Vertica tests need Vertica’s own ODBC driver, which the development image does not carry, so a full run excludes them:

$ ctest --test-dir build --output-on-failure -E vertica_tests
$ ctest --test-dir build --output-on-failure -R sqlite_tests

See README.md for the rest, under Tests.

Release

utility/publish.sh bumps the version in VERSION.txt, renames the changelog’s ## Unreleased heading to the new version, commits both and pushes the matching vX.Y.Z tag; pushing the tag is what drives the release and the documentation deployment. Changes are recorded under ## Unreleased as they land, and the script refuses to run without it, since that section becomes the release notes.

See README.md for the whole process, under Publish and Release Process.

Documentation

See doc/README.md.