Lightweight::SqlFaultSource Class Reference

Substitutes a scripted failure for an ODBC call that actually succeeded. More...

#include <Utils.hpp>

Public Member Functions
	SqlFaultSource (SqlFaultSource const &)=delete
SqlFaultSource &	operator= (SqlFaultSource const &)=delete
	SqlFaultSource (SqlFaultSource &&)=delete
SqlFaultSource &	operator= (SqlFaultSource &&)=delete
virtual std::optional< SqlErrorInfo >	NextFailure (SQLHSTMT hStmt, std::source_location const &sourceLocation)=0
	Decides whether the next statement-handle check should fail.
virtual std::optional< SqlErrorInfo >	NextConnectionFailure (SQLHDBC hDbc, std::source_location const &sourceLocation)
	Decides whether the next connection-handle check should fail.

Detailed Description

Substitutes a scripted failure for an ODBC call that actually succeeded.

Exists so error-recovery paths can be driven from a test. Some failures cannot be provoked through a real driver at all: a backup worker's transient-error retry arm needs a class-08 or HYT00 SQLSTATE, but every fault reachable from a test file (unreachable driver, unwritable path, dropped table) surfaces as HY000, which the retry policy classifies as non-transient. Without a seam those arms are unreachable rather than merely untested.

Production code never installs one: with no source configured, RequireSuccess consults nothing and returns on success exactly as before. This mirrors SqlDiagnosticSource and SqlLogger::SetLogger, injection mechanisms the project already uses.

See also

SetFaultSource

Definition at line 476 of file Utils.hpp.

Member Function Documentation

NextFailure()

virtual std::optional< SqlErrorInfo > Lightweight::SqlFaultSource::NextFailure ( SQLHSTMT  hStmt, std::source_location const &  sourceLocation  )

pure virtual

Decides whether the next statement-handle check should fail.

Called by RequireSuccess for a call that the driver reported as successful. Returning an engaged optional makes RequireSuccess throw SqlException carrying that diagnostic, as though the driver had failed.

Note

Never called for a null statement handle. RequireSuccess also guards SQLAllocHandle during statement construction, where failing would leave a half-constructed SqlStatement whose destructor cannot release the handle; it therefore skips injection entirely while hStmt is still SQL_NULL_HSTMT. A fake may narrow further via sourceLocation — the function name of a real execution is ExecuteDirect / Execute / Prepare — but does not have to in order to be safe.

Parameters

hStmt	The statement handle being checked, never SQL_NULL_HSTMT. A fake may ignore it.
sourceLocation	Where in the library the check is happening.

Returns

The error to inject, or std::nullopt to let the successful call through.

NextConnectionFailure()

virtual std::optional< SqlErrorInfo > Lightweight::SqlFaultSource::NextConnectionFailure ( SQLHDBC  hDbc, std::source_location const &  sourceLocation  )

inlinevirtual

Decides whether the next connection-handle check should fail.

The connection-side counterpart of NextFailure, consulted by detail::CheckOdbcConnectionCall for a call that the driver reported as successful on a SQLHDBC rather than a SQLHSTMT (e.g. a pre-connect attribute set). Returning an engaged optional makes the caller treat the call as failed, exactly as an injected NextFailure does for a statement check.

Defaults to never injecting, so a fake that predates connection-handle support and overrides only NextFailure keeps compiling and behaving exactly as before.

Note

Never called for a null connection handle, for the same reason NextFailure is never called for a null statement handle: a fault injected while a SqlConnection is still being constructed or is in the middle of tearing down its handle could leave the handle leaked or double-released.

Parameters

hDbc	The connection handle being checked, never SQL_NULL_HDBC. A fake may ignore it.
sourceLocation	Where in the library the check is happening.

Returns

The error to inject, or std::nullopt to let the successful call through.

Definition at line 524 of file Utils.hpp.

---

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

• Lightweight/Utils.hpp