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

#include <SqlStatement.hpp>

Inheritance diagram for Lightweight::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 &&other) noexcept
	Move constructor.

LIGHTWEIGHT_API SqlStatement &	operator= (SqlStatement &&other) noexcept
	Move assignment operator.

	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
	Checks whether the statement's connection is alive and the statement handle is valid.

LIGHTWEIGHT_API bool	IsPrepared () const noexcept
	Checks whether the statement has been prepared.

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) &&
	Prepares the statement for execution on an rvalue reference and returns the statement.

void	Prepare (SqlQueryObject auto const &queryObject) &

SqlStatement	Prepare (SqlQueryObject auto const &queryObject) &&
	Prepares the statement from a query object on an rvalue reference and returns the statement.

std::string const &	PreparedQuery () const noexcept
	Retrieves the last prepared query string.

template<SqlInputParameterBinder Arg>
void	BindInputParameter (SQLSMALLINT columnIndex, Arg const &arg)
	Binds an input parameter to the prepared statement at the given column index.

template<SqlInputParameterBinder Arg, typename ColumnName >
void	BindInputParameter (SQLSMALLINT columnIndex, Arg const &arg, ColumnName &&columnNameHint)
	Binds an input parameter to the prepared statement at the given column index with a column name hint.

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

LIGHTWEIGHT_API SqlResultCursor	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>
SqlResultCursor	ExecuteBatchNative (FirstColumnBatch const &firstColumnBatch, MoreColumnBatches const &... moreColumnBatches)

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

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

LIGHTWEIGHT_API SqlResultCursor	ExecuteBatch (std::span< SqlRawColumn const > columns, size_t rowCount)

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

SqlResultCursor	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 (std::string_view const &query, std::source_location location=std::source_location::current())

template<typename T > requires (std::same_as<T, SqlVariant>)
T	ExecuteDirectScalar (std::string_view const &query, std::source_location location=std::source_location::current())
	Executes the given query and returns the single result as an SqlVariant.

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())
	Executes the given query object and returns the single result as an SqlVariant.

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

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)
	Binds an input parameter to the prepared statement at the given column index.

template<SqlInputParameterBinder Arg, typename ColumnName >
LIGHTWEIGHT_FORCE_INLINE void	BindInputParameter (SQLSMALLINT columnIndex, Arg const &arg, ColumnName &&columnNameHint)
	Binds an input parameter to the prepared statement at the given column index with a column name hint.

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

Public Member Functions inherited from Lightweight::SqlDataBinderCallback
	SqlDataBinderCallback ()=default
	Default constructor.

	SqlDataBinderCallback (SqlDataBinderCallback &&)=default
	Default move constructor.

	SqlDataBinderCallback (SqlDataBinderCallback const &)=default
	Default copy constructor.

SqlDataBinderCallback &	operator= (SqlDataBinderCallback &&)=default
	Default move assignment operator.

SqlDataBinderCallback &	operator= (SqlDataBinderCallback const &)=default
	Default copy assignment operator.

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 52 of file SqlStatement.hpp.

Member Function Documentation

◆ IsAlive()

LIGHTWEIGHT_FORCE_INLINE bool Lightweight::SqlStatement::IsAlive ( ) const

inlinenoexcept

Checks whether the statement's connection is alive and the statement handle is valid.

Definition at line 594 of file SqlStatement.hpp.

References Lightweight::SqlConnection::IsAlive().

◆ IsPrepared()

LIGHTWEIGHT_FORCE_INLINE bool Lightweight::SqlStatement::IsPrepared ( ) const

inlinenoexcept

Checks whether the statement has been prepared.

Definition at line 599 of file SqlStatement.hpp.

◆ Connection() [1/2]

LIGHTWEIGHT_FORCE_INLINE SqlConnection & Lightweight::SqlStatement::Connection ( )

inlinenoexcept

Retrieves the connection associated with this statement.

Definition at line 604 of file SqlStatement.hpp.

◆ Connection() [2/2]

LIGHTWEIGHT_FORCE_INLINE SqlConnection const & Lightweight::SqlStatement::Connection ( ) const

inlinenoexcept

Retrieves the connection associated with this statement.

Definition at line 609 of file SqlStatement.hpp.

◆ LastError()

LIGHTWEIGHT_FORCE_INLINE SqlErrorInfo Lightweight::SqlStatement::LastError ( ) const

inline

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

Definition at line 614 of file SqlStatement.hpp.

References Lightweight::SqlErrorInfo::FromStatementHandle().

◆ NativeHandle()

LIGHTWEIGHT_FORCE_INLINE SQLHSTMT Lightweight::SqlStatement::NativeHandle ( ) const

inlinenoexcept

Retrieves the native handle of the statement.

Definition at line 619 of file SqlStatement.hpp.

◆ Prepare() [1/3]

LIGHTWEIGHT_API void Lightweight::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 Lightweight::DataMapper::ConfigureRelationAutoLoading(), Lightweight::DataMapper::Delete(), Lightweight::DataMapper::Query(), Lightweight::DataMapper::Query(), Lightweight::DataMapper::Query(), Lightweight::DataMapper::QuerySingle(), and Lightweight::DataMapper::Update().

◆ Prepare() [2/3]

LIGHTWEIGHT_FORCE_INLINE void Lightweight::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 624 of file SqlStatement.hpp.

◆ Prepare() [3/3]

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

inline

Prepares the statement from a query object on an rvalue reference and returns the statement.

Definition at line 629 of file SqlStatement.hpp.

◆ PreparedQuery()

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

inlinenoexcept

Retrieves the last prepared query string.

Definition at line 634 of file SqlStatement.hpp.

◆ Execute()

template<SqlInputParameterBinder... Args>

SqlResultCursor Lightweight::SqlStatement::Execute ( Args const &... args )

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

Definition at line 694 of file SqlStatement.hpp.

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

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

◆ ExecuteBatchNative()

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

SqlResultCursor Lightweight::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 752 of file SqlStatement.hpp.

Referenced by ExecuteBatch().

◆ ExecuteBatchSoft()

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

SqlResultCursor Lightweight::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 800 of file SqlStatement.hpp.

Referenced by ExecuteBatch().

◆ ExecuteBatch() [1/3]

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

SqlResultCursor Lightweight::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.

◆ ExecuteBatch() [2/3]

LIGHTWEIGHT_API SqlResultCursor Lightweight::SqlStatement::ExecuteBatch	(	std::span< SqlRawColumn const >	columns,
		size_t	rowCount
	)

Executes the prepared statement on a batch of SqlRawColumn-prepared data.

Parameters

columns	The columns to bind as input parameters.
rowCount	The number of rows to execute.

◆ ExecuteDirect()

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

inline

Executes the given query directly.

Definition at line 872 of file SqlStatement.hpp.

References ExecuteDirect().

◆ MigrateDirect()

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

void Lightweight::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 880 of file SqlStatement.hpp.

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

◆ ExecuteDirectScalar() [1/4]

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

std::optional< T > Lightweight::SqlStatement::ExecuteDirectScalar	(	std::string_view 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 893 of file SqlStatement.hpp.

Referenced by Lightweight::DataMapper::Execute().

◆ ExecuteDirectScalar() [2/4]

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

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

inline

Executes the given query and returns the single result as an SqlVariant.

Definition at line 902 of file SqlStatement.hpp.

References Lightweight::SqlNullValue.

◆ ExecuteDirectScalar() [3/4]

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

std::optional< T > Lightweight::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 913 of file SqlStatement.hpp.

◆ ExecuteDirectScalar() [4/4]

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

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

inline

Executes the given query object and returns the single result as an SqlVariant.

Definition at line 920 of file SqlStatement.hpp.

◆ BindOutputColumns()

template<SqlOutputColumnBinder... Args>

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

inline

Definition at line 641 of file SqlStatement.hpp.

◆ BindOutputColumn()

template<SqlOutputColumnBinder T>

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

inline

Definition at line 667 of file SqlStatement.hpp.

◆ BindInputParameter() [1/2]

template<SqlInputParameterBinder Arg>

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

inline

Binds an input parameter to the prepared statement at the given column index.

Definition at line 676 of file SqlStatement.hpp.

◆ BindInputParameter() [2/2]

template<SqlInputParameterBinder Arg, typename ColumnName >

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

inline

Binds an input parameter to the prepared statement at the given column index with a column name hint.

Definition at line 685 of file SqlStatement.hpp.

References BindInputParameter(), Lightweight::SqlLogger::GetLogger(), and Lightweight::SqlLogger::OnBindInputParameter().

◆ ExecuteBatch() [3/3]

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

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

inline

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.

Definition at line 788 of file SqlStatement.hpp.

References ExecuteBatchNative(), and ExecuteBatchSoft().

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()

◆ Execute()

◆ ExecuteBatchNative()

◆ ExecuteBatchSoft()

◆ ExecuteBatch() [1/3]

◆ ExecuteBatch() [2/3]

◆ ExecuteDirect()

◆ MigrateDirect()

◆ ExecuteDirectScalar() [1/4]

◆ ExecuteDirectScalar() [2/4]

◆ ExecuteDirectScalar() [3/4]

◆ ExecuteDirectScalar() [4/4]

◆ BindOutputColumns()

◆ BindOutputColumn()

◆ BindInputParameter() [1/2]

◆ BindInputParameter() [2/2]

◆ ExecuteBatch() [3/3]