StormByte::Database::Database Class Reference

Abstract backend. More...

#include <StormByte/database/database.hxx>

Inheritance diagram for StormByte::Database::Database:

Collaboration diagram for StormByte::Database::Database:

Public Member Functions
	Database (const StormByte::Shared< Logger::Log > &logger)
	Construct with an optional logger.
	Database (const Database &)=delete
	Copy constructor (deleted).
	Database (Database &&other) noexcept
	Move constructor.
Database &	operator= (const Database &)=delete
	Copy assignment (deleted).
Database &	operator= (Database &&other) noexcept
	Move assignment.
virtual	~Database () noexcept
	Destructor.
StormByte::Shared< Telemetry >	GetTelemetry () const noexcept
	Obtain the cumulative connection telemetry handle.
bool	Connect () noexcept
	Connect.
void	Disconnect () noexcept
	Disconnect.
bool	IsConnected () const noexcept
	Whether the connection is open.
void	SetSslMode (SslMode mode) noexcept
	TLS policy for the next Connect().
SslMode	GetSslMode () const noexcept
	Current TLS policy.
template<typename... Args>
ExpectedRows	ExecuteSTMT (std::string_view name, Args &&...args)
	Execute a prepared statement by name.
virtual ExpectedRows	Query (std::string_view query)=0
	Execute a query that returns rows.
virtual bool	SilentQuery (std::string_view query) noexcept=0
	Execute a query that does not return rows.
Expected< Transaction, TransactionError >	BeginTransaction (IsolationLevel level=IsolationLevel::Default)
	Begin a transaction.
void	CommitTransaction ()
	Commit the current transaction.
void	RollbackTransaction ()
	Roll back the current transaction.

Protected Member Functions
void	SetTelemetry (StormByte::Shared< Telemetry > telemetry) noexcept
	Replace the telemetry implementation, normally in a concrete backend constructor.
void	RecordBackendEvent (BackendEvent event) noexcept
	Record a categorized event reported by the active backend.
Telemetry::OperationScope	TrackOperation (Operation operation) const noexcept
	Start timing a Database operation without invoking user callbacks.
void	ClearPreparedSTMTs () noexcept
	Destroy all registered statements inside the Database module.
virtual StormByte::Unique< PreparedSTMT >	CreatePreparedSTMT (std::string_view name, std::string_view query) noexcept=0
	Create a backend prepared statement.
void	PrepareSTMT (std::string_view name, std::string_view query) noexcept
	Register a prepared statement under name.
void	DoPrepareSTMT (std::string_view name, std::string_view query) noexcept
	Same as PrepareSTMT; kept for hook symmetry.
virtual void	DoBeginTransaction (IsolationLevel level)=0
	Backend BEGIN with isolation.
virtual bool	DoSilentQuery (std::string_view query) noexcept=0
	Backend silent query.
Lifecycle hooks
Called by Connect() / Disconnect(). Prefer DoSilentQuery() and DoPrepareSTMT() from overrides.
virtual void	DoPreConnect () noexcept
	Pre-connect hook.
virtual bool	DoConnect () noexcept=0
	Backend connect.
virtual void	DoPostConnect () noexcept
	Post-connect hook.
virtual void	DoPreDisconnect () noexcept
	Pre-disconnect hook.
virtual void	DoDisconnect () noexcept=0
	Backend disconnect.
virtual void	DoPostDisconnect () noexcept
	Post-disconnect hook.

Protected Attributes
StormByte::Shared< std::recursive_mutex >	m_operation_mutex
	DLL-safe owner of the connection mutex.
StormByte::Shared< Telemetry >	m_telemetry
	Shared cumulative counters for this connection.
bool	m_connected
	Connection state.
SslMode	m_ssl_mode
	TLS policy for network backends.
StormByte::Shared< Logger::Log >	m_logger
	Shared logger, safe across the DLL boundary.

Friends
class	Transaction

Detailed Description

Abstract backend.

Note

Operations on one connection are serialized. A Transaction reserves its connection and must remain on its creating thread.

Custom backends must lock m_operation_mutex in public operations that access backend state.

Inheritance-oriented. Concrete backends expose protected constructors. Derive, call the backend constructor, override hooks if needed.

Constructor & Destructor Documentation

Database() [1/3]

StormByte::Database::Database::Database

(

const StormByte::Shared< Logger::Log > &

logger

)

Construct with an optional logger.

Parameters

logger

Logger instance (may be null).

Database() [2/3]

StormByte::Database::Database::Database ( const Database &  )

delete

Copy constructor (deleted).

Database() [3/3]

StormByte::Database::Database::Database ( Database &&  other )

noexcept

Move constructor.

~Database()

virtual StormByte::Database::Database::~Database ( )

virtualnoexcept

Destructor.

Member Function Documentation

BeginTransaction()

Expected< Transaction, TransactionError > StormByte::Database::Database::BeginTransaction

(

IsolationLevel

level = IsolationLevel::Default

)

Begin a transaction.

Parameters

level

Isolation (backend-specific mapping).

Returns

RAII Transaction (rollback on destruction if not committed).

ClearPreparedSTMTs()

void StormByte::Database::Database::ClearPreparedSTMTs ( )

protectednoexcept

Destroy all registered statements inside the Database module.

CommitTransaction()

void StormByte::Database::Database::CommitTransaction

(

)

Commit the current transaction.

Connect()

bool StormByte::Database::Database::Connect ( )

noexcept

Connect.

Returns

true on success.

CreatePreparedSTMT()

virtual StormByte::Unique< PreparedSTMT > StormByte::Database::Database::CreatePreparedSTMT ( std::string_view  name, std::string_view  query  )

protectedpure virtualnoexcept

Create a backend prepared statement.

Parameters

name	Statement name.
query	SQL text.

Returns

Statement or nullptr on failure.

Disconnect()

void StormByte::Database::Database::Disconnect ( )

noexcept

Disconnect.

Note

Has no effect when the database is already disconnected.

DoBeginTransaction()

virtual void StormByte::Database::Database::DoBeginTransaction ( IsolationLevel  level )

protectedpure virtual

Backend BEGIN with isolation.

Parameters

level

Isolation level.

DoConnect()

virtual bool StormByte::Database::Database::DoConnect ( )

protectedpure virtualnoexcept

Backend connect.

Returns

true on success.

DoDisconnect()

virtual void StormByte::Database::Database::DoDisconnect ( )

protectedpure virtualnoexcept

Backend disconnect.

DoPostConnect()

virtual void StormByte::Database::Database::DoPostConnect ( )

inlineprotectedvirtualnoexcept

Post-connect hook.

Default no-op.

DoPostDisconnect()

virtual void StormByte::Database::Database::DoPostDisconnect ( )

inlineprotectedvirtualnoexcept

Post-disconnect hook.

Default no-op.

DoPreConnect()

virtual void StormByte::Database::Database::DoPreConnect ( )

inlineprotectedvirtualnoexcept

Pre-connect hook.

Default no-op.

DoPreDisconnect()

virtual void StormByte::Database::Database::DoPreDisconnect ( )

inlineprotectedvirtualnoexcept

Pre-disconnect hook.

Default no-op.

DoPrepareSTMT()

void StormByte::Database::Database::DoPrepareSTMT ( std::string_view  name, std::string_view  query  )

protectednoexcept

Same as PrepareSTMT; kept for hook symmetry.

Parameters

name	Statement name.
query	SQL text.

DoSilentQuery()

virtual bool StormByte::Database::Database::DoSilentQuery ( std::string_view  query )

protectedpure virtualnoexcept

Backend silent query.

Parameters

query

SQL text.

Returns

true on success.

Implemented in StormByte::Database::MariaDB::MariaDB, StormByte::Database::Postgres::Postgres, and StormByte::Database::SQLite::SQLite3.

ExecuteSTMT()

template<typename... Args>

ExpectedRows StormByte::Database::Database::ExecuteSTMT ( std::string_view  name, Args &&...  args  )

inline

Execute a prepared statement by name.

Template Parameters

Args	Bind argument types.

Parameters

name	Prepared statement name.
args	Positional values (0-based).

Returns

Result rows or an error.

GetSslMode()

SslMode StormByte::Database::Database::GetSslMode ( ) const

inlinenoexcept

Current TLS policy.

Returns

Mode.

GetTelemetry()

StormByte::Shared< Telemetry > StormByte::Database::Database::GetTelemetry ( ) const

noexcept

Obtain the cumulative connection telemetry handle.

Returns

Shared counters that remain valid after close or Database destruction.

IsConnected()

bool StormByte::Database::Database::IsConnected ( ) const

inlinenoexcept

Whether the connection is open.

Returns

true if connected.

operator=() [1/2]

Database & StormByte::Database::Database::operator= ( const Database &  )

delete

Copy assignment (deleted).

operator=() [2/2]

Database & StormByte::Database::Database::operator= ( Database &&  other )

noexcept

Move assignment.

PrepareSTMT()

void StormByte::Database::Database::PrepareSTMT ( std::string_view  name, std::string_view  query  )

protectednoexcept

Register a prepared statement under name.

Parameters

name	Statement name.
query	SQL text.

Query()

virtual ExpectedRows StormByte::Database::Database::Query ( std::string_view  query )

pure virtual

Execute a query that returns rows.

Parameters

query

SQL text.

Returns

Result rows or an error.

Implemented in StormByte::Database::MariaDB::MariaDB, StormByte::Database::Postgres::Postgres, and StormByte::Database::SQLite::SQLite3.

RecordBackendEvent()

void StormByte::Database::Database::RecordBackendEvent ( BackendEvent  event )

inlineprotectednoexcept

Record a categorized event reported by the active backend.

Parameters

event

Backend event category.

RollbackTransaction()

void StormByte::Database::Database::RollbackTransaction

(

)

Roll back the current transaction.

SetSslMode()

void StormByte::Database::Database::SetSslMode ( SslMode  mode )

inlinenoexcept

TLS policy for the next Connect().

Ignored by SQLite.

Parameters

mode	Desired SSL mode.

SetTelemetry()

void StormByte::Database::Database::SetTelemetry ( StormByte::Shared< Telemetry >  telemetry )

protectednoexcept

Replace the telemetry implementation, normally in a concrete backend constructor.

Parameters

telemetry

Backend-specific telemetry allocated on Base's heap.

SilentQuery()

virtual bool StormByte::Database::Database::SilentQuery ( std::string_view  query )

pure virtualnoexcept

Execute a query that does not return rows.

Parameters

query

SQL text.

Returns

true on success.

Implemented in StormByte::Database::MariaDB::MariaDB, StormByte::Database::Postgres::Postgres, and StormByte::Database::SQLite::SQLite3.

TrackOperation()

Telemetry::OperationScope StormByte::Database::Database::TrackOperation ( Operation  operation ) const

inlineprotectednoexcept

Start timing a Database operation without invoking user callbacks.

Parameters

operation

Operation category.

Returns

Scope that records failure unless Complete() reports otherwise.

Friends And Related Symbol Documentation

Transaction

friend class Transaction

friend

Member Data Documentation

m_connected

bool StormByte::Database::Database::m_connected

protected

Connection state.

m_logger

StormByte::Shared<Logger::Log> StormByte::Database::Database::m_logger

protected

Shared logger, safe across the DLL boundary.

m_operation_mutex

StormByte::Shared<std::recursive_mutex> StormByte::Database::Database::m_operation_mutex

protected

DLL-safe owner of the connection mutex.

m_ssl_mode

SslMode StormByte::Database::Database::m_ssl_mode

protected

TLS policy for network backends.

m_telemetry

StormByte::Shared<Telemetry> StormByte::Database::Database::m_telemetry

protected

Shared cumulative counters for this connection.

---

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

• lib/public/StormByte/database/database.hxx