digiKam Developer Documentation: Digikam::BdEngineBackend Class Reference

| digiKam Developer Documentation Professional Photo Management with the Power of Open Source

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Protected Attributes | List of all members
Digikam::BdEngineBackend Class Reference
Inheritance diagram for Digikam::BdEngineBackend:

## Classes
class | QueryState

## Public Types
enum | DbType { SQLite , MySQL }
enum | QueryOperationStatus { ExecuteNormal , Wait , AbortQueries }
enum | QueryStateEnum { NoErrors , SQLError , ConnectionError }
enum | Status { Unavailable , Open , OpenSchemaChecked }

## Public Member Functions
| BdEngineBackend (const QString &backendName, DbEngineLocking *const locking)
| Creates a database backend.
| BdEngineBackend (const QString &backendName, DbEngineLocking *const locking, BdEngineBackendPrivate &dd)
QDateTime | asDBDateTime (const QDateTime &dateTime) const
| Depending on the database backend return a local or UTC date format.
BdEngineBackend::QueryState | beginTransaction ()
| Begin a database transaction.
bool | checkOrSetWALMode ()
| Check or set WAL mode for SQLite database if enabled in settings.
void | close ()
| Close the database connection.
BdEngineBackend::QueryState | commitTransaction ()
| Commit the current database transaction.
DbEngineConfigSettings | configElement () const
| Return config read from XML, corresponding to this backend's database type.
bool | connectionErrorHandling (int retries)
| Called when an attempted connection to the database failed.
QSqlQuery | copyQuery (const QSqlQuery &old)
| Creates a faithful copy of the passed query, with the current db connection.
DbType | databaseType () const
| Return the database type.
bool | exec (QSqlQuery &query)
| Calls exec/execBatch on the query, and handles debug output if something went wrong.
bool | execBatch (QSqlQuery &query)
QueryState | execDBAction (const DbEngineAction &action, const QMap< QString, QVariant > &bindingMap, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
| Performs the database action on the current database.
QueryState | execDBAction (const DbEngineAction &action, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
| Performs the database action on the current database.
QueryState | execDBAction (const QString &action, const QMap< QString, QVariant > &bindingMap, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execDBAction (const QString &action, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QSqlQuery | execDBActionQuery (const DbEngineAction &action, const QMap< QString, QVariant > &bindingMap)
| Performs the database action on the current database.
QSqlQuery | execDBActionQuery (const QString &action, const QMap< QString, QVariant > &bindingMap)
QueryState | execDirectSql (const QString &query)
| Calls exec on the query, and handles debug output if something went wrong.
QueryState | execDirectSqlWithResult (const QString &query, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
| Calls exec on the query, and handles debug output if something went wrong.
QSqlQuery | execQuery (const QString &sql)
| Executes the statement and returns the query object.
QSqlQuery | execQuery (const QString &sql, const QList< QVariant > &boundValues)
QSqlQuery | execQuery (const QString &sql, const QMap< QString, QVariant > &bindingMap)
| Method which accept a hashmap with key, values which are used for named binding.
QSqlQuery | execQuery (const QString &sql, const QVariant &boundValue1)
QSqlQuery | execQuery (const QString &sql, const QVariant &boundValue1, const QVariant &boundValue2)
QSqlQuery | execQuery (const QString &sql, const QVariant &boundValue1, const QVariant &boundValue2, const QVariant &boundValue3)
QSqlQuery | execQuery (const QString &sql, const QVariant &boundValue1, const QVariant &boundValue2, const QVariant &boundValue3, const QVariant &boundValue4)
void | execQuery (QSqlQuery &preparedQuery, const QList< QVariant > &boundValues)
void | execQuery (QSqlQuery &preparedQuery, const QVariant &boundValue1)
| Binds the values and executes the prepared query.
void | execQuery (QSqlQuery &preparedQuery, const QVariant &boundValue1, const QVariant &boundValue2)
void | execQuery (QSqlQuery &preparedQuery, const QVariant &boundValue1, const QVariant &boundValue2, const QVariant &boundValue3)
void | execQuery (QSqlQuery &preparedQuery, const QVariant &boundValue1, const QVariant &boundValue2, const QVariant &boundValue3, const QVariant &boundValue4)
QueryState | execSql (const QString &sql, const QList< QVariant > &boundValues, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execSql (const QString &sql, const QMap< QString, QVariant > &bindingMap, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
| Method which accepts a map for named binding.
QueryState | execSql (const QString &sql, const QVariant &boundValue1, const QVariant &boundValue2, const QVariant &boundValue3, const QVariant &boundValue4, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execSql (const QString &sql, const QVariant &boundValue1, const QVariant &boundValue2, const QVariant &boundValue3, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execSql (const QString &sql, const QVariant &boundValue1, const QVariant &boundValue2, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execSql (const QString &sql, const QVariant &boundValue1, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execSql (const QString &sql, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
| Executes the SQL statement, and write the returned data into the values list.
QueryState | execSql (QSqlQuery &preparedQuery, const QList< QVariant > &boundValues, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execSql (QSqlQuery &preparedQuery, const QVariant &boundValue1, const QVariant &boundValue2, const QVariant &boundValue3, const QVariant &boundValue4, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execSql (QSqlQuery &preparedQuery, const QVariant &boundValue1, const QVariant &boundValue2, const QVariant &boundValue3, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execSql (QSqlQuery &preparedQuery, const QVariant &boundValue1, const QVariant &boundValue2, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execSql (QSqlQuery &preparedQuery, const QVariant &boundValue1, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execSql (QSqlQuery &preparedQuery, QList< QVariant > *const values=nullptr, QVariant *const lastInsertId=nullptr)
QueryState | execUpsertDBAction (const DbEngineAction &action, const QVariant &id, const QStringList &fieldNames, const QList< QVariant > &values)
| Performs a special DBAction that is usually needed to "INSERT or UPDATE" entries in a table.
QueryState | execUpsertDBAction (const QString &action, const QVariant &id, const QStringList &fieldNames, const QList< QVariant > &values)
DbEngineAction | getDBAction (const QString &actionName) const
| Returns a database action with name, specified in actionName, for the current database.
QSqlQuery | getQuery ()
| Creates an empty query object waiting for the statement.
QueryState | handleQueryResult (QSqlQuery &query, QList< QVariant > *const values, QVariant *const lastInsertId)
| Checks if there was a connection error.
bool | isCompatible (const DbEngineParameters &parameters)
| Checks if the parameters can be used for this database backend.
bool | isInTransaction () const
| Returns if the database is in a different thread in a transaction.
bool | isOpen () const
bool | isReady () const
QString | lastError ()
| Returns a description of the last error that occurred on this database.
QSqlError | lastSQLError ()
| Returns the last error that occurred on this database.
int | maximumBoundValues () const
| Returns the maximum number of bound parameters allowed per query.
bool | open (const DbEngineParameters &parameters)
| Open the database connection.
QSqlQuery | prepareQuery (const QString &sql)
| Creates a query object prepared with the statement, waiting for bound values.
bool | queryErrorHandling (QSqlQuery &query, int retries)
| Called with a failed query.
QList< QVariant > | readToList (QSqlQuery &query)
| Reads data of returned result set into a list which is returned.
void | rollbackTransaction ()
| Rollback the current database transaction.
void | setDbEngineErrorHandler (DbEngineErrorHandler *const handler)
| Add a DbEngineErrorHandler.
void | setForeignKeyChecks (bool check)
| Enables or disables FOREIGN_KEY_CHECKS for the database.
Status | status () const
| Returns the current status of the database backend.
QStringList | tables ()
| Returns a list with the names of tables in the database.
bool | transactionErrorHandling (const QSqlError &lastError, int retries)

## Protected Attributes
BdEngineBackendPrivate *const | d_ptr = nullptr

## Member Enumeration Documentation

## ◆ QueryStateEnum

enum Digikam::BdEngineBackend::QueryStateEnum

Enumerator
NoErrors | No errors occurred while executing the query.
SQLError | An SQLError has occurred while executing the query.
ConnectionError | An connection error has occurred while executing the query.

## ◆ Status

enum Digikam::BdEngineBackend::Status

Enumerator
Unavailable | The database is not available, because it has not been opened yet or because of an error condition.
Open | The database is open. It has not been verified that the schema is up to date. This status is sufficient for use in a context where it can be assumed that the necessary schema check has been carried out by a master process.
OpenSchemaChecked | The database is open, and it has been verified that the schema is up to date, or the schema has been updated.

## Constructor & Destructor Documentation

## ◆ BdEngineBackend()

Digikam::BdEngineBackend::BdEngineBackend | ( | const QString & | backendName,
|  | DbEngineLocking *const | locking
| ) |  |
| explicit

The backend name is an arbitrary string that shall be unique for this backend object. It will be used to create unique connection names per backend and thread.

## Member Function Documentation

## ◆ asDBDateTime()

QDateTime Digikam::BdEngineBackend::asDBDateTime | ( | const QDateTime & | dateTime | ) | const

SQLite: local date format MySQL: UTC date format

## ◆ checkOrSetWALMode()

bool Digikam::BdEngineBackend::checkOrSetWALMode | ( |  | ) |

Returns
  true the WAL mode is confirmed enabled.

## ◆ close()

void Digikam::BdEngineBackend::close | ( |  | ) |

Shall only be called from the thread that called open().

## ◆ connectionErrorHandling()

bool Digikam::BdEngineBackend::connectionErrorHandling | ( | int | retries | ) |

If it returns true, retry; if it returns false, bail out. Pass the number of connection retries to help with some decisions.

## ◆ execDBAction() [1/2]

BdEngineBackend::QueryState Digikam::BdEngineBackend::execDBAction | ( | const DbEngineAction & | action,
|  | const QMap< QString, QVariant > & | bindingMap,
|  | QList< QVariant > *const | values = `nullptr`,
|  | QVariant *const | lastInsertId = `nullptr`
| ) |  |

Queries by the specified parameters can have named parameters which are substituted with values from the bindingMap parameter. The result values (if any) are stored within the values list.

## ◆ execDBAction() [2/2]

BdEngineBackend::QueryState Digikam::BdEngineBackend::execDBAction | ( | const DbEngineAction & | action,
|  | QList< QVariant > *const | values = `nullptr`,
|  | QVariant *const | lastInsertId = `nullptr`
| ) |  |

Queries by the specified parameters mustn't have named parameters. The result values (if any) are stored within the values list.

## ◆ execDBActionQuery()

QSqlQuery Digikam::BdEngineBackend::execDBActionQuery | ( | const DbEngineAction & | action,
|  | const QMap< QString, QVariant > & | bindingMap
| ) |  |

Queries by the specified parameters can have named parameters which are substituted with values from the bindingMap parameter. The result values (if any) are stored within the values list. This method returns the last query, which is used to handle special cases.

## ◆ execDirectSql()

BdEngineBackend::QueryState Digikam::BdEngineBackend::execDirectSql | ( | const QString & | query | ) |

The query is not prepared, which can be fail in certain situations (e.g. trigger statements on QMYSQL).

## ◆ execDirectSqlWithResult()

BdEngineBackend::QueryState Digikam::BdEngineBackend::execDirectSqlWithResult | ( | const QString & | query,
|  | QList< QVariant > *const | values = `nullptr`,
|  | QVariant *const | lastInsertId = `nullptr`
| ) |  |

The query is not prepared, which can be fail in certain situations (e.g. trigger statements on QMYSQL).

## ◆ execQuery()

QSqlQuery Digikam::BdEngineBackend::execQuery | ( | const QString & | sql | ) |

Methods are provided for up to four bound values (positional binding), or for a list of bound values.

## ◆ execSql() [1/2]

BdEngineBackend::QueryState Digikam::BdEngineBackend::execSql | ( | const QString & | sql,
|  | const QMap< QString, QVariant > & | bindingMap,
|  | QList< QVariant > *const | values = `nullptr`,
|  | QVariant *const | lastInsertId = `nullptr`
| ) |  |

For special cases it's also possible to add a DbEngineActionType which wraps another data object (also lists or maps) which can be used as field entry or as value (where it's prepared with positional binding). See more on DbEngineActionType class. If the wrapped data object is an instance of list, then the elements are separated by comma. If the wrapped data object is an instance of map, then the elements are inserted in the following way: key1=value1, key2=value2,...,keyN=valueN.

## ◆ execSql() [2/2]

BdEngineBackend::QueryState Digikam::BdEngineBackend::execSql | ( | const QString & | sql,
|  | QList< QVariant > *const | values = `nullptr`,
|  | QVariant *const | lastInsertId = `nullptr`
| ) |  |

If you are not interested in the returned data, set values to 0. Methods are provided for up to four bound values (positional binding), or for a list of bound values. If you want the last inserted id (and your query is suitable), set lastInsertId to the address of a QVariant. Additionally, methods are provided for prepared statements.

## ◆ execUpsertDBAction()

BdEngineBackend::QueryState Digikam::BdEngineBackend::execUpsertDBAction | ( | const DbEngineAction & | action,
|  | const QVariant & | id,
|  | const QStringList & | fieldNames,
|  | const QList< QVariant > & | values
| ) |  |

The corresponding DBAction must contain exactly the named parameters :id, :fieldValueList, :fieldList and :valueList. You pass the value to be bound to the ":id" field, then two lists of the same size: The first containing the field names, the second one containing the values as QVariants ready for binding.

## ◆ handleQueryResult()

BdEngineBackend::QueryState Digikam::BdEngineBackend::handleQueryResult | ( | QSqlQuery & | query,
|  | QList< QVariant > *const | values,
|  | QVariant *const | lastInsertId
| ) |  |

If so BdEngineBackend::ConnectionError is returned. If not, the values are extracted from the query and inserted in the values list, the last insertion id is taken from the query and BdEngineBackend::NoErrors is returned.

## ◆ isInTransaction()

bool Digikam::BdEngineBackend::isInTransaction | ( |  | ) | const

Note that a transaction does not require holding CoreDbAccess. Note that this does not give information about other processes locking the database.

## ◆ lastError()

QString Digikam::BdEngineBackend::lastError | ( |  | ) |

Use CoreDbAccess::lastError for errors presented to the user. This error will be included in that message. It may be empty.

## ◆ lastSQLError()

QSqlError Digikam::BdEngineBackend::lastSQLError | ( |  | ) |

Use CoreDbAccess::lastError for errors presented to the user. It may be empty.

## ◆ maximumBoundValues()

int Digikam::BdEngineBackend::maximumBoundValues | ( |  | ) | const

This value depends on the database engine.

## ◆ open()

bool Digikam::BdEngineBackend::open | ( | const DbEngineParameters & | parameters | ) |

Returns
  true on success

## ◆ queryErrorHandling()

bool Digikam::BdEngineBackend::queryErrorHandling | ( | QSqlQuery & | query,
|  | int | retries
| ) |  |

Handles certain known errors and debug output. If it returns true, reexecute the query; if it returns false, return it as failed. Pass the number of retries already done for this query to help with some decisions.

## ◆ readToList()

QList< QVariant > Digikam::BdEngineBackend::readToList | ( | QSqlQuery & | query | ) |

The read process is column wise, which means all data elements of a row is read, then the resultset is switched to the next row.

## ◆ setDbEngineErrorHandler()

void Digikam::BdEngineBackend::setDbEngineErrorHandler | ( | DbEngineErrorHandler *const | handler | ) |

This object must be created in the main thread. If a database error occurs, this object can handle problem solving and user interaction.

## ◆ setForeignKeyChecks()

void Digikam::BdEngineBackend::setForeignKeyChecks | ( | bool | check | ) |

This function depends on the database engine.