Install

nanodbc is distributed in form of source code package.

nanodbc is intentionally small enough that you can drag and drop the header and implementation files into your project and run with it.

Binary packages, if available, are provided and supported by third-parties, developers and maintainers of numerous package managers.

Source

You can build nanodbc library, build and run tests using CMake.

git clone https://github.com/nanodbc/nanodbc.git
cd nanodbc
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failure -E vertica_tests

The tests connect to real databases, so see Test below for what each of them needs.

C++ Standard

Each release line sets a minimum C++ standard. Pick the nanodbc version whose minimum your project can meet; anything newer than the minimum also works.

nanodbc version

Minimum C++ standard

< 2.12

C++11

>= 2.12

C++14

CI builds every supported compiler against C++14, C++17 and C++20, so all three are exercised on each change.

Requirements

  • C++ compiler with support for the standard the nanodbc version targets, see above

  • CMake 3.21.0 or later

  • ODBC SDK (unixODBC, iODBC, Windows SDK)

Optionally, you will also need:

  • ODBC drivers, depending on DBMS you want to target (eg. running tests).

  • Boost.Locale, alternative for Unicode conversion routines.

  • libc++, alternative C++ standard library implementation.

Build

Although detailed build process depends on CMake generator used, number of common targets are always available.

For example, CMake configuration using Makefiles generator:

cd nanodbc
mkdir build
cd build
cmake -G "Unix Makefiles" [options] ..
make          # builds the library, the tests and the examples
make nanodbc  # builds the library alone
make tests    # builds the tests
make test     # runs the tests
make examples # builds all the example programs
make install  # installs nanodbc.h and the library

The library is static unless BUILD_SHARED_LIBS is ON. Tests and examples are built by default only when nanodbc is the top level project.

CMake OPTION and cache entry variables are available to specify with -D switch to enable or disable nanodbc built-in features.

All boolean options follow the CMake OPTION default value convention: if no initial value is provided, OFF is used.

List of CMake options specific to nanodbc, in alphabetical order:

NANODBC_BUILD_EXAMPLESboolean

Build examples. On by default when nanodbc is the top level project.

NANODBC_BUILD_TESTSboolean

Build tests. On by default when nanodbc is the top level project.

NANODBC_DISABLE_ASYNCboolean

Disable all async features. The ODBC 3.8 async API is switched off automatically when the ODBC headers found at configure time do not declare it, so this is only needed to turn it off against headers that do.

NANODBC_DISABLE_MSSQL_TVPboolean

Do not use MSSQL table-valued parameters.

NANODBC_ENABLE_BOOSTboolean

Use Boost for Unicode string conversions (requires Boost.Locale and NANODBC_ENABLE_UNICODE=ON). Workaround to issue #24.

NANODBC_ENABLE_COVERAGEboolean

Enable code coverage analysis. Requires tests to be built.

NANODBC_ENABLE_UNICODEboolean

Enable Unicode support. nanodbc::string becomes std::u16string or std::u32string.

NANODBC_ENABLE_WORKAROUND_NODATAboolean

Enable SQL_NO_DATA workaround #43.

NANODBC_FORCE_LIBCXXboolean

Force the use of libc++. On by default if the compiler supports it.

NANODBC_FORCE_WARNINGS_AS_ERRORboolean

Treat compiler warnings as errors when building nanodbc.

NANODBC_GENERATE_INSTALLboolean

Generate the install target. On by default when nanodbc is the top level project.

NANODBC_ODBC_VERSIONstring

Forces ODBC version to use. Default is SQL_OV_ODBC3_80 if available, otherwise SQL_OV_ODBC3.

NANODBC_OVERALLOCATE_CHARboolean

Overallocate auto-bound n/var/char buffers to accommodate retrieving Unicode data in VARCHAR columns (requires NANODBC_ENABLE_UNICODE=ON) #219.

Standard CMake options are also available, for example:

BUILD_SHARED_LIBSboolean

Build nanodbc as a shared library. Default value is OFF.

If you are not using CMake to build nanodbc, you will need to set the options, using the corresponding names, as preprocessor defines yourself.

Test

Tests use the Catch2 test framework, vendored under test/catch as its amalgamated distribution, so the tests build without network access.

Once nanodbc build is ready, use ctest to run tests in CMake generator-agnostic way:

ctest --test-dir build --output-on-failure -E vertica_tests

Alternatively, build the test target (eg. make test).

There is one test program per database, so a single suite can be run on its own:

ctest --test-dir build --output-on-failure -R sqlite_tests

The utility tests need no database at all, and the SQLite tests need only a SQLite ODBC driver, registered as SQLite3 on *nix systems and as SQLite3 ODBC Driver on Windows, since the tests name the driver rather than a data source. Those two are the quickest way to check a build. The remaining suites need a running server, and the Vertica tests additionally need Vertica’s own ODBC driver, which is why a full run excludes them.

Each suite reads its own NANODBC_TEST_CONNSTR_<DB> environment variable for the connection string, falling back to NANODBC_TEST_CONNSTR. Rather than installing the servers, use the containers the repository provides, which preset those variables; see Develop.

Binaries

This section aim to list all known binary packages of nanodbc.

If you maintain binary package of nanodbc and you’d like to list it here, please submit new entry via pull request or open an issue

Windows