Repository files navigation

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

Branch	Linux/OSX	Windows	Coverity
master
latest
release

Note: The Coverity status uses thecoverity_scan branch. Whenmasterhas had a significant amount of work pushed to it, merge those changes intocoverity_scan as well to keep the status up to date.

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

Thelatest C++ standards andbest practices areenthusiastically incorporated to make the library as future-proof as possible. To accommodateusers who can not use the latest and greatest,semantic versioning andrelease notes will clarify required C++ features and/or standards for particular versions.

All complex objects in nanodbc follow thepimpl (Pointer to IMPLementation) idiom toprovide separation between interface and implementation, value semantics, and a cleannanodbc.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 featurefulas possible, but I can't guarantee you'll never have to write supporting ODBC code. Personally, Ihave never had to do so.

Major features beyond what's already supported by ODBC are not within the scope of nanodbc. This iswhere thenano part of nanodbc becomes relevant: This library isas minimal as possible. Thatmeans no dependencies beyond standard C++ and typical ODBC headers. No features unsupported byexisting ODBC API calls.

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

Tests use theCatch test framework, and CMake will automatically fetch the latest versionof Catch for you at build time. To build the tests you will also need to have either unixODBC oriODBC installed and discoverable by CMake. This is easy on OS X where you can useHomebrewto install unixODBC withbrew install unixodbc, or use the system provided iODBC if you have OS X10.9 or earlier.

The tests attempt to connect to aSQLite database, so you will have to have that and aSQLite ODBC driver installed. At the time of this writing, there happens to be a niceSQLite ODBC driver available from Christian Werner's website, also available viaHomebrew assqliteobdc! The tests expect to find a data source namedsqlite on *nix systems andSQLite3 ODBC Driver on Windows systems. For example, yourodbcinst.ini file on OS X must have asection like the following.

[sqlite]Description             = SQLite3 ODBC DriverSetup                   = /usr/lib/libsqlite3odbc-0.93.dylibDriver                  = /usr/lib/libsqlite3odbc-0.93.dylibThreading               = 2

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

If the tests fail, please don't hesitate toreport it by creating an issuewith your detailed test log (prepend yourmake command withenv CTEST_OUTPUT_ON_FAILURE=1 toenable verbose output please).

cd path/to/nanodbc/repositorymkdir buildcd buildcmake [Build Options] ..make# creates shared librarymake nanodbc# creates shared librarymake tests# builds the testsmaketest# runs the testsmake check# builds and then runs testsmake examples# builds all the example programsmake install# installs nanodbc.h and shared library

The following build options are available viaCMake command-line option-D. If youare not using CMake to build nanodbc, you will need to set the corresponding-D compile defineflags yourself.

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

Use the standard CMake option-DBUILD_SHARED_LIBS=ON to build nanodbc as shared library.

If you need to use theNANODBC_ENABLE_BOOST=ON option, you will have to configure your environment to useBoost.

Under Windowssizeof(wchar_t) == sizeof(SQLWCHAR) == 2, yet on Unix systemssizeof(wchar_t) == 4. On unixODBC,sizeof(SQLWCHAR) == 2 while on iODBC,sizeof(SQLWCHAR) == sizeof(wchar_t) == 4. This leads to incompatible ABIs between applicationsand drivers. If building against iODBC and the build optionNANODBC_USE_UNICODE isON, thennanodbc::string will bestd::u32string. InALL other cases it will bestd::u16string.

Continuous integration tests run onTravis-CI. The build platform does not make availablea Unicode-enabled iODBC driver. As such there is no guarantee that tests will pass in entirety on asystem using iODBC. My recommendation is to use unixODBC. If you must use iODBC, considerdisabling unicode mode to avoidwchar_t issues.

clang-format handles all C++ code formatting for nanodbc. This utility isbrew-installable on OS X (brew install clang-format) and is available on all majorplatforms. See our.clang-format configuration file for details on the style. The scriptutility/style.sh formats all code in the repository automatically. To runclang-format on asingle file use the following.

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

Please auto-format all code submitted in Pull Requests.

Source level documentation provided viaGitHub's gh-pages is available atnanodbc.lexicalunit.com. To re-build and update it, preform the following steps from theroot directory of the repository:

1. git clone -b gh-pages git@github.com: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 ofDoxygen andjekyll. See theMakefile on thegh-pages branch for more details.

To get up and running with nanodbc as fast as possible consider using the providedDockerfile orVagrantfile. For example, to spin up adockercontainer 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/bashroot@hash:/# mkdir -p /opt/nanodbc/build && cd /opt/nanodbc/buildroot@hash:/opt/nanodbc/build# cmake ..root@hash:/opt/nanodbc/build# make nanodbc

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

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

One of important objectives is to maintain nanodbc covered with tests. New contributionssubmitted via Pull Requests must include corresponding tests. This is important to ensurethe quality of new features.

The good news is that adding tests is easy!

The tests structure:

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

To add new test case:

1. Intests/base_test_fixture.h file, add a new test case method tobase_test_fixtureclass (e.g.void my_feature_test()).
2. In eachtests/<database>_test.cpp file, copy and paste theTEST_CASE_METHOD boilerplate,updating name, tags, etc.

If a feature requires a database-specific test case for each database, then skip thetests/base_test_fixture.h step and write a dedicated test case directly intests/<database>_test.cpp file.

Once your localmaster branch is ready for publishing(i.e.semantic versioning), use theutility/publish.sh script. This scriptbumps the major, minor, or patch version, then updates the repository'sVERSION file, adds a"Preparing" commit, and creates git tags appropriately. For example to make a minor update youwould run./utility/publish.sh minor.

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

To do this manually instead, use the following steps — for example a minor update from2.9.x to2.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 nanodbc with theutility/release.sh script. All this script does is push out themasterbranch to therelease branch, indicating that a new "stable" published version of nanodbc exists.To do so manually, executegit push -f origin master:release.Caution: Do this for versionsdeemed "stable" based on suitable criteria.

• 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 upbind_* 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 forrelease andlatest.For each major and minor published versions too?
• Add "HOWTO Build" documentation for Windows, OS X, and Linux.

MIT ©lexicalunit andcontributors.