#include <datasource.h>

Inheritance diagram for DataSource:

Collaboration diagram for DataSource:

Public Member Functions
	DataSource ()
	Construct a DataSource with default (empty) credentials.

	DataSource (const DatabaseCredentials &credentials)
	Construct a DataSource with the given database credentials.

virtual	~DataSource ()
	Destructor.

virtual bool	openConnection ()
	Open a database connection using the stored credentials.

virtual bool	closeConnection ()
	Close the current database connection.

bool	isOpen ()
	Return true if the database connection is currently open.

DatabaseCredentials	credentials () const
	Get the current database credentials.

void	setCredentials (const DatabaseCredentials &value)
	Set the database credentials.

QString	connectionName () const
	Get the Qt connection name for this data source.

void	setConnectionName (const QString &value)
	Set the Qt connection name.

bool	createOnOpenFailure () const
	Return true if the database should be created when opening fails.

void	setCreateOnOpenFailure (bool value)
	Set whether to create the database when opening fails.

QString	errorText () const
	Get a human-readable string describing the last error.

Static Public Member Functions
static bool	isSqlite (const QString &filename)
	Check whether the given file is a valid SQLite database.

Protected Member Functions
QSqlQuery	prepareQuery (const QString &sql, bool *success=nullptr)
	Prepare a QSqlQuery from the given SQL string.

QSqlQuery	executeQuery (const QString &sql, bool *success=nullptr)
	Execute a SQL string and return the resulting query.

bool	executeQuery (QSqlQuery &query)
	Execute an already-prepared QSqlQuery.

bool	querySuccessful (const QSqlQuery &query)
	Check whether a query completed without error.

bool	executeMultiple (const QStringList &queries)
	Execute multiple SQL statements in sequence.

virtual QString	createSql () const
	Return the SQL used to create the database schema.

virtual bool	migrate ()
	Perform any necessary database migrations.

virtual bool	integrityCheck ()
	Run an integrity check on the database.

void	logSql (const char *file, int line, Log::LogLevel level, const QString &sql)
	Log a SQL statement at the given log level.

void	logFailure (const QSqlQuery &query) const
	Log details of a failed query.

void	setDataSourceError (const QString &value)
	Set the data source error string.

bool	recreateSqliteDatabase ()
	Delete and recreate the SQLite database file from createSql().

virtual bool	executePostCreateScripts ()
	Execute any post-creation scripts after a new database is created.

bool	isSqlite () const
	Return true if the current credentials specify a SQLite engine.

Static Protected Member Functions
static QDateTime	utcTime (const QVariant &value)
	Convert a QVariant database value to a UTC QDateTime.

static QString	currentTimestamp ()
	Get the current UTC timestamp as a formatted string suitable for SQL.

template<typename T >
static QString	commaDelimitedList (const QList< T > &list)
	Build a comma-delimited string from a list of values.

static QString	commaDelimitedIntList (const QList< int > &list)
	Build a comma-delimited string from a list of integers.

static QString	commaDelimitedUuidList (const QList< QUuid > &list)
	Build a comma-delimited string from a list of UUIDs.

static QString	commaDelimitedStringList (const QStringList &list)
	Build a comma-delimited string from a list of strings.

static QString	escapedString (const QString &unescaped)
	Escape special characters in a string for safe inclusion in SQL.

Protected Attributes
QSqlDatabase	_db
	The underlying QSqlDatabase connection object.

Detailed Description

DataSource.

An abstraction model for databases.

Subclass this class to provide a Controller in the MVC programming paradigm.

Stephen Punak, January 11 2025

Abstract database access layer providing connection management, query execution, and utility methods.

Subclass this class to provide a Controller in the MVC programming paradigm.

Definition at line 21 of file datasource.h.

Constructor & Destructor Documentation

◆ DataSource() [1/2]

DataSource::DataSource ( )

inlineexplicit

Construct a DataSource with default (empty) credentials.

Definition at line 27 of file datasource.h.

◆ DataSource() [2/2]

DataSource::DataSource ( const DatabaseCredentials & credentials )

inlineexplicit

Construct a DataSource with the given database credentials.

Parameters

credentials The database connection credentials.

Definition at line 34 of file datasource.h.

◆ ~DataSource()

virtual DataSource::~DataSource ( )

virtual

Destructor.

Closes the database connection if open.

Member Function Documentation

◆ closeConnection()

virtual bool DataSource::closeConnection ( )

virtual

Close the current database connection.

Returns: true if the connection was closed successfully.

◆ commaDelimitedIntList()

static QString DataSource::commaDelimitedIntList ( const QList< int > & list )

staticprotected

Build a comma-delimited string from a list of integers.

Parameters

list	The list of integers.

Returns: A comma-separated string of integers.

◆ commaDelimitedList()

template<typename T >

static QString DataSource::commaDelimitedList ( const QList< T > & list )

staticprotected

Build a comma-delimited string from a list of values.

Parameters

list	The list of values to join.

Returns: A comma-separated string representation.

◆ commaDelimitedStringList()

static QString DataSource::commaDelimitedStringList ( const QStringList & list )

staticprotected

Build a comma-delimited string from a list of strings.

Parameters

list	The string list.

Returns: A comma-separated, quoted string.

◆ commaDelimitedUuidList()

static QString DataSource::commaDelimitedUuidList ( const QList< QUuid > & list )

staticprotected

Build a comma-delimited string from a list of UUIDs.

Parameters

list	The list of QUuid values.

Returns: A comma-separated string of UUIDs.

◆ connectionName()

QString DataSource::connectionName ( ) const

inline

Get the Qt connection name for this data source.

Returns: The connection name string.

Definition at line 69 of file datasource.h.

◆ createOnOpenFailure()

bool DataSource::createOnOpenFailure ( ) const

inline

Return true if the database should be created when opening fails.

Returns: true if auto-creation on failure is enabled.

Definition at line 78 of file datasource.h.

◆ createSql()

virtual QString DataSource::createSql ( ) const

inlineprotectedvirtual

Return the SQL used to create the database schema.

Override in subclasses.

Returns: The SQL creation string, or an empty string by default.

Definition at line 131 of file datasource.h.

◆ credentials()

DatabaseCredentials DataSource::credentials ( ) const

inline

Get the current database credentials.

Returns: The stored DatabaseCredentials.

Definition at line 60 of file datasource.h.

◆ currentTimestamp()

static QString DataSource::currentTimestamp ( )

staticprotected

Get the current UTC timestamp as a formatted string suitable for SQL.

Returns: The formatted timestamp string.

◆ errorText()

QString DataSource::errorText ( ) const

Get a human-readable string describing the last error.

Returns: The error description string.

◆ escapedString()

static QString DataSource::escapedString ( const QString & unescaped )

staticprotected

Escape special characters in a string for safe inclusion in SQL.

Parameters

unescaped The raw string.

Returns: The escaped string.

◆ executeMultiple()

bool DataSource::executeMultiple ( const QStringList & queries )

protected

Execute multiple SQL statements in sequence.

Parameters

queries The list of SQL statements to execute.

Returns: true if all statements executed successfully.

◆ executePostCreateScripts()

virtual bool DataSource::executePostCreateScripts ( )

inlineprotectedvirtual

Execute any post-creation scripts after a new database is created.

Override in subclasses.

Returns: true on success.

Definition at line 169 of file datasource.h.

◆ executeQuery() [1/2]

QSqlQuery DataSource::executeQuery	(	const QString &	sql,
		bool *	success = `nullptr`
	)

protected

Execute a SQL string and return the resulting query.

Parameters

sql	The SQL statement to execute.
success	Optional pointer set to true on success, false on failure.

Returns: The executed QSqlQuery.

◆ executeQuery() [2/2]

bool DataSource::executeQuery ( QSqlQuery & query )

protected

Execute an already-prepared QSqlQuery.

Parameters

query The query to execute.

Returns: true if execution succeeded.

◆ integrityCheck()

virtual bool DataSource::integrityCheck ( )

inlineprotectedvirtual

Run an integrity check on the database.

Override in subclasses.

Returns: true if the database passes the integrity check.

Definition at line 141 of file datasource.h.

◆ isOpen()

bool DataSource::isOpen ( )

inline

Return true if the database connection is currently open.

Returns: true if connected.

Definition at line 55 of file datasource.h.

References _db.

◆ isSqlite() [1/2]

bool DataSource::isSqlite ( ) const

inlineprotected

Return true if the current credentials specify a SQLite engine.

Returns: true if the engine is SQLite.

Definition at line 174 of file datasource.h.

References DatabaseCredentials::isSqlite().

◆ isSqlite() [2/2]

static bool DataSource::isSqlite ( const QString & filename )

static

Check whether the given file is a valid SQLite database.

Parameters

filename The file path to check.

Returns: true if the file is a SQLite database.

◆ logFailure()

void DataSource::logFailure ( const QSqlQuery & query ) const

protected

Log details of a failed query.

Parameters

query The failed QSqlQuery.

◆ logSql()

void DataSource::logSql	(	const char *	file,
		int	line,
		Log::LogLevel	level,
		const QString &	sql
	)

protected

Log a SQL statement at the given log level.

Parameters

file	The source file name (use FILE).
line	The source line number (use LINE).
level	The log level.
sql	The SQL statement to log.

◆ migrate()

virtual bool DataSource::migrate ( )

inlineprotectedvirtual

Perform any necessary database migrations.

Override in subclasses.

Returns: true on success.

Definition at line 136 of file datasource.h.

◆ openConnection()

virtual bool DataSource::openConnection ( )

virtual

Open a database connection using the stored credentials.

Returns: true if the connection was opened successfully.

◆ prepareQuery()

QSqlQuery DataSource::prepareQuery	(	const QString &	sql,
		bool *	success = `nullptr`
	)

protected

Prepare a QSqlQuery from the given SQL string.

Parameters

sql	The SQL statement to prepare.
success	Optional pointer set to true on success, false on failure.

Returns: The prepared QSqlQuery.

◆ querySuccessful()

bool DataSource::querySuccessful ( const QSqlQuery & query )

protected

Check whether a query completed without error.

Parameters

query The query to check.

Returns: true if the query was successful.

◆ recreateSqliteDatabase()

bool DataSource::recreateSqliteDatabase ( )

protected

Delete and recreate the SQLite database file from createSql().

Returns: true on success.

◆ setConnectionName()

void DataSource::setConnectionName ( const QString & value )

inline

Set the Qt connection name.

Parameters

value The connection name string.

Definition at line 73 of file datasource.h.

◆ setCreateOnOpenFailure()

void DataSource::setCreateOnOpenFailure ( bool value )

inline

Set whether to create the database when opening fails.

Parameters

value true to auto-create on failure.

Definition at line 82 of file datasource.h.

◆ setCredentials()

void DataSource::setCredentials ( const DatabaseCredentials & value )

inline

Set the database credentials.

Parameters

value The new credentials.

Definition at line 64 of file datasource.h.

◆ setDataSourceError()

void DataSource::setDataSourceError ( const QString & value )

inlineprotected

Set the data source error string.

Parameters

value The error description.

Definition at line 159 of file datasource.h.

◆ utcTime()

static QDateTime DataSource::utcTime ( const QVariant & value )

staticprotected

Convert a QVariant database value to a UTC QDateTime.

Parameters

value The QVariant containing the datetime value.

Returns: The corresponding QDateTime in UTC.

Member Data Documentation

◆ _db

QSqlDatabase DataSource::_db

protected

The underlying QSqlDatabase connection object.

Definition at line 188 of file datasource.h.

Referenced by isOpen().

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

include/Kanoop/database/datasource.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DataSource() [1/2]

◆ DataSource() [2/2]

◆ ~DataSource()

Member Function Documentation

◆ closeConnection()

◆ commaDelimitedIntList()

◆ commaDelimitedList()

◆ commaDelimitedStringList()

◆ commaDelimitedUuidList()

◆ connectionName()

◆ createOnOpenFailure()

◆ createSql()

◆ credentials()

◆ currentTimestamp()

◆ errorText()

◆ escapedString()

◆ executeMultiple()

◆ executePostCreateScripts()

◆ executeQuery() [1/2]

◆ executeQuery() [2/2]

◆ integrityCheck()

◆ isOpen()

◆ isSqlite() [1/2]

◆ isSqlite() [2/2]

◆ logFailure()

◆ logSql()

◆ migrate()

◆ openConnection()

◆ prepareQuery()

◆ querySuccessful()

◆ recreateSqliteDatabase()

◆ setConnectionName()

◆ setCreateOnOpenFailure()

◆ setCredentials()

◆ setDataSourceError()

◆ utcTime()

Member Data Documentation

◆ _db