QGIS API Documentation 3.29.0-Master (006c3c0232)
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"
25
26#include <QObject>
27
28class QgsFeedback;
29class QgsFieldDomain;
30class 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
75
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;
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( const QgsWkbTypes::Type &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
484 {
485 CreateVectorTable = 1 << 1,
486 DropRasterTable = 1 << 2,
487 DropVectorTable = 1 << 3,
488 RenameVectorTable = 1 << 4,
489 RenameRasterTable = 1 << 5,
490 CreateSchema = 1 << 6,
491 DropSchema = 1 << 7,
492 RenameSchema = 1 << 8,
493 ExecuteSql = 1 << 9,
494 Vacuum = 1 << 10,
495 Tables = 1 << 11,
496 Schemas = 1 << 12,
497 SqlLayers = 1 << 13,
498 TableExists = 1 << 14,
499 Spatial = 1 << 15,
500 CreateSpatialIndex = 1 << 16,
501 SpatialIndexExists = 1 << 17,
502 DeleteSpatialIndex = 1 << 18,
503 DeleteField = 1 << 19,
504 DeleteFieldCascade = 1 << 20,
505 AddField = 1 << 21,
506 ListFieldDomains = 1 << 22,
507 RetrieveFieldDomain = 1 << 23,
508 SetFieldDomain = 1 << 24,
509 AddFieldDomain = 1 << 25,
510 RenameField = 1 << 26,
511 RetrieveRelationships = 1 << 27,
512 AddRelationship = 1 << 28,
513 UpdateRelationship = 1 << 29,
514 DeleteRelationship = 1 << 30,
515 };
516 Q_ENUM( Capability )
517 Q_DECLARE_FLAGS( Capabilities, Capability )
518 Q_FLAG( Capabilities )
519
520
526 {
527 Z = 1 << 1,
528 M = 1 << 2,
529 SinglePart = 1 << 3,
530 Curves = 1 << 4,
531 SinglePoint = 1 << 5,
532 SingleLineString = 1 << 6,
533 SinglePolygon = 1 << 7,
534 };
535 // TODO QGIS 4.0 -- remove SinglePart
536
537 Q_ENUM( GeometryColumnCapability )
538 Q_DECLARE_FLAGS( GeometryColumnCapabilities, GeometryColumnCapability )
539 Q_FLAG( GeometryColumnCapabilities )
540
541
546 QgsAbstractDatabaseProviderConnection( const QString &name );
547
554 QgsAbstractDatabaseProviderConnection( const QString &uri, const QVariantMap &configuration );
555
556
557 // Public interface
558
562 Capabilities capabilities() const;
563
569 virtual GeometryColumnCapabilities geometryColumnCapabilities();
570
575 virtual Qgis::SqlLayerDefinitionCapabilities sqlLayerDefinitionCapabilities();
576
577 // Operations interface
578
585 virtual QString tableUri( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
586
592 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 );
593
599 virtual bool tableExists( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
600
607 virtual void dropVectorTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
608
615 virtual void dropRasterTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
616
623 virtual void renameVectorTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
624
631 virtual void renameRasterTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
632
638 virtual void createSchema( const QString &name ) const SIP_THROW( QgsProviderConnectionException );
639
648 virtual void dropSchema( const QString &name, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
649
661 virtual void deleteField( const QString &fieldName, const QString &schema, const QString &tableName, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
662
673 virtual void addField( const QgsField &field, const QString &schema, const QString &tableName ) const SIP_THROW( QgsProviderConnectionException );
674
688 virtual void renameField( const QString &schema, const QString &tableName, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
689
696 virtual void renameSchema( const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
697
704 virtual QList<QList<QVariant>> executeSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
705
711 virtual QgsVectorLayer *createSqlVectorLayer( const SqlVectorLayerOptions &options ) const SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;
712
720 virtual SqlVectorLayerOptions sqlOptions( const QString &layerSource ) SIP_THROW( QgsProviderConnectionException );
721
729 virtual QueryResult execSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
730
736 virtual void vacuum( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
737
746 virtual void createSpatialIndex( const QString &schema, const QString &name, const QgsAbstractDatabaseProviderConnection::SpatialIndexOptions &options = QgsAbstractDatabaseProviderConnection::SpatialIndexOptions() ) const SIP_THROW( QgsProviderConnectionException );
747
755 virtual bool spatialIndexExists( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
756
764 virtual void deleteSpatialIndex( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
765
774 virtual QList<QgsAbstractDatabaseProviderConnection::TableProperty> tables( const QString &schema = QString(), const QgsAbstractDatabaseProviderConnection::TableFlags &flags = QgsAbstractDatabaseProviderConnection::TableFlags() ) const SIP_SKIP;
775
783 virtual QgsAbstractDatabaseProviderConnection::TableProperty table( const QString &schema, const QString &table ) const SIP_THROW( QgsProviderConnectionException );
784
792 QList<QgsAbstractDatabaseProviderConnection::TableProperty> tablesInt( const QString &schema = QString(), const int flags = 0 ) const SIP_THROW( QgsProviderConnectionException ) SIP_PYNAME( tables );
793
794
795 // TODO: return more schema information and not just the name
796
802 virtual QStringList schemas() const SIP_THROW( QgsProviderConnectionException );
803
814 virtual QgsFields fields( const QString &schema, const QString &table ) const SIP_THROW( QgsProviderConnectionException );
815
822 virtual QList< QgsVectorDataProvider::NativeType > nativeTypes() const SIP_THROW( QgsProviderConnectionException ) = 0;
823
829 QString providerKey() const;
830
840 virtual QMultiMap<Qgis::SqlKeywordCategory, QStringList> sqlDictionary();
841
848 virtual QSet< QString > illegalFieldNames() const;
849
860 virtual QStringList fieldDomainNames() const SIP_THROW( QgsProviderConnectionException );
861
867 virtual QList< Qgis::FieldDomainType > supportedFieldDomainTypes() const;
868
881 virtual QgsFieldDomain *fieldDomain( const QString &name ) const SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;
882
894 virtual void setFieldDomainName( const QString &fieldName, const QString &schema, const QString &tableName, const QString &domainName ) const SIP_THROW( QgsProviderConnectionException );
895
905 virtual void addFieldDomain( const QgsFieldDomain &domain, const QString &schema ) const SIP_THROW( QgsProviderConnectionException );
906
912#ifndef SIP_RUN
913 virtual QList< Qgis::RelationshipCardinality > supportedRelationshipCardinalities() const;
914#else
915 SIP_PYOBJECT supportedRelationshipCardinalities() const SIP_TYPEHINT( List[Qgis.RelationshipCardinality] );
916 % MethodCode
917 // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
918
919 const QList< Qgis::RelationshipCardinality > cppRes = sipCpp->supportedRelationshipCardinalities();
920
921 PyObject *l = PyList_New( cppRes.size() );
922
923 if ( !l )
924 sipIsErr = 1;
925 else
926 {
927 for ( int i = 0; i < cppRes.size(); ++i )
928 {
929 PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
930 sipType_Qgis_RelationshipCardinality );
931
932 if ( !eobj )
933 {
934 sipIsErr = 1;
935 }
936
937 PyList_SetItem( l, i, eobj );
938 }
939
940 if ( !sipIsErr )
941 {
942 sipRes = l;
943 }
944 else
945 {
946 Py_DECREF( l );
947 }
948 }
949 % End
950#endif
951
957#ifndef SIP_RUN
958 virtual QList< Qgis::RelationshipStrength > supportedRelationshipStrengths() const;
959#else
960 SIP_PYOBJECT supportedRelationshipStrengths() const SIP_TYPEHINT( List[Qgis.RelationshipStrength] );
961 % MethodCode
962 // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
963
964 const QList< Qgis::RelationshipStrength > cppRes = sipCpp->supportedRelationshipStrengths();
965
966 PyObject *l = PyList_New( cppRes.size() );
967
968 if ( !l )
969 sipIsErr = 1;
970 else
971 {
972 for ( int i = 0; i < cppRes.size(); ++i )
973 {
974 PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
975 sipType_Qgis_RelationshipStrength );
976
977 if ( !eobj )
978 {
979 sipIsErr = 1;
980 }
981
982 PyList_SetItem( l, i, eobj );
983 }
984
985 if ( !sipIsErr )
986 {
987 sipRes = l;
988 }
989 else
990 {
991 Py_DECREF( l );
992 }
993 }
994 % End
995#endif
996
1002 virtual Qgis::RelationshipCapabilities supportedRelationshipCapabilities() const;
1003
1016 virtual QList< QgsWeakRelation > relationships( const QString &schema = QString(), const QString &tableName = QString() ) const SIP_THROW( QgsProviderConnectionException );
1017
1024 virtual void addRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );
1025
1032 virtual void updateRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );
1033
1040 virtual void deleteRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );
1041
1049 virtual QgsProviderSqlQueryBuilder *queryBuilder() const SIP_FACTORY;
1050
1071 virtual QList<QgsLayerMetadataProviderResult> searchLayerMetadata( const QgsMetadataSearchContext &searchContext, const QString &searchString = QString(), const QgsRectangle &geographicExtent = QgsRectangle(), QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException, QgsNotSupportedException );
1072
1073 protected:
1074
1076
1082 void checkCapability( Capability capability ) const;
1084
1085 Capabilities mCapabilities = Capabilities() SIP_SKIP;
1086 GeometryColumnCapabilities mGeometryColumnCapabilities = GeometryColumnCapabilities() SIP_SKIP;
1087 Qgis::SqlLayerDefinitionCapabilities mSqlLayerDefinitionCapabilities = Qgis::SqlLayerDefinitionCapabilities() SIP_SKIP;
1088 QString mProviderKey;
1089 QSet<QString> mIllegalFieldNames SIP_SKIP;
1090
1091};
1092
1094
1095#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
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...
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_TYPEHINT(type)
Definition: qgis_sip.h:227
#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
#define SIP_THROW(name,...)
Definition: qgis_sip.h:198
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.
QList< QVariant > nextRow() const
Returns the next result row or an empty row if there are no rows left.
long long rowCount() const
Returns the number of rows returned by a SELECT query or Qgis::FeatureCountState::UnknownCount if unk...
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.