imtdb Namespace Reference

Database Abstraction Layer (ORM Framework) for ImtCore applications. More...

Classes
class	CSqlDatabaseCollectionStructureIterator
class	CSqlDatabaseObjectCollectionComp
class	CSqlDatabaseObjectCollectionIterator
interface	IDatabaseConnector
	Manages database connection lifecycle for remote database servers. More...
interface	IDatabaseEngine
	Core database engine interface for low-level SQL execution and transaction management. More...
interface	IDatabaseLoginSettings
	Configuration interface for database connection credentials and parameters. More...
interface	IDatabaseObjectDelegate
	Core ORM interface for object-to-database mapping and SQL query generation. More...
interface	IDependentMetaInfoController
	Manages cascading metadata updates when related objects are deleted. More...
interface	IJsonBasedMetaInfoDelegate
	Converts document metadata to/from JSON representation. More...
class	IMetaInfoTableDelegate
interface	IMigrationController
	Controls database schema versioning and migration execution. More...
interface	ISqlDatabaseObjectCollection
	SQL-specific extension of IObjectCollection for database-backed object collections. More...
class	ISqlDatabaseObjectDelegate
interface	ISqlJsonXPathExtractor
	Database-specific JSON field extraction abstraction. More...

Functions
QString	SqlEncode (const QString &sqlQuery)
	Encodes a string for safe SQL usage.
QString	GetSqlResourcePath (const IDatabaseEngine &databaseEngine, const QString &fileName)
	Returns the resource path for an SQL script file based on the database driver.

Variables
static const QString	NULL_DATA_LITERAL = QStringLiteral("NULL")
	SQL NULL literal constant.
static const QString	DEFAULT_DATA_LITERAL = QStringLiteral("DEFAULT")
	SQL DEFAULT literal constant.

Detailed Description

Database Abstraction Layer (ORM Framework) for ImtCore applications.

The imtdb namespace provides a comprehensive database abstraction layer that enables multi-database support, object-relational mapping, transaction management, and schema migrations.

Overview

This library offers:

• Multi-database support: PostgreSQL, SQLite, and file-based databases
• Object-Relational Mapping (ORM): Automatic conversion between C++ objects and database records
• SQL query generation: Type-safe, parameterized query builders for CRUD operations
• Transaction management: ACID-compliant transactions with multi-collection coordination
• Schema migrations: Version-controlled database evolution with SQL scripts
• Document management: JSON-based serialization with rich metadata support
• Revision control: Complete audit trail and version history
• Hierarchical data: Tree structures with parent-child relationships

Architecture

The library follows a layered architecture:

* Application Layer (IObjectCollection)
*          ↓
* ORM Layer (ISqlDatabaseObjectDelegate)
*          ↓
* SQL Generation (Query Builders)
*          ↓
* Database Engine (IDatabaseEngine)
*          ↓
* Qt SQL Driver (QSqlDatabase)
*          ↓
* Database Server (PostgreSQL/SQLite)
* 

Key Interfaces

• imtdb::IDatabaseEngine - Low-level SQL execution and transaction management
• imtdb::IDatabaseConnector - Database connection lifecycle
• imtdb::ISqlDatabaseObjectCollection - Object collection management
• imtdb::ISqlDatabaseObjectDelegate - Object-to-SQL mapping strategy
• imtdb::IMigrationController - Schema versioning and migrations
• imtdb::ISqlJsonXPathExtractor - Database-agnostic JSON queries

Design Patterns

• Delegate Pattern: Separates collection logic from database operations
• Template Method: Base classes define algorithms, subclasses implement specifics
• Component Architecture: ACF-based dependency injection
• Observer Pattern: Cascading metadata updates
• Factory Pattern: Polymorphic object creation from database records

Usage Example

// Create and configure database engine
auto engine = acf::CreateComponent<imtdb::CDatabaseEngineComp>();
engine->SetDatabaseName("myapp.db");
engine->ConnectToDatabase();
 
// Create object collection
auto collection = acf::CreateComponent<imtdb::CSqlDatabaseObjectCollectionComp>();
auto delegate = acf::CreateComponent<imtdb::CSqlDatabaseDocumentDelegateComp>();
delegate->SetTableName("users");
collection->SetDelegate(delegate);
 
// Insert object
QString objectId;
collection->InsertNewObject(userObject, objectId);
 
// Query with filters
auto filters = acf::CreateComponent<iprm::CParamsSetComp>();
filters->SetValue("Name", "John%");
auto results = collection->CreateSubCollection(filters);

See also

Complete Architecture Documentation

This package is system independent and provides platform-agnostic database abstractions.

Function Documentation

GetSqlResourcePath()

QString imtdb::GetSqlResourcePath	(	const IDatabaseEngine &	databaseEngine,
		const QString &	fileName
	)

Returns the resource path for an SQL script file based on the database driver.

Selects between :/SQL/SQLite/ and :/SQL/Postgres/ prefixes depending on whether the engine uses the QSQLITE driver.

Parameters

databaseEngine	The database engine to query for the driver ID.
fileName	The SQL script file name (e.g. "CreateUsersTable.sql").

Returns

Full resource path to the SQL script.

SqlEncode()

QString imtdb::SqlEncode

(

const QString &

sqlQuery

)

Encodes a string for safe SQL usage.

Escapes special characters in SQL strings to prevent SQL injection attacks and syntax errors. Specifically:

• Single quotes (') are doubled ('')
• Semicolons (;) are replaced with backspace characters

Parameters

sqlQuery

The SQL string to encode

Returns

The encoded SQL string safe for use in queries

Warning

This function provides basic escaping but should not be relied upon as the sole defense against SQL injection. Always use parameterized queries via IDatabaseEngine.

Note

This is primarily used internally by query builders. Application code should use parameterized queries through the IDatabaseEngine interface instead of manual encoding.

Example:

QString userInput = "O'Reilly";
QString encoded = imtdb::SqlEncode(userInput);
// encoded = "O''Reilly"

Variable Documentation

DEFAULT_DATA_LITERAL

const QString imtdb::DEFAULT_DATA_LITERAL = QStringLiteral("DEFAULT")

static

SQL DEFAULT literal constant.

This constant represents the SQL DEFAULT keyword and should be used when constructing SQL queries that rely on column default values.

Definition at line 112 of file imtdb.h.

NULL_DATA_LITERAL

const QString imtdb::NULL_DATA_LITERAL = QStringLiteral("NULL")

static

SQL NULL literal constant.

This constant represents the SQL NULL value and should be used when constructing SQL queries that need to explicitly set NULL values.

Definition at line 104 of file imtdb.h.