QGIS API Documentation  3.27.0-Master (e113457133)
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 "qgsexception.h"
24 #include "qgsvectordataprovider.h"
25 
26 #include <QObject>
27 
28 class QgsFeedback;
29 class QgsFieldDomain;
30 
45 {
46 
47  Q_GADGET
48 
49  public:
50 
57  enum TableFlag
58  {
59  Aspatial = 1 << 1,
60  Vector = 1 << 2,
61  Raster = 1 << 3,
62  View = 1 << 4,
63  MaterializedView = 1 << 5,
64  Foreign = 1 << 6,
65  };
66 
67  Q_ENUM( TableFlag )
68  Q_DECLARE_FLAGS( TableFlags, TableFlag )
69  Q_FLAG( TableFlags )
70 
71 
83  struct CORE_EXPORT QueryResult
84  {
85 
89  QStringList columns() const;
90 
98  QList<QList<QVariant> > rows( QgsFeedback *feedback = nullptr );
99 
106  bool hasNextRow() const;
107 
114  QList<QVariant> nextRow() const;
115 
121  long long fetchedRowCount( ) const;
122 
128  long long rowCount( ) const;
129 
130 
131 #ifdef SIP_RUN
132  // Python iterator
133  QueryResult *__iter__();
134  % MethodCode
135  sipRes = sipCpp;
136  % End
137 
138  SIP_PYOBJECT __next__();
139  % MethodCode
140  QList<QVariant> result;
141  Py_BEGIN_ALLOW_THREADS
142  result = sipCpp->nextRow( );
143  Py_END_ALLOW_THREADS
144  if ( ! result.isEmpty() )
145  {
146  const sipTypeDef *qvariantlist_type = sipFindType( "QList<QVariant>" );
147  sipRes = sipConvertFromNewType( new QList<QVariant>( result ), qvariantlist_type, Py_None );
148  }
149  else
150  {
151  PyErr_SetString( PyExc_StopIteration, "" );
152  }
153  % End
154 #endif
155 
157 
163  struct CORE_EXPORT QueryResultIterator SIP_SKIP
164  {
166  QVariantList nextRow();
167 
169  bool hasNextRow() const;
170 
172  long long fetchedRowCount();
173 
175  long long rowCount();
176 
177  virtual ~QueryResultIterator() = default;
178 
179  private:
180 
181  virtual QVariantList nextRowPrivate() = 0;
182  virtual bool hasNextRowPrivate() const = 0;
183  virtual long long rowCountPrivate() const = 0;
184 
185  mutable qlonglong mFetchedRowCount = 0;
186  mutable QMutex mMutex;
187 
188  };
189 
195  void appendColumn( const QString &columnName ) SIP_SKIP;
196 
202  QueryResult( std::shared_ptr<QueryResultIterator> iterator ) SIP_SKIP;
203 
208  QueryResult( ) = default SIP_SKIP;
209 
213  double queryExecutionTime( ) const;
214 
218  void setQueryExecutionTime( double queryExecutionTime );
219 
221 
222  private:
223 
224  mutable std::shared_ptr<QueryResultIterator> mResultIterator;
225  QStringList mColumns;
227  double mQueryExecutionTime = 0;
228 
229  };
230 
237  struct CORE_EXPORT SqlVectorLayerOptions
238  {
240  QString sql;
242  QString filter;
244  QString layerName;
246  QStringList primaryKeyColumns;
248  QString geometryColumn;
250  bool disableSelectAtId = false;
251 
252  };
253 
265  struct CORE_EXPORT TableProperty
266  {
267 
268 #ifdef SIP_RUN
269  SIP_PYOBJECT __repr__();
270  % MethodCode
271  QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty: '%1'>" ).arg( sipCpp->tableName() );
272  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
273  % End
274 #endif
275 
280  struct CORE_EXPORT GeometryColumnType
281  {
282 #ifdef SIP_RUN
283  SIP_PYOBJECT __repr__();
284  % MethodCode
285  QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType: '%1, %2'>" ).arg( QgsWkbTypes::displayString( sipCpp->wkbType ), sipCpp->crs.authid() );
286  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
287  % End
288 #endif
291 
292  // TODO c++20 - replace with = default
293  inline bool operator==( const GeometryColumnType &other ) const
294  {
295  return this->crs == other.crs && this->wkbType == other.wkbType;
296  }
297  };
298 
299  public:
300 
306  QString tableName() const;
307 
313  void setTableName( const QString &name );
314 
318  void addGeometryColumnType( const QgsWkbTypes::Type &type, const QgsCoordinateReferenceSystem &crs );
319 
325  QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> geometryColumnTypes() const;
326 
330  void setGeometryColumnTypes( const QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> &geometryColumnTypes );
331 
339  QString defaultName() const;
340 
345  TableProperty at( int index ) const;
346 
350  QString schema() const;
351 
355  void setSchema( const QString &schema );
356 
360  QString geometryColumn() const;
361 
365  void setGeometryColumn( const QString &geometryColumn );
366 
370  QStringList primaryKeyColumns() const;
371 
375  void setPrimaryKeyColumns( const QStringList &primaryKeyColumns );
376 
380  QList<QgsCoordinateReferenceSystem> crsList() const;
381 
385  TableFlags flags() const;
386 
390  void setFlags( const TableFlags &flags );
391 
395  QString comment() const;
396 
400  void setComment( const QString &comment );
401 
408  QVariantMap info() const;
409 
416  void setInfo( const QVariantMap &info );
417 
423  int geometryColumnCount() const;
424 
428  void setGeometryColumnCount( int geometryColumnCount );
429 
433  void setFlag( const TableFlag &flag );
434 
441  int maxCoordinateDimensions() const;
442 
444 
445  private:
446 
448  QList<GeometryColumnType> mGeometryColumnTypes;
450  QString mSchema;
452  QString mTableName;
454  QString mGeometryColumn;
456  int mGeometryColumnCount;
458  QStringList mPkColumns;
459  TableFlags mFlags;
460  QString mComment;
462  QVariantMap mInfo;
463  };
464 
470  struct CORE_EXPORT SpatialIndexOptions
471  {
474  };
475 
480  {
481  CreateVectorTable = 1 << 1,
482  DropRasterTable = 1 << 2,
483  DropVectorTable = 1 << 3,
484  RenameVectorTable = 1 << 4,
485  RenameRasterTable = 1 << 5,
486  CreateSchema = 1 << 6,
487  DropSchema = 1 << 7,
488  RenameSchema = 1 << 8,
489  ExecuteSql = 1 << 9,
490  Vacuum = 1 << 10,
491  Tables = 1 << 11,
492  Schemas = 1 << 12,
493  SqlLayers = 1 << 13,
494  TableExists = 1 << 14,
495  Spatial = 1 << 15,
496  CreateSpatialIndex = 1 << 16,
497  SpatialIndexExists = 1 << 17,
498  DeleteSpatialIndex = 1 << 18,
499  DeleteField = 1 << 19,
500  DeleteFieldCascade = 1 << 20,
501  AddField = 1 << 21,
502  ListFieldDomains = 1 << 22,
503  RetrieveFieldDomain = 1 << 23,
504  SetFieldDomain = 1 << 24,
505  AddFieldDomain = 1 << 25,
506  };
507  Q_ENUM( Capability )
508  Q_DECLARE_FLAGS( Capabilities, Capability )
509  Q_FLAG( Capabilities )
510 
511 
517  {
518  Z = 1 << 1,
519  M = 1 << 2,
520  SinglePart = 1 << 3,
521  Curves = 1 << 4
522  };
523 
524  Q_ENUM( GeometryColumnCapability )
525  Q_DECLARE_FLAGS( GeometryColumnCapabilities, GeometryColumnCapability )
526  Q_FLAG( GeometryColumnCapabilities )
527 
528 
533  QgsAbstractDatabaseProviderConnection( const QString &name );
534 
541  QgsAbstractDatabaseProviderConnection( const QString &uri, const QVariantMap &configuration );
542 
543 
544  // Public interface
545 
549  Capabilities capabilities() const;
550 
556  virtual GeometryColumnCapabilities geometryColumnCapabilities();
557 
562  virtual Qgis::SqlLayerDefinitionCapabilities sqlLayerDefinitionCapabilities();
563 
564  // Operations interface
565 
572  virtual QString tableUri( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
573 
579  virtual void createVectorTable( const QString &schema, const QString &name, const QgsFields &fields, QgsWkbTypes::Type wkbType, const QgsCoordinateReferenceSystem &srs, bool overwrite, const QMap<QString, QVariant> *options ) const SIP_THROW( QgsProviderConnectionException );
580 
586  virtual bool tableExists( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
587 
594  virtual void dropVectorTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
595 
602  virtual void dropRasterTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
603 
610  virtual void renameVectorTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
611 
618  virtual void renameRasterTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
619 
625  virtual void createSchema( const QString &name ) const SIP_THROW( QgsProviderConnectionException );
626 
635  virtual void dropSchema( const QString &name, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
636 
648  virtual void deleteField( const QString &fieldName, const QString &schema, const QString &tableName, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
649 
660  virtual void addField( const QgsField &field, const QString &schema, const QString &tableName ) const SIP_THROW( QgsProviderConnectionException );
661 
668  virtual void renameSchema( const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
669 
676  virtual QList<QList<QVariant>> executeSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
677 
683  virtual QgsVectorLayer *createSqlVectorLayer( const SqlVectorLayerOptions &options ) const SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;
684 
692  virtual SqlVectorLayerOptions sqlOptions( const QString &layerSource ) SIP_THROW( QgsProviderConnectionException );
693 
701  virtual QueryResult execSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
702 
708  virtual void vacuum( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
709 
718  virtual void createSpatialIndex( const QString &schema, const QString &name, const QgsAbstractDatabaseProviderConnection::SpatialIndexOptions &options = QgsAbstractDatabaseProviderConnection::SpatialIndexOptions() ) const SIP_THROW( QgsProviderConnectionException );
719 
727  virtual bool spatialIndexExists( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
728 
736  virtual void deleteSpatialIndex( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
737 
746  virtual QList<QgsAbstractDatabaseProviderConnection::TableProperty> tables( const QString &schema = QString(), const QgsAbstractDatabaseProviderConnection::TableFlags &flags = QgsAbstractDatabaseProviderConnection::TableFlags() ) const SIP_SKIP;
747 
755  virtual QgsAbstractDatabaseProviderConnection::TableProperty table( const QString &schema, const QString &table ) const SIP_THROW( QgsProviderConnectionException );
756 
764  QList<QgsAbstractDatabaseProviderConnection::TableProperty> tablesInt( const QString &schema = QString(), const int flags = 0 ) const SIP_THROW( QgsProviderConnectionException ) SIP_PYNAME( tables );
765 
766 
767  // TODO: return more schema information and not just the name
768 
774  virtual QStringList schemas() const SIP_THROW( QgsProviderConnectionException );
775 
786  virtual QgsFields fields( const QString &schema, const QString &table ) const SIP_THROW( QgsProviderConnectionException );
787 
794  virtual QList< QgsVectorDataProvider::NativeType > nativeTypes() const SIP_THROW( QgsProviderConnectionException ) = 0;
795 
801  QString providerKey() const;
802 
812  virtual QMultiMap<Qgis::SqlKeywordCategory, QStringList> sqlDictionary();
813 
824  virtual QStringList fieldDomainNames() const SIP_THROW( QgsProviderConnectionException );
825 
838  virtual QgsFieldDomain *fieldDomain( const QString &name ) const SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;
839 
851  virtual void setFieldDomainName( const QString &fieldName, const QString &schema, const QString &tableName, const QString &domainName ) const SIP_THROW( QgsProviderConnectionException );
852 
862  virtual void addFieldDomain( const QgsFieldDomain &domain, const QString &schema ) const SIP_THROW( QgsProviderConnectionException );
863 
864  protected:
865 
867 
873  void checkCapability( Capability capability ) const;
875 
876  Capabilities mCapabilities = Capabilities() SIP_SKIP;
877  GeometryColumnCapabilities mGeometryColumnCapabilities = GeometryColumnCapabilities() SIP_SKIP;
878  Qgis::SqlLayerDefinitionCapabilities mSqlLayerDefinitionCapabilities = Qgis::SqlLayerDefinitionCapabilities() SIP_SKIP;
879  QString mProviderKey;
880 
881 };
882 
884 
885 #endif // QGSABSTRACTDATABASEPROVIDERCONNECTION_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:72
The QgsAbstractDatabaseProviderConnection class provides common functionality for DB based connection...
GeometryColumnCapability
The GeometryColumnCapability enum represents the geomery column features supported by the connection.
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:45
Base class for field domains.
Encapsulate a field in an attribute table or data source.
Definition: qgsfield.h:51
Container of fields for a vector layer.
Definition: qgsfields.h:45
Custom exception class for provider connection related exceptions.
Definition: qgsexception.h:101
This is the base class for vector data providers.
Represents a vector layer which manages a vector based data sets.
Type
The WKB type describes the number of dimensions a geometry has.
Definition: qgswkbtypes.h:70
static QString displayString(Type type) SIP_HOLDGIL
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:37
#define SIP_THROW(name)
Definition: qgis_sip.h:198
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_PYNAME(name)
Definition: qgis_sip.h:81
#define SIP_FACTORY
Definition: qgis_sip.h:76
bool operator==(const QgsFeatureIterator &fi1, const QgsFeatureIterator &fi2)
const QgsField & field
Definition: qgsfield.h:463
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsField::ConfigurationFlags) CORE_EXPORT QDataStream &operator<<(QDataStream &out
Writes the field to stream out. QGIS version compatibility is not guaranteed.
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.