nanodbc.h

Go to the documentation of this file.

 
 
 
#ifndef NANODBC_NANODBC_H
#define NANODBC_NANODBC_H
 
#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 requires C++17, so these always hold. They are still defined, so that code
// written against an earlier release and asking whether the feature is there keeps
// compiling; new code has no reason to ask.
#define NANODBC_HAS_STD_STRING_VIEW
#define NANODBC_HAS_STD_OPTIONAL
#define NANODBC_HAS_STD_VARIANT
#define NANODBC_HAS_STD_ANY
 
namespace nanodbc
{
 
// clang-format off
//  .d8888b.                     .d888 d8b                                   888    d8b
// d88P  Y88b                   d88P"  Y8P                                   888    Y8P
// 888    888                   888                                          888
// 888         .d88b.  88888b.  888888 888  .d88b.  888  888 888d888 8888b.  888888 888  .d88b.  88888b.
// 888        d88""88b 888 "88b 888    888 d88P"88b 888  888 888P"      "88b 888    888 d88""88b 888 "88b
// 888    888 888  888 888  888 888    888 888  888 888  888 888    .d888888 888    888 888  888 888  888
// Y88b  d88P Y88..88P 888  888 888    888 Y88b 888 Y88b 888 888    888  888 Y88b.  888 Y88..88P 888  888
//  "Y8888P"   "Y88P"  888  888 888    888  "Y88888  "Y88888 888    "Y888888  "Y888 888  "Y88P"  888  888
//                                              888
//                                         Y8b d88P
//                                          "Y88P"
// MARK: Configuration -
// clang-format on
 
#ifdef DOXYGEN
 
#define NANODBC_THROW_NO_SOURCE_LOCATION 1
 
#define NANODBC_ASSERT(expression) assert(expression)
 
#endif
 
// You must explicitly request Unicode support by defining NANODBC_ENABLE_UNICODE at compile time.
// NANODBC_ENABLE_UTF8 keeps string narrow, holding UTF-8, and calls the wide ODBC functions.
#if defined(NANODBC_ENABLE_UNICODE) && defined(NANODBC_ENABLE_UTF8)
#error "NANODBC_ENABLE_UNICODE and NANODBC_ENABLE_UTF8 are alternatives; define one"
#endif
#ifndef DOXYGEN
#ifdef NANODBC_ENABLE_UNICODE
#ifdef NANODBC_USE_IODBC_WIDE_STRINGS
#define NANODBC_TEXT(s) U##s
using string = std::u32string;
using string_view = std::u32string_view;
#else
#ifdef _MSC_VER
using string = std::wstring;
using string_view = std::wstring_view;
#define NANODBC_TEXT(s) L##s
#else
using string = std::u16string;
using string_view = std::u16string_view;
#define NANODBC_TEXT(s) u##s
#endif
#endif
#else
using string = std::string;
using string_view = std::string_view;
#define NANODBC_TEXT(s) s
#endif
 
#ifdef NANODBC_USE_IODBC_WIDE_STRINGS
using wide_string = std::u32string;
using wide_string_view = std::u32string_view;
#else
#ifdef _MSC_VER
using wide_string = std::wstring;
using wide_string_view = std::wstring_view;
#else
using wide_string = std::u16string;
using wide_string_view = std::u16string_view;
#endif
#endif
 
using wide_char_t = wide_string::value_type;
 
#if defined(_WIN64)
// LLP64 machine: Windows
using null_type = std::int64_t;
#elif !defined(_WIN64) && defined(__LP64__)
// LP64 machine: OS X or Linux
using null_type = long;
#else
// 32-bit machine
using null_type = long;
#endif
#else
#define NANODBC_TEXT(s) s
 
typedef unspecified - type string;
typedef unspecified - type null_type;
#endif
 
#define NANODBC_DEPRECATED [[deprecated]]
 
// forward declare
#ifndef NANODBC_DISABLE_MSSQL_TVP
class table_valued_parameter;
#endif
class statement;
class connection;
class transaction;
class catalog;
class result;
 
// clang-format off
// 8888888888                                      888    888                        888 888 d8b
// 888                                             888    888                        888 888 Y8P
// 888                                             888    888                        888 888
// 8888888    888d888 888d888 .d88b.  888d888      8888888888  8888b.  88888b.   .d88888 888 888 88888b.   .d88b.
// 888        888P"   888P"  d88""88b 888P"        888    888     "88b 888 "88b d88" 888 888 888 888 "88b d88P"88b
// 888        888     888    888  888 888          888    888 .d888888 888  888 888  888 888 888 888  888 888  888
// 888        888     888    Y88..88P 888          888    888 888  888 888  888 Y88b 888 888 888 888  888 Y88b 888
// 8888888888 888     888     "Y88P"  888          888    888 "Y888888 888  888  "Y88888 888 888 888  888  "Y88888
//                                                                                                             888
//                                                                                                        Y8b d88P
//                                                                                                         "Y88P"
// MARK: Error Handling -
// clang-format on
 
 
class type_incompatible_error : public std::runtime_error
{
public:
    type_incompatible_error();
 
    char const* what() const noexcept override;
};
 
class null_access_error : public std::runtime_error
{
public:
    null_access_error();
 
    char const* what() const noexcept override;
};
 
class index_range_error : public std::runtime_error
{
public:
    index_range_error();
 
    char const* what() const noexcept override;
};
 
class programming_error : public std::runtime_error
{
public:
    explicit programming_error(std::string const& info);
 
    char const* what() const noexcept override;
};
 
class database_error : public std::runtime_error
{
public:
    database_error(void* handle, short handle_type, std::string const& info = "");
 
    char const* what() const noexcept override;
 
    long native() const noexcept;
 
    std::string const& state() const noexcept;
 
private:
    long native_error;
    std::string sql_state;
    std::string message;
};
 
 
// clang-format off
// 888     888 888    d8b 888 d8b 888    d8b
// 888     888 888    Y8P 888 Y8P 888    Y8P
// 888     888 888        888     888
// 888     888 888888 888 888 888 888888 888  .d88b.  .d8888b
// 888     888 888    888 888 888 888    888 d8P  Y8b 88K
// 888     888 888    888 888 888 888    888 88888888 "Y8888b.
// Y88b. .d88P Y88b.  888 888 888 Y88b.  888 Y8b.          X88
//  "Y88888P"   "Y888 888 888 888  "Y888 888  "Y8888   88888P'
// MARK: Utilities -
// clang-format on
 
 
struct batch_ops
{
    long parameter_array_length{-1}; 
    long rowset_size{-1};            
 
    batch_ops() = default;
 
    batch_ops(const long all_length) noexcept
        : parameter_array_length(all_length)
        , rowset_size(all_length) {};
};
 
struct date
{
    std::int16_t year;  
    std::int16_t month; 
    std::int16_t day;   
};
 
struct time
{
    std::int16_t hour; 
    std::int16_t min;  
    std::int16_t sec;  
};
 
struct timestamp
{
    std::int16_t year;  
    std::int16_t month; 
    std::int16_t day;   
    std::int16_t hour;  
    std::int16_t min;   
    std::int16_t sec;   
    std::int32_t fract; 
};
 
struct timestampoffset
{
    timestamp stamp;            
    std::int16_t offset_hour;   
    std::int16_t offset_minute; 
};
 
//  `SQLSetConnectAttr`, or `SQLSetStmtAttr`.  The second is the StringLength,
//  and the third is used to inform the ValuePtr argument.  This argument,
class attribute
{
public:
#ifdef NANODBC_ENABLE_UNICODE
    using variant =
        std::variant<std::vector<uint8_t>, string, std::string, std::intptr_t, std::uintptr_t>;
#else
    using variant = std::variant<std::vector<uint8_t>, string, std::intptr_t, std::uintptr_t>;
#endif
    attribute() = delete;
    attribute& operator=(attribute const&) = delete;
 
    attribute(attribute const& other) noexcept;
 
    attribute(long const& attribute, long const& string_length, variant resource) noexcept;
 
protected:
    void extractValuePtr() noexcept;
 
    long attribute_;     
    long string_length_; 
    variant resource_;   
    void* value_ptr_{};  
};
 
template <typename T>
using is_string = std::bool_constant<
    std::is_same_v<std::decay_t<T>, std::string> || std::is_same_v<std::decay_t<T>, wide_string> ||
    std::is_same_v<std::decay_t<T>, std::string_view> ||
    std::is_same_v<std::decay_t<T>, wide_string_view>>;
 
template <typename T>
inline constexpr bool is_string_v = is_string<T>::value;
 
template <typename T>
using is_owning_string = std::bool_constant<
    std::is_same_v<std::decay_t<T>, std::string> || std::is_same_v<std::decay_t<T>, wide_string>>;
 
template <typename T>
inline constexpr bool is_owning_string_v = is_owning_string<T>::value;
 
template <typename T>
using is_character = std::bool_constant<
    std::is_same_v<std::decay_t<T>, std::string::value_type> ||
    std::is_same_v<std::decay_t<T>, wide_char_t>>;
 
template <typename T>
inline constexpr bool is_character_v = is_character<T>::value;
 
template <typename T>
using enable_if_string = std::enable_if_t<is_string_v<T>>;
 
template <typename T>
using enable_if_character = std::enable_if_t<is_character_v<T>>;
 
namespace detail
{
 
template <class T>
std::unique_ptr<bool[]>
split_optional(std::vector<std::optional<T>> const& values, std::vector<T>& column)
{
    auto nulls = std::make_unique<bool[]>(values.size());
    column.reserve(values.size());
    std::size_t i = 0;
    for (auto const& value : values)
    {
        nulls[i++] = !value.has_value();
        column.push_back(value ? *value : T());
    }
    return nulls;
}
 
} // namespace detail
 
 
 
// clang-format off
// 88888888888                                                  888    d8b
//     888                                                      888    Y8P
//     888                                                      888
//     888  888d888 8888b.  88888b.  .d8888b   8888b.   .d8888b 888888 888  .d88b.  88888b.
//     888  888P"      "88b 888 "88b 88K          "88b d88P"    888    888 d88""88b 888 "88b
//     888  888    .d888888 888  888 "Y8888b. .d888888 888      888    888 888  888 888  888
//     888  888    888  888 888  888      X88 888  888 Y88b.    Y88b.  888 Y88..88P 888  888
//     888  888    "Y888888 888  888  88888P' "Y888888  "Y8888P  "Y888 888  "Y88P"  888  888
// MARK: Transaction -
// clang-format on
 
class transaction
{
public:
    explicit transaction(const class connection& conn);
 
    void swap(transaction& rhs) noexcept;
 
    void commit();
 
    void rollback() noexcept;
 
    class connection& connection() noexcept;
 
    const class connection& connection() const noexcept;
 
    operator class connection &() noexcept;
 
    operator const class connection &() const noexcept;
 
private:
    class transaction_impl;
    friend class nanodbc::connection;
 
private:
    std::shared_ptr<transaction_impl> impl_;
};
 
// clang-format off
// 888b     d888  .d8888b.   .d8888b.   .d88888b.  888                       88888888888 888     888 8888888b.
// 8888b   d8888 d88P  Y88b d88P  Y88b d88P" "Y88b 888                           888     888     888 888   Y88b
// 88888b.d88888 Y88b.      Y88b.      888     888 888                           888     888     888 888    888
// 888Y88888P888  "Y888b.    "Y888b.   888     888 888                           888     Y88b   d88P 888   d88P
// 888 Y888P 888     "Y88b.     "Y88b. 888     888 888                           888      Y88b d88P  8888888P"
// 888  Y8P  888       "888       "888 888 Y8b 888 888           888888          888       Y88o88P   888
// 888   "   888 Y88b  d88P Y88b  d88P Y88b.Y8b88P 888                           888        Y888P    888
// 888       888  "Y8888P"   "Y8888P"   "Y888888"  88888888                      888         Y8P     888
//                                            Y8b
// MARK: MSSQL - TVP (Table Valued Parameters) -
// clang-format on
#ifndef NANODBC_DISABLE_MSSQL_TVP
class table_valued_parameter
{
public:
    table_valued_parameter();
 
    table_valued_parameter(const table_valued_parameter&) = default;
    table_valued_parameter(table_valued_parameter&&) = default;
    void operator=(const table_valued_parameter&) = delete;
    void operator=(table_valued_parameter&&) = delete;
 
    table_valued_parameter(statement& stmt, short param_index, size_t row_count);
 
    void open(statement& stmt, short param_index, std::size_t row_count);
 
    void close();
 
 
    template <class T>
    void bind(short param_index, T const* values, std::size_t batch_size);
 
    template <class T>
    void bind(short param_index, T const* values, std::size_t batch_size, T const* null_sentry);
 
    template <class T>
    void bind(short param_index, T const* values, std::size_t batch_size, bool const* nulls);
 
    void bind(short param_index, std::vector<std::vector<uint8_t>> const& values);
 
    void
    bind(short param_index, std::vector<std::vector<uint8_t>> const& values, bool const* nulls);
 
    NANODBC_DEPRECATED void bind(
        short param_index,
        std::vector<std::vector<uint8_t>> const& values,
        uint8_t const* null_sentry);
 
    void bind(
        short param_index,
        std::vector<std::vector<uint8_t>> const& values,
        std::vector<uint8_t> const& null_sentry);
 
 
 
    template <class T, typename = enable_if_character<T>>
    void bind_strings(
        short param_index,
        T const* values,
        std::size_t value_size,
        std::size_t batch_size);
 
    template <class T, typename = enable_if_string<T>>
    void bind_strings(short param_index, std::vector<T> const& values);
 
    template <
        std::size_t BatchSize,
        std::size_t ValueSize,
        class T,
        typename = enable_if_character<T>>
    void bind_strings(short param_index, T const (&values)[BatchSize][ValueSize])
    {
        auto param_values = reinterpret_cast<T const*>(values);
        bind_strings(param_index, param_values, ValueSize, BatchSize);
    }
 
    template <class T, typename = enable_if_character<T>>
    void bind_strings(
        short param_index,
        T const* values,
        std::size_t value_size,
        std::size_t batch_size,
        T const* null_sentry);
 
    template <class T, typename = enable_if_string<T>>
    void bind_strings(
        short param_index,
        std::vector<T> const& values,
        typename T::value_type const* null_sentry);
 
    template <
        std::size_t BatchSize,
        std::size_t ValueSize,
        class T,
        typename = enable_if_character<T>>
    void
    bind_strings(short param_index, T const (&values)[BatchSize][ValueSize], T const* null_sentry)
    {
        auto param_values = reinterpret_cast<T const*>(values);
        bind_strings(param_index, param_values, ValueSize, BatchSize, nullptr, null_sentry);
    }
 
    template <class T, typename = enable_if_character<T>>
    void bind_strings(
        short param_index,
        T const* values,
        std::size_t value_size,
        std::size_t batch_size,
        bool const* nulls);
 
    template <class T, typename = enable_if_string<T>>
    void bind_strings(short param_index, std::vector<T> const& values, bool const* nulls);
 
    template <
        std::size_t BatchSize,
        std::size_t ValueSize,
        class T,
        typename = enable_if_character<T>>
    void bind_strings(short param_index, T const (&values)[BatchSize][ValueSize], bool const* nulls)
    {
        auto param_values = reinterpret_cast<T const*>(values);
        bind_strings(param_index, param_values, ValueSize, BatchSize, nulls);
    }
 
 
    void bind_null(short param_index);
 
    void describe_parameters(
        const std::vector<short>& idx,
        const std::vector<short>& type,
        const std::vector<unsigned long>& size,
        const std::vector<short>& scale);
 
    short parameters() const noexcept;
 
    unsigned long parameter_size(short param_index) const;
 
    short parameter_scale(short param_index) const;
 
    short parameter_type(short param_index) const;
 
private:
    class table_valued_parameter_impl;
    friend class statement;
 
private:
    std::shared_ptr<table_valued_parameter_impl> impl_;
};
#endif // NANODBC_DISABLE_MSSQL_TVP
 
// clang-format off
//  .d8888b.  888             888                                            888
// d88P  Y88b 888             888                                            888
// Y88b.      888             888                                            888
//  "Y888b.   888888  8888b.  888888 .d88b.  88888b.d88b.   .d88b.  88888b.  888888
//     "Y88b. 888        "88b 888   d8P  Y8b 888 "888 "88b d8P  Y8b 888 "88b 888
//       "888 888    .d888888 888   88888888 888  888  888 88888888 888  888 888
// Y88b  d88P Y88b.  888  888 Y88b. Y8b.     888  888  888 Y8b.     888  888 Y88b.
//  "Y8888P"   "Y888 "Y888888  "Y888 "Y8888  888  888  888  "Y8888  888  888  "Y888
// MARK: Statement -
// clang-format on
 
class statement
{
 
private:
    class statement_impl;
 
public:
    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::statement::statement_impl;
    };
 
public:
    enum param_direction
    {
        PARAM_IN,    
        PARAM_OUT,   
        PARAM_INOUT, 
        PARAM_RETURN
    };
 
public:
    statement();
 
    explicit statement(class connection& conn);
 
    explicit statement(class connection& conn, std::list<attribute> const& attributes);
 
    statement(class connection& conn, string const& query, long timeout = 0);
 
    void swap(statement& rhs) noexcept;
 
    void open(class connection& conn);
 
    [[nodiscard]] bool open() const noexcept;
 
    [[nodiscard]] bool connected() const noexcept;
 
    class connection& connection() noexcept;
 
    const class connection& connection() const noexcept;
 
    [[nodiscard]] void* native_statement_handle() const noexcept;
 
    void close();
 
    void cancel();
 
    void prepare(class connection& conn, string const& query, long timeout = 0);
 
    void prepare(string const& query, long timeout = 0);
 
    void timeout(long timeout = 0);
 
    class result execute_direct(
        class connection& conn,
        string const& query,
        long batch_operations = 1,
        long timeout = 0);
 
    class result execute_direct(
        class connection& conn,
        string const& query,
        batch_ops const& array_sizes,
        long timeout = 0);
 
#if !defined(NANODBC_DISABLE_ASYNC)
    bool async_prepare(string const& query, void* event_handle, long timeout = 0);
 
    void complete_prepare();
 
    bool async_execute_direct(
        class connection& conn,
        void* event_handle,
        string const& query,
        long batch_operations = 1,
        long timeout = 0);
 
    bool async_execute(void* event_handle, long batch_operations = 1, long timeout = 0);
 
    class result complete_execute(long batch_operations = 1);
 
    void enable_async(void* event_handle);
 
    void disable_async() const;
#endif
 
    void just_execute_direct(
        class connection& conn,
        string const& query,
        long batch_operations = 1,
        long timeout = 0);
 
    class result execute(long batch_operations = 1, long timeout = 0);
 
    class result execute(batch_ops const& array_sizes, long timeout = 0);
 
    void just_execute(long batch_operations = 1, long timeout = 0);
 
    class result procedure_columns(
        string const& catalog,
        string const& schema,
        string const& procedure,
        string const& column);
 
    [[nodiscard]] long affected_rows() const;
 
    [[nodiscard]] short columns() const;
 
    void reset_parameters() noexcept;
 
    short parameters() const;
 
    unsigned long parameter_size(short param_index) const;
 
    short parameter_scale(short param_index) const;
 
    short parameter_type(short param_index) const;
 
    bool parameter_is_null(short param_index, std::size_t batch_index = 0) const;
 
 
    template <class T>
    void bind(short param_index, T const* value, param_direction direction = PARAM_IN);
 
    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);
    }
 
 
    template <class T>
    void bind(
        short param_index,
        T const* values,
        std::size_t batch_size,
        param_direction direction = PARAM_IN);
 
    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);
 
    template <class T>
    void bind(
        short param_index,
        T const* values,
        std::size_t batch_size,
        bool const* nulls,
        param_direction direction = PARAM_IN);
 
    void bind(
        short param_index,
        std::vector<std::vector<uint8_t>> const& values,
        param_direction direction = PARAM_IN);
 
    void bind(
        short param_index,
        std::vector<std::vector<uint8_t>> const& values,
        bool const* nulls,
        param_direction direction = PARAM_IN);
 
    NANODBC_DEPRECATED void bind(
        short param_index,
        std::vector<std::vector<uint8_t>> const& values,
        uint8_t const* null_sentry,
        param_direction direction = PARAM_IN);
 
    void bind(
        short param_index,
        std::vector<std::vector<uint8_t>> const& values,
        std::vector<uint8_t> const& null_sentry,
        param_direction direction = PARAM_IN);
 
    template <class T>
    void
    bind(short param_index, std::vector<T> const& values, param_direction direction = PARAM_IN);
 
    template <class T>
    void bind(
        short param_index,
        std::vector<T> const& values,
        bool const* nulls,
        param_direction direction = PARAM_IN);
 
    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);
    }
 
 
 
    template <class T, typename = enable_if_character<T>>
    void bind_strings(
        short param_index,
        T const* values,
        std::size_t value_size,
        std::size_t batch_size,
        param_direction direction = PARAM_IN);
 
    template <class T, typename = enable_if_string<T>>
    void bind_strings(
        short param_index,
        std::vector<T> const& values,
        param_direction direction = PARAM_IN);
 
    template <
        std::size_t BatchSize,
        std::size_t ValueSize,
        class T,
        typename = enable_if_character<T>>
    void bind_strings(
        short param_index,
        T const (&values)[BatchSize][ValueSize],
        param_direction direction = PARAM_IN)
    {
        auto param_values = reinterpret_cast<T const*>(values);
        bind_strings(param_index, param_values, ValueSize, BatchSize, direction);
    }
 
    template <class T, typename = enable_if_character<T>>
    void bind_strings(
        short param_index,
        T const* values,
        std::size_t value_size,
        std::size_t batch_size,
        T const* null_sentry,
        param_direction direction = PARAM_IN);
 
    template <class T, typename = enable_if_string<T>>
    void bind_strings(
        short param_index,
        std::vector<T> const& values,
        typename T::value_type const* null_sentry,
        param_direction direction = PARAM_IN);
 
    template <
        std::size_t BatchSize,
        std::size_t ValueSize,
        class T,
        typename = enable_if_character<T>>
    void bind_strings(
        short param_index,
        T const (&values)[BatchSize][ValueSize],
        T const* null_sentry,
        param_direction direction = PARAM_IN)
    {
        auto param_values = reinterpret_cast<T const*>(values);
        bind_strings(param_index, param_values, ValueSize, BatchSize, null_sentry, direction);
    }
 
    template <class T, typename = enable_if_character<T>>
    void bind_strings(
        short param_index,
        T const* values,
        std::size_t value_size,
        std::size_t batch_size,
        bool const* nulls,
        param_direction direction = PARAM_IN);
 
    template <class T, typename = enable_if_string<T>>
    void bind_strings(
        short param_index,
        std::vector<T> const& values,
        bool const* nulls,
        param_direction direction = PARAM_IN);
 
    template <
        std::size_t BatchSize,
        std::size_t ValueSize,
        class T,
        typename = enable_if_character<T>>
    void bind_strings(
        short param_index,
        T const (&values)[BatchSize][ValueSize],
        bool const* nulls,
        param_direction direction = PARAM_IN)
    {
        auto param_values = reinterpret_cast<T const*>(values);
        bind_strings(param_index, param_values, ValueSize, BatchSize, nulls, direction);
    }
 
    template <class T, typename = enable_if_string<T>>
    void bind_strings(
        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_strings(param_index, column, nulls.get(), direction);
    }
 
 
    void bind_null(short param_index, std::size_t batch_size = 1);
 
 
    void describe_parameters(
        const std::vector<short>& idx,
        const std::vector<short>& type,
        const std::vector<unsigned long>& size,
        const std::vector<short>& scale);
 
private:
    using null_predicate_type = std::function<bool(std::size_t)>;
    friend class nanodbc::result;
#ifndef NANODBC_DISABLE_MSSQL_TVP
    friend class nanodbc::table_valued_parameter::table_valued_parameter_impl;
#endif
 
private:
    std::shared_ptr<statement_impl> impl_;
};
 
// clang-format off
//  .d8888b.                                               888    d8b
// d88P  Y88b                                              888    Y8P
// 888    888                                              888
// 888         .d88b.  88888b.  88888b.   .d88b.   .d8888b 888888 888  .d88b.  88888b.
// 888        d88""88b 888 "88b 888 "88b d8P  Y8b d88P"    888    888 d88""88b 888 "88b
// 888    888 888  888 888  888 888  888 88888888 888      888    888 888  888 888  888
// Y88b  d88P Y88..88P 888  888 888  888 Y8b.     Y88b.    Y88b.  888 Y88..88P 888  888
//  "Y8888P"   "Y88P"  888  888 888  888  "Y8888   "Y8888P  "Y888 888  "Y88P"  888  888
// MARK: Connection -
// clang-format on
 
class connection
{
 
private:
    class connection_impl;
    friend class nanodbc::transaction::transaction_impl;
 
public:
    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;
    };
 
public:
    connection();
 
    void swap(connection&) noexcept;
 
    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);
 
    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);
#if !defined(NANODBC_DISABLE_ASYNC)
    bool async_connect(
        string const& dsn,
        string const& user,
        string const& pass,
        void* event_handle,
        long timeout = 0);
 
    bool async_connect(string const& connection_string, void* event_handle, long timeout = 0);
 
    void async_complete();
#endif
 
    [[nodiscard]] bool connected() const noexcept;
 
    void disconnect();
 
    [[nodiscard]] std::size_t transactions() const noexcept;
 
    [[nodiscard]] void* native_dbc_handle() const noexcept;
 
    [[nodiscard]] void* native_env_handle() const noexcept;
 
    template <class T>
    T get_info(short info_type) const;
 
    string dbms_name() const;
 
    string dbms_version() const;
 
    string driver_name() const;
 
    string driver_version() const;
 
    string database_name() const;
 
    string catalog_name() const;
 
private:
    std::size_t ref_transaction() noexcept;
    std::size_t unref_transaction() noexcept;
    bool rollback() const noexcept;
    void rollback(bool onoff) noexcept;
    bool restore_autocommit() const noexcept;
    void restore_autocommit(bool onoff) noexcept;
 
private:
    std::shared_ptr<connection_impl> impl_;
};
 
// clang-format off
// 8888888b.                            888 888
// 888   Y88b                           888 888
// 888    888                           888 888
// 888   d88P .d88b.  .d8888b  888  888 888 888888
// 8888888P" d8P  Y8b 88K      888  888 888 888
// 888 T88b  88888888 "Y8888b. 888  888 888 888
// 888  T88b Y8b.          X88 Y88b 888 888 Y88b.
// 888   T88b "Y8888   88888P'  "Y88888 888  "Y888
// MARK: Result -
// clang-format on
 
class catalog;
class variant_row_cached_result;
 
class result
{
public:
    result() = default;
 
    void swap(result& rhs) noexcept;
 
    [[nodiscard]] void* native_statement_handle() const noexcept;
 
    [[nodiscard]] long rowset_size() const noexcept;
 
    [[nodiscard]] long affected_rows() const;
 
    bool has_affected_rows() const;
 
    [[nodiscard]] long rows() const noexcept;
 
    [[nodiscard]] short columns() const;
 
    [[nodiscard]] bool first();
 
    [[nodiscard]] bool last();
 
    [[nodiscard]] bool next();
 
#if !defined(NANODBC_DISABLE_ASYNC)
    bool async_next(void* event_handle);
 
    bool complete_next();
#endif
 
    [[nodiscard]] bool prior();
 
    [[nodiscard]] bool move(long row);
 
    [[nodiscard]] bool skip(long rows);
 
    unsigned long position() const;
 
    bool at_end() const noexcept;
 
    void unbind();
 
    void unbind(string const& column_name);
 
    void unbind(short column);
 
 
    template <class T>
    void get_ref(short column, T& result) const;
 
    template <class T>
    void get_ref(short column, T const& fallback, T& result) const;
 
    template <class T>
    void get_ref(string const& column_name, T& result) const;
 
    template <class T>
    void get_ref(string const& column_name, T const& fallback, T& result) const;
 
    template <class T>
    [[nodiscard]] T get(short column) const;
 
    template <class T>
    [[nodiscard]] T get(short column, T const& fallback) const;
 
    template <class T>
    [[nodiscard]] T get_as(short column) const;
 
    template <class T>
    [[nodiscard]] T get_as(string const& column_name) const;
 
    template <class T>
    [[nodiscard]] T get(string const& column_name) const;
 
    template <class T>
    [[nodiscard]] T get(string const& column_name, T const& fallback) const;
 
 
    template <class T>
    bool get_chunks(
        short column,
        std::function<void(T const&)> const& callback,
        std::size_t chunk_size = 65536) const;
 
    template <class T>
    bool get_chunks(
        string const& column_name,
        std::function<void(T const&)> const& callback,
        std::size_t chunk_size = 65536) const;
 
    [[nodiscard]] bool is_null(short column) const;
 
    [[nodiscard]] bool is_null(string const& column_name) const;
 
    bool is_bound(short column) const;
 
    bool is_bound(string const& column_name) const;
 
    [[nodiscard]] short column(string const& column_name) const;
 
    [[nodiscard]] string column_name(short column) const;
 
    [[nodiscard]] long column_size(short column) const;
 
    [[nodiscard]] long column_size(string const& column_name) const;
 
    int column_decimal_digits(short column) const;
 
    int column_decimal_digits(string const& column_name) const;
 
    [[nodiscard]] int column_datatype(short column) const;
 
    [[nodiscard]] int column_datatype(string const& column_name) const;
 
    string column_datatype_name(short column) const;
 
    string column_datatype_name(string const& column_name) const;
 
    int column_c_datatype(short column) const;
 
    int column_c_datatype(string const& column_name) const;
 
    bool column_unsigned(short column) const;
 
    bool column_unsigned(string const& column_name) const;
 
    bool next_result();
 
    [[nodiscard]] explicit operator bool() const noexcept;
 
private:
    result(statement statement, long rowset_size);
 
    class result_impl;
    friend class nanodbc::statement::statement_impl;
    friend class nanodbc::catalog;
#ifdef _MSC_VER
    friend class nanodbc::variant_row_cached_result;
#endif
 
private:
    std::shared_ptr<result_impl> impl_;
};
 
class result_iterator
{
public:
    using iterator_category = std::input_iterator_tag; 
    using value_type = result;                         
    using pointer = result*;                           
    using reference = result&;                         
    using difference_type = std::ptrdiff_t;            
 
    result_iterator() = default;
 
    explicit result_iterator(result& r)
        : result_{r}
    {
        ++*this;
    }
 
    reference operator*() const noexcept { return result_; }
 
    pointer operator->() const
    {
        if (!result_)
            throw std::runtime_error("result is empty");
        return &operator*();
    }
 
    result_iterator& operator++()
    {
        try
        {
            if (!result_.next())
                result_ = {};
        }
        catch (...)
        {
            result_ = {};
        }
        return *this;
    }
 
    void operator++(int) { ++*this; }
 
    bool operator==(result_iterator const& rhs) const noexcept
    {
        if (result_ && rhs.result_)
            return result_.native_statement_handle() == rhs.result_.native_statement_handle();
        else
            return !result_ && !rhs.result_;
    }
 
    bool operator!=(result_iterator const& rhs) const noexcept { return !(*this == rhs); }
 
private:
    mutable result result_;
};
 
inline result_iterator begin(result& r)
{
    return result_iterator(r);
}
 
inline result_iterator end(result& /*r*/) noexcept
{
    return {};
}
 
// clang-format off
// 8888888b.                                     d8b          888
// 888  "Y88b                                    Y8P          888
// 888    888                                                 888
// 888    888  .d88b.  .d8888b   .d8888b 888d888 888 88888b.  888888 .d88b.  888d888 .d8888b
// 888    888 d8P  Y8b 88K      d88P"    888P"   888 888 "88b 888   d88""88b 888P"   88K
// 888    888 88888888 "Y8888b. 888      888     888 888  888 888   888  888 888     "Y8888b.
// 888  .d88P Y8b.          X88 Y88b.    888     888 888 d88P Y88b. Y88..88P 888          X88
// 8888888P"   "Y8888   88888P'  "Y8888P 888     888 88888P"   "Y888 "Y88P"  888      88888P'
//                                                   888
//                                                   888
//                                                   888
// MARK: Descriptors -
// clang-format on
 
class implementation_row_descriptor
{
public:
    implementation_row_descriptor(result const& result);
 
    implementation_row_descriptor(statement const& statement);
 
    auto alloc_type() const -> short;
 
    auto count() const noexcept -> short;
 
    // Descriptor record fields (records) accessors
 
    auto auto_unique_value(short record) const -> bool;
 
    auto base_column_name(short record) const -> string;
 
    auto base_table_name(short record) const -> string;
 
    auto case_sensitive(short record) const -> bool;
 
    auto catalog_name(short record) const -> string;
 
    auto concise_type(short record) const -> short;
 
    auto display_size(short record) const -> std::int64_t;
 
    auto fixed_prec_scale(short record) const -> short;
 
    auto label(short record) const -> string;
 
    auto length(short record) const -> std::uint64_t;
 
    auto local_type_name(short record) const -> string;
 
    auto name(short record) const -> string;
 
    auto nullable(short record) const -> short;
 
    auto num_prec_radix(short record) const -> short;
 
    auto octet_length(short record) const -> std::int64_t;
 
    auto precision(short record) const -> short;
 
    auto rowver(short record) const -> short;
 
    auto scale(short record) const -> short;
 
    auto schema_name(short record) const -> string;
 
    auto searchable(short record) const -> short;
 
    auto table_name(short record) const -> string;
 
    auto type(short record) const -> short;
 
    auto type_name(short record) const -> string;
 
    auto unnamed(short record) const -> bool;
 
    auto unsigned_(short record) const -> bool;
 
    auto updatable(short record) const -> short;
 
private:
    // Convenience wrapper for SQLGetDescrField accesor.
    struct sql_get_descr_field
    {
        sql_get_descr_field(
            implementation_row_descriptor const& ird,
            short record,
            std::uint16_t field_identifier) noexcept;
        operator std::int64_t() const;
        operator std::uint64_t() const;
        operator string() const;
 
        implementation_row_descriptor const& ird_;
        short record_;
        std::uint16_t field_identifier_;
    };
    friend sql_get_descr_field;
 
    void initialize_descriptor();
    void throw_if_record_is_out_of_range(short record) const;
 
    void* statement_handle_{nullptr};
    short statement_columns_count_{0};
    void* descriptor_handle_{nullptr};
    short descriptor_records_count_{0};
};
 
// clang-format off
//
//  .d8888b.           888             888
// d88P  Y88b          888             888
// 888    888          888             888
// 888         8888b.  888888  8888b.  888  .d88b.   .d88b.
// 888            "88b 888        "88b 888 d88""88b d88P"88b
// 888    888 .d888888 888    .d888888 888 888  888 888  888
// Y88b  d88P 888  888 Y88b.  888  888 888 Y88..88P Y88b 888
//  "Y8888P"  "Y888888  "Y888 "Y888888 888  "Y88P"   "Y88888
//                                                      888
//                                                 Y8b d88P
//                                                  "Y88P"
// MARK: Catalog -
// clang-format on
 
class catalog
{
public:
    class tables
    {
    public:
        [[nodiscard]] bool next();    
        string table_catalog() const; 
        string table_schema() const;  
        string table_name() const;    
        string table_type() const;    
        string table_remarks() const; 
 
    private:
        friend class nanodbc::catalog;
        explicit tables(result& find_result) noexcept;
        result result_;
    };
 
    class columns
    {
    public:
        [[nodiscard]] bool next();             
        string table_catalog() const;          
        string table_schema() const;           
        string table_name() const;             
        string column_name() const;            
        short data_type() const;               
        string type_name() const;              
        long column_size() const;              
        long buffer_length() const;            
        short decimal_digits() const;          
        short numeric_precision_radix() const; 
        short nullable() const;                
        string remarks() const;                
        string column_default() const;         
        short sql_data_type() const;           
        short sql_datetime_subtype() const;    
        long char_octet_length() const;        
 
        long ordinal_position() const;
 
        string is_nullable() const;
 
    private:
        friend class nanodbc::catalog;
        explicit columns(result& find_result) noexcept;
        result result_;
    };
 
    class primary_keys
    {
    public:
        [[nodiscard]] bool next();    
        string table_catalog() const; 
        string table_schema() const;  
        string table_name() const;    
        string column_name() const;   
 
        short column_number() const;
 
        string primary_key_name() const;
 
    private:
        friend class nanodbc::catalog;
        explicit primary_keys(result& find_result) noexcept;
        result result_;
    };
 
    class table_privileges
    {
    public:
        [[nodiscard]] bool next();    
        string table_catalog() const; 
        string table_schema() const;  
        string table_name() const;    
        string grantor() const;       
        string grantee() const;       
        string privilege() const;     
        string is_grantable() const;
 
    private:
        friend class nanodbc::catalog;
        explicit table_privileges(result& find_result) noexcept;
        result result_;
    };
 
    class procedures
    {
    public:
        [[nodiscard]] bool next();        
        string procedure_catalog() const; 
        string procedure_schema() const;  
        string procedure_name() const;    
        string procedure_remarks() const; 
        short procedure_type() const;     
 
    private:
        friend class nanodbc::catalog;
        explicit procedures(result& find_result) noexcept;
        result result_;
    };
 
    class procedure_columns
    {
    public:
        [[nodiscard]] bool next();             
        string procedure_catalog() const;      
        string procedure_schema() const;       
        string procedure_name() const;         
        string column_name() const;            
        short column_type() const;             
        short data_type() const;               
        string type_name() const;              
        long column_size() const;              
        long buffer_length() const;            
        short decimal_digits() const;          
        short numeric_precision_radix() const; 
        short nullable() const;                
        string remarks() const;                
        string column_default() const;         
        short sql_data_type() const;           
        short sql_datetime_subtype() const;    
        long char_octet_length() const;        
 
        long ordinal_position() const;
 
        string is_nullable() const;
 
    private:
        friend class nanodbc::catalog;
        explicit procedure_columns(result& find_result) noexcept;
        result result_;
    };
 
    explicit catalog(connection& conn) noexcept;
 
    catalog::tables find_tables(
        string const& table = {},
        string const& type = {},
        string const& schema = {},
        string const& catalog = {});
 
    catalog::table_privileges find_table_privileges(
        string const& catalog,
        string const& table = {},
        string const& schema = {});
 
    catalog::columns find_columns(
        string const& column = {},
        string const& table = {},
        string const& schema = {},
        string const& catalog = {});
 
    catalog::primary_keys
    find_primary_keys(string const& table, string const& schema = {}, string const& catalog = {});
 
 
    catalog::procedures find_procedures(
        string const& procedure = {},
        string const& schema = {},
        string const& catalog = {});
 
    catalog::procedure_columns find_procedure_columns(
        string const& column = {},
        string const& procedure = {},
        string const& schema = {},
        string const& catalog = {});
 
    std::list<string> list_catalogs();
 
    std::list<string> list_schemas();
 
    std::list<string> list_table_types();
 
private:
    connection conn_;
};
 
 
// clang-format off
// 8888888888                            8888888888                         888    d8b
// 888                                   888                                888    Y8P
// 888                                   888                                888
// 8888888 888d888 .d88b.   .d88b.       8888888 888  888 88888b.   .d8888b 888888 888  .d88b.  88888b.  .d8888b
// 888     888P"  d8P  Y8b d8P  Y8b      888     888  888 888 "88b d88P"    888    888 d88""88b 888 "88b 88K
// 888     888    88888888 88888888      888     888  888 888  888 888      888    888 888  888 888  888 "Y8888b.
// 888     888    Y8b.     Y8b.          888     Y88b 888 888  888 Y88b.    Y88b.  888 Y88..88P 888  888      X88
// 888     888     "Y8888   "Y8888       888      "Y88888 888  888  "Y8888P  "Y888 888  "Y88P"  888  888  88888P'
namespace detail
{
 
// Moves what a column held, which get<std::any>() worked out from the type the driver
// reports, into whatever the caller asked to hold it.
template <class T>
struct hold_column_value;
 
template <>
struct hold_column_value<std::any>
{
    static std::any from(std::any value) noexcept { return value; }
};
 
template <class Alternative, class Variant>
inline bool hold_alternative(Variant& variant, std::any const& value)
{
    if (auto const* held = std::any_cast<Alternative>(&value))
    {
        variant = *held;
        return true;
    }
    return false;
}
 
template <class... Ts>
struct hold_column_value<std::variant<Ts...>>
{
    static std::variant<Ts...> from(std::any const& value)
    {
        std::variant<Ts...> variant;
        if (!value.has_value())
            return variant; // the first alternative, which is what monostate is for
 
        // A disjunction fold, which stops at the first alternative able to hold it.
        bool const held = (hold_alternative<Ts>(variant, value) || ...);
 
        // The column holds something none of the alternatives can, which the compiler
        // cannot catch: what a column holds is only known once the driver has said.
        if (!held)
            throw type_incompatible_error();
 
        return variant;
    }
};
 
} // namespace detail
 
template <class T>
T result::get_as(short column) const
{
    return detail::hold_column_value<T>::from(get<std::any>(column));
}
 
template <class T>
T result::get_as(string const& column_name) const
{
    return get_as<T>(this->column(column_name));
}
 
// MARK: Free Functions -
// clang-format on
 
 
struct driver
{
    struct attribute
    {
        nanodbc::string keyword; 
        nanodbc::string value;   
    };
 
    nanodbc::string name;            
    std::list<attribute> attributes; 
};
 
struct datasource
{
    nanodbc::string name;   
    nanodbc::string driver; 
};
 
std::list<driver> list_drivers();
 
std::list<datasource> list_datasources();
 
result execute(connection& conn, string const& query, long batch_operations = 1, long timeout = 0);
 
void just_execute(
    connection& conn,
    string const& query,
    long batch_operations = 1,
    long timeout = 0);
 
namespace detail
{
 
template <class Row, class Member, class Class>
Member const& read_field(Row const& row, Member Class::* field)
{
    return row.*field;
}
 
template <class Row, class Accessor>
auto read_field(Row const& row, Accessor const& accessor) -> decltype(accessor(row))
{
    return accessor(row);
}
 
template <class Row, class Accessor>
struct field_type
{
    using type = std::decay_t<
        decltype(read_field(std::declval<Row const&>(), std::declval<Accessor const&>()))>;
};
 
template <class T>
struct is_optional : std::false_type
{
};
 
template <class T>
struct is_optional<std::optional<T>> : std::true_type
{
};
 
template <class T>
inline constexpr bool is_optional_v = is_optional<T>::value;
 
// Four ways to bind a column, told apart by what the accessor yields.
struct bind_as_value
{
};
struct bind_as_string
{
};
struct bind_as_optional_value
{
};
struct bind_as_optional_string
{
};
 
template <class T, bool IsOptional = is_optional_v<T>>
struct bind_kind
{
    using type = std::conditional_t<is_owning_string_v<T>, bind_as_string, bind_as_value>;
};
 
template <class T>
struct bind_kind<T, true>
{
    using type = std::conditional_t<
        is_owning_string_v<typename T::value_type>,
        bind_as_optional_string,
        bind_as_optional_value>;
};
 
template <class Rows, class Accessor>
void bind_column(
    statement& stmt,
    short param_index,
    Rows const& rows,
    Accessor const& accessor,
    bind_as_value)
{
    using value_type = typename field_type<typename Rows::value_type, Accessor>::type;
    std::vector<value_type> column;
    column.reserve(rows.size());
    for (auto const& row : rows)
        column.push_back(read_field(row, accessor));
    stmt.bind(param_index, column);
}
 
template <class Rows, class Accessor>
void bind_column(
    statement& stmt,
    short param_index,
    Rows const& rows,
    Accessor const& accessor,
    bind_as_string)
{
    using value_type = typename field_type<typename Rows::value_type, Accessor>::type;
    std::vector<value_type> column;
    column.reserve(rows.size());
    for (auto const& row : rows)
        column.push_back(read_field(row, accessor));
    stmt.bind_strings(param_index, column);
}
 
// An absent value still occupies its place in the column, so that the values line up with
// the flags marking which of them are null.
template <class Rows, class Accessor, class Column>
std::unique_ptr<bool[]> gather_optional(Rows const& rows, Accessor const& accessor, Column& column)
{
    auto nulls = std::make_unique<bool[]>(rows.size());
    std::size_t i = 0;
    for (auto const& row : rows)
    {
        auto const& value = read_field(row, accessor);
        nulls[i++] = !value.has_value();
        column.push_back(value ? *value : typename Column::value_type());
    }
    return nulls;
}
 
template <class Rows, class Accessor>
void bind_column(
    statement& stmt,
    short param_index,
    Rows const& rows,
    Accessor const& accessor,
    bind_as_optional_value)
{
    using optional_type = typename field_type<typename Rows::value_type, Accessor>::type;
    std::vector<typename optional_type::value_type> column;
    column.reserve(rows.size());
    auto const nulls = gather_optional(rows, accessor, column);
    stmt.bind(param_index, column, nulls.get());
}
 
template <class Rows, class Accessor>
void bind_column(
    statement& stmt,
    short param_index,
    Rows const& rows,
    Accessor const& accessor,
    bind_as_optional_string)
{
    using optional_type = typename field_type<typename Rows::value_type, Accessor>::type;
    std::vector<typename optional_type::value_type> column;
    column.reserve(rows.size());
    auto const nulls = gather_optional(rows, accessor, column);
    stmt.bind_strings(param_index, column, nulls.get());
}
 
template <class Rows, class Accessor>
void bind_one(statement& stmt, short param_index, Rows const& rows, Accessor const& accessor)
{
    using value_type = typename field_type<typename Rows::value_type, Accessor>::type;
    bind_column(stmt, param_index, rows, accessor, typename bind_kind<value_type>::type());
}
 
} // namespace detail
 
template <class Rows, class... Accessors>
void bind_rows(statement& stmt, Rows const& rows, Accessors const&... accessors)
{
    short param_index = 0;
    // A comma fold, which is ordered left to right, so the accessors line up with the
    // parameter markers in the order they were named.
    (detail::bind_one(stmt, param_index++, rows, accessors), ...);
}
 
result execute(statement& stmt, long batch_operations = 1);
 
void just_execute(statement& stmt, long batch_operations = 1);
 
result transact(statement& stmt, long batch_operations);
 
void just_transact(statement& stmt, long batch_operations);
 
void prepare(statement& stmt, string const& query, long timeout = 0);
 
 
} // namespace nanodbc
 
#endif