A small C++ wrapper for the native C ODBC API. Please see the online documentation for user information, example usage, propaganda, and detailed source level documentation.

Philosophy

The native C API for working with ODBC is exorbitantly verbose, ridiculously complicated, and fantastically brittle. nanodbc addresses these frustrations! The goal for nanodbc is to make developers happy. Common tasks should be easy, requiring concise and simple code.

The latest C++ standards and best practices are enthusiastically incorporated to make the library as future-proof as possible. To accommodate users who can not use the latest and greatest, semantic versioning and release notes will clarify required C++ features and/or standards for particular versions.

Design Decisions

All complex objects in nanodbc follow the pimpl (Pointer to IMPLementation) idiom to provide separation between interface and implementation, value semantics, and a clean nanodbc.h header file that includes nothing but standard C++ headers.

nanodbc wraps ODBC code, providing a simpler way to do the same thing. We try to be as featureful as possible, but I can't guarantee you'll never have to write supporting ODBC code. Personally, I have never had to do so.

Major features beyond what's already supported by ODBC are not within the scope of nanodbc. This is where the nano part of nanodbc becomes relevant: This library is as minimal as possible. That means no dependencies beyond standard C++ and typical ODBC headers. No features unsupported by existing ODBC API calls.

Branches

Version	Description
release	Most recent published version that's deemed "stable". Review the changelog notes to see if this version is right for you.
latest	Latest published version; please use this version if CI tests are all passing. See all available versions.
master	Contains the latest development code, not yet ready for a published version.
v2.x.x	Targets C++14+. All future development will build upon this version.
v1.x.x	Supports C++03 and optionally C++11. There is no longer any support for this version.

Build Status

Branch	Travis CI	AppVeyor	Coverity
master
latest
release

Note: The Coverity status uses the coverity_scan branch. When master has had a significant amount of work pushed to it, merge those changes into coverity_scan as well to keep the status up to date.

Building

nanodbc is intentionally small enough that you can drag and drop the header and implementation files into your project and run with it. For those that want it, I have also provided CMake files which build a library object, or build and run the included tests. The CMake files will also support out of source builds.

Tests use the Catch test framework, and CMake will automatically fetch the latest version of Catch for you at build time. To build the tests you will also need to have either unixODBC or iODBC installed and discoverable by CMake. This is easy on OS X where you can use Homebrew to install unixODBC with brew install unixodbc, or use the system provided iODBC if you have OS X 10.9 or earlier.

The tests attempt to connect to a SQLite database, so you will have to have that and a SQLite ODBC driver installed. At the time of this writing, there happens to be a nice SQLite ODBC driver available from Christian Werner's website, also available via Homebrew as sqliteobdc! The tests expect to find a data source named sqlite on *nix systems and SQLite3 ODBC Driver on Windows systems. For example, your odbcinst.ini file on OS X must have a section like the following.

[sqlite]
Description             = SQLite3 ODBC Driver
Setup                   = /usr/lib/libsqlite3odbc-0.93.dylib
Driver                  = /usr/lib/libsqlite3odbc-0.93.dylib
Threading               = 2

Example Build Process

It's most convenient to create a build directory for an out of source build, but this isn't required. After you've used cmake to generate your Makefiles, make nanodbc will build your shared object. make check will build and run the tests. You can also install nanodbc to your system using make install.

If the tests fail, please don't hesitate to report it by creating an issue with your detailed test log (prepend your make command with env CTEST_OUTPUT_ON_FAILURE=1 to enable verbose output please).

cd path/to/nanodbc/repository
mkdir build
cd build
cmake [Build Options] ..
make # creates shared library
make nanodbc # creates shared library
make tests # builds the tests
make test # runs the tests
make check # builds and then runs tests
make examples # builds all the example programs
make install # installs nanodbc.h and shared library

Build Options

The following build options are available via CMake command-line option -D. If you are not using CMake to build nanodbc, you will need to set the corresponding -D compile define flags yourself. You will need to configure your build to use boost if you want to use the NANODBC_USE_BOOST_CONVERT option.

CMake Option	Possible Values	Default	Details
NANODBC_DISABLE_ASYNC	OFF or ON	OFF	Disables all async features. Can resolve build issues in older ODBC versions.
NANODBC_ENABLE_LIBCXX	OFF or ON	ON	Enables usage of libc++ if found on the system.
NANODBC_EXAMPLES	OFF or ON	ON	Enables building of examples.
NANODBC_HANDLE_NODATA_BUG	OFF or ON	OFF	Provided to resolve issue #33, details in this commit.
NANODBC_INSTALL	OFF or ON	ON	Enables install target.
NANODBC_ODBC_VERSION	SQL_OV_ODBC3[...]	See Details	[Optional] Sets the ODBC version macro for nanodbc to use. Default is SQL_OV_ODBC3_80 if available, otherwise SQL_OV_ODBC3.
NANODBC_STATIC	OFF or ON	OFF	Enables building a static library, otherwise the build process produces a shared library.
NANODBC_TEST	OFF or ON	ON	Enables tests target (alias check).
NANODBC_USE_BOOST_CONVERT	OFF or ON	OFF	Provided as workaround to issue #44.
NANODBC_USE_UNICODE	OFF or ON	OFF	Enables full unicode support. nanodbc::string becomes std::u16string or std::u32string.

Note About iODBC

Under Windows sizeof(wchar_t) == sizeof(SQLWCHAR) == 2, yet on Unix systems sizeof(wchar_t) == 4. On unixODBC, sizeof(SQLWCHAR) == 2 while on iODBC, sizeof(SQLWCHAR) == sizeof(wchar_t) == 4. This leads to incompatible ABIs between applications and drivers. If building against iODBC and the build option NANODBC_USE_UNICODE is ON, then nanodbc::string_type will be std::u32string. In ALL other cases it will be std::u16string.

Continuous integration tests run on Travis-CI. The build platform does not make available a Unicode-enabled iODBC driver. As such there is no guarantee that tests will pass in entirety on a system using iODBC. My recommendation is to use unixODBC. If you must use iODBC, consider disabling unicode mode to avoid wchar_t issues.

---

Contributing

Code Style

clang-format handles all C++ code formatting for nanodbc. This utility is brew-installable on OS X (brew install clang-format) and is available on all major platforms. See our .clang-format configuration file for details on the style. The script scripts/style.sh formats all code in the repository automatically. To run clang-format on a single file use the following.

$ clang-format -i /path/to/file

Please auto-format all code submitted in Pull Requests.

Source Level Documentation

Source level documentation provided via GitHub's gh-pages is available at nanodbc.lexicalunit.com. To re-build and update it, preform the following steps from the root directory of the repository:

1. git clone -b gh-pages [email protected]:lexicalunit/nanodbc.git doc Necessary the first time, not subsequently.
2. cd doc
3. make Generates updated documentation locally.
4. make commit Adds and commits any updated documentation.
5. git push origin gh-pages Deploys the changes to github.

Building documentation and gh-pages requires the use of Doxygen and jekyll. See the Makefile on the gh-pages branch for more details.

Quick Setup for Testing or Development Environments

To get up and running with nanodbc as fast as possible consider using the provided Dockerfile or Vagrantfile. For example, to spin up a docker container suitable for testing and development of nanodbc:

$ cd /path/to/nanodbc
$ docker build -t nanodbc .
$ docker run -v "$(pwd)":"/opt/$(basename $(pwd))" -it nanodbc /bin/bash
root@hash:/# mkdir -p /opt/nanodbc/build && cd /opt/nanodbc/build
root@hash:/opt/nanodbc/build# cmake ..
root@hash:/opt/nanodbc/build# make nanodbc

Or, to build and ssh into a vagrant VM (using VirtualBox for example) use:

$ cd /path/to/nanodbc
$ vagrant up
$ vagrant ssh
vagrant@vagrant-ubuntu-precise-64:~$ git clone https://github.com/lexicalunit/nanodbc.git
vagrant@vagrant-ubuntu-precise-64:~$ mkdir -p nanodbc/build && cd nanodbc/build
vagrant@vagrant-ubuntu-precise-64:~$ CXX=g++-5 cmake ..
vagrant@vagrant-ubuntu-precise-64:~$ make nanodbc

Tests

One of important objectives is to maintain nanodbc covered with tests. Thus, new contributions, especially new features, submitted via Pull requests should be accompanied by corresponding tests.

Short procedure of adding new tests to nanodbc is outlined below.

The tests structure:

• tests/base_test_fixture.h is where a set of common test cases is maintained.
• tests/<database>_test.cpp is a source code for an independent test program that includes both, common and database-specific test cases.

In order to add new test case:

1. In tests/base_test_fixture.h file, add a new test case method to base_test_fixture class (e.g. void my_feature_test()).
2. In each tests/<database>_test.cpp file, copy and paste the TEST_CASE_METHOD boilerplate, updating name, tags, etc.

If a feature requires a database-specific test case for each database, then skip the tests/base_test_fixture.h step and implement dedicated test case directly in tests/<database>_test.cpp file.

Publish and Release Process

Once your local master branch is ready for publishing (i.e. semantic versioning), use the scripts/publish.sh script. This script bumps the major, minor, or patch version, then updates the repository's VERSION file, adds a "Preparing" commit, and creates git tags appropriately. For example to make a minor update you would run ./scripts/publish.sh minor.

Important: Always update CHANGELOG.md with information about new changes, bug fixes, and features when making a new release. Use the ./scripts/changes.sh script to aid in your composition of this document. The publish script itself will attempt to verify that the changelog file has been properly updated.

To do this manually instead, use the following steps — for example a minor update from 2.9.x to 2.10.0:

1. echo "2.10.0" > VERSION
2. git add VERSION
3. git commit -m "Preparing 2.10.0 release."
4. git tag -f "v2.10.0"
5. git push -f origin "v2.10.0"
6. git push -f origin master:latest

Release Process

Release nanodbc with the scripts/release.sh script. All this script does is push out the master branch to the release branch, indicating that a new "stable" published version of nanodbc exists. To do so manually, execute git push -f origin master:release. Caution: Do this for versions deemed "stable" based on suitable criteria.

Future work

Good to Have / Want Someday

• Refactor tests to follow BDD pattern.
• Update codebase to use more C++14 idioms and patterns.
• Write more tests with the goal to have much higher code coverage.
• More tests for a large variety of drivers. Include performance tests.
• Clean up bind_* family of functions, reduce any duplication.
• Improve documentation: The main website and API docs should be more responsive.
• Provide more examples in documentation, more details, and point out any gotchas.
• Versioned generated source level API documentation for release and latest. For each major and minor published versions too?
• Add "HOWTO Build" documentation for Windows, OS X, and Linux.