QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
qgsabstractdatabaseproviderconnection.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgsabstractdatabaseproviderconnection.h - QgsAbstractDatabaseProviderConnection
3 
4  ---------------------
5  begin : 2.8.2019
6  copyright : (C) 2019 by Alessandro Pasotti
7  email : elpaso at itopen dot it
8  ***************************************************************************
9  * *
10  * This program is free software; you can redistribute it and/or modify *
11  * it under the terms of the GNU General Public License as published by *
12  * the Free Software Foundation; either version 2 of the License, or *
13  * (at your option) any later version. *
14  * *
15  ***************************************************************************/
16 #ifndef QGSABSTRACTDATABASEPROVIDERCONNECTION_H
17 #define QGSABSTRACTDATABASEPROVIDERCONNECTION_H
18 
21 #include "qgis_core.h"
22 #include "qgsfields.h"
23 #include "qgsvectordataprovider.h"
25 
26 #include <QObject>
27 
28 class QgsFeedback;
29 class QgsFieldDomain;
30 class QgsWeakRelation;
32 
33 
48 {
49 
50  Q_GADGET
51 
52  public:
53 
61  {
62  Aspatial = 1 << 1,
63  Vector = 1 << 2,
64  Raster = 1 << 3,
65  View = 1 << 4,
66  MaterializedView = 1 << 5,
67  Foreign = 1 << 6,
68  IncludeSystemTables = 1 << 7,
69  };
70 
71  Q_ENUM( TableFlag )
72  Q_DECLARE_FLAGS( TableFlags, TableFlag )
73  Q_FLAG( TableFlags )
74 
87  struct CORE_EXPORT QueryResult
88  {
89 
93  QStringList columns() const;
94 
102  QList<QList<QVariant> > rows( QgsFeedback *feedback = nullptr );
103 
110  bool hasNextRow() const;
111 
118  QList<QVariant> nextRow() const;
119 
125  long long fetchedRowCount( ) const;
126 
132  long long rowCount( ) const;
133 
134 
135 #ifdef SIP_RUN
136  // Python iterator
137  QueryResult *__iter__();
138  % MethodCode
139  sipRes = sipCpp;
140  % End
141 
142  SIP_PYOBJECT __next__();
143  % MethodCode
144  QList<QVariant> result;
145  Py_BEGIN_ALLOW_THREADS
146  result = sipCpp->nextRow( );
147  Py_END_ALLOW_THREADS
148  if ( ! result.isEmpty() )
149  {
150  const sipTypeDef *qvariantlist_type = sipFindType( "QList<QVariant>" );
151  sipRes = sipConvertFromNewType( new QList<QVariant>( result ), qvariantlist_type, Py_None );
152  }
153  else
154  {
155  PyErr_SetString( PyExc_StopIteration, "" );
156  }
157  % End
158 #endif
159 
161 
167  struct CORE_EXPORT QueryResultIterator SIP_SKIP
168  {
170  QVariantList nextRow();
171 
173  bool hasNextRow() const;
174 
176  long long fetchedRowCount();
177 
179  long long rowCount();
180 
181  virtual ~QueryResultIterator() = default;
182 
183  private:
184 
185  virtual QVariantList nextRowPrivate() = 0;
186  virtual bool hasNextRowPrivate() const = 0;
187  virtual long long rowCountPrivate() const = 0;
188 
189  mutable qlonglong mFetchedRowCount = 0;
190  mutable QMutex mMutex;
191 
192  };
193 
199  void appendColumn( const QString &columnName ) SIP_SKIP;
200 
206  QueryResult( std::shared_ptr<QueryResultIterator> iterator ) SIP_SKIP;
207 
212  QueryResult( ) = default SIP_SKIP;
213 
217  double queryExecutionTime( ) const;
218 
222  void setQueryExecutionTime( double queryExecutionTime );
223 
225 
226  private:
227 
228  mutable std::shared_ptr<QueryResultIterator> mResultIterator;
229  QStringList mColumns;
231  double mQueryExecutionTime = 0;
232 
233  };
234 
241  struct CORE_EXPORT SqlVectorLayerOptions
242  {
244  QString sql;
246  QString filter;
248  QString layerName;
250  QStringList primaryKeyColumns;
252  QString geometryColumn;
254  bool disableSelectAtId = false;
255 
256  };
257 
269  struct CORE_EXPORT TableProperty
270  {
271 
272 #ifdef SIP_RUN
273  SIP_PYOBJECT __repr__();
274  % MethodCode
275  QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty: '%1'>" ).arg( sipCpp->tableName() );
276  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
277  % End
278 #endif
279 
284  struct CORE_EXPORT GeometryColumnType
285  {
286 #ifdef SIP_RUN
287  SIP_PYOBJECT __repr__();
288  % MethodCode
289  QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType: '%1, %2'>" ).arg( QgsWkbTypes::displayString( sipCpp->wkbType ), sipCpp->crs.authid() );
290  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
291  % End
292 #endif
295 
296  // TODO c++20 - replace with = default
297  inline bool operator==( const GeometryColumnType &other ) const
298  {
299  return this->crs == other.crs && this->wkbType == other.wkbType;
300  }
301  };
302 
303  public:
304 
310  QString tableName() const;
311 
317  void setTableName( const QString &name );
318 
322  void addGeometryColumnType( Qgis::WkbType type, const QgsCoordinateReferenceSystem &crs );
323 
329  QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> geometryColumnTypes() const;
330 
334  void setGeometryColumnTypes( const QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> &geometryColumnTypes );
335 
343  QString defaultName() const;
344 
349  TableProperty at( int index ) const;
350 
354  QString schema() const;
355 
359  void setSchema( const QString &schema );
360 
364  QString geometryColumn() const;
365 
369  void setGeometryColumn( const QString &geometryColumn );
370 
374  QStringList primaryKeyColumns() const;
375 
379  void setPrimaryKeyColumns( const QStringList &primaryKeyColumns );
380 
384  QList<QgsCoordinateReferenceSystem> crsList() const;
385 
389  TableFlags flags() const;
390 
394  void setFlags( const TableFlags &flags );
395 
399  QString comment() const;
400 
404  void setComment( const QString &comment );
405 
412  QVariantMap info() const;
413 
420  void setInfo( const QVariantMap &info );
421 
427  int geometryColumnCount() const;
428 
432  void setGeometryColumnCount( int geometryColumnCount );
433 
437  void setFlag( const TableFlag &flag );
438 
445  int maxCoordinateDimensions() const;
446 
448 
449  private:
450 
452  QList<GeometryColumnType> mGeometryColumnTypes;
454  QString mSchema;
456  QString mTableName;
458  QString mGeometryColumn;
460  int mGeometryColumnCount;
462  QStringList mPkColumns;
463  TableFlags mFlags;
464  QString mComment;
466  QVariantMap mInfo;
467  };
468 
474  struct CORE_EXPORT SpatialIndexOptions
475  {
478  };
479 
486  {
487  CreateVectorTable = 1 << 1,
488  DropRasterTable = 1 << 2,
489  DropVectorTable = 1 << 3,
490  RenameVectorTable = 1 << 4,
491  RenameRasterTable = 1 << 5,
492  CreateSchema = 1 << 6,
493  DropSchema = 1 << 7,
494  RenameSchema = 1 << 8,
495  ExecuteSql = 1 << 9,
496  Vacuum = 1 << 10,
497  Tables = 1 << 11,
498  Schemas = 1 << 12,
499  SqlLayers = 1 << 13,
500  TableExists = 1 << 14,
501  Spatial = 1 << 15,
502  CreateSpatialIndex = 1 << 16,
503  SpatialIndexExists = 1 << 17,
504  DeleteSpatialIndex = 1 << 18,
505  DeleteField = 1 << 19,
506  DeleteFieldCascade = 1 << 20,
507  AddField = 1 << 21,
508  ListFieldDomains = 1 << 22,
509  RetrieveFieldDomain = 1 << 23,
510  SetFieldDomain = 1 << 24,
511  AddFieldDomain = 1 << 25,
512  RenameField = 1 << 26,
513  RetrieveRelationships = 1 << 27,
514  AddRelationship = 1 << 28,
515  UpdateRelationship = 1 << 29,
516  DeleteRelationship = 1 << 30,
517  };
518  Q_ENUM( Capability )
519  Q_DECLARE_FLAGS( Capabilities, Capability )
520  Q_FLAG( Capabilities )
521 
528  {
529  Z = 1 << 1,
530  M = 1 << 2,
531  SinglePart = 1 << 3,
532  Curves = 1 << 4,
533  SinglePoint = 1 << 5,
534  SingleLineString = 1 << 6,
535  SinglePolygon = 1 << 7,
536  };
537  // TODO QGIS 4.0 -- remove SinglePart
538 
539  Q_ENUM( GeometryColumnCapability )
542 
548  QgsAbstractDatabaseProviderConnection( const QString &name );
549 
556  QgsAbstractDatabaseProviderConnection( const QString &uri, const QVariantMap &configuration );
557 
558 
559  // Public interface
560 
566  Capabilities capabilities() const;
567 
574  Qgis::DatabaseProviderConnectionCapabilities2 capabilities2() const;
575 
581  virtual GeometryColumnCapabilities geometryColumnCapabilities();
582 
587  virtual Qgis::SqlLayerDefinitionCapabilities sqlLayerDefinitionCapabilities();
588 
589  // Operations interface
590 
597  virtual QString tableUri( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
598 
604  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 );
605 
611  virtual bool tableExists( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
612 
619  virtual void dropVectorTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
620 
627  virtual void dropRasterTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
628 
635  virtual void renameVectorTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
636 
643  virtual void renameRasterTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
644 
650  virtual void createSchema( const QString &name ) const SIP_THROW( QgsProviderConnectionException );
651 
660  virtual void dropSchema( const QString &name, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
661 
673  virtual void deleteField( const QString &fieldName, const QString &schema, const QString &tableName, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
674 
685  virtual void addField( const QgsField &field, const QString &schema, const QString &tableName ) const SIP_THROW( QgsProviderConnectionException );
686 
700  virtual void renameField( const QString &schema, const QString &tableName, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
701 
708  virtual void renameSchema( const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
709 
716  virtual QList<QList<QVariant>> executeSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
717 
723  virtual QgsVectorLayer *createSqlVectorLayer( const SqlVectorLayerOptions &options ) const SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;
724 
732  virtual SqlVectorLayerOptions sqlOptions( const QString &layerSource ) SIP_THROW( QgsProviderConnectionException );
733 
741  virtual QueryResult execSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
742 
748  virtual void vacuum( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
749 
758  virtual void createSpatialIndex( const QString &schema, const QString &name, const QgsAbstractDatabaseProviderConnection::SpatialIndexOptions &options = QgsAbstractDatabaseProviderConnection::SpatialIndexOptions() ) const SIP_THROW( QgsProviderConnectionException );
759 
767  virtual bool spatialIndexExists( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
768 
776  virtual void deleteSpatialIndex( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
777 
787  virtual QList<QgsAbstractDatabaseProviderConnection::TableProperty> tables( const QString &schema = QString(), const QgsAbstractDatabaseProviderConnection::TableFlags &flags = QgsAbstractDatabaseProviderConnection::TableFlags(), QgsFeedback *feedback = nullptr ) const SIP_SKIP;
788 
798  virtual QgsAbstractDatabaseProviderConnection::TableProperty table( const QString &schema, const QString &table, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
799 
807  QList<QgsAbstractDatabaseProviderConnection::TableProperty> tablesInt( const QString &schema = QString(), const int flags = 0 ) const SIP_THROW( QgsProviderConnectionException ) SIP_PYNAME( tables );
808 
809 
810  // TODO: return more schema information and not just the name
811 
817  virtual QStringList schemas() const SIP_THROW( QgsProviderConnectionException );
818 
831  virtual QgsFields fields( const QString &schema, const QString &table, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
832 
839  virtual QList< QgsVectorDataProvider::NativeType > nativeTypes() const SIP_THROW( QgsProviderConnectionException ) = 0;
840 
846  QString providerKey() const;
847 
857  virtual QMultiMap<Qgis::SqlKeywordCategory, QStringList> sqlDictionary();
858 
865  virtual QSet< QString > illegalFieldNames() const;
866 
877  virtual QStringList fieldDomainNames() const SIP_THROW( QgsProviderConnectionException );
878 
884  virtual QList< Qgis::FieldDomainType > supportedFieldDomainTypes() const;
885 
898  virtual QgsFieldDomain *fieldDomain( const QString &name ) const SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;
899 
911  virtual void setFieldDomainName( const QString &fieldName, const QString &schema, const QString &tableName, const QString &domainName ) const SIP_THROW( QgsProviderConnectionException );
912 
922  virtual void addFieldDomain( const QgsFieldDomain &domain, const QString &schema ) const SIP_THROW( QgsProviderConnectionException );
923 
935  virtual void setFieldAlias( const QString &fieldName, const QString &schema, const QString &tableName, const QString &alias ) const SIP_THROW( QgsProviderConnectionException );
936 
948  virtual void setFieldComment( const QString &fieldName, const QString &schema, const QString &tableName, const QString &comment ) const SIP_THROW( QgsProviderConnectionException );
949 
955 #ifndef SIP_RUN
956  virtual QList< Qgis::RelationshipCardinality > supportedRelationshipCardinalities() const;
957 #else
958  SIP_PYOBJECT supportedRelationshipCardinalities() const SIP_TYPEHINT( List[Qgis.RelationshipCardinality] );
959  % MethodCode
960  // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
961 
962  const QList< Qgis::RelationshipCardinality > cppRes = sipCpp->supportedRelationshipCardinalities();
963 
964  PyObject *l = PyList_New( cppRes.size() );
965 
966  if ( !l )
967  sipIsErr = 1;
968  else
969  {
970  for ( int i = 0; i < cppRes.size(); ++i )
971  {
972  PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
973  sipType_Qgis_RelationshipCardinality );
974 
975  if ( !eobj )
976  {
977  sipIsErr = 1;
978  }
979 
980  PyList_SetItem( l, i, eobj );
981  }
982 
983  if ( !sipIsErr )
984  {
985  sipRes = l;
986  }
987  else
988  {
989  Py_DECREF( l );
990  }
991  }
992  % End
993 #endif
994 
1000 #ifndef SIP_RUN
1001  virtual QList< Qgis::RelationshipStrength > supportedRelationshipStrengths() const;
1002 #else
1003  SIP_PYOBJECT supportedRelationshipStrengths() const SIP_TYPEHINT( List[Qgis.RelationshipStrength] );
1004  % MethodCode
1005  // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
1006 
1007  const QList< Qgis::RelationshipStrength > cppRes = sipCpp->supportedRelationshipStrengths();
1008 
1009  PyObject *l = PyList_New( cppRes.size() );
1010 
1011  if ( !l )
1012  sipIsErr = 1;
1013  else
1014  {
1015  for ( int i = 0; i < cppRes.size(); ++i )
1016  {
1017  PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
1018  sipType_Qgis_RelationshipStrength );
1019 
1020  if ( !eobj )
1021  {
1022  sipIsErr = 1;
1023  }
1024 
1025  PyList_SetItem( l, i, eobj );
1026  }
1027 
1028  if ( !sipIsErr )
1029  {
1030  sipRes = l;
1031  }
1032  else
1033  {
1034  Py_DECREF( l );
1035  }
1036  }
1037  % End
1038 #endif
1039 
1045  virtual Qgis::RelationshipCapabilities supportedRelationshipCapabilities() const;
1046 
1057  virtual QStringList relatedTableTypes() const;
1058 
1071  virtual QList< QgsWeakRelation > relationships( const QString &schema = QString(), const QString &tableName = QString() ) const SIP_THROW( QgsProviderConnectionException );
1072 
1079  virtual void addRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );
1080 
1087  virtual void updateRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );
1088 
1095  virtual void deleteRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );
1096 
1104  virtual QgsProviderSqlQueryBuilder *queryBuilder() const SIP_FACTORY;
1105 
1126  virtual QList<QgsLayerMetadataProviderResult> searchLayerMetadata( const QgsMetadataSearchContext &searchContext, const QString &searchString = QString(), const QgsRectangle &geographicExtent = QgsRectangle(), QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException, QgsNotSupportedException );
1127 
1128  protected:
1129 
1131 
1137  void checkCapability( Capability capability ) const;
1138 
1144  void checkCapability( Qgis::DatabaseProviderConnectionCapability2 capability ) const;
1146 
1148  Qgis::DatabaseProviderConnectionCapabilities2 mCapabilities2 = Qgis::DatabaseProviderConnectionCapabilities2() SIP_SKIP;
1149 
1151  Qgis::SqlLayerDefinitionCapabilities mSqlLayerDefinitionCapabilities = Qgis::SqlLayerDefinitionCapabilities() SIP_SKIP;
1152  QString mProviderKey;
1153  QSet<QString> mIllegalFieldNames SIP_SKIP;
1154 
1155 };
1156 
1158 
1159 #endif // QGSABSTRACTDATABASEPROVIDERCONNECTION_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:54
QFlags< RelationshipCapability > RelationshipCapabilities
Relationship capabilities.
Definition: qgis.h:3649
WkbType
The WKB type describes the number of dimensions a geometry has.
Definition: qgis.h:182
The QgsAbstractDatabaseProviderConnection class provides common functionality for DB based connection...
GeometryColumnCapability
The GeometryColumnCapability enum represents the geometry column features supported by the connection...
QFlags< GeometryColumnCapability > GeometryColumnCapabilities
Capability
The Capability enum represents the operations supported by the connection.
The QgsAbstractProviderConnection provides an interface for data provider connections.
This class represents a coordinate reference system (CRS).
Base class for feedback objects to be used for cancellation of something running in a worker thread.
Definition: qgsfeedback.h:44
Base class for field domains.
Encapsulate a field in an attribute table or data source.
Definition: qgsfield.h:53
Container of fields for a vector layer.
Definition: qgsfields.h:45
Result record of layer metadata provider search.
Custom exception class which is raised when an operation is not supported.
Definition: qgsexception.h:118
Custom exception class for provider connection related exceptions.
Definition: qgsexception.h:101
Provides an interface for provider-specific creation of SQL queries.
A rectangle specified with double values.
Definition: qgsrectangle.h:42
This is the base class for vector data providers.
Represents a vector layer which manages a vector based data sets.
The QgsWeakRelation class represent a QgsRelation with possibly unresolved layers or unmatched fields...
static QString displayString(Qgis::WkbType type)
Returns a non-translated display string type for a WKB type, e.g., the geometry name used in WKT geom...
#define str(x)
Definition: qgis.cpp:38
#define SIP_TYPEHINT(type)
Definition: qgis_sip.h:232
#define SIP_ENUM_BASETYPE(type)
Definition: qgis_sip.h:278
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_MONKEYPATCH_SCOPEENUM_UNNEST(OUTSIDE_CLASS, FORMERNAME)
Definition: qgis_sip.h:271
#define SIP_PYNAME(name)
Definition: qgis_sip.h:81
#define SIP_FACTORY
Definition: qgis_sip.h:76
#define SIP_THROW(name,...)
Definition: qgis_sip.h:203
bool operator==(const QgsFeatureIterator &fi1, const QgsFeatureIterator &fi2)
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsTextRendererUtils::CurvedTextFlags)
const QgsCoordinateReferenceSystem & crs
The QueryResult class represents the result of a query executed by execSql()
QList< QList< QVariant > > rows(QgsFeedback *feedback=nullptr)
Returns the result rows by calling the iterator internally and fetching all the rows,...
long long fetchedRowCount() const
Returns the number of fetched rows.
bool hasNextRow() const
Returns true if there are more rows to fetch.
long long rowCount() const
Returns the number of rows returned by a SELECT query or Qgis::FeatureCountState::UnknownCount if unk...
QList< QVariant > nextRow() const
Returns the next result row or an empty row if there are no rows left.
QStringList columns() const
Returns the column names.
The SpatialIndexOptions contains extra options relating to spatial index creation.
QString geometryColumnName
Specifies the name of the geometry column to create the index for.
The SqlVectorLayerOptions stores all information required to create a SQL (query) layer.
QString sql
The SQL expression that defines the SQL (query) layer.
QString filter
Additional subset string (provider-side filter), not all data providers support this feature: check s...
The GeometryColumnType struct represents the combination of geometry type and CRS for the table geome...
The TableProperty class represents a database table or view.