Retry and Backoff

A reusable, injectable retry/backoff policy for transient database failures. More...

Classes
class	Lightweight::SqlRetryClassifier
	Dialect-specific classification of SQL errors into transient and permanent. More...
struct	Lightweight::SqlRetrySettings
struct	Lightweight::SqlRetryState
struct	Lightweight::SqlRetryDecision
struct	Lightweight::SqlRetryAttempt
class	Lightweight::SqlRetrySleeper
	Supplies the wait between retries. More...
class	Lightweight::SqlRetryPolicy
	A reusable retry/backoff policy for transient database failures. More...

Enumerations
enum class	Lightweight::SqlErrorTransience : std::uint8_t { SqlErrorTransience::Permanent , SqlErrorTransience::Transient }
enum class	Lightweight::SqlRetryAction : std::uint8_t { SqlRetryAction::Retry , SqlRetryAction::GiveUp }
enum class	Lightweight::SqlRetryGiveUpReason : std::uint8_t { SqlRetryGiveUpReason::None , SqlRetryGiveUpReason::NotTransient , SqlRetryGiveUpReason::RetriesExhausted , SqlRetryGiveUpReason::DelayBudgetExhausted }

Functions
LIGHTWEIGHT_API SqlRetryClassifier const &	Lightweight::GenericRetryOps () noexcept
	Returns the dialect-agnostic classifier.
LIGHTWEIGHT_API SqlRetryClassifier const &	Lightweight::SqliteRetryOps () noexcept
	Returns the SQLite-specific singleton classifier.
LIGHTWEIGHT_API SqlRetryClassifier const &	Lightweight::SqlServerRetryOps () noexcept
	Returns the SQL Server-specific singleton classifier. See SqliteRetryOps().
LIGHTWEIGHT_API SqlRetryClassifier const &	Lightweight::PostgreSqlRetryOps () noexcept
	Returns the PostgreSQL-specific singleton classifier. See SqliteRetryOps().
LIGHTWEIGHT_API SqlRetrySleeper &	Lightweight::ThreadSleeper () noexcept
	Returns the production sleeper, which forwards to std::this_thread::sleep_for.

Detailed Description

A reusable, injectable retry/backoff policy for transient database failures.

The pieces are deliberately split so each one is usable — and testable — on its own:

• SqlRetryClassifier decides whether a given SqlErrorInfo is worth another attempt. It is a per-DBMS extension point, reached through SqlQueryFormatter::RetryOps().
• SqlRetrySettings carries the backoff knobs (budget, initial delay, multiplier, caps).
• SqlRetryPolicy combines the two into a decision function and a small driver that runs a callable until it succeeds or the policy gives up.

Enumeration Type Documentation

SqlErrorTransience

enum class Lightweight::SqlErrorTransience : std::uint8_t

strong

Whether a failed operation is worth attempting again.

Enumerator
Permanent	The condition is permanent — a constraint violation, a syntax error, a missing table. Retrying it will fail identically, so the caller should surface the failure.
Transient	The condition is temporary — a dropped connection, a lock timeout, a deadlock-victim rollback. The very same statement may well succeed on a later attempt.

Definition at line 26 of file SqlRetryClassifier.hpp.

SqlRetryAction

enum class Lightweight::SqlRetryAction : std::uint8_t

strong

What a retry loop should do after an attempt failed.

Enumerator
Retry	Wait for SqlRetryDecision::delay and try again.
GiveUp	Surface the failure to the caller.

Definition at line 67 of file SqlRetryPolicy.hpp.

SqlRetryGiveUpReason

enum class Lightweight::SqlRetryGiveUpReason : std::uint8_t

strong

Why SqlRetryPolicy::Decide declined to retry. Reported so callers and logs can tell an exhausted budget apart from an error that was never retryable to begin with.

Enumerator
None	Not giving up — set when the action is SqlRetryAction::Retry.
NotTransient	The error is permanent; another attempt would fail identically.
RetriesExhausted	The error was transient, but SqlRetrySettings::maxRetries is spent.
DelayBudgetExhausted	The error was transient and retries remained, but the next delay would overrun SqlRetrySettings::totalDelayBudget.

Definition at line 79 of file SqlRetryPolicy.hpp.

Function Documentation

GenericRetryOps()

LIGHTWEIGHT_API SqlRetryClassifier const & Lightweight::GenericRetryOps ( )

noexcept

Returns the dialect-agnostic classifier.

Recognises the transient SQLSTATE classes every ODBC driver shares (connection class 08, transaction-rollback class 40, and the HYT00 / HYT01 timeouts) plus the widely observed native codes and driver messages. It is the fallback used when the dialect is not known — for instance when no connection is at hand, or for a server type that has no formatter of its own.

SqliteRetryOps()

LIGHTWEIGHT_API SqlRetryClassifier const & Lightweight::SqliteRetryOps ( )

noexcept

Returns the SQLite-specific singleton classifier.

Defined in SqlRetryPolicy.cpp for the same reason the advisory-lock handlers are defined out of line — the formatter overrides delegate to these free functions inline, which keeps every formatter's vtable weak. See SqliteAdvisoryLockOps().