nanodbc

https://nanodbc.github.io/nanodbc/
Admin
nanodbc is a small, simple C++ library that wraps the ODBC API to make database programming easy,...
Tokens:50,364
Snippets:443
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Quickstart nanodbc connection and execution

Source: https://nanodbc.github.io/nanodbc/use.html

Demonstrates establishing a connection, executing SQL commands, and iterating through result sets.

```cpp
#include <nanodbc/nanodbc.h>

#include <cstdlib>
#include <exception>
#include <iostream>

int main() try
{
  auto const connstr = NANODBC_TEXT("..."); // an ODBC connection string to your database
  nanodbc::connection conn(connstr);
  nanodbc::execute(conn, NANODBC_TEXT("create table t (i int)"));
  nanodbc::execute(conn, NANODBC_TEXT("insert into t values (1)"));

  auto result = nanodbc::execute(conn, NANODBC_TEXT("select i from t"));
  while (result.next())
  {
    std::cout << result.get<int>(0) << std::endl;
  }
  return EXIT_SUCCESS;
}
catch (std::exception const& e)
{
    std::cerr << e.what() << std::endl;
    return EXIT_FAILURE;
}
```

--------------------------------

### Initialize development environment with Docker Compose

Source: https://nanodbc.github.io/nanodbc/develop.html

Starts database services and enters the development container to build and test nanodbc.

```bash
$ cd /path/to/nanodbc
$ docker compose up -d
$ docker compose run --rm nanodbc /bin/bash
root@hash:/opt/nanodbc# cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
root@hash:/opt/nanodbc# cmake --build build --parallel
root@hash:/opt/nanodbc# ctest --test-dir build --output-on-failure -E vertica_tests
```

--------------------------------

### Build and run the development image

Source: https://nanodbc.github.io/nanodbc/develop.html

Builds the development Docker image and starts an interactive session with the local directory mounted.

```bash
$ docker build -f Dockerfile.dev -t nanodbc .
$ docker run -v "$(pwd)":/opt/nanodbc -it nanodbc /bin/bash
```

--------------------------------

### General nanodbc library usage example

Source: https://nanodbc.github.io/nanodbc/use.html

Demonstrates connection establishment, table creation, direct execution, result set access, and various parameter binding methods including null values.

```cpp
#include "example_unicode_utils.h"
#include <nanodbc/nanodbc.h>

#include <algorithm>
#include <cstring>
#include <iostream>

using namespace std;
using namespace nanodbc;

void show(nanodbc::result& results);

void run_test(nanodbc::string const& connection_string)
{
    // Establishing connections
    nanodbc::connection connection(connection_string);
    // or connection(connection_string, timeout_seconds);
    // or connection("data source name", "username", "password");
    // or connection("data source name", "username", "password", timeout_seconds);
    cout << "Connected with driver " << convert(connection.driver_name()) << endl;

    // Setup
    execute(connection, NANODBC_TEXT("drop table if exists simple_test;"));
    execute(connection, NANODBC_TEXT("create table simple_test (a int, b varchar(10));"));

    // Direct execution
    {
        execute(connection, NANODBC_TEXT("insert into simple_test values (1, 'one');"));
        execute(connection, NANODBC_TEXT("insert into simple_test values (2, 'two');"));
        execute(connection, NANODBC_TEXT("insert into simple_test values (3, 'tri');"));
        execute(connection, NANODBC_TEXT("insert into simple_test (b) values ('z');"));
        nanodbc::result results = execute(connection, NANODBC_TEXT("select * from simple_test;"));
        show(results);
    }

    // Accessing results by name, or column number
    {
        nanodbc::result results = execute(
            connection,
            NANODBC_TEXT("select a as first, b as second from simple_test where a = 1;"));
        if (results.next())
        {
            auto const value = results.get<nanodbc::string>(1);
            cout << endl
                 << results.get<int>(NANODBC_TEXT("first")) << ", " << convert(value) << endl;
        }
    }

    // Binding parameters
    {
        nanodbc::statement statement(connection);

        // Inserting values
        prepare(statement, NANODBC_TEXT("insert into simple_test (a, b) values (?, ?);"));
        const int eight_int = 8;
        statement.bind(0, &eight_int);
        nanodbc::string const eight_str = NANODBC_TEXT("eight");
        statement.bind(1, eight_str.c_str());
        execute(statement);

        // Inserting null values
        prepare(statement, NANODBC_TEXT("insert into simple_test (a, b) values (?, ?);"));
        statement.bind_null(0);
        statement.bind_null(1);
        execute(statement);

        // Inserting multiple null values
        prepare(statement, NANODBC_TEXT("insert into simple_test (a, b) values (?, ?);"));
        statement.bind_null(0, 2);
        statement.bind_null(1, 2);
        execute(statement, 2);

        prepare(statement, NANODBC_TEXT("select * from simple_test;"));
        nanodbc::result results = execute(statement);
        show(results);
    }
```

--------------------------------

### Binding rows to a statement

Source: https://nanodbc.github.io/nanodbc/api/group__mainf.html

Example demonstrating how to define a struct, populate a vector, and bind the data to a prepared statement using member pointers.

```cpp
struct person
{
long id;
nanodbc::string name;
};
std::vector<person> people = load();
nanodbc::statement stmt(conn);
prepare(stmt, NANODBC_TEXT("insert into people (id, name) values (?, ?)"));
bind_rows(stmt, people, &person::id, &person::name);
execute(stmt, people.size());
```

--------------------------------

### Define PARAM_RETURN usage

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1statement.html

Example of the escape sequence syntax for a procedure return value.

```sql
{ ? = CALL proc(?) }
```

--------------------------------

### Example Class Hierarchy for Doxygen Graphs

Source: https://nanodbc.github.io/nanodbc/api/graph_legend.html

A set of C++ classes demonstrating various inheritance, template, and usage relationships for graph generation.

```cpp
/*! Invisible class because of truncation */
class Invisible { };
/*! Truncated class, inheritance relation is hidden */
class Truncated : public Invisible { };
/* Class not documented with doxygen comments */
class Undocumented { };
/*! Class that is inherited using public inheritance */
class PublicBase : public Truncated { };
/*! A template class */
template<class T> class Templ { };
/*! Class that is inherited using protected inheritance */
class ProtectedBase { };
/*! Class that is inherited using private inheritance */
class PrivateBase { };
/*! Class that is used by the Inherited class */
class Used { };
/*! Super class that inherits a number of other classes */
class Inherited : public PublicBase,
protected ProtectedBase,
private PrivateBase,
public Undocumented,
public Templ<int>
{
private:
Used *m_usedClass;
};
```

--------------------------------

### Build nanodbc from source

Source: https://nanodbc.github.io/nanodbc/install.html

Commands to clone the repository, configure the build with CMake, and compile the library.

```bash
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
```

--------------------------------

### Configure and build with Makefiles

Source: https://nanodbc.github.io/nanodbc/install.html

Standard workflow for configuring nanodbc using the Unix Makefiles generator and building specific targets.

```bash
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
```

--------------------------------

### Retrieve null values using std::optional

Source: https://nanodbc.github.io/nanodbc/use.html

Use get<std::optional<T>>() to retrieve column data; it returns an empty optional instead of throwing null_access_error if the column is null.

```cpp
#include <nanodbc/nanodbc.h>
#include <iostream>
#include <optional>

int main()
{
    nanodbc::connection conn(NANODBC_TEXT("dsn"));
    auto results = execute(conn, NANODBC_TEXT("select age from people"));
    while (results.next())
    {
        auto const age = results.get<std::optional<int>>(0);
        std::cout << (age ? std::to_string(*age) : "unknown") << '\n';
    }
}
```

--------------------------------

### Handle command-line arguments and connection

Source: https://nanodbc.github.io/nanodbc/use.html

Defines a usage helper and a main function to parse connection strings and execute database tests.

```cpp
void usage(ostream& out, std::string const& binary_name)
{
    out << "usage: " << binary_name << " connection_string" << endl;
}

int main(int argc, char* argv[])
{
    if (argc != 2)
    {
        char* app_name = strrchr(argv[0], '/');
        app_name = app_name ? app_name + 1 : argv[0];
        if (0 == strncmp(app_name, "lt-", 3))
            app_name += 3; // remove libtool prefix
        usage(cerr, app_name);
        return EXIT_FAILURE;
    }

    try
    {
        auto const connection_string(convert(argv[1]));
        run_test(connection_string);
        return EXIT_SUCCESS;
    }
    catch (const exception& e)
    {
        cerr << e.what() << endl;
    }
    return EXIT_FAILURE;
}
```

--------------------------------

### execute

Source: https://nanodbc.github.io/nanodbc/api/namespacenanodbc.html

Immediately opens, prepares, and executes the given query directly on the given connection.

```APIDOC
## result execute(connection &conn, string const &query, long batch_operations=1, long timeout=0)

### Description
Immediately opens, prepares, and executes the given query directly on the given connection.
```

--------------------------------

### async_connect(connection_string, event_handle, timeout)

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Initiates an asynchronous connection using a full connection string.

```APIDOC
## bool nanodbc::connection::async_connect(string const & connection_string, void * event_handle, long timeout = 0)

### Description
Initiate an asynchronous connection operation using the given connection string. This method is only available if nanodbc is built with asynchronous ODBC support.

### Parameters
- **connection_string** (string const &) - The connection string for establishing a connection.
- **event_handle** (void *) - Event handle the caller will wait before calling async_complete.
- **timeout** (long) - Seconds before connection timeout. Default is 0 indicating no timeout.

### Returns
- **Boolean** - true if event handle needs to be awaited, false if connection is ready now.

### Exceptions
- **database_error**
```

--------------------------------

### prepare

Source: https://nanodbc.github.io/nanodbc/api/nanodbc_8h_source.html

Prepares a SQL query for execution.

```APIDOC
## void prepare(statement& stmt, string const& query, long timeout = 0)

### Description
Prepares a SQL query string for execution on the provided statement object.

### Parameters
- **stmt** (statement&) - The statement object.
- **query** (string const&) - The SQL query string.
- **timeout** (long) - Optional timeout value.
```

--------------------------------

### prepare

Source: https://nanodbc.github.io/nanodbc/api/namespacenanodbc.html

Prepares the given statement to execute on it associated connection.

```APIDOC
## void prepare(statement &stmt, string const &query, long timeout=0)

### Description
Prepares the given statement to execute on it associated connection.
```

--------------------------------

### async_connect(dsn, user, pass, event_handle, timeout)

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Initiates an asynchronous connection to a data source using DSN, username, and password.

```APIDOC
## bool nanodbc::connection::async_connect(string const & dsn, string const & user, string const & pass, void * event_handle, long timeout = 0)

### Description
Initiate an asynchronous connection operation to the given data source. This method is only available if nanodbc is built with asynchronous ODBC support.

### Parameters
- **dsn** (string const &) - The name of the data source.
- **user** (string const &) - The username for authenticating to the data source.
- **pass** (string const &) - The password for authenticating to the data source.
- **event_handle** (void *) - The event handle the caller will wait before calling async_complete.
- **timeout** (long) - Seconds before connection timeout. Default is 0 indicating no timeout.

### Returns
- **Boolean** - true if event handle needs to be awaited, false if connection is ready now.

### Exceptions
- **database_error**
```

--------------------------------

### begin

Source: https://nanodbc.github.io/nanodbc/api/namespacenanodbc.html

Returns an iterator to the beginning of the given result set.

```APIDOC
## result_iterator begin(result &r)

### Description
Returns an iterator to the beginning of the given result set.
```

--------------------------------

### Execute Batch Inserts

Source: https://nanodbc.github.io/nanodbc/use.html

Shows how to bind multiple data elements to a statement and execute them in a single batch operation.

```cpp
{
    nanodbc::statement statement(connection);
    execute(connection, NANODBC_TEXT("drop table if exists batch_test;"));
    execute(
        connection,
        NANODBC_TEXT(
            "create table batch_test (x varchar(10), x2 varchar(10), y int, z float);"));
    prepare(
        statement, NANODBC_TEXT("insert into batch_test (x, x2, y, z) values (?, ?, ?, ?);"));

    const size_t elements = 4;

    nanodbc::string::value_type xdata[elements][10] = {
        NANODBC_TEXT("this"), NANODBC_TEXT("is"), NANODBC_TEXT("a"), NANODBC_TEXT("test")};
    statement.bind_strings(0, xdata);

    std::vector<nanodbc::string> x2data(xdata, xdata + elements);
    statement.bind_strings(1, x2data);

    int ydata[elements] = {1, 2, 3, 4};
    statement.bind(2, ydata, elements);

    float zdata[elements] = {1.1f, 2.2f, 3.3f, 4.4f};
    statement.bind(3, zdata, elements);

    transact(statement, elements);

    nanodbc::result results = execute(connection, NANODBC_TEXT("select * from batch_test;"));
    show(results);

    execute(connection, NANODBC_TEXT("drop table if exists batch_test;"));
}
```

--------------------------------

### open()

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1table__valued__parameter.html

Opens the parameter on a statement to prepare it for value binding.

```APIDOC
## Method: nanodbc::table_valued_parameter::open

### Description
Opens the parameter on a statement, ready for values to be bound to it. Only one table-valued parameter may be open on a statement at a time.

### Parameters
- **stmt** (statement &) - The prepared statement carrying the parameter marker.
- **param_index** (short) - Zero-based index of parameter marker.
- **row_count** (std::size_t) - Number of rows that will be bound.

### Exceptions
- **database_error**
```

--------------------------------

### Read database rows using nanodbc

Source: https://nanodbc.github.io/nanodbc/index.html

Demonstrates the simplified, modern C++ approach to fetching data using the nanodbc library.

```cpp
 #include <nanodbc/nanodbc.h>

 #include <iostream>

 int main()
 {
     nanodbc::connection conn(NANODBC_TEXT("NorthWind"));
     auto rows = nanodbc::execute(
         conn, NANODBC_TEXT("SELECT CustomerID, ContactName, Phone"
                            " FROM CUSTOMERS ORDER BY 2, 1, 3"));

     for (auto& row : rows)
     {
         std::cout << row.get<std::string>(0) << " "
                   << row.get<std::string>(1) << " "
                   << row.get<std::string>(2) << '\n';
     }
 }
```

--------------------------------

### Standard Library Includes

Source: https://nanodbc.github.io/nanodbc/api/nanodbc_8h_source.html

Essential C++17 standard library headers required for nanodbc functionality.

```cpp
#include <any>
#include <cstddef>
#include <cstdint>
#include <exception>
#include <functional>
#include <iterator>
#include <list>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
#include <variant>
#include <vector>
```

--------------------------------

### nanodbc::connection::connect

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Establishes a connection to a database using a connection string and optional attributes.

```APIDOC
## void nanodbc::connection::connect(string const & connection_string, std::list< attribute > const & attributes)

### Description
Sets the connection attributes passed by the user and connects to the database using the provided connection string.

### Parameters
- **connection_string** (string const &) - Required - The connection string for establishing a connection.
- **attributes** (std::list< attribute > const &) - Required - A list of connection attributes to be set prior to connecting.

### Exceptions
- **database_error** - Thrown if the connection fails.
```

--------------------------------

### nanodbc::prepare

Source: https://nanodbc.github.io/nanodbc/api/group__mainf.html

Prepares a statement for execution.

```APIDOC
## void nanodbc::prepare(statement &stmt, string const &query, long timeout=0)

### Description
Prepares the given statement to execute on its associated connection.

### Parameters
- **stmt** (statement&) - Required - The statement object to prepare.
- **query** (string const&) - Required - The SQL query string.
- **timeout** (long) - Optional - Execution timeout (default 0).
```

--------------------------------

### connection(string const & connection_string, std::list< attribute > const & attributes)

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Creates a new connection object, sets the specified connection attributes, and establishes a connection using the provided connection string.

```APIDOC
## connection(string const & connection_string, std::list< attribute > const & attributes)

### Description
Creates a new connection object, sets the provided connection attributes, and connects to the database using the specified connection string. This method invokes the ODBC API SQLDriverConnect and SQLSetConnectAttr.

### Parameters
- **connection_string** (string const &) - Required - The connection string for establishing a connection.
- **attributes** (std::list< attribute > const &) - Required - A list of connection attributes to be set prior to connecting.

### Exceptions
- **database_error** - Thrown if the connection fails.
```

--------------------------------

### allocate()

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Allocates environment and connection handles for configuring the ODBC environment before connection.

```APIDOC
## allocate()

### Description
Allocates environment and connection handles. This allows for on-demand configuration of the ODBC environment and attributes before a connection is established.

### Exceptions
- **database_error** - Thrown if allocation fails.
```

--------------------------------

### bind_strings(short param_index, T const *values, std::size_t value_size, std::size_t batch_size, bool const *nulls)

Source: https://nanodbc.github.io/nanodbc/api/group__bind__strings.html

Binds multiple string values using a raw pointer, size parameters, and a null indicator array.

```APIDOC
## void nanodbc::table_valued_parameter::bind_strings(short param_index, T const *values, std::size_t value_size, std::size_t batch_size, bool const *nulls)

### Description
Binds multiple string values to a table-valued parameter using a raw pointer, explicit size constraints, and a boolean array for NULL indicators.

### Parameters
- **param_index** (short) - The index of the parameter to bind.
- **values** (T const *) - Pointer to the string data.
- **value_size** (std::size_t) - The size of each string value.
- **batch_size** (std::size_t) - The number of strings in the batch.
- **nulls** (bool const *) - An array of booleans indicating which values are NULL.
```

--------------------------------

### connection::connect

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Establishes a connection to a database using a DSN or a connection string, with optional timeout and attributes.

```APIDOC
## void connect(string const &dsn, string const &user, string const &pass, long timeout=0)
## void connect(string const &connection_string, long timeout=0)

### Description
Connects to a database using either a DSN with credentials or a full connection string. Optional timeout can be specified.

### Parameters
- **dsn** (string) - Data Source Name
- **user** (string) - Username
- **pass** (string) - Password
- **connection_string** (string) - Full ODBC connection string
- **timeout** (long) - Connection timeout in seconds
```

--------------------------------

### Binding parameters without preparation in C++

Source: https://nanodbc.github.io/nanodbc/use.html

Uses describe_parameters to provide parameter metadata manually, allowing execute_direct to run without a prior prepare call.

```cpp
#include <nanodbc/nanodbc.h>
#include <sql.h>
#include <sqlext.h>
#include <vector>

int main()
{
    nanodbc::connection conn(NANODBC_TEXT("dsn"));
    nanodbc::statement stmt(conn);

    std::vector<short> const index{0, 1};
    std::vector<short> const type{SQL_INTEGER, SQL_VARCHAR};
    std::vector<unsigned long> const size{10, 20};
    std::vector<short> const scale{0, 0};
    stmt.describe_parameters(index, type, size, scale);

    int const i = 7;
    nanodbc::string const s = NANODBC_TEXT("no prepare");
    stmt.bind(0, &i);
    stmt.bind(1, s.c_str());

    stmt.execute_direct(conn, NANODBC_TEXT("insert into t (i, s) values (?, ?)"));
}
```

--------------------------------

### Format nanodbc codebase with clang-format

Source: https://nanodbc.github.io/nanodbc/develop.html

Applies clang-format to all C++ header and source files in the repository.

```bash
clang-format -i $(git ls-files '*.h' '*.cpp')
```

--------------------------------

### execute

Source: https://nanodbc.github.io/nanodbc/api/nanodbc_8h_source.html

Executes a prepared statement.

```APIDOC
## result execute(statement& stmt, long batch_operations = 1)

### Description
Executes the given statement. Returns a result object representing the outcome of the execution.

### Parameters
- **stmt** (statement&) - The statement to execute.
- **batch_operations** (long) - Optional number of batch operations to perform.
```

--------------------------------

### Read database rows using native ODBC C API

Source: https://nanodbc.github.io/nanodbc/index.html

Demonstrates the standard, verbose approach to fetching data using the native ODBC C API.

```cpp
 #include <sql.h>
 #include <sqlext.h>
 #include <stdio.h>

 #define NAME_LEN 50
 #define PHONE_LEN 20

 int main()
 {
     SQLHENV henv;
     SQLHDBC hdbc;
     SQLHSTMT hstmt = 0;
     SQLRETURN retcode;
     SQLCHAR sCustID[NAME_LEN], szName[NAME_LEN], szPhone[PHONE_LEN];
     SQLLEN cbName = 0, cbCustID = 0, cbPhone = 0;

     retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
     if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)
     {
         retcode =
             SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER)SQL_OV_ODBC3, 0);
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)
         {
             retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
             if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)
             {
                 SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
                 retcode = SQLConnect(
                     hdbc, (SQLCHAR*)"NorthWind", SQL_NTS, NULL, 0, NULL, 0);
                 if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)
                 {
                     retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
                     retcode = SQLExecDirect(
                         hstmt,
                         (SQLCHAR*)"SELECT CustomerID, ContactName, Phone"
                                   " FROM CUSTOMERS ORDER BY 2, 1, 3",
                         SQL_NTS);
                     if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)
                     {
                         SQLBindCol(
                             hstmt, 1, SQL_C_CHAR, sCustID, NAME_LEN, &cbCustID);
                         SQLBindCol(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);
                         SQLBindCol(
                             hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN, &cbPhone);
                         for (int i = 0;; i++)
                         {
                             retcode = SQLFetch(hstmt);
                             if (retcode == SQL_ERROR ||
                                 retcode == SQL_SUCCESS_WITH_INFO)
                                 printf("error\n");
                             if (retcode == SQL_SUCCESS ||
                                 retcode == SQL_SUCCESS_WITH_INFO)
                                 printf(
                                     "%d: %s %s %s\n",
                                     i + 1,
                                     sCustID,
                                     szName,
                                     szPhone);
                             else
                                 break;
                         }
                         SQLCancel(hstmt);
                         SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
                     }
                     SQLDisconnect(hdbc);
                 }
                 SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
             }
         }
         SQLFreeHandle(SQL_HANDLE_ENV, henv);
     }
 }
```

--------------------------------

### nanodbc::connection::browse_connect

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Interactively discovers connection requirements from the ODBC driver.

```APIDOC
## string nanodbc::connection::browse_connect(string const & connection_string, bool & more_wanted)

### Description
Wraps ODBC's SQLBrowseConnect to ask the driver what information is required to establish a connection. This method can be called repeatedly until the driver has sufficient information.

### Parameters
- **connection_string** (string const &) - Required - What is known so far, beginning with the driver or DSN.
- **more_wanted** (bool &) - Required - Set to true if the driver requires more information, false otherwise.

### Returns
- **string** - The attributes wanted next by the driver, or an empty string once connected.

### Exceptions
- **database_error** - Thrown if the driver does not support browse_connect or if an error occurs.
```

--------------------------------

### Connection Management and Attributes

Source: https://nanodbc.github.io/nanodbc/api/nanodbc_8h_source.html

Classes and methods for establishing and managing database connections.

```cpp
class attribute : public nanodbc::attribute
{
public:
attribute(
long const& attribute,
long const& string_length,
variant const& resource) noexcept
: nanodbc::attribute(attribute, string_length, resource) {};

private:
friend class nanodbc::connection::connection_impl;
};
```

```cpp
connection();
connection(const connection& rhs) noexcept;
connection(connection&& rhs) noexcept;
connection& operator=(connection rhs) noexcept;
void swap(connection&) noexcept;
```

```cpp
connection(string const& dsn, string const& user, string const& pass, long timeout = 0);
explicit connection(string const& connection_string, long timeout = 0);
connection(
string const& dsn,
string const& user,
string const& pass,
std::list<attribute> const& attributes);
connection(string const& connection_string, std::list<attribute> const& attributes);
~connection() noexcept;
```

```cpp
void allocate();
void deallocate();
void connect(string const& dsn, string const& user, string const& pass, long timeout = 0);
void connect(string const& connection_string, long timeout = 0);
void connect(
string const& dsn,
string const& user,
string const& pass,
std::list<attribute> const& attributes);
void connect(string const& connection_string, std::list<attribute> const& attributes);
string browse_connect(string const& connection_string, bool& more_wanted);
bool async_connect(
string const& dsn,
string const& user,
```

--------------------------------

### nanodbc::list_drivers

Source: https://nanodbc.github.io/nanodbc/api/group__mainf.html

Retrieves a list of ODBC drivers configured on the system.

```APIDOC
## std::list<driver> nanodbc::list_drivers()

### Description
Returns a list of ODBC drivers currently configured on your system.

### Returns
- **std::list<driver>** - A list of driver objects.
```

--------------------------------

### statement::async_prepare

Source: https://nanodbc.github.io/nanodbc/api/nanodbc_8h_source.html

Asynchronously prepares a SQL query.

```APIDOC
## async_prepare

### Description
Initiates an asynchronous preparation of a SQL query. This is only available if NANODBC_DISABLE_ASYNC is not defined.

### Signature
`bool async_prepare(string const& query, void* event_handle, long timeout = 0);`
```

--------------------------------

### Doxygen Configuration Macros

Source: https://nanodbc.github.io/nanodbc/api/nanodbc_8h_source.html

Macros used for documentation generation purposes.

```cpp
#define NANODBC_THROW_NO_SOURCE_LOCATION 1
#define NANODBC_ASSERT(expression) assert(expression)
```

--------------------------------

### nanodbc::just_execute

Source: https://nanodbc.github.io/nanodbc/api/group__mainf.html

Opens, prepares, and executes a query directly without creating a result object.

```APIDOC
## nanodbc::just_execute

### Description
Opens, prepares, and executes query directly without creating result object.

### Parameters
- **conn** (connection &) - The connection where the statement will be executed.
- **query** (string const &) - The SQL query that will be executed.
- **batch_operations** (long) - Rows to fetch per rowset, or number of batch parameters to process. Default is 1.
- **timeout** (long) - The number in seconds before query timeout. Default is 0 (no timeout).
```

--------------------------------

### execute

Source: https://nanodbc.github.io/nanodbc/api/nanodbc_8h_source.html

Executes a SQL query on the provided connection.

```APIDOC
## result execute(connection& conn, string const& query, long batch_operations = 1, long timeout = 0)

### Description
Executes a SQL query string against the specified connection. Returns a result object containing the query output.

### Parameters
- **conn** (connection&) - Required - The active database connection.
- **query** (string const&) - Required - The SQL query to execute.
- **batch_operations** (long) - Optional - Number of batch operations (default: 1).
- **timeout** (long) - Optional - Execution timeout in seconds (default: 0).

### Return Value
- **result** - The result set of the executed query.
```

--------------------------------

### Handle Date and Time Types

Source: https://nanodbc.github.io/nanodbc/use.html

Retrieves datetime values from the database and maps them to nanodbc::date structures.

```cpp
{
    execute(connection, NANODBC_TEXT("drop table if exists date_test;"));
    execute(connection, NANODBC_TEXT("create table date_test (x datetime);"));
    execute(connection, NANODBC_TEXT("insert into date_test values (current_timestamp);"));

    nanodbc::result results = execute(connection, NANODBC_TEXT("select * from date_test;"));
    if (results.next())
    {
        nanodbc::date date = results.get<nanodbc::date>(0);
        cout << endl << date.year << "-" << date.month << "-" << date.day << endl;
    }

    results = execute(connection, NANODBC_TEXT("select * from date_test;"));
    show(results);

    execute(connection, NANODBC_TEXT("drop table if exists date_test;"));
}
```

--------------------------------

### nanodbc::connection::connect(connection_string, timeout)

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Connects to a data source using a full connection string and an optional timeout.

```APIDOC
## void nanodbc::connection::connect(string const & connection_string, long timeout = 0)

### Description
Connect using the given connection string.

### Parameters
- **connection_string** (string const &) - Required - The connection string for establishing a connection.
- **timeout** (long) - Optional - Seconds before connection timeout. Default is 0 indicating no timeout.

### Exceptions
- **database_error**
```

--------------------------------

### just_execute

Source: https://nanodbc.github.io/nanodbc/api/namespacenanodbc.html

Opens, prepares, and executes query directly without creating result object.

```APIDOC
## void just_execute(connection &conn, string const &query, long batch_operations=1, long timeout=0)

### Description
Opens, prepares, and executes query directly without creating result object.
```

--------------------------------

### nanodbc::connection::connect(dsn, user, pass, timeout)

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Connects to a data source using a DSN, username, password, and an optional timeout.

```APIDOC
## void nanodbc::connection::connect(string const & dsn, string const & user, string const & pass, long timeout = 0)

### Description
Connect to the given data source using credentials.

### Parameters
- **dsn** (string const &) - Required - The name of the data source.
- **user** (string const &) - Required - The username for authenticating to the data source.
- **pass** (string const &) - Required - The password for authenticating to the data source.
- **timeout** (long) - Optional - Seconds before connection timeout. Default is 0 indicating no timeout.

### Exceptions
- **database_error**
```

--------------------------------

### Format a single file with clang-format

Source: https://nanodbc.github.io/nanodbc/develop.html

Applies clang-format to a specific file path.

```bash
clang-format -i /path/to/file
```

--------------------------------

### nanodbc::catalog::catalog

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1catalog.html

Constructor to create a catalog object operating on a database accessible through the specified connection.

```APIDOC
## catalog(connection &conn)

### Description
Creates a catalog object that operates on the database accessible through the provided connection.

### Parameters
- **conn** (connection&) - Required - The database connection to use for metadata queries.
```

--------------------------------

### bind_strings(short param_index, T const (&values)[BatchSize][ValueSize], T const *null_sentry)

Source: https://nanodbc.github.io/nanodbc/api/group__bind__strings.html

Binds multiple string values using a fixed-size character array and a null sentry pointer.

```APIDOC
## void nanodbc::table_valued_parameter::bind_strings(short param_index, T const (&values)[BatchSize][ValueSize], T const *null_sentry)

### Description
Binds multiple string values to a table-valued parameter using a fixed-size 2D character array and a null sentry pointer.

### Parameters
- **param_index** (short) - The index of the parameter to bind.
- **values** (T const (&)[BatchSize][ValueSize]) - A 2D array containing the string values.
- **null_sentry** (T const *) - A pointer to the value used to represent NULL.
```

--------------------------------

### nanodbc::connection::connect(dsn, user, pass, attributes)

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Connects to a data source using a DSN, credentials, and a list of connection attributes.

```APIDOC
## void nanodbc::connection::connect(string const & dsn, string const & user, string const & pass, std::list< attribute > const & attributes)

### Description
Set the connection attributes passed by the user, and connect to the given data source.

### Parameters
- **dsn** (string const &) - Required - The name of the data source.
- **user** (string const &) - Required - The username for authenticating to the data source.
- **pass** (string const &) - Required - The password for authenticating to the data source.
- **attributes** (std::list< attribute > const &) - Required - A list of connection attributes to be set prior to connecting.

### Exceptions
- **database_error**
```

--------------------------------

### nanodbc::statement::async_execute_direct

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1statement.html

Opens, prepares, and executes query directly on the given connection in async mode.

```APIDOC
## nanodbc::statement::async_execute_direct(connection& conn, void* event_handle, string const& query, long batch_operations = 1, long timeout = 0)

### Description
Opens, prepares, and executes query directly on the given connection in asynchronous mode. This method is only available if nanodbc is built with asynchronous support enabled.

### Parameters
- **conn** (connection&) - The connection where the statement will be executed.
- **event_handle** (void*) - The event handle the caller will wait before calling complete_execute.
- **query** (string const&) - The SQL query that will be executed.
- **batch_operations** (long) - Rows to fetch per rowset or number of batch parameters to process.
- **timeout** (long) - The number in seconds before query timeout. Default 0 meaning no timeout.

### Returns
- **bool** - True if event handle needs to be awaited, false if result ready now.

### Exceptions
- **database_error**
```

--------------------------------

### nanodbc::statement::complete_prepare

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1statement.html

Completes a previously initiated asynchronous query preparation.

```APIDOC
## nanodbc::statement::complete_prepare()

### Description
Completes a previously initiated asynchronous query preparation. This method is only available if nanodbc is built with asynchronous support enabled.

### Exceptions
- **database_error**
```

--------------------------------

### nanodbc::statement::execute

Source: https://nanodbc.github.io/nanodbc/api/functions_e.html

Executes the prepared statement.

```APIDOC
result execute(long batch_operations = 1);
```

--------------------------------

### statement::prepare

Source: https://nanodbc.github.io/nanodbc/api/nanodbc_8h_source.html

Prepares a SQL query for execution on a connection, optionally setting a timeout.

```APIDOC
## prepare

### Description
Prepares a SQL statement for execution. This allows the statement to be executed multiple times with different parameters.

### Signature
`void prepare(connection& conn, string const& query, long timeout = 0);`
`void prepare(string const& query, long timeout = 0);`
```

--------------------------------

### nanodbc::batch_ops::batch_ops()

Source: https://nanodbc.github.io/nanodbc/api/structnanodbc_1_1batch__ops.html

Default constructor that initializes both parameter_array_length and rowset_size to -1.

```APIDOC
### Constructor
`nanodbc::batch_ops()`

### Description
Creates an instance with lengths set to -1, indicating that neither parameter array length nor rowset size has been explicitly configured.
```

--------------------------------

### nanodbc::connection::connection(dsn, user, pass, timeout)

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Creates a new connection object and immediately connects to the specified data source using SQLConnect.

```APIDOC
## Constructor: connection(dsn, user, pass, timeout)

### Description
Creates a new connection object and immediately connects to the given data source using the ODBC SQLConnect API.

### Parameters
- **dsn** (string) - Required - The name of the data source name (DSN).
- **user** (string) - Required - The username for authenticating to the data source.
- **pass** (string) - Required - The password for authenticating to the data source.
- **timeout** (long) - Optional - Seconds before connection timeout. Default is 0 (no timeout).

### Exceptions
- **database_error** - Thrown if the connection fails.
```

--------------------------------

### describe_parameters()

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1statement.html

Sets descriptions for parameters in the prepared statement.

```APIDOC
### void nanodbc::statement::describe_parameters(const std::vector< short > & idx, const std::vector< short > & type, const std::vector< unsigned long > & size, const std::vector< short > & scale)

Sets descriptions for parameters in the prepared statement. This is used to define SQL type, size, and scale for parameter markers.

#### Parameters
- **idx** (const std::vector< short > &) - Vector of zero-based indices of parameters.
- **type** (const std::vector< short > &) - Vector of short integer types.
- **size** (const std::vector< unsigned long > &) - Vector of unsigned long sizes.
- **scale** (const std::vector< short > &) - Vector of short integer decimal precision / scale.
```

--------------------------------

### Iterate and display database rows

Source: https://nanodbc.github.io/nanodbc/use.html

Iterates through result sets and prints column data, using a specified null value string for empty fields.

```cpp
// show the column data for each row
nanodbc::string const null_value = NANODBC_TEXT("null");
while (results.next())
{
    cout << rows_displayed++ << "\t";
    for (short col = 0; col < columns; ++col)
    {
        auto const value = results.get<nanodbc::string>(col, null_value);
        cout << "(" << convert(value) << ")\t";
    }
    cout << endl;
}
}
```

--------------------------------

### get_info()

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1connection.html

Retrieves information from the ODBC connection as a string or fixed-size value using the SQLGetInfo function.

```APIDOC
## template<class T> T nanodbc::connection::get_info(short info_type)

### Description
Returns information from the ODBC connection as a string or fixed-size value.
```

--------------------------------

### Library Forward Declarations

Source: https://nanodbc.github.io/nanodbc/api/nanodbc_8h_source.html

Forward declarations for primary nanodbc classes.

```cpp
#ifndef NANODBC_DISABLE_MSSQL_TVP
class table_valued_parameter;
#endif
class statement;
class connection;
class transaction;
class catalog;
class result;
```

--------------------------------

### Parameter Binding Methods

Source: https://nanodbc.github.io/nanodbc/api/nanodbc_8h_source.html

Template-based methods for binding single values, optional values, and batch data to parameters.

```cpp
template <class T>
void bind(short param_index, T const* value, param_direction direction = PARAM_IN);
```

```cpp
template <class T>
void
bind(short param_index, std::optional<T> const& value, param_direction direction = PARAM_IN)
{
if (!value.has_value())
{
bind_null(param_index, 1);
return;
}
if constexpr (is_owning_string_v<T>)
bind(param_index, value->c_str(), direction);
else
bind(param_index, &*value, direction);
}
```

```cpp
template <class T>
void bind(
short param_index,
T const* values,
std::size_t batch_size,
param_direction direction = PARAM_IN);
```

```cpp
template <class T>
void bind(
short param_index,
T const* values,
std::size_t batch_size,
T const* null_sentry,
param_direction direction = PARAM_IN);
```

```cpp
template <class T>
void bind(
short param_index,
T const* values,
std::size_t batch_size,
bool const* nulls,
param_direction direction = PARAM_IN);
```

```cpp
void bind(
short param_index,
std::vector<std::vector<uint8_t>> const& values,
param_direction direction = PARAM_IN);
```

```cpp
void bind(
short param_index,
std::vector<std::vector<uint8_t>> const& values,
bool const* nulls,
param_direction direction = PARAM_IN);
```

```cpp
void bind(
short param_index,
std::vector<std::vector<uint8_t>> const& values,
uint8_t const* null_sentry,
param_direction direction = PARAM_IN);
```

```cpp
template <class T>
void
bind(short param_index, std::vector<T> const& values, param_direction direction = PARAM_IN);
```

```cpp
template <class T>
void bind(
short param_index,
std::vector<T> const& values,
bool const* nulls,
param_direction direction = PARAM_IN);
```

```cpp
template <class T>
void bind(
short param_index,
std::vector<std::optional<T>> const& values,
param_direction direction = PARAM_IN)
{
std::vector<T> column;
auto const nulls = detail::split_optional(values, column);
bind(param_index, column, nulls.get(), direction);
}
```

--------------------------------

### nanodbc::begin

Source: https://nanodbc.github.io/nanodbc/api/group__mainc.html

Returns an iterator to the beginning of the given result set.

```APIDOC
## nanodbc::begin(result &r)

### Description
Returns an iterator to the beginning of the given result set.

### Parameters
- **r** (result &) - The result set to iterate over.

### Returns
- **result_iterator** - An iterator pointing to the start of the result set.
```

--------------------------------

### list_datasources

Source: https://nanodbc.github.io/nanodbc/api/namespacenanodbc.html

Returns a list of ODBC data sources on your system.

```APIDOC
## std::list<datasource> list_datasources()

### Description
Returns a list of ODBC data sources on your system.
```

--------------------------------

### nanodbc::catalog

Source: https://nanodbc.github.io/nanodbc/api/nanodbc_8h_source.html

The catalog class provides methods to query database metadata. Users can instantiate it with a connection and use methods like find_tables, find_columns, and find_table_privileges to retrieve metadata objects.

```APIDOC
## nanodbc::catalog

### Description
The catalog class is used to inspect database metadata. It provides methods to search for tables, columns, primary keys, and privileges.

### Methods
- **find_tables(string table, string type, string schema, string catalog)**: Returns a `catalog::tables` object to iterate over matching tables.
- **find_columns(string column, string table, string schema)**: Returns a `catalog::columns` object to iterate over matching columns.
- **find_table_privileges(string catalog, string table, string schema)**: Returns a `catalog::table_privileges` object to iterate over table privileges.

### Usage
Each returned object (e.g., `tables`, `columns`) provides a `next()` method to iterate through the result set and various getter methods (e.g., `table_name()`, `column_name()`) to access metadata fields.
```

--------------------------------

### nanodbc::statement::async_prepare

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1statement.html

Prepare the given statement in asynchronous mode.

```APIDOC
## nanodbc::statement::async_prepare(string const& query, void* event_handle, long timeout = 0)

### Description
Prepares the given statement in asynchronous mode. This method is only available if nanodbc is built with asynchronous support enabled.

### Parameters
- **query** (string const&) - The SQL query that will be prepared.
- **event_handle** (void*) - The event handle the caller will wait before calling complete_prepare.
- **timeout** (long) - The number in seconds before query timeout. Default 0 meaning no timeout.

### Returns
- **bool** - True if the event handle needs to be awaited, false if the result is ready now.

### Exceptions
- **database_error**
```

--------------------------------

### execute()

Source: https://nanodbc.github.io/nanodbc/api/classnanodbc_1_1statement.html

Executes a previously prepared query synchronously.

```APIDOC
## class result nanodbc::statement::execute(long batch_operations = 1, long timeout = 0)

### Description
Executes the previously prepared query and returns a result set object.

### Parameters
- **batch_operations** (long) - Optional - Rows to fetch per rowset or number of batch parameters to process. Default is 1.
- **timeout** (long) - Optional - The number in seconds before query timeout. Default is 0 (no timeout).

### Exceptions
- **database_error** - Thrown if the execution fails.

## class result nanodbc::statement::execute(batch_ops const &array_sizes, long timeout = 0)

### Description
Executes the previously prepared query, sizing the parameter array and the rowset separately.

### Parameters
- **array_sizes** (batch_ops const &) - Required - Parameter array length and rowset size.
- **timeout** (long) - Optional - The number in seconds before query timeout. Default is 0 (no timeout).
```
Tokens:
Raw