### nanodbc Quickstart Example

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

Demonstrates basic database operations: connecting, creating a table, inserting data, and querying it. Ensure you replace '...' with a valid ODBC connection string.

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

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 (1)"));

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


```

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

### Quickstart Database Interaction

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

A basic example demonstrating how to connect to a database, execute SQL commands, and iterate through result sets.

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

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 (1)"));

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

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

### Configure and build with Makefiles

Source: https://nanodbc.github.io/nanodbc/_sources/install.rst.txt

Example of using the Unix Makefiles generator with specific build targets.

```console
cd nanodbc
mkdir build
cd build
cmake -G "Unix Makefiles" [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
```

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

### Begin Transaction

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

Starts a transaction on the given connection. Operations after this must be committed.

```cpp
explicit transaction(const class connection &conn)
    

    
    Begin a transaction on the given connection object.  

    Throws
        
database_error –  

    Post
        
    Operations that modify the database must now be committed before taking effect.  
```

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

### Build nanodbc with Makefiles Generator

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

Configure nanodbc using CMake with the 'Unix Makefiles' generator, then build the shared library, tests, and examples. The 'install' target is also available.

```bash
cd nanodbc
mkdir build
cd build
cmake -G "Unix Makefiles" [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

```

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

### Get Native Environment Handle

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

Returns the native ODBC environment handle.

```cpp
void *native_env_handle() const
```

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

### Get Native Database Handle

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

Returns the native ODBC database connection handle.

```cpp
void *native_dbc_handle() const
```

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

### Get DBMS Version

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

Returns the version of the DBMS product accessed by the driver via the current connection.

```cpp
string dbms_version() const
```

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

### Get Statement Connection

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

Returns the associated connection object for the statement.

```cpp
class connection &connection()
    
    
    Returns the associated connection object if any.  
```

```cpp
const class connection &connection() const
    
    
    Returns the associated connection object if any. 
```

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

### Get ODBC Driver Name

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

Returns the name of the ODBC driver.

```cpp
string driver_name() const
```

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

### Get Native Statement Handle

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

Retrieves the native ODBC statement handle.

```cpp
void *native_statement_handle() const
    
    
    Returns the native ODBC statement handle. 
```

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

### Get Database Name

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

Returns the name of the currently connected database. Corresponds to the SQL_DATABASE_NAME information value.

```cpp
string database_name() const
```

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

### Get Catalog Name

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

Returns the name of the current catalog. Corresponds to the connection attribute SQL_ATTR_CURRENT_CATALOG.

```cpp
string catalog_name() const
```

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

### Inserting NULL Values with Sentry

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

Illustrates inserting NULL values using a sentry value. The `bind` function takes an optional pointer to an integer array where a non-zero value indicates a NULL. This example inserts NULLs for column 'a' and 'b'.

```cpp
nanodbc::statement statement(connection);
          prepare(statement, "insert into public.simple_test (a, b) values (?, ?);");

          const int elements = 5;
          const int a_null = 0;
          const char* b_null = "";
          int a_data[elements] = {0, 88, 0, 0, 0};
          char b_data[elements][10] = {"", "non-null", "", "", ""};

          statement.bind(0, a_data, elements, &a_null);
          statement.bind_strings(1, b_data, b_null);

          execute(statement, elements);

          nanodbc::result results = execute(connection, "select * from public.simple_test;");
          show(results);
```

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

### Get Connection from Transaction

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

Returns the connection object associated with the transaction.

```cpp
class connection &connection()
    
    
    Returns the connection object.  
```

```cpp
const class connection &connection() const
    
    
    Returns the connection object.  
```

```cpp
operator class connection&()
    
    
    Returns the connection object.  
```

```cpp
operator const class connection&() const
    
    
    Returns the connection object. 
```

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

### Get DBMS Name

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

Returns the name of the DBMS product accessed by the driver via the current connection. Corresponds to ODBC information type SQL_DBMS_NAME.

```cpp
string dbms_name() const
```

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

### Build nanodbc with Vagrant

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

Launch a Vagrant VM, clone the nanodbc repository, and build the project using C++11 compiler. This sets up a consistent development environment.

```bash
$ cd /path/to/nanodbc
$ vagrant up
$ vagrant ssh
vagrant@vagrant-ubuntu-precise-64:~$ git clone https://github.com/nanodbc/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
```

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

### Build nanodbc from source

Source: https://nanodbc.github.io/nanodbc/_sources/install.rst.txt

Standard sequence of commands to clone the repository, configure the build with CMake, and execute tests.

```console
git clone https://github.com/nanodbc/nanodbc.git
cd nanodbc
mkdir build
cd build
cmake ..
cmake --build .
ctest -V --output-on-failure
```

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

### Clone and Build nanodbc with CMake

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

Clone the nanodbc repository, navigate to the build directory, configure with CMake, build the library, and run tests.

```bash
git clone https://github.com/nanodbc/nanodbc.git
cd nanodbc
mkdir build
cd build
cmake ..
cmake --build .
ctest -V --output-on-failure

```

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

### Get Transaction Count

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

Returns the number of transactions currently held for this connection.

```cpp
std::size_t transactions() const
```

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

### Prepare and Execute Statement

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

Demonstrates preparing an insert statement, binding null values, and executing it. Also shows preparing a select statement and executing it.

```cpp
prepare(statement, "insert into public.simple_test (a, b) values (?, ?);");
          statement.bind_null(0, 2);
          statement.bind_null(1, 2);
          execute(statement, 2);

          prepare(statement, "select * from public.simple_test;");
          results = execute(statement);
          show(results);
```

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

### Application Entry Point and Usage

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

Handles command-line arguments and provides a standard error output for incorrect usage.

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

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

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

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

### Build nanodbc with Docker

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

Spin up a Docker container for testing and development. This command builds the Docker image and then runs a container, mounting the current directory.

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

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

### Bind and Execute SQL Statements

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

Demonstrates binding data arrays to prepared statements and executing them against a connection.

```cpp
        statement.bind(0, a_data, elements, &a_null);
        statement.bind_strings(1, b_data, b_null);

        execute(statement, elements);

        nanodbc::result results = execute(connection, "select * from public.simple_test;");
        show(results);
    }
```

```cpp
    // Inserting NULL values with flags
    {
        nanodbc::statement statement(connection);
        prepare(statement, "insert into public.simple_test (a, b) values (?, ?);");

        const int elements = 2;
        int a_data[elements] = {0, 42};
        char b_data[elements][10] = {"", "every"};
        bool nulls[elements] = {true, false};

        statement.bind(0, a_data, elements, nulls);
        statement.bind_strings(1, b_data, nulls);

        execute(statement, elements);

        nanodbc::result results = execute(connection, "select * from public.simple_test;");
        show(results);
    }
```

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

### Assert Affected Rows Logic

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

An assertion example demonstrating the relationship between `has_affected_rows()` and `affected_rows()`.

```cpp
assert(r.has_affected_rows() == (r.affected_rows() >= 0));

```

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

### Database Operations with nanodbc

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

Demonstrates core functionality including connection establishment, direct SQL execution, parameter binding, transaction management, batch inserts, and date handling.

```cpp
#include <algorithm>
#include <cstring>
#include <iostream>

#include <nanodbc/nanodbc.h>

using namespace std;

void show(nanodbc::result& results);

void run_test(const char* 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 " << connection.driver_name() << endl;

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

    nanodbc::result results;

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

    // Accessing results by name, or column number
    {
        results = execute(
            connection, "select a as first, b as second from public.simple_test where a = 1;");
        results.next();
        cout << endl << results.get<int>("first") << ", " << results.get<string>(1) << endl;
    }

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

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

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

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

        prepare(statement, "select * from public.simple_test;");
        results = execute(statement);
        show(results);
    }

    // Transactions
    {
        {
            cout << "\ndeleting all rows ... " << flush;
            nanodbc::transaction transaction(connection);
            execute(connection, "delete from public.simple_test;");
            // transaction will be rolled back if we don't call transaction.commit()
        }
        results = execute(connection, "select count(1) from public.simple_test;");
        results.next();
        cout << "still have " << results.get<int>(0) << " rows!" << endl;
    }

    // Batch inserting
    {
        nanodbc::statement statement(connection);
        execute(connection, "drop table if exists public.batch_test;");
        execute(connection, "create table public.batch_test (x varchar(10), y int, z float);");
        prepare(statement, "insert into public.batch_test (x, y, z) values (?, ?, ?);");

        const std::size_t elements = 4;

        char xdata[elements][10] = {"this", "is", "a", "test"};
        statement.bind_strings(0, xdata);

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

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

        transact(statement, elements);

        results = execute(connection, "select * from public.batch_test;", 3);
        show(results);

        execute(connection, "drop table if exists public.batch_test;");
    }

    // Dates and Times
    {
        execute(connection, "drop table if exists public.date_test;");
        execute(connection, "create table public.date_test (x datetime);");
        execute(connection, "insert into public.date_test values (current_timestamp);");

        results = execute(connection, "select * from public.date_test;");
        results.next();

        nanodbc::date date = results.get<nanodbc::date>(0);
        cout << endl << date.year << "-" << date.month << "-" << date.day << endl;

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

        execute(connection, "drop table if exists public.date_test;");
    }

    // Inserting NULL values with a sentry
    {
        nanodbc::statement statement(connection);
        prepare(statement, "insert into public.simple_test (a, b) values (?, ?);");

        const int elements = 5;
        const int a_null = 0;
        const char* b_null = "";
        int a_data[elements] = {0, 88, 0, 0, 0};
        char b_data[elements][10] = {"", "non-null", "", "", ""};
```

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

### void prepare(statement &stmt, const string &query, long timeout)

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

Prepares a SQL query for execution on an associated connection.

```APIDOC
## prepare

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

### Parameters
- **stmt** (statement &) - Required - The prepared statement that will be executed in batch.
- **query** (const string &) - Required - The SQL query that will be executed.
- **timeout** (long) - Optional - The number in seconds before query timeout. Default is 0 indicating no timeout.

### Throws
- **programming_error** - Thrown if the statement is not open.
- **database_error** - Thrown if an error occurs during preparation.
```

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

### Get Affected Rows

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

Returns the number of rows affected by the request, or -1 if unavailable. Throws database_error.

```cpp
long affected_rows() const
```

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

### Main Function Entry Point

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

The main function of the application, which checks for the correct number of command-line arguments and initiates the program flow.

```cpp
int main(int argc, char* argv[])
  {
      if (argc != 2)
      {
          char* app_name = std::strrchr(argv[0], '/');
          app_name = app_name ? app_name + 1 : argv[0];
```

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

### connection::connect

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

Establishes a connection to a database using either a DSN or a connection string.

```APIDOC
## [METHOD] connection::connect

### Description
Connects to a data source using provided credentials or a connection string.

### Parameters
#### Path Parameters
- **dsn** (string) - Required - The name of the data source.
- **user** (string) - Required - The username for authentication.
- **pass** (string) - Required - The password for authentication.
- **connection_string** (string) - Required - The connection string for establishing a connection.
- **timeout** (long) - Optional - Seconds before connection timeout. Default is 0.

### Response
#### Success Response (void)
- No return value.

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

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

### Prepare Statement

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

Prepares a statement for execution on a given connection or its associated connection. Allows setting a timeout.

```cpp
void prepare(class connection &conn, const string &query, long timeout = 0)
    
    
    Opens and prepares the given statement to execute on the given connection.  
See also
open()

Parameters
    
  * **conn** – The connection where the statement will be executed.  
  * **query** – The SQL query that will be executed.  
  * **timeout** – The number in seconds before query timeout. Default 0 meaning no timeout. 

Throws
    
database_error –  
```

```cpp
void prepare(const string &query, long timeout = 0)
    
    
    Prepares the given statement to execute its associated connection.  
See also
open()
Note
If the statement is not open throws programming_error.  

Parameters
    
  * **query** – The SQL query that will be executed.  
  * **timeout** – The number in seconds before query timeout. Default 0 meaning no timeout. 

Throws
    
database_error –  
```

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

### Result Set Information

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

Provides methods to get information about the results of a query, such as affected rows and column count.

```APIDOC
## affected_rows

### Description
Returns rows affected by the request or -1 if affected rows is not available.

### Method
long affected_rows() const

### Throws
database_error

## columns

### Description
Returns the number of columns in a result set.

### Method
short columns() const

### Throws
database_error
```

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

### Handling Dates and Times

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

Demonstrates inserting the current timestamp into a datetime column and retrieving it as a nanodbc::date object. It also shows displaying the results.

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

          results = execute(connection, "select * from public.date_test;");
          results.next();

          nanodbc::date date = results.get<nanodbc::date>(0);
          cout << endl << date.year << "-" << date.month << "-" << date.day << endl;

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

          execute(connection, "drop table if exists public.date_test;");
```

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

### Describe Parameters

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

Sets descriptions for parameters in a prepared statement, including index, type, size, and scale.

```cpp
void describe_parameters(const std::vector<short> &idx, const std::vector<short> &type, const std::vector<unsigned long> &size, const std::vector<short> &scale)
```

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

### statement::describe_parameters

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

Describes SQL parameter markers for a prepared statement.

```APIDOC
## [METHOD] statement::describe_parameters

### Description
Describes the SQL type, size, and scale for parameter markers in a prepared SQL query.

### Parameters
#### Request Body
- **idx** (vector<size_t>) - Required - Zero-based indices of parameters.
- **type** (vector<short>) - Required - SQL types for the parameters.
- **size** (vector<unsigned long>) - Required - Sizes for the parameters.
- **scale** (vector<short>) - Required - Decimal precision/scale for the parameters.

### Errors
- **programming_error** - Thrown if the description fails.
```

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

### nanodbc API Overview

Source: https://nanodbc.github.io/nanodbc/_sources/api.rst.txt

This section provides an overview of the nanodbc C++ API, including its namespace and macro conventions.

```APIDOC
## nanodbc C++ API Overview

### Description
nanodbc is a library offering its primary API in the C++ language. All functions and classes provided by the nanodbc library reside in the ``nanodbc`` namespace, and all macros have the prefix ``NANODBC_``.

### Namespace
``nanodbc``

### Macro Prefix
``NANODBC_``

### Doxygen File
.. autodoxygenfile:: nanodbc.h
   :project: nanodbc
```

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

### Transaction Management

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

Illustrates how to use nanodbc transactions. A transaction is automatically rolled back if not explicitly committed.

```cpp
nanodbc::transaction transaction(connection);
              execute(connection, "delete from public.simple_test;");
              // transaction will be rolled back if we don't call transaction.commit()
```

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

### Usage Function

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

A simple function to display the usage instructions for the application, indicating the expected command-line arguments.

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

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

### Comprehensive Database Operations

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

Demonstrates advanced usage including connection variants, direct execution, result access by name or index, and parameter binding.

```cpp
#include <algorithm>
#include <cstring>
#include <iostream>

#include <nanodbc/nanodbc.h>

using namespace std;

void show(nanodbc::result& results);

void run_test(const char* 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 " << connection.driver_name() << endl;

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

    nanodbc::result results;

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

    // Accessing results by name, or column number
    {
        results = execute(
            connection, "select a as first, b as second from public.simple_test where a = 1;");
        results.next();
        cout << endl << results.get<int>("first") << ", " << results.get<string>(1) << endl;
    }

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

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

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

        // Inserting multiple null values
```

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

### Initiate Asynchronous Connection

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

Initiates an asynchronous connection. Requires nanodbc built with ODBC headers and library supporting asynchronous mode. Asynchronous features can be disabled by defining NANODBC_DISABLE_ASYNC.

```cpp
bool async_connect(const string &connection_string, void *event_handle, long timeout = 0)
```

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

### Batch Inserting Data

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

Shows how to perform batch inserts into a table using nanodbc. This involves preparing a statement and then binding arrays of data for multiple rows.

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

          const std::size_t elements = 4;

          char xdata[elements][10] = {"this", "is", "a", "test"};
          statement.bind_strings(0, xdata);

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

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

          transact(statement, elements);

          results = execute(connection, "select * from public.batch_test;", 3);
          show(results);

          execute(connection, "drop table if exists public.batch_test;");
```

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

### Complete Prepare

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

Completes a previously initiated asynchronous query preparation.

```APIDOC
## complete_prepare()

### Description
Completes a previously initiated asynchronous query preparation. This method is only available if nanodbc is built against ODBC headers and a library that supports asynchronous mode.

### Method
`void complete_prepare()`

### Endpoint
N/A (This is a library function)

### Parameters
None

### Throws
* `database_error`

### See Also
* `async_prepare()`
* `NANODBC_DISABLE_ASYNC` (build flag)
```

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

### Execute Prepared Queries

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

Executes a prepared query and returns a result set object. Transactions are recommended for batch operations.

```cpp
class result execute(long batch_operations = 1, long timeout = 0)
```

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

### Execute query directly asynchronously

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

Opens, prepares, and executes a query directly on a connection in asynchronous mode.

```cpp
bool async_execute_direct(class connection &conn, void *event_handle, const string &query, long batch_operations = 1, long timeout = 0)
```

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

### Open Statement

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

Opens a statement for a given connection. Throws database_error on failure.

```cpp
void open(class connection &conn)
    
    
    Creates a statement for the given connection.  

Parameters
    
**conn** – The connection where the statement will be executed.  

Throws
    
database_error –  
```

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

### describe_parameters

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

Sets descriptions for parameters in the prepared statement.

```APIDOC
## describe_parameters

### Description
Sets metadata descriptions for parameters in the prepared statement.

### Parameters
- **idx** (std::vector<short>) - Required - Parameter indices.
- **type** (std::vector<short>) - Required - Parameter types.
- **size** (std::vector<unsigned long>) - Required - Parameter sizes.
- **scale** (std::vector<short>) - Required - Parameter scales.
```

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

### Prepare query asynchronously

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

Initiates a statement preparation in asynchronous mode. Requires ODBC support for asynchronous events.

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

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

### bind

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

Binds multiple values to a parameter placeholder in a prepared statement.

```APIDOC
## bind

### Description
Binds multiple values to a parameter placeholder in a prepared statement.

### Parameters
- **param_index** (short) - Required - Zero-based index of parameter marker.
- **values** (T const *) - Required - Pointer to the values to bind.
- **batch_size** (std::size_t) - Required - The number of elements being bound.
- **direction** (param_direction) - Optional - ODBC parameter direction (default: PARAM_IN).
- **null_sentry** (T const *) - Optional - Value representing NULL.
- **nulls** (bool const *) - Optional - Array indicating which values are NULL.

### Throws
- database_error
```

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

### Execute Test with Exception Handling

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

Wraps test execution in a try-catch block to handle standard exceptions and report errors to standard error.

```cpp
if (0 == std::strncmp(app_name, "lt-", 3))
              app_name += 3; // remove libtool prefix
          usage(std::cerr, app_name);
          return 1;
      }

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

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

### Execute Direct

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

Executes a query directly on the given connection without preparing it first. Supports batch operations and timeouts.

```cpp
class result execute_direct(class connection &conn, const string &query, long batch_operations = 1, long timeout = 0)
    
    
```

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

### Execute prepared query asynchronously

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

Executes a previously prepared query in asynchronous mode.

```cpp
bool async_execute(void *event_handle, long batch_operations = 1, long timeout = 0)
```

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

### Run nanodbc Tests with ctest

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

Execute nanodbc tests using ctest after the build is complete. This provides a generator-agnostic way to run tests.

```bash
ctest -V --output-on-failure

```

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

### Format C++ Code with clang-format

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

Use clang-format to automatically format C++ code according to the project's style guidelines. Ensure all submitted code is auto-formatted.

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

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

### Complete asynchronous preparation

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

Finalizes a previously initiated asynchronous query preparation.

```cpp
void complete_prepare()
```

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

### Inserting NULL Values with Flags

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

Demonstrates inserting NULL values using a boolean array of flags. `true` in the flags array indicates that the corresponding parameter should be treated as NULL.

```cpp
nanodbc::statement statement(connection);
          prepare(statement, "insert into public.simple_test (a, b) values (?, ?);");

          const int elements = 2;
          int a_data[elements] = {0, 42};
          char b_data[elements][10] = {"", "every"};
          bool nulls[elements] = {true, false};

          statement.bind(0, a_data, elements, nulls);
          statement.bind_strings(1, b_data, nulls);

          execute(statement, elements);

          nanodbc::result results = execute(connection, "select * from public.simple_test;");
          show(results);
```

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

### Asynchronous Prepare

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

Prepares a SQL statement asynchronously. This method is available if nanodbc is built with support for asynchronous operations.

```APIDOC
## async_prepare(query, event_handle, timeout)

### Description
Prepares the given statement in asynchronous mode. This method is only available if nanodbc is built against ODBC headers and a library that supports asynchronous mode.

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

### Endpoint
N/A (This is a library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **event_handle** (void*) - Required - The event handle the caller will wait on before calling `complete_prepare`.
* **query** (string) - Required - The SQL query to be prepared.
* **timeout** (long) - Optional - The number of seconds before query timeout. Defaults to 0 (no timeout).

### Throws
* `database_error`

### Returns
* Boolean: `true` if the event handle needs to be awaited, `false` if the result is ready immediately.

### See Also
* `complete_prepare()`
* `NANODBC_DISABLE_ASYNC` (build flag)
```

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

### Statement Constructor

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

Creates a new statement object. Can be used to create an unprepared statement or one associated with a connection and query.

```cpp
statement()
    
    
    Creates a new un-prepared statement.  
See also
execute(), just_execute(), execute_direct(), just_execute_direct(), open(), prepare() 
```

```cpp
explicit statement(class connection &conn)
    
    
    Constructs a statement object and associates it to the given connection.  
See also
open(), prepare() 

Parameters
    
**conn** – The connection to use.  
```

```cpp
statement(class connection &conn, const string &query, long timeout = 0)
    
    
    Constructs and prepares a statement using the given connection and query.  
See also
execute(), just_execute(), execute_direct(), just_execute_direct(), open(), prepare() 

Parameters
    
  * **conn** – The connection to use.  
  * **query** – The SQL query statement.  
  * **timeout** – The number in seconds before query timeout. Default: 0 meaning no timeout. 
```

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

### Asynchronous Execute Direct

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

Opens, prepares, and executes a query directly on a connection in asynchronous mode.

```APIDOC
## async_execute_direct(conn, event_handle, query, batch_operations, timeout)

### Description
Opens, prepares, and executes a query directly on the given connection, in asynchronous mode. This method is only available if nanodbc is built against ODBC headers and a library that supports asynchronous mode.

### Method
`bool async_execute_direct(class connection &conn, void *event_handle, const string &query, long batch_operations = 1, long timeout = 0)`

### Endpoint
N/A (This is a library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **conn** (class connection&) - Required - The connection on which the statement will be executed.
* **event_handle** (void*) - Required - The event handle the caller will wait on before calling `complete_execute`.
* **query** (string) - Required - The SQL query to be executed.
* **batch_operations** (long) - Optional - The number of rows to fetch per rowset, or the number of batch parameters to process. Defaults to 1.
* **timeout** (long) - Optional - The number of seconds before query timeout. Defaults to 0 (no timeout).

### Throws
* `database_error`

### Returns
* Boolean: `true` if the event handle needs to be awaited, `false` if the result is ready immediately.

### Attention
Use transactions for batch operations to prevent auto-commits after each individual operation.

### See Also
* `complete_execute()`
* `open()`
* `prepare()`
* `execute()`
* `result`
* `transaction`
* `NANODBC_DISABLE_ASYNC` (build flag)
```

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

### Execute Prepared Queries Directly

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

Executes a prepared query without constructing a result object. Use transactions to prevent auto-commits during batch operations.

```cpp
void just_execute_direct(class connection &conn, const string &query, long batch_operations = 1, long timeout = 0)
```

```cpp
void just_execute(long batch_operations = 1, long timeout = 0)
```

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

### Fetch First Row

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

Fetches the first row in the current result set. Throws database_error.

```cpp
bool first()
```

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

### Retrieve Database Information

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

Retrieves information from the ODBC connection, such as DBMS name or version. Uses the SQLGetInfo function.

```cpp
template<class T>
T get_info(short info_type) const
```

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

### Bind Parameters to Prepared Statement

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

Binds a value to a specific placeholder index in a prepared statement. Not suitable for batch operations.

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

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

### Show Results Function

Source: https://nanodbc.github.io/nanodbc/_sources/use.rst.txt

A helper function to display the results of a query, including column names and row data. It handles 'null' values by displaying them as the string 'null'.

```cpp
void show(nanodbc::result& results)
  {
      const short columns = results.columns();
      long rows_displayed = 0;

      cout << "\nDisplaying " << results.affected_rows() << " rows "
          << "(" << results.rowset_size() << " fetched at a time):" << endl;

      // show the column names
      cout << "row\t";
      for (short i = 0; i < columns; ++i)
          cout << results.column_name(i) << "\t";
      cout << endl;

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

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

### Driver and Datasource Listing

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

Functions to retrieve a list of available ODBC drivers and configured data sources on the system.

```APIDOC
## List Drivers and Datasources

### Description
Functions to retrieve lists of ODBC drivers and data sources available on the system.

### Functions

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

Returns a list of ODBC drivers on your system.

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

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

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

### Buffer Management

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

Methods for managing data buffers for columns.

```APIDOC
## Unbind Methods

### Methods
- **unbind()**: Unbinds data buffers for all columns.
- **unbind(const string &column_name)**: Unbinds data buffer for a specific column by name.
- **unbind(short column)**: Unbinds data buffer for a specific column by index.

### Errors
- **index_range_error**: Thrown if the column index or name is invalid.
```

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

### Connection Status and Information

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

Provides methods to check the connection status and retrieve database information.

```APIDOC
## GET /api/connection/status

### Description
Returns true if connected to the database.

### Method
GET

### Endpoint
/api/connection/status

### Parameters
None

### Response
#### Success Response (200)
- **connected** (boolean) - true if connected to the database.

### Response Example
```json
{
  "connected": true
}
```
```

```APIDOC
## GET /api/connection/transactions

### Description
Returns the number of transactions currently held for this connection.

### Method
GET

### Endpoint
/api/connection/transactions

### Parameters
None

### Response
#### Success Response (200)
- **transactions** (size_t) - The number of transactions currently held.

### Response Example
```json
{
  "transactions": 2
}
```
```

```APIDOC
## GET /api/connection/native_dbc_handle

### Description
Returns the native ODBC database connection handle.

### Method
GET

### Endpoint
/api/connection/native_dbc_handle

### Parameters
None

### Response
#### Success Response (200)
- **handle** (void*) - The native ODBC database connection handle.

### Response Example
```json
{
  "handle": "0x87654321"
}
```
```

```APIDOC
## GET /api/connection/native_env_handle

### Description
Returns the native ODBC environment handle.

### Method
GET

### Endpoint
/api/connection/native_env_handle

### Parameters
None

### Response
#### Success Response (200)
- **handle** (void*) - The native ODBC environment handle.

### Response Example
```json
{
  "handle": "0x11223344"
}
```
```

```APIDOC
## GET /api/connection/info

### Description
Returns information from the ODBC connection as a string or fixed-size value. The general information about the driver and data source associated with a connection is obtained using `SQLGetInfo` function.

### Method
GET

### Endpoint
/api/connection/info

### Parameters
#### Query Parameters
- **info_type** (short) - Required - The ODBC information type to query.

### Response
#### Success Response (200)
- **value** (string or other type) - The requested information value.

### Response Example
```json
{
  "value": "SQLite3 ODBC Driver"
}
```

### Throws
- **database_error**
```

```APIDOC
## GET /api/connection/dbms_name

### Description
Returns the name of the DBMS product. Returns the ODBC information type SQL_DBMS_NAME of the DBMS product accessed by the driver via the current connection.

### Method
GET

### Endpoint
/api/connection/dbms_name

### Parameters
None

### Response
#### Success Response (200)
- **dbms_name** (string) - The name of the DBMS product.

### Response Example
```json
{
  "dbms_name": "SQLite"
}
```

### Throws
- **database_error**
```

```APIDOC
## GET /api/connection/dbms_version

### Description
Returns the version of the DBMS product. Returns the ODBC information type SQL_DBMS_VER of the DBMS product accessed by the driver via the current connection.

### Method
GET

### Endpoint
/api/connection/dbms_version

### Parameters
None

### Response
#### Success Response (200)
- **dbms_version** (string) - The version of the DBMS product.

### Response Example
```json
{
  "dbms_version": "3.36.0"
}
```

### Throws
- **database_error**
```

```APIDOC
## GET /api/connection/driver_name

### Description
Returns the name of the ODBC driver.

### Method
GET

### Endpoint
/api/connection/driver_name

### Parameters
None

### Response
#### Success Response (200)
- **driver_name** (string) - The name of the ODBC driver.

### Response Example
```json
{
  "driver_name": "SQLite3 ODBC Driver"
}
```

### Throws
- **database_error**
```

```APIDOC
## GET /api/connection/database_name

### Description
Returns the name of the currently connected database. Returns the current SQL_DATABASE_NAME information value associated with the connection.

### Method
GET

### Endpoint
/api/connection/database_name

### Parameters
None

### Response
#### Success Response (200)
- **database_name** (string) - The name of the currently connected database.

### Response Example
```json
{
  "database_name": "main"
}
```

### Throws
- **database_error**
```

```APIDOC
## GET /api/connection/catalog_name

### Description
Returns the name of the current catalog. Returns the current setting of the connection attribute SQL_ATTR_CURRENT_CATALOG.

### Method
GET

### Endpoint
/api/connection/catalog_name

### Parameters
None

### Response
#### Success Response (200)
- **catalog_name** (string) - The name of the current catalog.

### Response Example
```json
{
  "catalog_name": "main"
}
```
```