#include <database_connection.h>

Classes
struct	DATA_SOURCE
	A data source configured in the ODBC driver manager. More...

Public Types
enum class	FAILURE { UNKNOWN , LOGIN , UNREACHABLE , TIMEOUT , NO_DSN , NO_DRIVER }
	Why a connection attempt failed, as far as the driver's report tells. More...

typedef std::map< std::string, std::any >	ROW

Public Member Functions
	DATABASE_CONNECTION (const std::string &aDataSourceName, const std::string &aUsername, const std::string &aPassword, int aTimeoutSeconds=DEFAULT_TIMEOUT, bool aConnectNow=true)

	DATABASE_CONNECTION (const std::string &aConnectionString, int aTimeoutSeconds=DEFAULT_TIMEOUT, bool aConnectNow=true)

	~DATABASE_CONNECTION ()

void	SetCacheParams (int aMaxSize, int aMaxAge)

bool	Connect ()

bool	Disconnect ()

bool	IsConnected () const

bool	CacheTableInfo (const std::string &aTable, const std::set< std::string > &aRequiredColumns, const std::set< std::string > &aOptionalColumns={})
	Caches schema information for a table so that subsequent queries know which columns exist.

bool	SelectOne (const std::string &aTable, const std::pair< std::string, std::string > &aWhere, ROW &aResult)
	Retrieves a single row from a database table.

bool	SelectAll (const std::string &aTable, const std::string &aKey, std::vector< ROW > &aResults)
	Retrieves all rows from a database table.

bool	SelectSample (const std::string &aTable, size_t aMaxRows, std::vector< std::string > &aColumns, std::vector< ROW > &aRows)
	Reads the first rows of a table with a forward-only cursor, bypassing the row cache.

bool	GetTables (std::vector< std::string > &aTables)
	Lists the tables and views visible through this connection, sorted by name.

bool	GetColumns (const std::string &aTable, std::vector< std::string > &aColumns)
	Lists the columns of a table in catalog order.

void	ClearCache (const std::string &aTable)

std::string	GetLastError () const

std::string	GetLastState () const

Static Public Member Functions
static std::vector< DATA_SOURCE >	ListDataSourceDetails ()

static std::vector< std::string >	ListDrivers ()

static FAILURE	ClassifyFailure (const std::string &aState, const std::string &aMessage)
	Classifies a driver error from its SQLSTATE, falling back to its text since drivers disagree on states.

Static Public Attributes
static const long	DEFAULT_TIMEOUT = 10

Private Types
typedef DATABASE_CACHE< std::map< std::string, ROW > >	DB_CACHE_TYPE

Private Member Functions
void	init ()

bool	getQuoteChar ()

std::string	quoted (const std::string &aIdentifier) const
	Wraps an identifier in the driver's quote character, doubling any it contains.

std::string	escapePattern (const std::string &aName) const
	Escapes catalog search pattern characters so a name matches only itself.

std::string	columnsFor (const std::string &aTable)

bool	selectAllAndCache (const std::string &aTable, const std::string &aKey)
	The caller must already hold m_queryMutex.

Private Attributes
std::unique_ptr< nanodbc::connection >	m_conn

std::string	m_dsn

std::string	m_user

std::string	m_pass

std::string	m_connectionString

std::string	m_lastError

std::string	m_lastState

std::map< std::string, std::string >	m_tables

std::map< std::string, std::map< std::string, int > >	m_columnCache
	Map of table -> map of column name -> data type.

long	m_timeout

char	m_quoteChar

std::string	m_patternEscape

std::mutex	m_queryMutex

std::unique_ptr< DB_CACHE_TYPE >	m_cache

Detailed Description

Definition at line 42 of file database_connection.h.

Member Typedef Documentation

◆ DB_CACHE_TYPE

typedef DATABASE_CACHE<std::map<std::string, ROW> > DATABASE_CONNECTION::DB_CACHE_TYPE

private

Definition at line 203 of file database_connection.h.

◆ ROW

typedef std::map<std::string, std::any> DATABASE_CONNECTION::ROW

Definition at line 47 of file database_connection.h.

Member Enumeration Documentation

◆ FAILURE

enum class DATABASE_CONNECTION::FAILURE

strong

Why a connection attempt failed, as far as the driver's report tells.

Enumerator
UNKNOWN
LOGIN	The server rejected the user name or password.
UNREACHABLE	Nothing answered at the server address, or it refused the connection.
TIMEOUT	The server did not answer within the timeout.
NO_DSN	The data source name is not configured.
NO_DRIVER	The driver named by the data source could not be loaded.

Definition at line 50 of file database_connection.h.

Constructor & Destructor Documentation

◆ DATABASE_CONNECTION() [1/2]

DATABASE_CONNECTION::DATABASE_CONNECTION	(	const std::string &	aDataSourceName,
		const std::string &	aUsername,
		const std::string &	aPassword,
		int	aTimeoutSeconds = DEFAULT_TIMEOUT,
		bool	aConnectNow = true )

Definition at line 140 of file database_connection.cpp.

References Connect(), init(), m_dsn, m_pass, m_quoteChar, m_timeout, and m_user.

◆ DATABASE_CONNECTION() [2/2]

DATABASE_CONNECTION::DATABASE_CONNECTION	(	const std::string &	aConnectionString,
		int	aTimeoutSeconds = DEFAULT_TIMEOUT,
		bool	aConnectNow = true )

References DEFAULT_TIMEOUT.

◆ ~DATABASE_CONNECTION()

DATABASE_CONNECTION::~DATABASE_CONNECTION ( )

Definition at line 172 of file database_connection.cpp.

References Disconnect(), and m_conn.

Member Function Documentation

◆ CacheTableInfo()

bool DATABASE_CONNECTION::CacheTableInfo	(	const std::string &	aTable,
		const std::set< std::string > &	aRequiredColumns,
		const std::set< std::string > &	aOptionalColumns = {} )

Caches schema information for a table so that subsequent queries know which columns exist.

Required columns are trusted even if the driver doesn't report them (e.g. SQLite generated columns). Optional columns are added only if confirmed present; otherwise they are dropped with a warning rather than breaking every query against the table. Matching is case-insensitive.

Parameters

aTable	the name of a table in the database
aRequiredColumns	columns that must be present in queries even if the driver does not report them
aOptionalColumns	columns that are added only when the driver confirms they exist

Returns: true on success

Definition at line 286 of file database_connection.cpp.

References escapePattern(), fromUTF8(), m_columnCache, m_conn, m_lastError, m_queryMutex, m_tables, toUTF8(), and traceDatabase.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), and BOOST_AUTO_TEST_CASE().

◆ ClassifyFailure()

DATABASE_CONNECTION::FAILURE DATABASE_CONNECTION::ClassifyFailure	(	const std::string &	aState,
		const std::string &	aMessage )

static

Classifies a driver error from its SQLSTATE, falling back to its text since drivers disagree on states.

Definition at line 964 of file database_connection.cpp.

References LOGIN, message, NO_DRIVER, NO_DSN, TIMEOUT, UNKNOWN, and UNREACHABLE.

Referenced by describeFailure().

◆ ClearCache()

void DATABASE_CONNECTION::ClearCache ( const std::string & aTable )

inline

Definition at line 150 of file database_connection.h.

References m_cache.

◆ columnsFor()

std::string DATABASE_CONNECTION::columnsFor ( const std::string & aTable )

private

Definition at line 448 of file database_connection.cpp.

References empty(), m_columnCache, quoted(), and traceDatabase.

Referenced by selectAllAndCache(), and SelectOne().

◆ Connect()

bool DATABASE_CONNECTION::Connect ( )

Definition at line 201 of file database_connection.cpp.

References fromUTF8(), getQuoteChar(), IsConnected(), m_conn, m_connectionString, m_dsn, m_lastError, m_lastState, m_pass, m_patternEscape, m_tables, m_timeout, m_user, toUTF8(), and traceDatabase.

Referenced by BOOST_AUTO_TEST_CASE(), and DATABASE_CONNECTION().

◆ Disconnect()

bool DATABASE_CONNECTION::Disconnect ( )

Definition at line 255 of file database_connection.cpp.

References m_conn, and traceDatabase.

Referenced by BOOST_AUTO_TEST_CASE(), selectAllAndCache(), SelectOne(), and ~DATABASE_CONNECTION().

◆ escapePattern()

std::string DATABASE_CONNECTION::escapePattern ( const std::string & aName ) const

private

Escapes catalog search pattern characters so a name matches only itself.

Definition at line 428 of file database_connection.cpp.

References m_patternEscape.

Referenced by CacheTableInfo(), GetColumns(), and GetTables().

◆ GetColumns()

bool DATABASE_CONNECTION::GetColumns	(	const std::string &	aTable,
		std::vector< std::string > &	aColumns )

Lists the columns of a table in catalog order.

Definition at line 899 of file database_connection.cpp.

References escapePattern(), fromUTF8(), m_conn, m_lastError, m_queryMutex, toUTF8(), and traceDatabase.

◆ GetLastError()

std::string DATABASE_CONNECTION::GetLastError ( ) const

inline

Definition at line 156 of file database_connection.h.

References m_lastError.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), and describeFailure().

◆ GetLastState()

std::string DATABASE_CONNECTION::GetLastState ( ) const

inline

Returns: the SQLSTATE of the last driver error, or an empty string

Definition at line 159 of file database_connection.h.

References m_lastState.

Referenced by describeFailure().

◆ getQuoteChar()

bool DATABASE_CONNECTION::getQuoteChar ( )

private

Definition at line 390 of file database_connection.cpp.

References m_conn, m_lastError, m_quoteChar, toUTF8(), and traceDatabase.

Referenced by Connect().

◆ GetTables()

bool DATABASE_CONNECTION::GetTables ( std::vector< std::string > & aTables )

Lists the tables and views visible through this connection, sorted by name.

Definition at line 845 of file database_connection.cpp.

References escapePattern(), fromUTF8(), m_conn, m_lastError, m_queryMutex, toUTF8(), and traceDatabase.

◆ init()

void DATABASE_CONNECTION::init ( )

private

Definition at line 179 of file database_connection.cpp.

References m_cache.

Referenced by DATABASE_CONNECTION().

◆ IsConnected()

bool DATABASE_CONNECTION::IsConnected ( ) const

Definition at line 277 of file database_connection.cpp.

References m_conn.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), and Connect().

◆ ListDataSourceDetails()

std::vector< DATABASE_CONNECTION::DATA_SOURCE > DATABASE_CONNECTION::ListDataSourceDetails ( )

static

Returns: the data sources configured in the ODBC driver manager, with the driver each one uses

Definition at line 928 of file database_connection.cpp.

References source, toUTF8(), and traceDatabase.

Referenced by DIALOG_DATABASE_LIB_SETTINGS::loadDataSources().

◆ ListDrivers()

std::vector< std::string > DATABASE_CONNECTION::ListDrivers ( )

static

Returns: the driver names installed in the ODBC driver manager

Definition at line 946 of file database_connection.cpp.

References toUTF8(), and traceDatabase.

Referenced by DIALOG_DATABASE_LIB_SETTINGS::TransferDataToWindow().

◆ quoted()

std::string DATABASE_CONNECTION::quoted ( const std::string & aIdentifier ) const

private

Wraps an identifier in the driver's quote character, doubling any it contains.

Definition at line 417 of file database_connection.cpp.

References m_quoteChar.

Referenced by columnsFor(), selectAllAndCache(), SelectOne(), and SelectSample().

◆ SelectAll()

bool DATABASE_CONNECTION::SelectAll	(	const std::string &	aTable,
		const std::string &	aKey,
		std::vector< ROW > &	aResults )

Retrieves all rows from a database table.

Parameters

aTable	the name of a table in the database
aKey	holds the column name of the primary key used for caching results
aResults	will be filled with all rows in the table

Returns: true if the query succeeded and at least one ROW was found, false otherwise

Definition at line 740 of file database_connection.cpp.

References m_cache, m_conn, m_queryMutex, m_tables, selectAllAndCache(), and traceDatabase.

Referenced by BOOST_AUTO_TEST_CASE().

◆ selectAllAndCache()

bool DATABASE_CONNECTION::selectAllAndCache	(	const std::string &	aTable,
		const std::string &	aKey )

private

The caller must already hold m_queryMutex.

Definition at line 642 of file database_connection.cpp.

References columnsFor(), decodeRow(), Disconnect(), fromUTF8(), m_cache, m_conn, m_lastError, PROF_TIMER::msecs(), quoted(), result, resultColumns(), PROF_TIMER::Stop(), and traceDatabase.

Referenced by SelectAll(), and SelectOne().

◆ SelectOne()

bool DATABASE_CONNECTION::SelectOne	(	const std::string &	aTable,
		const std::pair< std::string, std::string > &	aWhere,
		DATABASE_CONNECTION::ROW &	aResult )

Retrieves a single row from a database table.

Table and column names are cached when the connection is created, so schema changes to the database won't be recognized unless the connection is recreated.

Parameters

aTable	the name of a table in the database
aWhere	column to search, and the value to search for
aResult	will be filled with a row in the database if one was found

Returns: true if aResult was filled; false otherwise

Definition at line 477 of file database_connection.cpp.

References columnsFor(), decodeRow(), Disconnect(), fromUTF8(), m_cache, m_columnCache, m_conn, m_lastError, m_queryMutex, m_tables, PROF_TIMER::msecs(), quoted(), resultColumns(), selectAllAndCache(), PROF_TIMER::Stop(), toUTF8(), and traceDatabase.

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), and BOOST_AUTO_TEST_CASE().

◆ SelectSample()

bool DATABASE_CONNECTION::SelectSample	(	const std::string &	aTable,
		size_t	aMaxRows,
		std::vector< std::string > &	aColumns,
		std::vector< ROW > &	aRows )

Reads the first rows of a table with a forward-only cursor, bypassing the row cache.

Parameters

aTable	the name of a table in the database
aMaxRows	stop fetching after this many rows; zero fetches only the column names
aColumns	will be filled with the column names in result order
aRows	will be filled with up to aMaxRows rows

Returns: true if the query succeeded

Definition at line 791 of file database_connection.cpp.

References decodeRow(), fromUTF8(), m_conn, m_lastError, m_queryMutex, m_timeout, quoted(), resultColumns(), and traceDatabase.

◆ SetCacheParams()

void DATABASE_CONNECTION::SetCacheParams	(	int	aMaxSize,
		int	aMaxAge )

Definition at line 185 of file database_connection.cpp.

References m_cache.

Referenced by BOOST_AUTO_TEST_CASE().

Member Data Documentation

◆ DEFAULT_TIMEOUT

const long DATABASE_CONNECTION::DEFAULT_TIMEOUT = 10

static

Definition at line 45 of file database_connection.h.

Referenced by DATABASE_CONNECTION().

◆ m_cache

std::unique_ptr<DB_CACHE_TYPE> DATABASE_CONNECTION::m_cache

private

Definition at line 205 of file database_connection.h.

Referenced by ClearCache(), init(), SelectAll(), selectAllAndCache(), SelectOne(), and SetCacheParams().

◆ m_columnCache

std::map<std::string, std::map<std::string, int> > DATABASE_CONNECTION::m_columnCache

private

Map of table -> map of column name -> data type.

Definition at line 193 of file database_connection.h.

Referenced by CacheTableInfo(), columnsFor(), and SelectOne().

◆ m_conn

std::unique_ptr<nanodbc::connection> DATABASE_CONNECTION::m_conn

private

Definition at line 180 of file database_connection.h.

Referenced by CacheTableInfo(), Connect(), Disconnect(), GetColumns(), getQuoteChar(), GetTables(), IsConnected(), SelectAll(), selectAllAndCache(), SelectOne(), SelectSample(), and ~DATABASE_CONNECTION().

◆ m_connectionString

std::string DATABASE_CONNECTION::m_connectionString

private

Definition at line 185 of file database_connection.h.

Referenced by Connect().

◆ m_dsn

std::string DATABASE_CONNECTION::m_dsn

private

Definition at line 182 of file database_connection.h.

Referenced by Connect(), and DATABASE_CONNECTION().

◆ m_lastError

std::string DATABASE_CONNECTION::m_lastError

private

Definition at line 187 of file database_connection.h.

Referenced by CacheTableInfo(), Connect(), GetColumns(), GetLastError(), getQuoteChar(), GetTables(), selectAllAndCache(), SelectOne(), and SelectSample().

◆ m_lastState

std::string DATABASE_CONNECTION::m_lastState

private

Definition at line 188 of file database_connection.h.

Referenced by Connect(), and GetLastState().

◆ m_pass

std::string DATABASE_CONNECTION::m_pass

private

Definition at line 184 of file database_connection.h.

Referenced by Connect(), and DATABASE_CONNECTION().

◆ m_patternEscape

std::string DATABASE_CONNECTION::m_patternEscape

private

Definition at line 199 of file database_connection.h.

Referenced by Connect(), and escapePattern().

◆ m_queryMutex

std::mutex DATABASE_CONNECTION::m_queryMutex

mutableprivate

Definition at line 201 of file database_connection.h.

Referenced by CacheTableInfo(), GetColumns(), GetTables(), SelectAll(), SelectOne(), and SelectSample().

◆ m_quoteChar

char DATABASE_CONNECTION::m_quoteChar

private

Definition at line 197 of file database_connection.h.

Referenced by DATABASE_CONNECTION(), getQuoteChar(), and quoted().

◆ m_tables

std::map<std::string, std::string> DATABASE_CONNECTION::m_tables

private

Definition at line 190 of file database_connection.h.

Referenced by CacheTableInfo(), Connect(), SelectAll(), and SelectOne().

◆ m_timeout

long DATABASE_CONNECTION::m_timeout

private

Definition at line 195 of file database_connection.h.

Referenced by Connect(), DATABASE_CONNECTION(), and SelectSample().

◆ m_user

std::string DATABASE_CONNECTION::m_user

private

Definition at line 183 of file database_connection.h.

Referenced by Connect(), and DATABASE_CONNECTION().

The documentation for this class was generated from the following files:

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ DB_CACHE_TYPE

◆ ROW

Member Enumeration Documentation

◆ FAILURE

Constructor & Destructor Documentation

◆ DATABASE_CONNECTION() [1/2]

◆ DATABASE_CONNECTION() [2/2]

◆ ~DATABASE_CONNECTION()

Member Function Documentation

◆ CacheTableInfo()

◆ ClassifyFailure()

◆ ClearCache()

◆ columnsFor()

◆ Connect()

◆ Disconnect()

◆ escapePattern()

◆ GetColumns()

◆ GetLastError()

◆ GetLastState()

◆ getQuoteChar()

◆ GetTables()

◆ init()

◆ IsConnected()

◆ ListDataSourceDetails()

◆ ListDrivers()

◆ quoted()

◆ SelectAll()

◆ selectAllAndCache()

◆ SelectOne()

◆ SelectSample()

◆ SetCacheParams()

Member Data Documentation

◆ DEFAULT_TIMEOUT

◆ m_cache

◆ m_columnCache

◆ m_conn

◆ m_connectionString

◆ m_dsn

◆ m_lastError

◆ m_lastState

◆ m_pass

◆ m_patternEscape

◆ m_queryMutex

◆ m_quoteChar

◆ m_tables

◆ m_timeout

◆ m_user