imtdb::IDatabaseEngine

Core database engine interface for low-level SQL execution and transaction management. More...

#include <IDatabaseEngine.h>

Inherits istd::IPolymorphic.

Inherited by imtdb::CDatabaseEngineComp [virtual].

Public Member Functions
virtual bool	BeginTransaction () const =0
	Begins a new database transaction.
virtual bool	FinishTransaction () const =0
	Commits the current transaction.
virtual bool	CancelTransaction () const =0
	Rolls back the current transaction.
virtual QByteArray	GetDatabaseDriverId () const =0
	Returns the database driver identifier.
virtual QSqlQuery	ExecSqlQuery (const QByteArray &queryString, QSqlError *sqlError=nullptr, bool isForwardOnly=false) const =0
	Executes a SQL query without parameters.
virtual QSqlQuery	ExecSqlQuery (const QByteArray &queryString, const QVariantMap &bindValues, QSqlError *sqlError=nullptr, bool isForwardOnly=false) const =0
	Executes a parameterized SQL query with bound values.
virtual QSqlQuery	ExecSqlQueryFromFile (const QString &filePath, QSqlError *sqlError=nullptr, bool isForwardOnly=false) const =0
	Executes SQL query from a file without parameters.
virtual QSqlQuery	ExecSqlQueryFromFile (const QString &filePath, const QVariantMap &bindValues, QSqlError *sqlError=nullptr, bool isForwardOnly=false) const =0
	Executes parameterized SQL query from a file.

Detailed Description

Core database engine interface for low-level SQL execution and transaction management.

IDatabaseEngine provides the fundamental database operations layer, handling:

• SQL query execution with parameterized binding
• Transaction lifecycle management (begin, commit, rollback)
• Query execution from files (SQL scripts)
• Forward-only result set optimization

This interface is database-agnostic and wraps Qt's QSqlDatabase functionality, providing a consistent API across different database backends (PostgreSQL, SQLite, etc.).

Transaction Management

The engine supports ACID-compliant transactions:

if (engine->BeginTransaction()) {
    // Execute multiple operations
    engine->ExecSqlQuery("INSERT INTO users...");
    engine->ExecSqlQuery("UPDATE orders...");
    
    if (success) {
        engine->FinishTransaction();  // Commit
    } else {
        engine->CancelTransaction();  // Rollback
    }
}

Parameterized Queries

The engine supports bound parameters to prevent SQL injection:

QVariantMap bindings;
bindings[":name"] = userName;
bindings[":age"] = userAge;
engine->ExecSqlQuery("SELECT * FROM users WHERE name = :name AND age > :age", bindings);

Note

Implementations typically use Qt's QSqlDatabase under the hood.

See also

CDatabaseEngineComp for the primary implementation

CSqlDatabaseObjectCollectionComp for usage in object collections

Definition at line 60 of file IDatabaseEngine.h.

Member Function Documentation

BeginTransaction()

virtual bool imtdb::IDatabaseEngine::BeginTransaction ( ) const

pure virtual

Begins a new database transaction.

Starts a transaction on the underlying database connection. All subsequent SQL operations will be part of this transaction until either FinishTransaction() (commit) or CancelTransaction() (rollback) is called.

Returns

true if transaction started successfully, false otherwise

Note

Transactions ensure ACID properties for database operations

Nested transactions are not supported - begin/finish must be balanced

Warning

Always pair with FinishTransaction() or CancelTransaction()

See also

FinishTransaction(), CancelTransaction()

CancelTransaction()

virtual bool imtdb::IDatabaseEngine::CancelTransaction ( ) const

pure virtual

Rolls back the current transaction.

Discards all changes made during the current transaction, reverting the database to its state before BeginTransaction() was called.

Returns

true if rollback succeeded, false otherwise

Note

Use this when an error occurs during transaction to maintain data integrity

Warning

Must be called after BeginTransaction()

See also

BeginTransaction(), FinishTransaction()

ExecSqlQuery() [1/2]

virtual QSqlQuery imtdb::IDatabaseEngine::ExecSqlQuery ( const QByteArray &  queryString, const QVariantMap &  bindValues, QSqlError *  sqlError = nullptr, bool  isForwardOnly = false  ) const

pure virtual

Executes a parameterized SQL query with bound values.

Executes a SQL query with placeholder parameters that are safely bound to prevent SQL injection. Placeholders use the syntax :paramName and are matched with keys in the bindValues map.

Parameters

queryString	The SQL query with placeholders (e.g., "SELECT * FROM users WHERE id = :userId")
bindValues	Map of placeholder names to values (e.g., {":userId", 42})
sqlError	Optional pointer to receive error information if execution fails
isForwardOnly	If true, creates a forward-only result set (more efficient)

Returns

QSqlQuery object containing the results

Note

This is the preferred method for queries with dynamic values

Parameter binding prevents SQL injection attacks

QVariantMap bindings;
bindings[":name"] = userName;
bindings[":minAge"] = 18;
QSqlQuery result = engine->ExecSqlQuery(
    "SELECT * FROM users WHERE name LIKE :name AND age >= :minAge",
    bindings
);

See also

ExecSqlQuery(const QByteArray&, QSqlError*, bool)

ExecSqlQuery() [2/2]

virtual QSqlQuery imtdb::IDatabaseEngine::ExecSqlQuery ( const QByteArray &  queryString, QSqlError *  sqlError = nullptr, bool  isForwardOnly = false  ) const

pure virtual

Executes a SQL query without parameters.

Executes a raw SQL query string. The query can be SELECT, INSERT, UPDATE, DELETE, or any other valid SQL statement.

Parameters

queryString	The SQL query to execute (UTF-8 encoded)
sqlError	Optional pointer to receive error information if execution fails
isForwardOnly	If true, creates a forward-only result set (more efficient for large results)

Returns

QSqlQuery object containing the results (check isActive() to verify success)

Warning

For queries with user input, use the parameterized version to prevent SQL injection

QSqlError error;
QSqlQuery result = engine->ExecSqlQuery("SELECT * FROM users", &error);
if (result.isActive()) {
    while (result.next()) {
        QString name = result.value("name").toString();
    }
}

See also

ExecSqlQuery(const QByteArray&, const QVariantMap&, QSqlError*, bool)

ExecSqlQueryFromFile() [1/2]

virtual QSqlQuery imtdb::IDatabaseEngine::ExecSqlQueryFromFile ( const QString &  filePath, const QVariantMap &  bindValues, QSqlError *  sqlError = nullptr, bool  isForwardOnly = false  ) const

pure virtual

Executes parameterized SQL query from a file.

Reads SQL content from a file and executes it with parameter binding. Combines the benefits of external SQL files with safe parameterization.

Parameters

filePath	Path to the SQL file containing placeholders
bindValues	Map of placeholder names to values
sqlError	Optional pointer to receive error information
isForwardOnly	If true, creates a forward-only result set

Returns

QSqlQuery object containing the results

Note

Useful for templated SQL scripts with runtime parameters

QVariantMap params;
params[":schemaName"] = "public";
QSqlQuery result = engine->ExecSqlQueryFromFile("./queries/list_tables.sql", params);

See also

ExecSqlQueryFromFile(const QString&, QSqlError*, bool)

ExecSqlQueryFromFile() [2/2]

virtual QSqlQuery imtdb::IDatabaseEngine::ExecSqlQueryFromFile ( const QString &  filePath, QSqlError *  sqlError = nullptr, bool  isForwardOnly = false  ) const

pure virtual

Executes SQL query from a file without parameters.

Reads SQL content from a file and executes it. Useful for schema creation, migration scripts, and complex queries stored externally.

Parameters

filePath	Path to the SQL file (absolute or relative)
sqlError	Optional pointer to receive error information
isForwardOnly	If true, creates a forward-only result set

Returns

QSqlQuery object containing the results

Note

The file is read using UTF-8 encoding

Comments and multi-line statements are supported

QSqlQuery result = engine->ExecSqlQueryFromFile("./migrations/v001_create_users.sql");

See also

ExecSqlQueryFromFile(const QString&, const QVariantMap&, QSqlError*, bool)

FinishTransaction()

virtual bool imtdb::IDatabaseEngine::FinishTransaction ( ) const

pure virtual

Commits the current transaction.

Commits all changes made during the current transaction to the database, making them permanent and visible to other connections.

Returns

true if transaction committed successfully, false if commit failed

Note

If commit fails, changes are automatically rolled back

Warning

Must be called after BeginTransaction()

See also

BeginTransaction(), CancelTransaction()

GetDatabaseDriverId()

virtual QByteArray imtdb::IDatabaseEngine::GetDatabaseDriverId ( ) const

pure virtual

Returns the database driver identifier.

Returns

Database driver ID used by Qt (e.g., "QPSQL", "QSQLITE")