Lightweight 0.20250904.0
Loading...
Searching...
No Matches
Public Member Functions | List of all members
Lightweight::SqlStatement Class Referencefinal

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

#include <SqlStatement.hpp>

Inheritance diagram for Lightweight::SqlStatement:
Lightweight::SqlDataBinderCallback

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
 
LIGHTWEIGHT_API SqlStatement & operator= (SqlStatement &&other) 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 (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())
 
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<SqlGetColumnNativeType T>
T GetColumnOr (SQLUSMALLINT column, T &&defaultValue) 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 Lightweight::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:

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

Definition at line 50 of file SqlStatement.hpp.

Member Function Documentation

◆ IsAlive()

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

Definition at line 578 of file SqlStatement.hpp.

◆ IsPrepared()

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

Definition at line 583 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 588 of file SqlStatement.hpp.

Referenced by Lightweight::SqlCoreDataMapperQueryBuilder< Record, Derived >::All(), Lightweight::SqlCoreDataMapperQueryBuilder< Record, Derived >::All(), MigrateDirect(), Lightweight::DataMapper::Query(), Lightweight::DataMapper::Query(), Lightweight::DataMapper::QuerySingleWithoutRelationAutoLoading(), and Lightweight::DataMapper::QueryToTuple().

◆ Connection() [2/2]

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

Retrieves the connection associated with this statement.

Definition at line 593 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 598 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 603 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::CreateExplicit(), Lightweight::DataMapper::Delete(), Lightweight::DataMapper::Query(), Lightweight::DataMapper::Query(), Lightweight::DataMapper::QuerySingleWithoutRelationAutoLoading(), Lightweight::DataMapper::QueryToTuple(), 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 608 of file SqlStatement.hpp.

◆ Prepare() [3/3]

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

Definition at line 613 of file SqlStatement.hpp.

◆ PreparedQuery()

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

Definition at line 618 of file SqlStatement.hpp.

◆ BindOutputColumns() [1/2]

template<SqlOutputColumnBinder... Args>
void Lightweight::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 Lightweight::SqlStatement::BindOutputColumnsToRecord ( Records *...  records)

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

Parameters
recordsThe 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 634 of file SqlStatement.hpp.

◆ Execute()

template<SqlInputParameterBinder... Args>
void Lightweight::SqlStatement::Execute ( Args const &...  args)

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

Definition at line 674 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::CreateExplicit(), Lightweight::DataMapper::Delete(), Lightweight::DataMapper::Query(), Lightweight::DataMapper::Query(), Lightweight::DataMapper::QuerySingleWithoutRelationAutoLoading(), Lightweight::DataMapper::QueryToTuple(), and Lightweight::DataMapper::Update().

◆ ExecuteBatchNative()

template<SqlInputParameterBatchBinder FirstColumnBatch, std::ranges::contiguous_range... MoreColumnBatches>
void 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 731 of file SqlStatement.hpp.

◆ ExecuteBatchSoft()

template<SqlInputParameterBatchBinder FirstColumnBatch, std::ranges::range... MoreColumnBatches>
void 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 775 of file SqlStatement.hpp.

◆ ExecuteBatch() [1/2]

template<SqlInputParameterBatchBinder FirstColumnBatch, std::ranges::range... MoreColumnBatches>
void 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.

◆ ExecuteDirect()

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

Executes the given query directly.

Definition at line 843 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 851 of file SqlStatement.hpp.

References CloseCursor(), 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 865 of file SqlStatement.hpp.

◆ 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

Definition at line 875 of file SqlStatement.hpp.

◆ 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 887 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

Definition at line 894 of file SqlStatement.hpp.

◆ FetchRow()

LIGHTWEIGHT_API bool Lightweight::SqlStatement::FetchRow ( )

Fetches the next row of the result set.

Note
Automatically closes the cursor at the end of the result set.
Return values
trueThe next result row was successfully fetched
falseNo result row was fetched, because the end of the result set was reached.

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

◆ CloseCursor()

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

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

Referenced by Lightweight::DataMapper::ConfigureRelationAutoLoading(), and MigrateDirect().

◆ GetResultCursor()

LIGHTWEIGHT_FORCE_INLINE SqlResultCursor Lightweight::SqlStatement::GetResultCursor ( )
inlinenoexcept

Retrieves the result cursor for reading an SQL query result.

Definition at line 906 of file SqlStatement.hpp.

Referenced by Lightweight::SqlCoreDataMapperQueryBuilder< Record, Derived >::All(), Lightweight::SqlCoreDataMapperQueryBuilder< Record, Derived >::All(), Lightweight::SqlCoreDataMapperQueryBuilder< Record, Derived >::Count(), Lightweight::DataMapper::Query(), Lightweight::DataMapper::Query(), Lightweight::DataMapper::QuerySingleWithoutRelationAutoLoading(), and Lightweight::DataMapper::QueryToTuple().

◆ GetVariantRowCursor()

LIGHTWEIGHT_FORCE_INLINE SqlVariantRowCursor Lightweight::SqlStatement::GetVariantRowCursor ( )
inlinenoexcept

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

Definition at line 911 of file SqlStatement.hpp.

◆ GetColumn() [1/2]

template<SqlGetColumnNativeType T>
bool Lightweight::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 799 of file SqlStatement.hpp.

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

◆ GetColumn() [2/2]

template<SqlGetColumnNativeType T>
T Lightweight::SqlStatement::GetColumn ( SQLUSMALLINT  column) const
inline

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

Definition at line 815 of file SqlStatement.hpp.

◆ GetNullableColumn()

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

◆ GetColumnOr()

template<SqlGetColumnNativeType T>
T Lightweight::SqlStatement::GetColumnOr ( SQLUSMALLINT  column,
T &&  defaultValue 
) const

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

If the value is NULL, the given defaultValue is returned.

Definition at line 838 of file SqlStatement.hpp.

◆ BindOutputColumns() [2/2]

template<SqlOutputColumnBinder... Args>
LIGHTWEIGHT_FORCE_INLINE void Lightweight::SqlStatement::BindOutputColumns ( Args *...  args)
inline

Definition at line 624 of file SqlStatement.hpp.

◆ BindOutputColumn()

template<SqlOutputColumnBinder T>
LIGHTWEIGHT_FORCE_INLINE void Lightweight::SqlStatement::BindOutputColumn ( SQLUSMALLINT  columnIndex,
T *  arg 
)
inline

Definition at line 649 of file SqlStatement.hpp.

◆ BindInputParameter() [1/2]

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

Definition at line 657 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

Definition at line 665 of file SqlStatement.hpp.

◆ ExecuteBatch() [2/2]

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

Definition at line 763 of file SqlStatement.hpp.

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