{"id":13495015,"url":"https://github.com/nanodbc/nanodbc","last_synced_at":"2025-04-08T01:35:51.866Z","repository":{"id":25913772,"uuid":"106881466","full_name":"nanodbc/nanodbc","owner":"nanodbc","description":"A small C++ wrapper for the native C ODBC API | Requires C++14 since v2.12","archived":false,"fork":false,"pushed_at":"2025-01-22T18:42:24.000Z","size":11510,"stargazers_count":350,"open_issues_count":62,"forks_count":86,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-04-01T00:34:08.126Z","etag":null,"topics":["cplusplus","cplusplus-14","cpp","database-access","database-access-library","mysql","odbc","odbc-api","postgresql","sqlite3","sqlserver","vertica"],"latest_commit_sha":null,"homepage":"http://nanodbc.io","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nanodbc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-13T23:11:57.000Z","updated_at":"2025-03-28T12:22:16.000Z","dependencies_parsed_at":"2024-01-31T09:03:28.743Z","dependency_job_id":"cb22fbdd-7b21-4021-9974-b4ca057246f8","html_url":"https://github.com/nanodbc/nanodbc","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanodbc%2Fnanodbc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanodbc%2Fnanodbc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanodbc%2Fnanodbc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanodbc%2Fnanodbc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nanodbc","download_url":"https://codeload.github.com/nanodbc/nanodbc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247761051,"owners_count":20991531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cplusplus","cplusplus-14","cpp","database-access","database-access-library","mysql","odbc","odbc-api","postgresql","sqlite3","sqlserver","vertica"],"created_at":"2024-07-31T19:01:30.380Z","updated_at":"2025-04-08T01:35:51.838Z","avatar_url":"https://github.com/nanodbc.png","language":"C++","funding_links":[],"categories":["Database","C++"],"sub_categories":[],"readme":"# nanodbc\n\n![nanodbc-banner][nanodbc-banner]\n\nA small C++ wrapper for the native C ODBC API. Please see the [online documentation][nanodbc] for\nuser information, example usage, propaganda, and detailed source level documentation.\n\n[![GitHub release](https://img.shields.io/github/tag/nanodbc/nanodbc.svg)](https://github.com/nanodbc/nanodbc/releases) [![GitHub commits](https://img.shields.io/github/commits-since/nanodbc/nanodbc/v2.14.0.svg?style=flat-square)](https://github.com/nanodbc/nanodbc/releases/tag/v2.14.0)\n[![License](https://img.shields.io/github/license/nanodbc/nanodbc.svg?style=flat-square)](https://github.com/nanodbc/nanodbc/blob/main/LICENSE) [![Gitter](https://img.shields.io/gitter/room/nanodbc/nanodbc.svg?style=flat-square)](https://gitter.im/nanodbc-help/Lobby)\n\n## Build Status\n\n| Branch | Linux/OSX | Windows | Coverage | Coverity |\n| :---   |:---       |:---     |:---      |:---      |\n|`main` | [![main](https://github.com/nanodbc/nanodbc/actions/workflows/ci-linux.yml/badge.svg?branch=main)](https://github.com/nanodbc/nanodbc/actions/workflows/ci-linux.yml) | [![main](https://github.com/nanodbc/nanodbc/actions/workflows/ci-windows.yml/badge.svg?branch=main)](https://github.com/nanodbc/nanodbc/actions/workflows/ci-windows.yml) | [![codecov](https://codecov.io/gh/nanodbc/nanodbc/branch/main/graph/badge.svg)](https://codecov.io/gh/nanodbc/nanodbc) | [![coverity_scan][coverity-badge]][coverity] |\n\n\u003e **Note:** The Coverity status uses the [coverity_scan][nanodbc-coverity] branch.\n\u003e When `main` has had a significant amount of work pushed to it,\n\u003e merge those changes into `coverity_scan` as well to keep the status up to date.\n\n## Philosophy\n\nThe native C API for working with ODBC is exorbitantly verbose, ridiculously complicated, and\nfantastically brittle. nanodbc addresses these frustrations! The goal for nanodbc is to make\ndevelopers happy. Common tasks should be easy, requiring concise and simple code.\n\nThe [latest C++ standards][cpp-std] and [best practices][cpp-core] are\n_enthusiastically_ incorporated to make the library as future-proof as possible. To accommodate\nusers who can not use the latest and greatest, [semantic versioning][semver] and\nrelease notes will clarify required C++ features and/or standards for particular versions.\n\n### Design Decisions\n\nAll complex objects in nanodbc follow the [pimpl (Pointer to IMPLementation)][pimpl] idiom to\nprovide separation between interface and implementation, value semantics, and a clean `nanodbc.h`\nheader file that includes nothing but standard C++ headers.\n\nnanodbc wraps ODBC code, providing a simpler way to do the same thing. We try to be as featureful\nas possible, but I can't guarantee you'll never have to write supporting ODBC code. Personally, I\nhave never had to do so.\n\nMajor features beyond what's already supported by ODBC are not within the scope of nanodbc. This is\nwhere the _nano_ part of nanodbc becomes relevant: This library is _as minimal as possible_. That\nmeans no dependencies beyond standard C++ and typical ODBC headers and libraries to link against.\nNo features unsupported by existing ODBC API calls.\n\n## Building\n\nnanodbc is intentionally small enough that you can drag and drop the header and implementation\nfiles into your project and run with it. For those that want it, I have also provided\n[CMake][cmake] files which build a library object, or build and run the included tests.\nThe CMake files will also support out of source builds.\n\nTests use the [Catch][catch] test framework, and CMake will automatically fetch the latest version\nof Catch for you at build time. To build the nanodbc and the tests you will also need to have\neither [unixODBC] or [iODBC] installed and discoverable by CMake.\nThis is easy on OS X where you can use [Homebrew][brew] to install unixODBC with `brew install unixodbc`,\nor use the system provided iODBC if you have OS X 10.9 or earlier.\n\nThe tests attempt to connect to a [SQLite][sqlite] database, so you will have to have that and a\nSQLite ODBC driver installed. At the time of this writing, there happens to be a nice\n[SQLite ODBC driver][sqliteodbc] available from Christian Werner's website, also available via\nHomebrew as `sqliteobdc`! The tests expect to find a data source named `sqlite` on *nix systems and\n`SQLite3 ODBC Driver` on Windows systems. For example, your `odbcinst.ini` file on OS X must have a\nsection like the following.\n\n```ini\n[sqlite]\nDescription             = SQLite3 ODBC Driver\nSetup                   = /usr/lib/libsqlite3odbc-0.93.dylib\nDriver                  = /usr/lib/libsqlite3odbc-0.93.dylib\nThreading               = 2\n```\n\n### Example Build Process\n\nIt's most convenient to create a build directory for an out of source build, but this isn't\nrequired. After you've used cmake to generate your Makefiles, `make nanodbc` will build your shared\nobject. `make check` will build and run the tests. You can also install nanodbc to your system\nusing `make install`.\n\nIf the tests fail, please don't hesitate to [**report it**][nanodbc-new-issue] by creating an issue\nwith your detailed test log (prepend your `make` command with `env CTEST_OUTPUT_ON_FAILURE=1` to\nenable verbose output please).\n\n```shell\ncd path/to/nanodbc/repository\nmkdir build\ncd build\ncmake [Build Options] ..\nmake           # creates shared library\nmake nanodbc   # creates shared library\nmake tests     # builds the tests\nmake test      # runs the tests\nmake check     # builds and then runs tests\nmake examples  # builds all the example programs\nmake install   # installs nanodbc.h and shared library\n```\n\n### Build Options\n\nThe following build options are available via [CMake command-line option][cmake-docs] `-D`. If you\nare not using CMake to build nanodbc, you will need to set the corresponding `-D` compile define\nflags yourself.\n\nAll boolean options follow the CMake [OPTION][cmake-option] default value convention:\nif no initial value is provided, `OFF` is used.\n\nUse the standard CMake option `-DBUILD_SHARED_LIBS=ON` to build nanodbc as shared library.\n\nIf you need to use the `NANODBC_ENABLE_BOOST=ON` option, you will have to configure your\nenvironment to use [Boost][boost].\n\n| CMake\u0026nbsp;Option                  | Possible\u0026nbsp;Values | Details |\n| -----------------------------------| ---------------------| ------- |\n| `NANODBC_DISABLE_ASYNC`            | `OFF` or `ON`        | Disable all async features. May resolve build issues in older ODBC versions. |\n| `NANODBC_DISABLE_EXAMPLES`         | `OFF` or `ON`        | Do not build examples. |\n| `NANODBC_DISABLE_INSTALL`          | `OFF` or `ON`        | Do not generate install target. |\n| `NANODBC_DISABLE_LIBCXX`           | `OFF` or `ON`        | Do not use libc++, if available on the system. |\n| `NANODBC_DISABLE_TESTS`            | `OFF` or `ON`        | Do not build tests. |\n| `NANODBC_ENABLE_BOOST`             | `OFF` or `ON`        | Use Boost for Unicode string convertions (requires [Boost.Locale][boost-locale]). Workaround to issue [#24](https://github.com/nanodbc/nanodbc/issues/24). |\n| `NANODBC_ENABLE_UNICODE`           | `OFF` or `ON`        | Enable Unicode support. `nanodbc::string` becomes `std::u16string` or `std::u32string`. |\n| `NANODBC_ENABLE_WORKAROUND_NODATA` | `OFF` or `ON`        | Enable `SQL_NO_DATA` workaround to issue [#43](https://github.com/nanodbc/nanodbc/issues/43). |\n| `NANODBC_OVERALLOCATE_CHAR`        | `OFF` or `ON`        | Overallocate auto-bound n/var/char buffers to accomodate retrieving Unicode data in VARCHAR columns [#219](https://github.com/nanodbc/nanodbc/issues/219). |\n| `NANODBC_ODBC_VERSION`             | `SQL_OV_ODBC3[...]`  | Forces ODBC version to use. Default is `SQL_OV_ODBC3_80` if available, otherwise `SQL_OV_ODBC3`. |\n\n### Note About iODBC\n\nUnder Windows `sizeof(wchar_t) == sizeof(SQLWCHAR) == 2`, yet on Unix systems\n`sizeof(wchar_t) == 4`. On unixODBC, `sizeof(SQLWCHAR) == 2` while on iODBC,\n`sizeof(SQLWCHAR) == sizeof(wchar_t) == 4`. This leads to incompatible ABIs between applications\nand drivers. If building against iODBC and the build option `NANODBC_USE_UNICODE` is `ON`, then\n`nanodbc::string` will be `std::u32string`. In **ALL** other cases it will be `std::u16string`.\n\nThe CI builds do not exercise a Unicode-enabled iODBC driver. As such there is no guarantee\nthat tests will pass in entirety on a system using iODBC. My recommendation is to use unixODBC.\nIf you must use iODBC, consider _disabling_ unicode mode to avoid `wchar_t` issues.\n\n---\n\n## Contributing\n\n### Code Style\n\n[clang-format][clang-format] version 15 handles all C++ code formatting for nanodbc.\nSee our [.clang-format](.clang-format) configuration file for details on the style and\ncurrently required version of `clang-format` specified in the comment at the top of the file\nThe script [utility/style.sh](utility/style.sh) formats all code in the repository automatically.\n\nTo run `clang-format` against the whole nanodbc codebase:\n\n```shell\n./utility/style.sh\n```\n\nTo run `clang-format` on a single file use the following.\n\n```shell\nclang-format -i /path/to/file\n```\n\n**Please auto-format all code submitted in Pull Requests.**\n\n### Source Level Documentation\n\nSource level documentation provided via [GitHub's gh-pages][gh-pages] is available\nat [nanodbc.io][nanodbc]. To re-build and update it, preform the following steps\nfrom the [doc/README.md](doc/README.md) file.\n\n### Quick Setup for Testing or Development Environments\n\nTo get up and running with nanodbc as fast as possible consider using the provided\n[Dockerfile](Dockerfile) and [docker-compose.yml](docker-compose.yml) or [Vagrantfile](Vagrantfile).\n\nFor example, to spin up a [docker][docker] container suitable for testing and development of nanodbc:\n\n```shell\n$ cd /path/to/nanodbc\n$ docker build -t nanodbc .\n\n# To build using the nanodbc already source within the container\n$ docker run -it nanodbc /bin/bash\n\n# Alternatively, mount the nanodbc repository into the container as a volume\n$ docker run -v \"$(pwd)\":\"/opt/$(basename $(pwd))\" -it nanodbc /bin/bash\n\n# Then, enter the source directory and build nanodbc:\nroot@hash:/# mkdir -p /opt/nanodbc/build\nroot@hash:/# cd /opt/nanodbc/build\nroot@hash:/opt/nanodbc/build# cmake ..\nroot@hash:/opt/nanodbc/build# make nanodbc\n```\n\nOr, spin up the complete multi-container environment with database services:\n\n```shell\ncd /path/to/nanodbc\ndocker-compose build\ndocker-compose up -d\ndocker exec -it nanodbc /bin/bash\n```\n\nOr, to build and ssh into a [vagrant][vagrant] VM (using VirtualBox for example) use:\n\n```shell\ncd /path/to/nanodbc\nvagrant up\nvagrant ssh\nvagrant@vagrant-ubuntu-precise-64:~$ git clone https://github.com/nanodbc/nanodbc.git\nvagrant@vagrant-ubuntu-precise-64:~$ mkdir -p nanodbc/build \u0026\u0026 cd nanodbc/build\nvagrant@vagrant-ubuntu-precise-64:~$ CXX=g++-5 cmake ..\nvagrant@vagrant-ubuntu-precise-64:~$ make nanodbc\n```\n\n### Tests\n\nOne of important objectives is to maintain nanodbc covered with tests. New contributions\nsubmitted via Pull Requests must include corresponding tests. This is important to ensure\nthe quality of new features.\n\nThe good news is that adding tests is easy!\n\nThe tests structure:\n\n- `tests/base_test_fixture.h` includes a set of common test cases.\n- `tests/\u003cdatabase\u003e_test.cpp` is a source code for an independent test program that includes both,\n  common and database-specific test cases.\n\nTo add new test case:\n\n1. In `tests/base_test_fixture.h` file, add a new test case method to `base_test_fixture`\n   class (e.g. `void my_feature_test()`).\n2. In each `tests/\u003cdatabase\u003e_test.cpp` file, copy and paste the `TEST_CASE_METHOD` boilerplate,\n   updating name, tags, etc.\n\nIf a feature requires a database-specific test case for each database, then skip the\n`tests/base_test_fixture.h` step and write a dedicated test case directly in\n`tests/\u003cdatabase\u003e_test.cpp` file.\n\n## Publish and Release Process\n\nOnce your local `main` branch is ready for publishing\n(i.e. [semantic versioning][semver]), use the `utility/publish.sh` script. This script\nbumps the major, minor, or patch version, then updates the repository's `VERSION.txt` file, adds a\n\"Preparing\" commit, and creates git tags appropriately. For example to make a minor update you\nwould run `./utility/publish.sh minor`.\nReview files of CMake configuration, documentation and Sphinx configuration,\nand update version number wherever necessary.\n\n\u003e **Important:** Always update [`CHANGELOG.md`](CHANGELOG.md) with information about new changes,\n\u003e bug fixes, and features when making a new release.\n\u003e Use the `./utility/changes.sh` script to aid in your composition of this document.\n\u003e The publish script itself will attempt to verify that the changelog file has been properly updated.\n\nTo do this manually instead, use the following steps \u0026mdash; for example a minor update from\n`2.9.x` to `2.10.0`:\n\n1. `echo \"2.10.0\" \u003e VERSION.txt`\n2. `git add VERSION.txt`\n3. `git commit -m \"Preparing 2.10.0 release.\"`\n4. `git tag -f \"v2.10.0\"`\n5. `git push -f origin \"v2.10.0\"`\n\nNext, switch to `gh-pages` branch, build latest documentation, commit and push.\n\nFinally, announce the new release to the public.\n\n## Future work\n\n### Good to Have / Want Someday\n\n- Refactor tests to follow BDD pattern.\n- Update codebase to use more C++14 idioms and patterns.\n- Write more tests with the goal to have much higher code coverage.\n- More tests for a large variety of drivers. Include performance tests.\n- Clean up `bind_*` family of functions, reduce any duplication.\n- Improve documentation: The main website and API docs should be more responsive.\n- Provide more examples in documentation, more details, and point out any gotchas.\n- Versioned generated source level API documentation for `master` and previous releases.\n- Add \"HOWTO Build\" documentation for Windows, OS X, and Linux.\n\n---\n\n[MIT][mit] \u0026copy; [lexicalunit, mloskot][authors] and [contributors][contributors].\n\n[mit]:              http://opensource.org/licenses/MIT\n[authors]:          https://github.com/orgs/nanodbc/people\n[contributors]:     https://github.com/nanodbc/nanodbc/graphs/contributors\n\n[nanodbc]:              http://nanodbc.io\n[nanodbc-banner]:       https://cloud.githubusercontent.com/assets/1903876/11858632/cc0e21e6-a428-11e5-9a84-39fa27984914.png\n[nanodbc-coverity]:     https://github.com/nanodbc/nanodbc/tree/coverity_scan\n[nanodbc-new-issue]:    https://github.com/nanodbc/nanodbc/issues/new\n\n[boost]:        http://www.boost.org/\n[boost-locale]: http://www.boost.org/doc/libs/release/libs/locale/\n[brew]:         http://brew.sh/\n[catch]:        https://github.com/philsquared/Catch\n[clang-format]: http://clang.llvm.org/docs/ClangFormat.html\n[cmake-docs]:   https://cmake.org/cmake/help/latest/manual/cmake.1.html\n[cmake]:        http://www.cmake.org/\n[cmake-option]: http://cmake.org/cmake/help/latest/command/option.html\n[cpp-core]:     https://github.com/isocpp/CppCoreGuidelines\n[cpp-std]:      https://isocpp.org/std/status\n[docker]:       https://www.docker.com/\n[gh-pages]:     https://help.github.com/articles/what-are-github-pages/\n[iodbc]:        http://www.iodbc.org/\n[pimpl]:        http://c2.com/cgi/wiki?PimplIdiom\n[semver]:       http://semver.org/\n[sqlite]:       https://www.sqlite.org/\n[sqliteodbc]:   http://www.ch-werner.de/sqliteodbc/\n[unixodbc]:     http://www.unixodbc.org/\n[vagrant]:      https://www.vagrantup.com/\n\n[coverity]:         https://scan.coverity.com/projects/nanodbc-nanodbc\n[coverity-badge]:   https://scan.coverity.com/projects/7437/badge.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanodbc%2Fnanodbc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnanodbc%2Fnanodbc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanodbc%2Fnanodbc/lists"}