database::core::database_backend Class Reference

Abstract base class for database backends. More...

#include <database_backend.h>

Inheritance diagram for database::core::database_backend:

Collaboration diagram for database::core::database_backend:

Public Member Functions
virtual	~database_backend ()=default
virtual database_types	type () const =0
	Get the database type of this backend.
virtual kcenon::common::VoidResult	initialize (const connection_config &config)=0
	Initialize the database backend.
virtual kcenon::common::VoidResult	shutdown ()=0
	Shutdown the database backend gracefully.
virtual bool	is_initialized () const =0
	Check if backend is initialized and ready.
virtual kcenon::common::Result< database_result >	select_query (const std::string &query_string)=0
	Execute a SELECT query.
virtual kcenon::common::VoidResult	execute_query (const std::string &query_string)=0
	Execute a general SQL query (DDL, DML)
virtual kcenon::common::Result< database_result >	select_prepared (const std::string &query, const std::vector< database_value > &params)
	Execute a parameterized SELECT query (prepared statement)
virtual kcenon::common::VoidResult	execute_prepared (const std::string &query, const std::vector< database_value > &params)
	Execute a parameterized DML/DDL query (prepared statement)
virtual kcenon::common::VoidResult	begin_transaction ()=0
	Begin a transaction.
virtual kcenon::common::VoidResult	commit_transaction ()=0
	Commit the current transaction.
virtual kcenon::common::VoidResult	rollback_transaction ()=0
	Rollback the current transaction.
virtual bool	in_transaction () const =0
	Check if backend is currently in a transaction.
virtual std::string	last_error () const =0
	Get last error message from backend.
virtual std::map< std::string, std::string >	connection_info () const =0
	Get backend-specific connection information.

Static Protected Member Functions
static std::string	expand_params (const std::string &query, const std::vector< database_value > &params)
	Expand positional parameters into a SQL string (fallback)

Static Private Member Functions
static std::string	value_to_sql (const database_value &val)

Detailed Description

Abstract base class for database backends.

All database backends (PostgreSQL, SQLite, MongoDB, Redis) must implement this interface. This enables runtime polymorphism and eliminates conditional compilation.

Design Pattern:

• Strategy pattern: Backends implement different strategies for database access
• Factory pattern: backend_registry creates backends by name
• RAII: Backends manage connection lifecycle (connect in init, disconnect in shutdown)

Thread Safety:

• Implementations must be thread-safe for read operations
• Write operations require external synchronization or internal locking

Example Usage:

auto backend = backend_registry::create("postgresql", config);
if (auto result = backend->initialize(); !result) {
    // Handle initialization error
}
auto rows = backend->select_query("SELECT * FROM users");
backend->execute_query("INSERT INTO users (name) VALUES ('John')");
backend->shutdown();

Definition at line 98 of file database_backend.h.

Constructor & Destructor Documentation

~database_backend()

virtual database::core::database_backend::~database_backend ( )

virtualdefault

Member Function Documentation

begin_transaction()

virtual kcenon::common::VoidResult database::core::database_backend::begin_transaction ( )

pure virtual

Begin a transaction.

Returns

VoidResult::ok() on success, error on failure

Implemented in database::backends::mongodb_backend, database::backends::postgresql_backend, database::backends::redis_backend, database::backends::sqlite_backend, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

commit_transaction()

virtual kcenon::common::VoidResult database::core::database_backend::commit_transaction ( )

pure virtual

Commit the current transaction.

Returns

VoidResult::ok() on success, error on failure

Implemented in database::backends::mongodb_backend, database::backends::postgresql_backend, database::backends::redis_backend, database::backends::sqlite_backend, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

connection_info()

virtual std::map< std::string, std::string > database::core::database_backend::connection_info ( ) const

pure virtual

Get backend-specific connection information.

Returns

Map of connection properties (for debugging/monitoring)

Example keys: "server_version", "connection_id", "protocol_version"

Implemented in database::backends::mongodb_backend, database::backends::postgresql_backend, database::backends::redis_backend, database::backends::sqlite_backend, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

execute_prepared()

virtual kcenon::common::VoidResult database::core::database_backend::execute_prepared ( const std::string & query, const std::vector< database_value > & params )

inlinenodiscardvirtual

Execute a parameterized DML/DDL query (prepared statement)

Parameters

query	SQL with positional placeholders ($1, $2, ... or ?, ?, ...)
params	Parameter values to bind

Returns

VoidResult::ok() on success, error on failure

See also

select_prepared for details on parameterized queries

Reimplemented in database::backends::postgresql_backend, and database::backends::sqlite_backend.

Definition at line 187 of file database_backend.h.

    {
        auto expanded = expand_params(query, params);
        return execute_query(expanded);
    }

References execute_query(), and expand_params().

Here is the call graph for this function:

execute_query()

virtual kcenon::common::VoidResult database::core::database_backend::execute_query ( const std::string & query_string )

pure virtual

Execute a general SQL query (DDL, DML)

Parameters

query_string

SQL statement

Returns

VoidResult::ok() on success, error on failure

Implemented in database::backends::mongodb_backend, database::backends::postgresql_backend, database::backends::redis_backend, database::backends::sqlite_backend, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

Referenced by execute_prepared().

Here is the caller graph for this function:

expand_params()

static std::string database::core::database_backend::expand_params ( const std::string & query, const std::vector< database_value > & params )

inlinestaticprotected

Expand positional parameters into a SQL string (fallback)

Substitutes $1, $2, ... or ?, ?, ... placeholders with stringified parameter values. Used by the default select_prepared/execute_prepared implementations. Backends with native prepared statements should override the virtual methods instead of relying on this.

Warning

This performs string interpolation, NOT wire-level binding. Override select_prepared/execute_prepared for true security.

Definition at line 245 of file database_backend.h.

    {
        std::string result = query;
 
        // Replace $N placeholders (PostgreSQL-style, 1-indexed)
        for (size_t i = params.size(); i > 0; --i) {
            auto placeholder = "$" + std::to_string(i);
            auto pos = result.find(placeholder);
            if (pos != std::string::npos) {
                result.replace(pos, placeholder.size(), value_to_sql(params[i - 1]));
            }
        }
 
        // Replace ? placeholders (SQLite-style, left-to-right)
        size_t param_idx = 0;
        auto pos = result.find('?');
        while (pos != std::string::npos && param_idx < params.size()) {
            auto val = value_to_sql(params[param_idx++]);
            result.replace(pos, 1, val);
            pos = result.find('?', pos + val.size());
        }
 
        return result;
    }

References value_to_sql().

Referenced by execute_prepared(), and select_prepared().

Here is the call graph for this function:

Here is the caller graph for this function:

in_transaction()

virtual bool database::core::database_backend::in_transaction ( ) const

pure virtual

Check if backend is currently in a transaction.

Returns

true if transaction is active

Implemented in database::backends::mongodb_backend, database::backends::postgresql_backend, database::backends::redis_backend, database::backends::sqlite_backend, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

initialize()

virtual kcenon::common::VoidResult database::core::database_backend::initialize ( const connection_config & config )

pure virtual

Initialize the database backend.

Parameters

config

Connection configuration

Returns

VoidResult::ok() on success, error on failure

This method should:

• Establish database connection
• Validate connection parameters
• Set up connection pooling if applicable
• Initialize backend-specific resources

Implemented in database::core::backend_base< Derived, Type >, database::core::backend_base< mongodb_backend, database_types::mongodb >, database::core::backend_base< postgresql_backend, database_types::postgres >, database::core::backend_base< redis_backend, database_types::redis >, database::core::backend_base< sqlite_backend, database_types::sqlite >, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

is_initialized()

virtual bool database::core::database_backend::is_initialized ( ) const

pure virtual

Check if backend is initialized and ready.

Returns

true if initialized and can accept queries

Implemented in database::core::backend_base< Derived, Type >, database::core::backend_base< mongodb_backend, database_types::mongodb >, database::core::backend_base< postgresql_backend, database_types::postgres >, database::core::backend_base< redis_backend, database_types::redis >, database::core::backend_base< sqlite_backend, database_types::sqlite >, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

last_error()

virtual std::string database::core::database_backend::last_error ( ) const

pure virtual

Get last error message from backend.

Returns

Error message, or empty string if no error

Implemented in database::backends::mongodb_backend, database::backends::postgresql_backend, database::backends::redis_backend, database::backends::sqlite_backend, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

rollback_transaction()

virtual kcenon::common::VoidResult database::core::database_backend::rollback_transaction ( )

pure virtual

Rollback the current transaction.

Returns

VoidResult::ok() on success, error on failure

Implemented in database::backends::mongodb_backend, database::backends::postgresql_backend, database::backends::redis_backend, database::backends::sqlite_backend, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

select_prepared()

virtual kcenon::common::Result< database_result > database::core::database_backend::select_prepared ( const std::string & query, const std::vector< database_value > & params )

inlinenodiscardvirtual

Execute a parameterized SELECT query (prepared statement)

Parameters are bound at the wire-protocol level, providing stronger SQL injection protection than string escaping. Backends that support native prepared statements (PostgreSQL, SQLite) should override this.

Parameters

query	SQL with positional placeholders ($1, $2, ... or ?, ?, ...)
params	Parameter values to bind

Returns

Query results as rows, or error

Note

Default implementation falls back to string interpolation via execute_query/select_query for backends that have not yet implemented native prepared statement support.

Reimplemented in database::backends::postgresql_backend, and database::backends::sqlite_backend.

Definition at line 169 of file database_backend.h.

    {
        // Default fallback: substitute params inline (less secure, but functional)
        auto expanded = expand_params(query, params);
        return select_query(expanded);
    }

References expand_params(), and select_query().

Here is the call graph for this function:

select_query()

virtual kcenon::common::Result< database_result > database::core::database_backend::select_query ( const std::string & query_string )

pure virtual

Execute a SELECT query.

Parameters

query_string

SQL SELECT statement

Returns

Query results as rows, or error

Implemented in database::backends::mongodb_backend, database::backends::postgresql_backend, database::backends::redis_backend, database::backends::sqlite_backend, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

Referenced by database::query_builder::execute(), and select_prepared().

Here is the caller graph for this function:

shutdown()

virtual kcenon::common::VoidResult database::core::database_backend::shutdown ( )

pure virtual

Shutdown the database backend gracefully.

Returns

VoidResult::ok() on success, error on failure

This method should:

• Close active connections
• Release connection pool resources
• Flush pending transactions
• Clean up backend-specific resources

Implemented in database::core::backend_base< Derived, Type >, database::core::backend_base< mongodb_backend, database_types::mongodb >, database::core::backend_base< postgresql_backend, database_types::postgres >, database::core::backend_base< redis_backend, database_types::redis >, database::core::backend_base< sqlite_backend, database_types::sqlite >, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

type()

virtual database_types database::core::database_backend::type ( ) const

pure virtual

Get the database type of this backend.

Returns

Database type identifier

Implemented in database::core::backend_base< Derived, Type >, database::core::backend_base< mongodb_backend, database_types::mongodb >, database::core::backend_base< postgresql_backend, database_types::postgres >, database::core::backend_base< redis_backend, database_types::redis >, database::core::backend_base< sqlite_backend, database_types::sqlite >, database::postgres_manager, database::testing::mock_backend, and database::testing::mock_database.

value_to_sql()

static std::string database::core::database_backend::value_to_sql ( const database_value & val )

inlinestaticprivate

Definition at line 273 of file database_backend.h.

    {
        return std::visit([](const auto& v) -> std::string {
            using T = std::decay_t<decltype(v)>;
            if constexpr (std::is_same_v<T, std::nullptr_t>) {
                return "NULL";
            } else if constexpr (std::is_same_v<T, bool>) {
                return v ? "TRUE" : "FALSE";
            } else if constexpr (std::is_same_v<T, std::string>) {
                // Basic escaping — backends should override for proper security
                std::string escaped;
                escaped.reserve(v.size() + 2);
                escaped += '\'';
                for (char c : v) {
                    if (c == '\'') escaped += "''";
                    else escaped += c;
                }
                escaped += '\'';
                return escaped;
            } else {
                return std::to_string(v);
            }
        }, val);
    }

Referenced by expand_params().

Here is the caller graph for this function:

---

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

• database/core/database_backend.h