# FindODBC

Added in version 3.12.

Finds the Open Database Connectivity (ODBC) library, which implements a standard API for accessing database systems:

    find_package(ODBC [...])

ODBC enables applications to communicate with different database management systems (DBMS) using a common set of functions. Communication with a specific database is handled through ODBC drivers, which the library loads at runtime.

On Windows, when building with Visual Studio, this module assumes the ODBC library is provided by the available Windows SDK.

On Unix-like systems, this module searches for ODBC library provided by unixODBC or iODBC implementations of ODBC API. By default, this module looks for the ODBC config program to determine the ODBC library and include directory, first from unixODBC, then from iODBC. If no config program is found, it searches for ODBC header and library in standard locations.

## Imported Targets

This module provides the following Imported Targets:

`ODBC::ODBC`

  Target encapsulating the ODBC usage requirements, available if ODBC is found.

## Result Variables

This module defines the following variables:

`ODBC_FOUND`

  Boolean indicating whether ODBC was found.

`ODBC_INCLUDE_DIRS`

  Include directories containing headers needed to use ODBC.

`ODBC_LIBRARIES`

  Libraries needed to link against to use ODBC.

## Cache Variables

The following cache variables may also be set:

`ODBC_INCLUDE_DIR`

  The path to the directory containing `sql.h` and other ODBC headers. May be empty on Windows, where the include directory corresponding to the expected Windows SDK is already available in the compilation environment.

`ODBC_LIBRARY`

  The path to the ODBC library or a library name. On Windows, this may be only a library name, because the library directory corresponding to the expected Windows SDK is already available in the compilation environment.

`ODBC_CONFIG`

  The path to the ODBC config program if found or specified. For example, `odbc_config` for unixODBC, or `iodbc-config` for iODBC.

## Limitations

- On Windows, this module does not search for iODBC.

- On Unix-like systems, there is no built-in mechanism to prefer unixODBC over iODBC, or vice versa. To bypass this limitation, explicitly set the `ODBC_CONFIG` variable to the path of the desired ODBC config program.

- This module does not support searching for or selecting a specific ODBC driver.

## Examples

### Example: Finding and Using ODBC

Finding ODBC and linking it to a project target:

`CMakeLists.txt`

    find_package(ODBC)
    target_link_libraries(project_target PRIVATE ODBC::ODBC)

### Example: Finding a Custom ODBC Installation

The following examples are for Unix-like systems and demonstrate how to set hint and cache variables during the CMake configuration phase to help this module find a custom ODBC implementation (e.g. one not supported by default).

To specify the installation prefix using `CMAKE_PREFIX_PATH`:

    $ cmake -D CMAKE_PREFIX_PATH=/path/to/odbc-installation -B build

Or using the dedicated `ODBC_ROOT` variable:

    $ cmake -D ODBC_ROOT=/path/to/odbc-installation -B build

To manually specify the ODBC config program, if available, so that the ODBC installation can be automatically determined based on the config tool:

    $ cmake -D ODBC_CONFIG=/path/to/odbc/bin/odbc-config -B build

To manually specify the ODBC library and include directory:

    $ cmake \
        -D ODBC_LIBRARY=/path/to/odbc/lib/libodbc.so \
        -D ODBC_INCLUDE_DIR=/path/to/odbc/include \
        -B build