QGIS API Documentation  3.21.0-Master (56b4176581)
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 
44 {
45 
46  Q_GADGET
47 
48  public:
49 
56  enum TableFlag
57  {
58  Aspatial = 1 << 1,
59  Vector = 1 << 2,
60  Raster = 1 << 3,
61  View = 1 << 4,
62  MaterializedView = 1 << 5,
63  Foreign = 1 << 6,
64  };
65 
66  Q_ENUM( TableFlag )
67  Q_DECLARE_FLAGS( TableFlags, TableFlag )
68  Q_FLAG( TableFlags )
69 
70 
82  struct CORE_EXPORT QueryResult
83  {
84 
88  QStringList columns() const;
89 
97  QList<QList<QVariant> > rows( QgsFeedback *feedback = nullptr );
98 
105  bool hasNextRow() const;
106 
113  QList<QVariant> nextRow() const;
114 
120  long long fetchedRowCount( ) const;
121 
127  long long rowCount( ) const;
128 
129 
130 #ifdef SIP_RUN
131  // Python iterator
132  QueryResult *__iter__();
133  % MethodCode
134  sipRes = sipCpp;
135  % End
136 
137  SIP_PYOBJECT __next__();
138  % MethodCode
139  QList<QVariant> result;
140  Py_BEGIN_ALLOW_THREADS
141  result = sipCpp->nextRow( );
142  Py_END_ALLOW_THREADS
143  if ( ! result.isEmpty() )
144  {
145  const sipTypeDef *qvariantlist_type = sipFindType( "QList<QVariant>" );
146  sipRes = sipConvertFromNewType( new QList<QVariant>( result ), qvariantlist_type, Py_None );
147  }
148  else
149  {
150  PyErr_SetString( PyExc_StopIteration, "" );
151  }
152  % End
153 #endif
154 
156 
162  struct CORE_EXPORT QueryResultIterator SIP_SKIP
163  {
165  QVariantList nextRow();
166 
168  bool hasNextRow() const;
169 
171  long long fetchedRowCount();
172 
174  long long rowCount();
175 
176  virtual ~QueryResultIterator() = default;
177 
178  private:
179 
180  virtual QVariantList nextRowPrivate() = 0;
181  virtual bool hasNextRowPrivate() const = 0;
182  virtual long long rowCountPrivate() const = 0;
183 
184  mutable qlonglong mFetchedRowCount = 0;
185  mutable QMutex mMutex;
186 
187  };
188 
194  void appendColumn( const QString &columnName ) SIP_SKIP;
195 
201  QueryResult( std::shared_ptr<QueryResultIterator> iterator ) SIP_SKIP;
202 
207  QueryResult( ) = default SIP_SKIP;
208 
212  double queryExecutionTime( );
213 
217  void setQueryExecutionTime( double queryExecutionTime );
218 
220 
221  private:
222 
223  mutable std::shared_ptr<QueryResultIterator> mResultIterator;
224  QStringList mColumns;
226  double mQueryExecutionTime = 0;
227 
228  };
229 
236  struct CORE_EXPORT SqlVectorLayerOptions
237  {
239  QString sql;
241  QString filter;
243  QString layerName;
245  QStringList primaryKeyColumns;
247  QString geometryColumn;
249  bool disableSelectAtId = false;
250 
251  };
252 
264  struct CORE_EXPORT TableProperty
265  {
266 
267 #ifdef SIP_RUN
268  SIP_PYOBJECT __repr__();
269  % MethodCode
270  QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty: '%1'>" ).arg( sipCpp->tableName() );
271  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
272  % End
273 #endif
274 
279  struct CORE_EXPORT GeometryColumnType
280  {
281 #ifdef SIP_RUN
282  SIP_PYOBJECT __repr__();
283  % MethodCode
284  QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType: '%1, %2'>" ).arg( QgsWkbTypes::displayString( sipCpp->wkbType ), sipCpp->crs.authid() );
285  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
286  % End
287 #endif
290 
291  // TODO c++20 - replace with = default
292  inline bool operator==( const GeometryColumnType &other ) const
293  {
294  return this->crs == other.crs && this->wkbType == other.wkbType;
295  }
296  };
297 
298  public:
299 
305  QString tableName() const;
306 
312  void setTableName( const QString &name );
313 
317  void addGeometryColumnType( const QgsWkbTypes::Type &type, const QgsCoordinateReferenceSystem &crs );
318 
324  QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> geometryColumnTypes() const;
325 
329  void setGeometryColumnTypes( const QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> &geometryColumnTypes );
330 
338  QString defaultName() const;
339 
344  TableProperty at( int index ) const;
345 
349  QString schema() const;
350 
354  void setSchema( const QString &schema );
355 
359  QString geometryColumn() const;
360 
364  void setGeometryColumn( const QString &geometryColumn );
365 
369  QStringList primaryKeyColumns() const;
370 
374  void setPrimaryKeyColumns( const QStringList &primaryKeyColumns );
375 
379  QList<QgsCoordinateReferenceSystem> crsList() const;
380 
384  TableFlags flags() const;
385 
389  void setFlags( const TableFlags &flags );
390 
394  QString comment() const;
395 
399  void setComment( const QString &comment );
400 
407  QVariantMap info() const;
408 
415  void setInfo( const QVariantMap &info );
416 
422  int geometryColumnCount() const;
423 
427  void setGeometryColumnCount( int geometryColumnCount );
428 
432  void setFlag( const TableFlag &flag );
433 
440  int maxCoordinateDimensions() const;
441 
443 
444  private:
445 
447  QList<GeometryColumnType> mGeometryColumnTypes;
449  QString mSchema;
451  QString mTableName;
453  QString mGeometryColumn;
455  int mGeometryColumnCount;
457  QStringList mPkColumns;
458  TableFlags mFlags;
459  QString mComment;
461  QVariantMap mInfo;
462  };
463 
469  struct CORE_EXPORT SpatialIndexOptions
470  {
473  };
474 
479  {
480  CreateVectorTable = 1 << 1,
481  DropRasterTable = 1 << 2,
482  DropVectorTable = 1 << 3,
483  RenameVectorTable = 1 << 4,
484  RenameRasterTable = 1 << 5,
485  CreateSchema = 1 << 6,
486  DropSchema = 1 << 7,
487  RenameSchema = 1 << 8,
488  ExecuteSql = 1 << 9,
489  Vacuum = 1 << 10,
490  Tables = 1 << 11,
491  Schemas = 1 << 12,
492  SqlLayers = 1 << 13,
493  TableExists = 1 << 14,
494  Spatial = 1 << 15,
495  CreateSpatialIndex = 1 << 16,
496  SpatialIndexExists = 1 << 17,
497  DeleteSpatialIndex = 1 << 18,
498  DeleteField = 1 << 19,
499  DeleteFieldCascade = 1 << 20,
500  AddField = 1 << 21,
501  };
502  Q_ENUM( Capability )
503  Q_DECLARE_FLAGS( Capabilities, Capability )
504  Q_FLAG( Capabilities )
505 
506 
512  {
513  Z = 1 << 1,
514  M = 1 << 2,
515  SinglePart = 1 << 3,
516  Curves = 1 << 4
517  };
518 
519  Q_ENUM( GeometryColumnCapability )
520  Q_DECLARE_FLAGS( GeometryColumnCapabilities, GeometryColumnCapability )
521  Q_FLAG( GeometryColumnCapabilities )
522 
523 
528  QgsAbstractDatabaseProviderConnection( const QString &name );
529 
536  QgsAbstractDatabaseProviderConnection( const QString &uri, const QVariantMap &configuration );
537 
538 
539  // Public interface
540 
544  Capabilities capabilities() const;
545 
551  virtual GeometryColumnCapabilities geometryColumnCapabilities();
552 
557  virtual Qgis::SqlLayerDefinitionCapabilities sqlLayerDefinitionCapabilities();
558 
559  // Operations interface
560 
567  virtual QString tableUri( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
568 
574  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 );
575 
581  virtual bool tableExists( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
582 
589  virtual void dropVectorTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
590 
597  virtual void dropRasterTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
598 
605  virtual void renameVectorTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
606 
613  virtual void renameRasterTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
614 
620  virtual void createSchema( const QString &name ) const SIP_THROW( QgsProviderConnectionException );
621 
630  virtual void dropSchema( const QString &name, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
631 
643  virtual void deleteField( const QString &fieldName, const QString &schema, const QString &tableName, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
644 
655  virtual void addField( const QgsField &field, const QString &schema, const QString &tableName ) const SIP_THROW( QgsProviderConnectionException );
656 
663  virtual void renameSchema( const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
664 
671  virtual QList<QList<QVariant>> executeSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
672 
678  virtual QgsVectorLayer *createSqlVectorLayer( const SqlVectorLayerOptions &options ) const SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;
679 
687  virtual SqlVectorLayerOptions sqlOptions( const QString &layerSource ) SIP_THROW( QgsProviderConnectionException );
688 
696  virtual QueryResult execSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
697 
703  virtual void vacuum( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
704 
713  virtual void createSpatialIndex( const QString &schema, const QString &name, const QgsAbstractDatabaseProviderConnection::SpatialIndexOptions &options = QgsAbstractDatabaseProviderConnection::SpatialIndexOptions() ) const SIP_THROW( QgsProviderConnectionException );
714 
722  virtual bool spatialIndexExists( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
723 
731  virtual void deleteSpatialIndex( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
732 
741  virtual QList<QgsAbstractDatabaseProviderConnection::TableProperty> tables( const QString &schema = QString(), const QgsAbstractDatabaseProviderConnection::TableFlags &flags = QgsAbstractDatabaseProviderConnection::TableFlags() ) const SIP_SKIP;
742 
750  virtual QgsAbstractDatabaseProviderConnection::TableProperty table( const QString &schema, const QString &table ) const SIP_THROW( QgsProviderConnectionException );
751 
759  QList<QgsAbstractDatabaseProviderConnection::TableProperty> tablesInt( const QString &schema = QString(), const int flags = 0 ) const SIP_THROW( QgsProviderConnectionException ) SIP_PYNAME( tables );
760 
761 
762  // TODO: return more schema information and not just the name
763 
769  virtual QStringList schemas() const SIP_THROW( QgsProviderConnectionException );
770 
781  virtual QgsFields fields( const QString &schema, const QString &table ) const SIP_THROW( QgsProviderConnectionException );
782 
789  virtual QList< QgsVectorDataProvider::NativeType > nativeTypes() const SIP_THROW( QgsProviderConnectionException ) = 0;
790 
796  QString providerKey() const;
797 
807  virtual QMultiMap<Qgis::SqlKeywordCategory, QStringList> sqlDictionary();
808 
809  protected:
810 
812 
818  void checkCapability( Capability capability ) const;
820 
821  Capabilities mCapabilities = Capabilities() SIP_SKIP;
822  GeometryColumnCapabilities mGeometryColumnCapabilities = GeometryColumnCapabilities() SIP_SKIP;
823  Qgis::SqlLayerDefinitionCapabilities mSqlLayerDefinitionCapabilities = Qgis::SqlLayerDefinitionCapabilities() SIP_SKIP;
824  QString mProviderKey;
825 
826 };
827 
829 
830 #endif // QGSABSTRACTDATABASEPROVIDERCONNECTION_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:63
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
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:189
#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.