High level API for (prepared) raw SQL statements. More...

#include <SqlStatement.hpp>

Inheritance diagram for SqlStatement:

Public Member Functions
LIGHTWEIGHT_API	SqlStatement ()
	Construct a new SqlStatement object, using a new connection, and connect to the default database.

LIGHTWEIGHT_API	SqlStatement (SqlStatement &&) noexcept

LIGHTWEIGHT_API SqlStatement &	operator= (SqlStatement &&) noexcept

	SqlStatement (SqlStatement const &) noexcept=delete

SqlStatement &	operator= (SqlStatement const &) noexcept=delete

LIGHTWEIGHT_API	SqlStatement (SqlConnection &relatedConnection)
	Construct a new SqlStatement object, using the given connection.

LIGHTWEIGHT_API	SqlStatement (std::nullopt_t)
	Construct a new empty SqlStatement object. No SqlConnection is associated with this statement.

LIGHTWEIGHT_API bool	IsAlive () const noexcept

LIGHTWEIGHT_API bool	IsPrepared () const noexcept

LIGHTWEIGHT_API SqlConnection &	Connection () noexcept
	Retrieves the connection associated with this statement.

LIGHTWEIGHT_API SqlConnection const &	Connection () const noexcept
	Retrieves the connection associated with this statement.

LIGHTWEIGHT_API SqlErrorInfo	LastError () const
	Retrieves the last error information with respect to this SQL statement handle.

LIGHTWEIGHT_API SqlQueryBuilder	Query (std::string_view const &table={}) const
	Creates a new query builder for the given table, compatible with the SQL server being connected.

LIGHTWEIGHT_API SqlQueryBuilder	QueryAs (std::string_view const &table, std::string_view const &tableAlias) const
	Creates a new query builder for the given table with an alias, compatible with the SQL server being connected.

LIGHTWEIGHT_API SQLHSTMT	NativeHandle () const noexcept
	Retrieves the native handle of the statement.

LIGHTWEIGHT_API void	Prepare (std::string_view query) &

LIGHTWEIGHT_API SqlStatement	Prepare (std::string_view query) &&

void	Prepare (SqlQueryObject auto const &queryObject) &

SqlStatement	Prepare (SqlQueryObject auto const &queryObject) &&

std::string const &	PreparedQuery () const noexcept

template<SqlInputParameterBinder Arg>
void	BindInputParameter (SQLSMALLINT columnIndex, Arg const &arg)

template<SqlInputParameterBinder Arg, typename ColumnName >
void	BindInputParameter (SQLSMALLINT columnIndex, Arg const &arg, ColumnName &&columnNameHint)

template<SqlOutputColumnBinder... Args>
void	BindOutputColumns (Args *... args)

template<typename... Records> requires (((std::is_class_v<Records> && std::is_aggregate_v<Records>) && ...))
void	BindOutputColumnsToRecord (Records *... records)

template<SqlOutputColumnBinder T>
void	BindOutputColumn (SQLUSMALLINT columnIndex, T *arg)

template<SqlInputParameterBinder... Args>
void	Execute (Args const &... args)
	Binds the given arguments to the prepared statement and executes it.

LIGHTWEIGHT_API void	ExecuteWithVariants (std::vector< SqlVariant > const &args)
	Binds the given arguments to the prepared statement and executes it.

template<SqlInputParameterBatchBinder FirstColumnBatch, std::ranges::contiguous_range... MoreColumnBatches>
void	ExecuteBatchNative (FirstColumnBatch const &firstColumnBatch, MoreColumnBatches const &... moreColumnBatches)

template<SqlInputParameterBatchBinder FirstColumnBatch, std::ranges::range... MoreColumnBatches>
void	ExecuteBatchSoft (FirstColumnBatch const &firstColumnBatch, MoreColumnBatches const &... moreColumnBatches)

template<SqlInputParameterBatchBinder FirstColumnBatch, std::ranges::range... MoreColumnBatches>
void	ExecuteBatch (FirstColumnBatch const &firstColumnBatch, MoreColumnBatches const &... moreColumnBatches)

LIGHTWEIGHT_API void	ExecuteDirect (std::string_view const &query, std::source_location location=std::source_location::current())
	Executes the given query directly.

void	ExecuteDirect (SqlQueryObject auto const &query, std::source_location location=std::source_location::current())
	Executes the given query directly.

template<typename Callable > requires std::invocable<Callable, SqlMigrationQueryBuilder&>
void	MigrateDirect (Callable const &callable, std::source_location location=std::source_location::current())
	Executes an SQL migration query, as created b the callback.

template<typename T > requires (!std::same_as<T, SqlVariant>)
std::optional< T >	ExecuteDirectScalar (const std::string_view &query, std::source_location location=std::source_location::current())

template<typename T > requires (std::same_as<T, SqlVariant>)
T	ExecuteDirectScalar (const std::string_view &query, std::source_location location=std::source_location::current())

template<typename T > requires (!std::same_as<T, SqlVariant>)
std::optional< T >	ExecuteDirectScalar (SqlQueryObject auto const &query, std::source_location location=std::source_location::current())

template<typename T > requires (std::same_as<T, SqlVariant>)
T	ExecuteDirectScalar (SqlQueryObject auto const &query, std::source_location location=std::source_location::current())

LIGHTWEIGHT_API size_t	NumRowsAffected () const
	Retrieves the number of rows affected by the last query.

LIGHTWEIGHT_API size_t	NumColumnsAffected () const
	Retrieves the number of columns affected by the last query.

LIGHTWEIGHT_API size_t	LastInsertId (std::string_view tableName)
	Retrieves the last insert ID of the given table.

LIGHTWEIGHT_API bool	FetchRow ()

LIGHTWEIGHT_API std::expected< bool, SqlErrorInfo >	TryFetchRow (std::source_location location=std::source_location::current()) noexcept

void	CloseCursor () noexcept

SqlResultCursor	GetResultCursor () noexcept
	Retrieves the result cursor for reading an SQL query result.

SqlVariantRowCursor	GetVariantRowCursor () noexcept
	Retrieves the variant row cursor for reading an SQL query result of unknown column types and column count.

template<SqlGetColumnNativeType T>
bool	GetColumn (SQLUSMALLINT column, T *result) const

template<SqlGetColumnNativeType T>
T	GetColumn (SQLUSMALLINT column) const
	Retrieves the value of the column at the given index for the currently selected row.

template<SqlGetColumnNativeType T>
std::optional< T >	GetNullableColumn (SQLUSMALLINT column) const

template<SqlOutputColumnBinder... Args>
LIGHTWEIGHT_FORCE_INLINE void	BindOutputColumns (Args *... args)

template<SqlOutputColumnBinder T>
LIGHTWEIGHT_FORCE_INLINE void	BindOutputColumn (SQLUSMALLINT columnIndex, T *arg)

template<SqlInputParameterBinder Arg>
LIGHTWEIGHT_FORCE_INLINE void	BindInputParameter (SQLSMALLINT columnIndex, Arg const &arg)

template<SqlInputParameterBinder Arg, typename ColumnName >
LIGHTWEIGHT_FORCE_INLINE void	BindInputParameter (SQLSMALLINT columnIndex, Arg const &arg, ColumnName &&columnNameHint)

template<SqlInputParameterBatchBinder FirstColumnBatch, std::ranges::range... MoreColumnBatches>
LIGHTWEIGHT_FORCE_INLINE void	ExecuteBatch (FirstColumnBatch const &firstColumnBatch, MoreColumnBatches const &... moreColumnBatches)

Public Member Functions inherited from SqlDataBinderCallback
	SqlDataBinderCallback (SqlDataBinderCallback &&)=default

	SqlDataBinderCallback (SqlDataBinderCallback const &)=default

SqlDataBinderCallback &	operator= (SqlDataBinderCallback &&)=default

SqlDataBinderCallback &	operator= (SqlDataBinderCallback const &)=default

Detailed Description

High level API for (prepared) raw SQL statements.

SQL prepared statement lifecycle:

Prepare the statement
Optionally bind output columns to local variables
Execute the statement (optionally with input parameters)
Fetch rows (if any)
Repeat steps 3 and 4 as needed

Definition at line 47 of file SqlStatement.hpp.

Member Function Documentation

◆ IsAlive()

LIGHTWEIGHT_FORCE_INLINE bool SqlStatement::IsAlive ( ) const

inlinenoexcept

Definition at line 556 of file SqlStatement.hpp.

◆ IsPrepared()

LIGHTWEIGHT_FORCE_INLINE bool SqlStatement::IsPrepared ( ) const

inlinenoexcept

Definition at line 561 of file SqlStatement.hpp.

◆ Connection() [1/2]

LIGHTWEIGHT_FORCE_INLINE SqlConnection & SqlStatement::Connection ( )

inlinenoexcept

Retrieves the connection associated with this statement.

Definition at line 566 of file SqlStatement.hpp.

Referenced by SqlQuerySingleBuilder< Record >::Get(), and MigrateDirect().

◆ Connection() [2/2]

LIGHTWEIGHT_FORCE_INLINE SqlConnection const & SqlStatement::Connection ( ) const

inlinenoexcept

Retrieves the connection associated with this statement.

Definition at line 571 of file SqlStatement.hpp.

◆ LastError()

LIGHTWEIGHT_FORCE_INLINE SqlErrorInfo SqlStatement::LastError ( ) const

inline

Retrieves the last error information with respect to this SQL statement handle.

Definition at line 576 of file SqlStatement.hpp.

References SqlErrorInfo::fromStatementHandle().

◆ NativeHandle()

LIGHTWEIGHT_FORCE_INLINE SQLHSTMT SqlStatement::NativeHandle ( ) const

inlinenoexcept

Retrieves the native handle of the statement.

Definition at line 581 of file SqlStatement.hpp.

◆ Prepare() [1/3]

LIGHTWEIGHT_API void SqlStatement::Prepare ( std::string_view query ) &

Prepares the statement for execution.

Note: When preparing a new SQL statement the previously executed statement, yielding a result set, must have been closed.

Referenced by DataMapper::ConfigureRelationAutoLoading(), DataMapper::CreateExplicit(), DataMapper::Delete(), DataMapper::Query(), DataMapper::Query(), DataMapper::QuerySingle(), DataMapper::QuerySingle(), and DataMapper::Update().

◆ Prepare() [2/3]

LIGHTWEIGHT_FORCE_INLINE void SqlStatement::Prepare ( SqlQueryObject auto const & queryObject ) &

inline

Prepares the statement for execution.

Note: When preparing a new SQL statement the previously executed statement, yielding a result set, must have been closed.

Definition at line 586 of file SqlStatement.hpp.

◆ Prepare() [3/3]

LIGHTWEIGHT_FORCE_INLINE SqlStatement SqlStatement::Prepare ( SqlQueryObject auto const & queryObject ) &&

inline

Definition at line 591 of file SqlStatement.hpp.

◆ PreparedQuery()

LIGHTWEIGHT_FORCE_INLINE std::string const & SqlStatement::PreparedQuery ( ) const

inlinenoexcept

Definition at line 596 of file SqlStatement.hpp.

◆ BindOutputColumns() [1/2]

template<SqlOutputColumnBinder... Args>

void SqlStatement::BindOutputColumns ( Args *... args )

Binds the given arguments to the prepared statement to store the fetched data to.

Note: The statement must be prepared before calling this function.

◆ BindOutputColumnsToRecord()

template<typename... Records>
requires (((std::is_class_v<Records> && std::is_aggregate_v<Records>) && ...))

void SqlStatement::BindOutputColumnsToRecord ( Records *... records )

Binds the given arguments to the prepared statement to store the fetched data to.

Parameters

records The records to bind each member to.

Note: The statement must be prepared before calling this function.; The records must be aggregate types, i.e. classes with public members and no user-defined constructors.

Definition at line 612 of file SqlStatement.hpp.

◆ Execute()

template<SqlInputParameterBinder... Args>

void SqlStatement::Execute ( Args const &... args )

Binds the given arguments to the prepared statement and executes it.

Definition at line 653 of file SqlStatement.hpp.

References SqlErrorInfo::fromStatementHandle(), SqlLogger::GetLogger(), SqlLogger::OnBindInputParameter(), and SqlLogger::OnExecute().

Referenced by DataMapper::ConfigureRelationAutoLoading(), DataMapper::CreateExplicit(), DataMapper::Delete(), DataMapper::Query(), DataMapper::Query(), DataMapper::QuerySingle(), DataMapper::QuerySingle(), and DataMapper::Update().

◆ ExecuteBatchNative()

template<SqlInputParameterBatchBinder FirstColumnBatch, std::ranges::contiguous_range... MoreColumnBatches>

void SqlStatement::ExecuteBatchNative	(	FirstColumnBatch const &	firstColumnBatch,
		MoreColumnBatches const &...	moreColumnBatches
	)

Executes the prepared statement on a batch of data.

Each parameter represents a column, to be bound as input parameter. The element types of each column container must be explicitly supported.

In order to support column value types, their underlying storage must be contiguous. Also the input range itself must be contiguous. If any of these conditions are not met, the function will not compile - use ExecuteBatch() instead.

Definition at line 710 of file SqlStatement.hpp.

◆ ExecuteBatchSoft()

template<SqlInputParameterBatchBinder FirstColumnBatch, std::ranges::range... MoreColumnBatches>

void SqlStatement::ExecuteBatchSoft	(	FirstColumnBatch const &	firstColumnBatch,
		MoreColumnBatches const &...	moreColumnBatches
	)

Executes the prepared statement on a batch of data.

Each parameter represents a column, to be bound as input parameter, and the number of elements in these bound column containers will mandate how many executions will happen.

This function will bind and execute each row separately, which is less efficient than ExecuteBatchNative(), but works non-contiguous input ranges.

Definition at line 754 of file SqlStatement.hpp.

◆ ExecuteBatch() [1/2]

template<SqlInputParameterBatchBinder FirstColumnBatch, std::ranges::range... MoreColumnBatches>

void SqlStatement::ExecuteBatch	(	FirstColumnBatch const &	firstColumnBatch,
		MoreColumnBatches const &...	moreColumnBatches
	)

Executes the prepared statement on a batch of data.

Each parameter represents a column, to be bound as input parameter, and the number of elements in these bound column containers will mandate how many executions will happen.

◆ ExecuteDirect()

LIGHTWEIGHT_FORCE_INLINE void SqlStatement::ExecuteDirect	(	SqlQueryObject auto const &	query,
		std::source_location	location = `std::source_location::current()`
	)

inline

Executes the given query directly.

Definition at line 817 of file SqlStatement.hpp.

References ExecuteDirect().

◆ MigrateDirect()

template<typename Callable >
requires std::invocable<Callable, SqlMigrationQueryBuilder&>

void SqlStatement::MigrateDirect	(	Callable const &	callable,
		std::source_location	location = `std::source_location::current()`
	)

Executes an SQL migration query, as created b the callback.

Definition at line 825 of file SqlStatement.hpp.

References Connection(), ExecuteDirect(), and SqlConnection::QueryFormatter().

◆ ExecuteDirectScalar() [1/4]

template<typename T >
requires (!std::same_as<T, SqlVariant>)

std::optional< T > SqlStatement::ExecuteDirectScalar	(	const std::string_view &	query,
		std::source_location	location = `std::source_location::current()`
	)

inline

Executes the given query, assuming that only one result row and column is affected, that one will be returned.

Definition at line 836 of file SqlStatement.hpp.

◆ ExecuteDirectScalar() [2/4]

template<typename T >
requires (std::same_as<T, SqlVariant>)

T SqlStatement::ExecuteDirectScalar	(	const std::string_view &	query,
		std::source_location	location = `std::source_location::current()`
	)

inline

Definition at line 846 of file SqlStatement.hpp.

◆ ExecuteDirectScalar() [3/4]

template<typename T >
requires (!std::same_as<T, SqlVariant>)

std::optional< T > SqlStatement::ExecuteDirectScalar	(	SqlQueryObject auto const &	query,
		std::source_location	location = `std::source_location::current()`
	)

inline

Executes the given query, assuming that only one result row and column is affected, that one will be returned.

Definition at line 858 of file SqlStatement.hpp.

◆ ExecuteDirectScalar() [4/4]

template<typename T >
requires (std::same_as<T, SqlVariant>)

T SqlStatement::ExecuteDirectScalar	(	SqlQueryObject auto const &	query,
		std::source_location	location = `std::source_location::current()`
	)

inline

Definition at line 866 of file SqlStatement.hpp.

◆ FetchRow()

LIGHTWEIGHT_API bool SqlStatement::FetchRow ( )

Fetches the next row of the result set.

Note: Automatically closes the cursor at the end of the result set.

Return values

true	The next result row was successfully fetched
false	No result row was fetched, because the end of the result set was reached.

Referenced by DataMapper::ConfigureRelationAutoLoading(), DataMapper::Query(), DataMapper::Query(), DataMapper::QuerySingle(), and DataMapper::QuerySingle().

◆ CloseCursor()

LIGHTWEIGHT_FORCE_INLINE void SqlStatement::CloseCursor ( )

inlinenoexcept

Closes the result cursor on queries that yield a result set, e.g. SELECT statements.

Call this function when done with fetching the results before the end of the result set is reached.

Definition at line 871 of file SqlStatement.hpp.

References SqlLogger::GetLogger(), and SqlLogger::OnFetchEnd().

Referenced by DataMapper::ConfigureRelationAutoLoading(), DataMapper::QuerySingle(), and DataMapper::QuerySingle().

◆ GetResultCursor()

LIGHTWEIGHT_FORCE_INLINE SqlResultCursor SqlStatement::GetResultCursor ( )

inlinenoexcept

Retrieves the result cursor for reading an SQL query result.

Definition at line 878 of file SqlStatement.hpp.

Referenced by SqlQuerySingleBuilder< Record >::Get().

◆ GetVariantRowCursor()

LIGHTWEIGHT_FORCE_INLINE SqlVariantRowCursor SqlStatement::GetVariantRowCursor ( )

inlinenoexcept

Retrieves the variant row cursor for reading an SQL query result of unknown column types and column count.

Definition at line 883 of file SqlStatement.hpp.

◆ GetColumn() [1/2]

template<SqlGetColumnNativeType T>

bool SqlStatement::GetColumn	(	SQLUSMALLINT	column,
		T *	result
	)		const

inline

Retrieves the value of the column at the given index for the currently selected row.

Returns true if the value is not NULL, false otherwise.

Definition at line 779 of file SqlStatement.hpp.

Referenced by DataMapper::ConfigureRelationAutoLoading(), and DataMapper::Query().

◆ GetColumn() [2/2]

template<SqlGetColumnNativeType T>

T SqlStatement::GetColumn ( SQLUSMALLINT column ) const

inline

Retrieves the value of the column at the given index for the currently selected row.

Definition at line 795 of file SqlStatement.hpp.

◆ GetNullableColumn()

template<SqlGetColumnNativeType T>

std::optional< T > SqlStatement::GetNullableColumn ( SQLUSMALLINT column ) const

inline

Retrieves the value of the column at the given index for the currently selected row.

If the value is NULL, std::nullopt is returned.

Definition at line 807 of file SqlStatement.hpp.

◆ BindOutputColumns() [2/2]

template<SqlOutputColumnBinder... Args>

LIGHTWEIGHT_FORCE_INLINE void SqlStatement::BindOutputColumns ( Args *... args )

inline

Definition at line 602 of file SqlStatement.hpp.

◆ BindOutputColumn()

template<SqlOutputColumnBinder T>

LIGHTWEIGHT_FORCE_INLINE void SqlStatement::BindOutputColumn	(	SQLUSMALLINT	columnIndex,
		T *	arg
	)

inline

Definition at line 627 of file SqlStatement.hpp.

◆ BindInputParameter() [1/2]

template<SqlInputParameterBinder Arg>

LIGHTWEIGHT_FORCE_INLINE void SqlStatement::BindInputParameter	(	SQLSMALLINT	columnIndex,
		Arg const &	arg
	)

inline

Definition at line 636 of file SqlStatement.hpp.

◆ BindInputParameter() [2/2]

template<SqlInputParameterBinder Arg, typename ColumnName >

LIGHTWEIGHT_FORCE_INLINE void SqlStatement::BindInputParameter	(	SQLSMALLINT	columnIndex,
		Arg const &	arg,
		ColumnName &&	columnNameHint
	)

inline

Definition at line 644 of file SqlStatement.hpp.

◆ ExecuteBatch() [2/2]

template<SqlInputParameterBatchBinder FirstColumnBatch, std::ranges::range... MoreColumnBatches>

LIGHTWEIGHT_FORCE_INLINE void SqlStatement::ExecuteBatch	(	FirstColumnBatch const &	firstColumnBatch,
		MoreColumnBatches const &...	moreColumnBatches
	)

inline

Definition at line 742 of file SqlStatement.hpp.

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

Lightweight/SqlStatement.hpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ IsAlive()

◆ IsPrepared()

◆ Connection() [1/2]

◆ Connection() [2/2]

◆ LastError()

◆ NativeHandle()

◆ Prepare() [1/3]

◆ Prepare() [2/3]

◆ Prepare() [3/3]

◆ PreparedQuery()

◆ BindOutputColumns() [1/2]

◆ BindOutputColumnsToRecord()

◆ Execute()

◆ ExecuteBatchNative()

◆ ExecuteBatchSoft()

◆ ExecuteBatch() [1/2]

◆ ExecuteDirect()

◆ MigrateDirect()

◆ ExecuteDirectScalar() [1/4]

◆ ExecuteDirectScalar() [2/4]

◆ ExecuteDirectScalar() [3/4]

◆ ExecuteDirectScalar() [4/4]

◆ FetchRow()

◆ CloseCursor()

◆ GetResultCursor()

◆ GetVariantRowCursor()

◆ GetColumn() [1/2]

◆ GetColumn() [2/2]

◆ GetNullableColumn()

◆ BindOutputColumns() [2/2]

◆ BindOutputColumn()

◆ BindInputParameter() [1/2]

◆ BindInputParameter() [2/2]

◆ ExecuteBatch() [2/2]