dbenginebackend.h

Go to the documentation of this file.

/* ============================================================
 *
 * This file is a part of digiKam project
 * https://www.digikam.org
 *
 * Date        : 2007-06-07
 * Description : Database engine abstract database backend
 *
 * Copyright (C) 2007-2010 by Marcel Wiesweg <marcel dot wiesweg at gmx dot de>
 * Copyright (C) 2010-2022 by Gilles Caulier <caulier dot gilles at gmail dot com>
 *
 * This program is free software; you can redistribute it
 * and/or modify it under the terms of the GNU General
 * Public License as published by the Free Software Foundation;
 * either version 2, or (at your option)
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * ============================================================ */
 
#ifndef DIGIKAM_DB_ENGINE_BACKEND_H
#define DIGIKAM_DB_ENGINE_BACKEND_H
 
// Qt includes
 
#include <QMap>
#include <QObject>
#include <QString>
#include <QStringList>
#include <QSqlQuery>
#include <QSqlError>
#include <QRecursiveMutex>
 
// Local includes
 
#include "digikam_export.h"
#include "dbengineparameters.h"
#include "dbenginesqlquery.h"
 
namespace Digikam
{
 
class DbEngineConfigSettings;
class BdEngineBackendPrivate;
class DbEngineErrorHandler;
 
class DIGIKAM_EXPORT DbEngineLocking
{
public:
 
    explicit DbEngineLocking();
 
public:
 
    QRecursiveMutex mutex;
    int             lockCount;
};
 
// -----------------------------------------------------------------
 
class DIGIKAM_EXPORT BdEngineBackend : public QObject
{
    Q_OBJECT
 
public:
 
    enum QueryStateEnum
    {
        NoErrors,
 
        SQLError,
 
        ConnectionError
    };
 
    enum Status
    {
        Unavailable,
 
        Open,
 
        OpenSchemaChecked
    };
 
    enum QueryOperationStatus
    {
        ExecuteNormal,
        Wait,
        AbortQueries
    };
 
    enum DbType
    {
        SQLite,
        MySQL
    };
 
public:
 
    explicit BdEngineBackend(const QString& backendName, DbEngineLocking* const locking);
    BdEngineBackend(const QString& backendName, DbEngineLocking* const locking, BdEngineBackendPrivate& dd);
    ~BdEngineBackend() override;
 
    bool isCompatible(const DbEngineParameters& parameters);
 
    bool open(const DbEngineParameters& parameters);
 
    void close();
 
public:
 
    class QueryState
    {
    public:
 
        QueryState()
            : value(BdEngineBackend::NoErrors)
        {
        }
 
        explicit QueryState(const QueryStateEnum value)    // krazy:exclude=explicit
            : value(value)
        {
        }
 
        operator QueryStateEnum() const
        {
            return value;
        }
 
        operator bool() const
        {
            return (value == BdEngineBackend::NoErrors);
        }
 
    private:
 
        QueryStateEnum value;
    };
 
public:
 
    Status status() const;
 
    bool isOpen() const
    {
        return (status() > Unavailable);
    }
 
    bool isReady() const
    {
        return (status() == OpenSchemaChecked);
    }
 
    void setDbEngineErrorHandler(DbEngineErrorHandler* const handler);
 
    DbEngineConfigSettings configElement() const;
 
    DbType databaseType() const;
 
    DbEngineAction getDBAction(const QString& actionName) const;
 
    QueryState execDBAction(const DbEngineAction& action, QList<QVariant>* const values = nullptr, QVariant* const lastInsertId = nullptr);
 
    QueryState execDBAction(const QString& action, QList<QVariant>* const values = nullptr, QVariant* const lastInsertId = nullptr);
 
    QueryState execDBAction(const DbEngineAction& action, const QMap<QString, QVariant>& bindingMap,
                            QList<QVariant>* const values = nullptr, QVariant* const lastInsertId = nullptr);
 
    QueryState execDBAction(const QString& action, const QMap<QString, QVariant>& bindingMap,
                            QList<QVariant>* const values = nullptr, QVariant* const lastInsertId = nullptr);
 
    QueryState execUpsertDBAction(const DbEngineAction& action, const QVariant& id,
                                  const QStringList& fieldNames, const QList<QVariant>& values);
    QueryState execUpsertDBAction(const QString& action, const QVariant& id,
                                  const QStringList& fieldNames, const QList<QVariant>& values);
 
    QSqlQuery execDBActionQuery(const DbEngineAction& action, const QMap<QString, QVariant>& bindingMap);
 
    QSqlQuery execDBActionQuery(const QString& action, const QMap<QString, QVariant>& bindingMap);
 
    QueryState execSql(const QString& sql,
                       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,
                       const QVariant& boundValue1,
                       const QVariant& boundValue2,
                       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,
                       const QVariant& boundValue3,
                       const QVariant& boundValue4,
                       QList<QVariant>* const values = nullptr,
                       QVariant* const lastInsertId = nullptr);
    QueryState execSql(const QString& sql,
                       const QList<QVariant>& boundValues,
                       QList<QVariant>* const values = nullptr,
                       QVariant* const lastInsertId = nullptr);
 
    QueryState execSql(DbEngineSqlQuery& preparedQuery,
                       QList<QVariant>* const values = nullptr,
                       QVariant* const lastInsertId = nullptr);
    QueryState execSql(DbEngineSqlQuery& preparedQuery,
                       const QVariant& boundValue1,
                       QList<QVariant>* const values = nullptr,
                       QVariant* const lastInsertId = nullptr);
    QueryState execSql(DbEngineSqlQuery& preparedQuery,
                       const QVariant& boundValue1,
                       const QVariant& boundValue2,
                       QList<QVariant>* const values = nullptr,
                       QVariant* const lastInsertId = nullptr);
    QueryState execSql(DbEngineSqlQuery& preparedQuery,
                       const QVariant& boundValue1,
                       const QVariant& boundValue2,
                       const QVariant& boundValue3,
                       QList<QVariant>* const values = nullptr,
                       QVariant* const lastInsertId = nullptr);
    QueryState execSql(DbEngineSqlQuery& preparedQuery,
                       const QVariant& boundValue1,
                       const QVariant& boundValue2,
                       const QVariant& boundValue3,
                       const QVariant& boundValue4,
                       QList<QVariant>* const values = nullptr,
                       QVariant* const lastInsertId = nullptr);
    QueryState execSql(DbEngineSqlQuery& preparedQuery,
                       const QList<QVariant>& boundValues,
                       QList<QVariant>* const values = nullptr,
                       QVariant* const lastInsertId = nullptr);
 
    QueryState handleQueryResult(DbEngineSqlQuery& query,
                                 QList<QVariant>* const values,
                                 QVariant* const lastInsertId);
 
    QueryState execSql(const QString& sql,
                       const QMap<QString, QVariant>& bindingMap,
                       QList<QVariant>* const values = nullptr,
                       QVariant* const lastInsertId = nullptr);
    QueryState execDirectSql(const QString& query);
 
    QueryState execDirectSqlWithResult(const QString& query,
                                       QList<QVariant>* const values = nullptr,
                                       QVariant* const lastInsertId = nullptr);
 
    DbEngineSqlQuery execQuery(const QString& sql);
    DbEngineSqlQuery execQuery(const QString& sql,
                               const QVariant& boundValue1);
    DbEngineSqlQuery execQuery(const QString& sql,
                               const QVariant& boundValue1,
                               const QVariant& boundValue2);
    DbEngineSqlQuery execQuery(const QString& sql,
                               const QVariant& boundValue1,
                               const QVariant& boundValue2,
                               const QVariant& boundValue3);
    DbEngineSqlQuery execQuery(const QString& sql,
                               const QVariant& boundValue1,
                               const QVariant& boundValue2,
                               const QVariant& boundValue3,
                               const QVariant& boundValue4);
    DbEngineSqlQuery execQuery(const QString& sql,
                               const QList<QVariant>& boundValues);
 
    void execQuery(DbEngineSqlQuery& preparedQuery,
                   const QVariant& boundValue1);
    void execQuery(DbEngineSqlQuery& preparedQuery,
                   const QVariant& boundValue1,
                   const QVariant& boundValue2);
    void execQuery(DbEngineSqlQuery& preparedQuery,
                   const QVariant& boundValue1,
                   const QVariant& boundValue2,
                   const QVariant& boundValue3);
    void execQuery(DbEngineSqlQuery& preparedQuery,
                   const QVariant& boundValue1,
                   const QVariant& boundValue2,
                   const QVariant& boundValue3,
                   const QVariant& boundValue4);
    void execQuery(DbEngineSqlQuery& preparedQuery,
                   const QList<QVariant>& boundValues);
 
    DbEngineSqlQuery execQuery(const QString& sql,
                               const QMap<QString, QVariant>& bindingMap);
 
    bool exec(DbEngineSqlQuery& query);
    bool execBatch(DbEngineSqlQuery& query);
 
    DbEngineSqlQuery prepareQuery(const QString& sql);
    DbEngineSqlQuery getQuery();
    DbEngineSqlQuery copyQuery(const DbEngineSqlQuery& old);
 
    bool queryErrorHandling(DbEngineSqlQuery& query, int retries);
    bool transactionErrorHandling(const QSqlError& lastError, int retries);
 
    bool connectionErrorHandling(int retries);
 
    QList<QVariant> readToList(DbEngineSqlQuery& query);
 
    BdEngineBackend::QueryState beginTransaction();
    BdEngineBackend::QueryState commitTransaction();
    void rollbackTransaction();
 
    bool isInTransaction() const;
 
    QStringList tables();
 
    QString lastError();
 
    QSqlError lastSQLError();
 
    int maximumBoundValues() const;
 
    void setForeignKeyChecks(bool check);
 
    /*
        Qt SQL driver supported features
        SQLITE3:
            BLOB
            Transactions
            Unicode
            LastInsertId
            PreparedQueries
            PositionalPlaceholders
            SimpleLocking
        MySQL:
            Transactions (3.?)
            QuerySize
            BLOB
            LastInsertId
            Unicode
            PreparedQueries (4.1)
            PositionalPlaceholders (4.1)
        Postgresql:
            Transactions
            QuerySize
            LastInsertId
    */
 
protected:
 
    BdEngineBackendPrivate* const d_ptr;
 
private:
 
    Q_DECLARE_PRIVATE(BdEngineBackend)
 
    // Disable
    BdEngineBackend(QObject*) = delete;
};
 
} // namespace Digikam
 
Q_DECLARE_METATYPE(QSqlError)
 
#endif // DIGIKAM_DB_ENGINE_BACKEND_H