qgsabstractdatabaseproviderconnection.h

Go to the documentation of this file.

/***************************************************************************
  qgsabstractdatabaseproviderconnection.h - QgsAbstractDatabaseProviderConnection
 
 ---------------------
 begin                : 2.8.2019
 copyright            : (C) 2019 by Alessandro Pasotti
 email                : elpaso at itopen dot it
 ***************************************************************************
 *                                                                         *
 *   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 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
#ifndef QGSABSTRACTDATABASEPROVIDERCONNECTION_H
#define QGSABSTRACTDATABASEPROVIDERCONNECTION_H
 
#include "qgis_core.h"
#include "qgsabstractlayermetadataprovider.h"
#include "qgsabstractproviderconnection.h"
#include "qgscoordinatereferencesystem.h"
#include "qgsfields.h"
#include "qgsvectordataprovider.h"
 
#include <QObject>
#include <QString>
 
using namespace Qt::StringLiterals;
 
class QgsFeedback;
class QgsFieldDomain;
class QgsWeakRelation;
class QgsProviderSqlQueryBuilder;
 

class CORE_EXPORT QgsAbstractDatabaseProviderConnection : public QgsAbstractProviderConnection
{
    Q_GADGET
 
  public:
    enum class TableFlag SIP_MONKEYPATCH_SCOPEENUM_UNNEST( QgsAbstractDatabaseProviderConnection, TableFlag ) : int SIP_ENUM_BASETYPE( IntFlag )
    {
      Aspatial = 1 << 1,            
      Vector = 1 << 2,              
      Raster = 1 << 3,              
      View = 1 << 4,                
      MaterializedView = 1 << 5,    
      Foreign = 1 << 6,             
      IncludeSystemTables = 1 << 7, 
    };
 
    Q_ENUM( TableFlag )
    Q_DECLARE_FLAGS( TableFlags, TableFlag )
    Q_FLAG( TableFlags )

    struct CORE_EXPORT QueryResult
    {
        QStringList columns() const;

        QList<QList<QVariant> > rows( QgsFeedback *feedback = nullptr );

        bool hasNextRow() const;

        QList<QVariant> nextRow() const;

        long long fetchedRowCount() const;

        long long rowCount() const;
 
 
#ifdef SIP_RUN
        // clang-format off
        // Python iterator
        QueryResult *__iter__();
        % MethodCode
        sipRes = sipCpp;
        % End
 
        SIP_PYOBJECT __next__();
        % MethodCode
        QList<QVariant> result;
        Py_BEGIN_ALLOW_THREADS
        result = sipCpp->nextRow( );
        Py_END_ALLOW_THREADS
        if ( ! result.isEmpty() )
        {
          const sipTypeDef *qvariantlist_type = sipFindType( "QList<QVariant>" );
          sipRes = sipConvertFromNewType( new QList<QVariant>( result ), qvariantlist_type, Py_None );
        }
        else
        {
          PyErr_SetString( PyExc_StopIteration, "" );
        }
        % End
// clang-format on
#endif


          struct CORE_EXPORT QueryResultIterator SIP_SKIP
        {
            QVariantList nextRow();

            bool hasNextRow() const;

            long long fetchedRowCount();

            long long rowCount();
 
            virtual ~QueryResultIterator() = default;
 
          private:
            virtual QVariantList nextRowPrivate() = 0;
            virtual bool hasNextRowPrivate() const = 0;
            virtual long long rowCountPrivate() const = 0;
 
            mutable qlonglong mFetchedRowCount = 0;
            mutable QMutex mMutex;
        };

        void appendColumn( const QString &columnName ) SIP_SKIP;

        QueryResult( std::shared_ptr<QueryResultIterator> iterator ) SIP_SKIP;

        QueryResult() = default SIP_SKIP;

        double queryExecutionTime() const;

        void setQueryExecutionTime( double queryExecutionTime );

 
      private:
        mutable std::shared_ptr<QueryResultIterator> mResultIterator;
        QStringList mColumns;
        double mQueryExecutionTime = 0;
    };

    static bool splitSimpleQuery( const QString &sql, QStringList &columns, QStringList &tables, QString &where ) SIP_SKIP;
 

    struct CORE_EXPORT SqlVectorLayerOptions
    {
        QString sql;
        QString filter;
        QString layerName;
        QStringList primaryKeyColumns;
        QString geometryColumn;
        bool disableSelectAtId = false;
    };

    struct CORE_EXPORT TableProperty
    {
#ifdef SIP_RUN
        // clang-format off
        SIP_PYOBJECT __repr__();
        % MethodCode
        QString str = u"<QgsAbstractDatabaseProviderConnection.TableProperty: '%1'>"_s.arg( sipCpp->tableName() );
        sipRes = PyUnicode_FromString( str.toUtf8().constData() );
        % End
// clang-format on
#endif

          struct CORE_EXPORT GeometryColumnType
        {
#ifdef SIP_RUN
            // clang-format off
          SIP_PYOBJECT __repr__();
          % MethodCode
          QString str = u"<QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType: '%1, %2'>"_s.arg( QgsWkbTypes::displayString( sipCpp->wkbType ), sipCpp->crs.authid() );
          sipRes = PyUnicode_FromString( str.toUtf8().constData() );
          % End
// clang-format on
#endif
                Qgis::WkbType wkbType;
            QgsCoordinateReferenceSystem crs;
 
            // TODO c++20 - replace with = default
            inline bool operator==( const GeometryColumnType &other ) const { return this->crs == other.crs && this->wkbType == other.wkbType; }
        };
 
      public:
        QString tableName() const;

        void setTableName( const QString &name );

        void addGeometryColumnType( Qgis::WkbType type, const QgsCoordinateReferenceSystem &crs );

        QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> geometryColumnTypes() const;

        void setGeometryColumnTypes( const QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> &geometryColumnTypes );

        QString defaultName() const;

        TableProperty at( int index ) const;

        QString schema() const;

        void setSchema( const QString &schema );

        QString geometryColumn() const;

        void setGeometryColumn( const QString &geometryColumn );

        QStringList primaryKeyColumns() const;

        void setPrimaryKeyColumns( const QStringList &primaryKeyColumns );

        QList<QgsCoordinateReferenceSystem> crsList() const;

        TableFlags flags() const;

        void setFlags( const TableFlags &flags );

        QString comment() const;

        void setComment( const QString &comment );

        QVariantMap info() const;

        void setInfo( const QVariantMap &info );

        int geometryColumnCount() const;

        void setGeometryColumnCount( int geometryColumnCount );

        void setFlag( const TableFlag &flag );

        int maxCoordinateDimensions() const;
 
        bool operator==( const QgsAbstractDatabaseProviderConnection::TableProperty &other ) const;
 
      private:
        QList<GeometryColumnType> mGeometryColumnTypes;
        QString mSchema;
        QString mTableName;
        QString mGeometryColumn;
        int mGeometryColumnCount = 0;
        QStringList mPkColumns;
        TableFlags mFlags;
        QString mComment;
        QVariantMap mInfo;
    };

    struct CORE_EXPORT SpatialIndexOptions
    {
        QString geometryColumnName;
    };

    enum Capability SIP_ENUM_BASETYPE( IntFlag )
    {
      CreateVectorTable = 1 << 1,      
      DropRasterTable = 1 << 2,        
      DropVectorTable = 1 << 3,        
      RenameVectorTable = 1 << 4,      
      RenameRasterTable = 1 << 5,      
      CreateSchema = 1 << 6,           
      DropSchema = 1 << 7,             
      RenameSchema = 1 << 8,           
      ExecuteSql = 1 << 9,             
      Vacuum = 1 << 10,                
      Tables = 1 << 11,                
      Schemas = 1 << 12,               
      SqlLayers = 1 << 13,             
      TableExists = 1 << 14,           
      Spatial = 1 << 15,               
      CreateSpatialIndex = 1 << 16,    
      SpatialIndexExists = 1 << 17,    
      DeleteSpatialIndex = 1 << 18,    
      DeleteField = 1 << 19,           
      DeleteFieldCascade = 1 << 20,    
      AddField = 1 << 21,              
      ListFieldDomains = 1 << 22,      
      RetrieveFieldDomain = 1 << 23,   
      SetFieldDomain = 1 << 24,        
      AddFieldDomain = 1 << 25,        
      RenameField = 1 << 26,           
      RetrieveRelationships = 1 << 27, 
      AddRelationship = 1 << 28,       
      UpdateRelationship = 1 << 29,    
      DeleteRelationship = 1 << 30,    
      MoveTableToSchema = 1u << 31,    
    };
    Q_ENUM( Capability )
    Q_DECLARE_FLAGS( Capabilities, Capability )
    Q_FLAG( Capabilities )

    enum GeometryColumnCapability SIP_ENUM_BASETYPE( IntFlag )
    {
      Z = 1 << 1,                  
      M = 1 << 2,                  
      SinglePart = 1 << 3,         
      Curves = 1 << 4,             
      SinglePoint = 1 << 5,        
      SingleLineString = 1 << 6,   
      SinglePolygon = 1 << 7,      
      PolyhedralSurfaces = 1 << 8, 
    };
    // TODO QGIS 5.0 -- remove SinglePart
 
    Q_ENUM( GeometryColumnCapability )
    Q_DECLARE_FLAGS( GeometryColumnCapabilities, GeometryColumnCapability )
    Q_FLAG( GeometryColumnCapabilities )

    QgsAbstractDatabaseProviderConnection( const QString &name );

    QgsAbstractDatabaseProviderConnection( const QString &uri, const QVariantMap &configuration );
 
 
    // Public interface

    Capabilities capabilities() const;

    Qgis::DatabaseProviderConnectionCapabilities2 capabilities2() const;

    virtual GeometryColumnCapabilities geometryColumnCapabilities();

    virtual Qgis::DatabaseProviderTableImportCapabilities tableImportCapabilities() const = 0;

    virtual Qgis::SqlLayerDefinitionCapabilities sqlLayerDefinitionCapabilities();
 
    // Operations interface

    virtual QString tableUri( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );

    virtual void createVectorTable(
      const QString &schema, const QString &name, const QgsFields &fields, Qgis::WkbType wkbType, const QgsCoordinateReferenceSystem &srs, bool overwrite, const QMap<QString, QVariant> *options
    ) const SIP_THROW( QgsProviderConnectionException );

    struct CORE_EXPORT VectorLayerExporterOptions
    {
        QString layerName;

        QString schema;

        Qgis::WkbType wkbType = Qgis::WkbType::NoGeometry;

        QStringList primaryKeyColumns;

        QString geometryColumn;
    };

    virtual QString createVectorLayerExporterDestinationUri( const QgsAbstractDatabaseProviderConnection::VectorLayerExporterOptions &options, QVariantMap &providerOptions SIP_OUT ) const SIP_THROW(
      QgsProviderConnectionException
    );

    virtual bool tableExists( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );

    virtual void dropVectorTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );

    virtual void dropRasterTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );

    virtual void renameVectorTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );

    virtual void renameRasterTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );

    virtual void createSchema( const QString &name ) const SIP_THROW( QgsProviderConnectionException );

    virtual void dropSchema( const QString &name, bool force = false ) const SIP_THROW( QgsProviderConnectionException );

    virtual void deleteField( const QString &fieldName, const QString &schema, const QString &tableName, bool force = false ) const SIP_THROW( QgsProviderConnectionException );

    virtual void addField( const QgsField &field, const QString &schema, const QString &tableName ) const SIP_THROW( QgsProviderConnectionException );

    virtual void renameField( const QString &schema, const QString &tableName, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );

    virtual void renameSchema( const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );

    virtual QList<QList<QVariant>> executeSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );

    virtual QgsVectorLayer *createSqlVectorLayer( const SqlVectorLayerOptions &options ) const SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;

    virtual bool validateSqlVectorLayer( const SqlVectorLayerOptions &options, QString &message SIP_OUT ) const SIP_THROW( QgsProviderConnectionException );

    virtual SqlVectorLayerOptions sqlOptions( const QString &layerSource ) SIP_THROW( QgsProviderConnectionException );

    virtual QueryResult execSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );

    virtual void vacuum( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );

    virtual void createSpatialIndex(
      const QString &schema, const QString &name, const QgsAbstractDatabaseProviderConnection::SpatialIndexOptions &options = QgsAbstractDatabaseProviderConnection::SpatialIndexOptions()
    ) const SIP_THROW( QgsProviderConnectionException );

    virtual bool spatialIndexExists( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );

    virtual void deleteSpatialIndex( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );

    virtual QList<QgsAbstractDatabaseProviderConnection::TableProperty> tables(
      const QString &schema = QString(), const QgsAbstractDatabaseProviderConnection::TableFlags &flags = QgsAbstractDatabaseProviderConnection::TableFlags(), QgsFeedback *feedback = nullptr
    ) const SIP_SKIP;

    virtual QgsAbstractDatabaseProviderConnection::TableProperty table( const QString &schema, const QString &table, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );

    QList<QgsAbstractDatabaseProviderConnection::TableProperty> tablesInt( const QString &schema = QString(), const int flags = 0 ) const SIP_THROW( QgsProviderConnectionException ) SIP_PYNAME( tables );
 
 
    // TODO: return more schema information and not just the name

    virtual QStringList schemas() const SIP_THROW( QgsProviderConnectionException );

    virtual QgsFields fields( const QString &schema, const QString &table, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );

    virtual QList< QgsVectorDataProvider::NativeType > nativeTypes() const SIP_THROW( QgsProviderConnectionException ) = 0;

    QString providerKey() const;

    virtual QMultiMap<Qgis::SqlKeywordCategory, QStringList> sqlDictionary();

    virtual QSet< QString > illegalFieldNames() const;

    virtual QString defaultPrimaryKeyColumnName() const;

    virtual QString defaultGeometryColumnName() const;

    virtual QStringList fieldDomainNames() const SIP_THROW( QgsProviderConnectionException );

    virtual QList< Qgis::FieldDomainType > supportedFieldDomainTypes() const;

    virtual QgsFieldDomain *fieldDomain( const QString &name ) const SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;

    virtual void setFieldDomainName( const QString &fieldName, const QString &schema, const QString &tableName, const QString &domainName ) const SIP_THROW( QgsProviderConnectionException );

    virtual void addFieldDomain( const QgsFieldDomain &domain, const QString &schema ) const SIP_THROW( QgsProviderConnectionException );

    virtual void updateFieldDomain( QgsFieldDomain *domain, const QString &schema ) const SIP_THROW( QgsProviderConnectionException );

    virtual void deleteFieldDomain( const QString &name, const QString &schema ) const SIP_THROW( QgsProviderConnectionException );

    virtual void setFieldAlias( const QString &fieldName, const QString &schema, const QString &tableName, const QString &alias ) const SIP_THROW( QgsProviderConnectionException );

    virtual void setTableComment( const QString &schema, const QString &tableName, const QString &comment ) const SIP_THROW( QgsProviderConnectionException );

    virtual void setFieldComment( const QString &fieldName, const QString &schema, const QString &tableName, const QString &comment ) const SIP_THROW( QgsProviderConnectionException );

    virtual void moveTableToSchema( const QString &sourceSchema, const QString &tableName, const QString &targetSchema ) const SIP_THROW( QgsProviderConnectionException );
 

#ifndef SIP_RUN
    virtual QList< Qgis::RelationshipCardinality > supportedRelationshipCardinalities() const;
#else
    // clang-format off
    SIP_PYOBJECT supportedRelationshipCardinalities() const SIP_TYPEHINT( List[Qgis.RelationshipCardinality] );
    % MethodCode
    // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
 
    const QList< Qgis::RelationshipCardinality > cppRes = sipCpp->supportedRelationshipCardinalities();
 
    PyObject *l = PyList_New( cppRes.size() );
 
    if ( !l )
      sipIsErr = 1;
    else
    {
      for ( int i = 0; i < cppRes.size(); ++i )
      {
        PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
                                             sipType_Qgis_RelationshipCardinality );
 
        if ( !eobj )
        {
          sipIsErr = 1;
        }
 
        PyList_SetItem( l, i, eobj );
      }
 
      if ( !sipIsErr )
      {
        sipRes = l;
      }
      else
      {
        Py_DECREF( l );
      }
    }
    % End
// clang-format on
#endif

#ifndef SIP_RUN
    virtual QList< Qgis::RelationshipStrength > supportedRelationshipStrengths() const;
#else
        // clang-format off
    SIP_PYOBJECT supportedRelationshipStrengths() const SIP_TYPEHINT( List[Qgis.RelationshipStrength] );
    % MethodCode
    // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
 
    const QList< Qgis::RelationshipStrength > cppRes = sipCpp->supportedRelationshipStrengths();
 
    PyObject *l = PyList_New( cppRes.size() );
 
    if ( !l )
      sipIsErr = 1;
    else
    {
      for ( int i = 0; i < cppRes.size(); ++i )
      {
        PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
                                             sipType_Qgis_RelationshipStrength );
 
        if ( !eobj )
        {
          sipIsErr = 1;
        }
 
        PyList_SetItem( l, i, eobj );
      }
 
      if ( !sipIsErr )
      {
        sipRes = l;
      }
      else
      {
        Py_DECREF( l );
      }
    }
    % End
// clang-format on
#endif

    virtual Qgis::RelationshipCapabilities supportedRelationshipCapabilities() const;

    virtual QStringList relatedTableTypes() const;

    virtual QList< QgsWeakRelation > relationships( const QString &schema = QString(), const QString &tableName = QString() ) const SIP_THROW( QgsProviderConnectionException );

    virtual void addRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );

    virtual void updateRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );

    virtual void deleteRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );

    virtual QgsProviderSqlQueryBuilder *queryBuilder() const SIP_FACTORY;

    virtual QList<QgsLayerMetadataProviderResult> searchLayerMetadata(
      const QgsMetadataSearchContext &searchContext, const QString &searchString = QString(), const QgsRectangle &geographicExtent = QgsRectangle(), QgsFeedback *feedback = nullptr
    ) const SIP_THROW( QgsProviderConnectionException, QgsNotSupportedException );
 
  protected:

    void checkCapability( Capability capability ) const;

    void checkCapability( Qgis::DatabaseProviderConnectionCapability2 capability ) const;

    QString sanitizeSqlForQueryLayer( const QString &sql ) const SIP_SKIP;

 
    Capabilities mCapabilities = Capabilities() SIP_SKIP;
    Qgis::DatabaseProviderConnectionCapabilities2 mCapabilities2 = Qgis::DatabaseProviderConnectionCapabilities2() SIP_SKIP;
 
    GeometryColumnCapabilities mGeometryColumnCapabilities = GeometryColumnCapabilities() SIP_SKIP;
    Qgis::SqlLayerDefinitionCapabilities mSqlLayerDefinitionCapabilities = Qgis::SqlLayerDefinitionCapabilities() SIP_SKIP;
    QString mProviderKey;
    QSet<QString> mIllegalFieldNames SIP_SKIP;
};
 
Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAbstractDatabaseProviderConnection::Capabilities )
 
#endif // QGSABSTRACTDATABASEPROVIDERCONNECTION_H