QGIS API Documentation 3.99.0-Master (c637e42516f)
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
47{
48
49 Q_GADGET
50
51 public:
52
60 {
61 Aspatial = 1 << 1,
62 Vector = 1 << 2,
63 Raster = 1 << 3,
64 View = 1 << 4,
65 MaterializedView = 1 << 5,
66 Foreign = 1 << 6,
67 IncludeSystemTables = 1 << 7,
68 };
69
70 Q_ENUM( TableFlag )
71 Q_DECLARE_FLAGS( TableFlags, TableFlag )
72 Q_FLAG( TableFlags )
73
86 struct CORE_EXPORT QueryResult
87 {
88
92 QStringList columns() const;
93
101 QList<QList<QVariant> > rows( QgsFeedback *feedback = nullptr );
102
109 bool hasNextRow() const;
110
117 QList<QVariant> nextRow() const;
118
124 long long fetchedRowCount( ) const;
125
131 long long rowCount( ) const;
132
133
134#ifdef SIP_RUN
135 // Python iterator
136 QueryResult *__iter__();
137 % MethodCode
138 sipRes = sipCpp;
139 % End
140
141 SIP_PYOBJECT __next__();
142 % MethodCode
143 QList<QVariant> result;
144 Py_BEGIN_ALLOW_THREADS
145 result = sipCpp->nextRow( );
146 Py_END_ALLOW_THREADS
147 if ( ! result.isEmpty() )
148 {
149 const sipTypeDef *qvariantlist_type = sipFindType( "QList<QVariant>" );
150 sipRes = sipConvertFromNewType( new QList<QVariant>( result ), qvariantlist_type, Py_None );
151 }
152 else
153 {
154 PyErr_SetString( PyExc_StopIteration, "" );
155 }
156 % End
157#endif
158
160
166 struct CORE_EXPORT QueryResultIterator SIP_SKIP
167 {
169 QVariantList nextRow();
170
172 bool hasNextRow() const;
173
175 long long fetchedRowCount();
176
178 long long rowCount();
179
180 virtual ~QueryResultIterator() = default;
181
182 private:
183
184 virtual QVariantList nextRowPrivate() = 0;
185 virtual bool hasNextRowPrivate() const = 0;
186 virtual long long rowCountPrivate() const = 0;
187
188 mutable qlonglong mFetchedRowCount = 0;
189 mutable QMutex mMutex;
190
191 };
192
198 void appendColumn( const QString &columnName ) SIP_SKIP;
199
205 QueryResult( std::shared_ptr<QueryResultIterator> iterator ) SIP_SKIP;
206
211 QueryResult( ) = default SIP_SKIP;
212
216 double queryExecutionTime( ) const;
217
221 void setQueryExecutionTime( double queryExecutionTime );
222
224
225 private:
226
227 mutable std::shared_ptr<QueryResultIterator> mResultIterator;
228 QStringList mColumns;
230 double mQueryExecutionTime = 0;
231
232 };
233
240 struct CORE_EXPORT SqlVectorLayerOptions
241 {
243 QString sql;
245 QString filter;
247 QString layerName;
249 QStringList primaryKeyColumns;
253 bool disableSelectAtId = false;
254
255 };
256
268 struct CORE_EXPORT TableProperty
269 {
270
271#ifdef SIP_RUN
272 SIP_PYOBJECT __repr__();
273 % MethodCode
274 QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty: '%1'>" ).arg( sipCpp->tableName() );
275 sipRes = PyUnicode_FromString( str.toUtf8().constData() );
276 % End
277#endif
278
283 struct CORE_EXPORT GeometryColumnType
284 {
285#ifdef SIP_RUN
286 SIP_PYOBJECT __repr__();
287 % MethodCode
288 QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType: '%1, %2'>" ).arg( QgsWkbTypes::displayString( sipCpp->wkbType ), sipCpp->crs.authid() );
289 sipRes = PyUnicode_FromString( str.toUtf8().constData() );
290 % End
291#endif
294
295 // TODO c++20 - replace with = default
296 inline bool operator==( const GeometryColumnType &other ) const
297 {
298 return this->crs == other.crs && this->wkbType == other.wkbType;
299 }
300 };
301
302 public:
303
309 QString tableName() const;
310
316 void setTableName( const QString &name );
317
321 void addGeometryColumnType( Qgis::WkbType type, const QgsCoordinateReferenceSystem &crs );
322
328 QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> geometryColumnTypes() const;
329
333 void setGeometryColumnTypes( const QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> &geometryColumnTypes );
334
342 QString defaultName() const;
343
348 TableProperty at( int index ) const;
349
353 QString schema() const;
354
358 void setSchema( const QString &schema );
359
363 QString geometryColumn() const;
364
368 void setGeometryColumn( const QString &geometryColumn );
369
373 QStringList primaryKeyColumns() const;
374
378 void setPrimaryKeyColumns( const QStringList &primaryKeyColumns );
379
383 QList<QgsCoordinateReferenceSystem> crsList() const;
384
388 TableFlags flags() const;
389
393 void setFlags( const TableFlags &flags );
394
398 QString comment() const;
399
403 void setComment( const QString &comment );
404
411 QVariantMap info() const;
412
419 void setInfo( const QVariantMap &info );
420
426 int geometryColumnCount() const;
427
431 void setGeometryColumnCount( int geometryColumnCount );
432
436 void setFlag( const TableFlag &flag );
437
444 int maxCoordinateDimensions() const;
445
447
448 private:
449
451 QList<GeometryColumnType> mGeometryColumnTypes;
453 QString mSchema;
455 QString mTableName;
457 QString mGeometryColumn;
459 int mGeometryColumnCount;
461 QStringList mPkColumns;
462 TableFlags mFlags;
463 QString mComment;
465 QVariantMap mInfo;
466 };
467
473 struct CORE_EXPORT SpatialIndexOptions
474 {
477 };
478
485 {
486 CreateVectorTable = 1 << 1,
487 DropRasterTable = 1 << 2,
488 DropVectorTable = 1 << 3,
489 RenameVectorTable = 1 << 4,
490 RenameRasterTable = 1 << 5,
491 CreateSchema = 1 << 6,
492 DropSchema = 1 << 7,
493 RenameSchema = 1 << 8,
494 ExecuteSql = 1 << 9,
495 Vacuum = 1 << 10,
496 Tables = 1 << 11,
497 Schemas = 1 << 12,
498 SqlLayers = 1 << 13,
499 TableExists = 1 << 14,
500 Spatial = 1 << 15,
501 CreateSpatialIndex = 1 << 16,
502 SpatialIndexExists = 1 << 17,
503 DeleteSpatialIndex = 1 << 18,
504 DeleteField = 1 << 19,
505 DeleteFieldCascade = 1 << 20,
506 AddField = 1 << 21,
507 ListFieldDomains = 1 << 22,
508 RetrieveFieldDomain = 1 << 23,
509 SetFieldDomain = 1 << 24,
510 AddFieldDomain = 1 << 25,
511 RenameField = 1 << 26,
512 RetrieveRelationships = 1 << 27,
513 AddRelationship = 1 << 28,
514 UpdateRelationship = 1 << 29,
515 DeleteRelationship = 1 << 30,
516 MoveTableToSchema = 1u << 31,
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 PolyhedralSurfaces = 1 << 8,
537 };
538 // TODO QGIS 4.0 -- remove SinglePart
539
540 Q_ENUM( GeometryColumnCapability )
543
549 QgsAbstractDatabaseProviderConnection( const QString &name );
550
557 QgsAbstractDatabaseProviderConnection( const QString &uri, const QVariantMap &configuration );
558
559
560 // Public interface
561
567 Capabilities capabilities() const;
568
575 Qgis::DatabaseProviderConnectionCapabilities2 capabilities2() const;
576
582 virtual GeometryColumnCapabilities geometryColumnCapabilities();
583
589 virtual Qgis::DatabaseProviderTableImportCapabilities tableImportCapabilities() const = 0;
590
595 virtual Qgis::SqlLayerDefinitionCapabilities sqlLayerDefinitionCapabilities();
596
597 // Operations interface
598
605 virtual QString tableUri( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
606
612 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 );
613
620 struct CORE_EXPORT VectorLayerExporterOptions
621 {
623 QString layerName;
624
626 QString schema;
627
630
632 QStringList primaryKeyColumns;
633
636
637 };
638
648 virtual QString createVectorLayerExporterDestinationUri( const QgsAbstractDatabaseProviderConnection::VectorLayerExporterOptions &options, QVariantMap &providerOptions SIP_OUT ) const SIP_THROW( QgsProviderConnectionException );
649
655 virtual bool tableExists( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
656
663 virtual void dropVectorTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
664
671 virtual void dropRasterTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
672
679 virtual void renameVectorTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
680
687 virtual void renameRasterTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
688
694 virtual void createSchema( const QString &name ) const SIP_THROW( QgsProviderConnectionException );
695
704 virtual void dropSchema( const QString &name, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
705
717 virtual void deleteField( const QString &fieldName, const QString &schema, const QString &tableName, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
718
729 virtual void addField( const QgsField &field, const QString &schema, const QString &tableName ) const SIP_THROW( QgsProviderConnectionException );
730
744 virtual void renameField( const QString &schema, const QString &tableName, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
745
752 virtual void renameSchema( const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
753
760 virtual QList<QList<QVariant>> executeSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
761
773 virtual QgsVectorLayer *createSqlVectorLayer( const SqlVectorLayerOptions &options ) const SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;
774
790 virtual bool validateSqlVectorLayer( const SqlVectorLayerOptions &options, QString &message SIP_OUT ) const SIP_THROW( QgsProviderConnectionException );
791
799 virtual SqlVectorLayerOptions sqlOptions( const QString &layerSource ) SIP_THROW( QgsProviderConnectionException );
800
808 virtual QueryResult execSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
809
815 virtual void vacuum( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
816
825 virtual void createSpatialIndex( const QString &schema, const QString &name, const QgsAbstractDatabaseProviderConnection::SpatialIndexOptions &options = QgsAbstractDatabaseProviderConnection::SpatialIndexOptions() ) const SIP_THROW( QgsProviderConnectionException );
826
834 virtual bool spatialIndexExists( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
835
843 virtual void deleteSpatialIndex( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
844
854 virtual QList<QgsAbstractDatabaseProviderConnection::TableProperty> tables( const QString &schema = QString(), const QgsAbstractDatabaseProviderConnection::TableFlags &flags = QgsAbstractDatabaseProviderConnection::TableFlags(), QgsFeedback *feedback = nullptr ) const SIP_SKIP;
855
865 virtual QgsAbstractDatabaseProviderConnection::TableProperty table( const QString &schema, const QString &table, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
866
874 QList<QgsAbstractDatabaseProviderConnection::TableProperty> tablesInt( const QString &schema = QString(), const int flags = 0 ) const SIP_THROW( QgsProviderConnectionException ) SIP_PYNAME( tables );
875
876
877 // TODO: return more schema information and not just the name
878
884 virtual QStringList schemas() const SIP_THROW( QgsProviderConnectionException );
885
898 virtual QgsFields fields( const QString &schema, const QString &table, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
899
906 virtual QList< QgsVectorDataProvider::NativeType > nativeTypes() const SIP_THROW( QgsProviderConnectionException ) = 0;
907
913 QString providerKey() const;
914
924 virtual QMultiMap<Qgis::SqlKeywordCategory, QStringList> sqlDictionary();
925
932 virtual QSet< QString > illegalFieldNames() const;
933
943 virtual QString defaultPrimaryKeyColumnName() const;
944
954 virtual QString defaultGeometryColumnName() const;
955
966 virtual QStringList fieldDomainNames() const SIP_THROW( QgsProviderConnectionException );
967
973 virtual QList< Qgis::FieldDomainType > supportedFieldDomainTypes() const;
974
987 virtual QgsFieldDomain *fieldDomain( const QString &name ) const SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;
988
1000 virtual void setFieldDomainName( const QString &fieldName, const QString &schema, const QString &tableName, const QString &domainName ) const SIP_THROW( QgsProviderConnectionException );
1001
1011 virtual void addFieldDomain( const QgsFieldDomain &domain, const QString &schema ) const SIP_THROW( QgsProviderConnectionException );
1012
1024 virtual void setFieldAlias( const QString &fieldName, const QString &schema, const QString &tableName, const QString &alias ) const SIP_THROW( QgsProviderConnectionException );
1025
1036 virtual void setTableComment( const QString &schema, const QString &tableName, const QString &comment ) const SIP_THROW( QgsProviderConnectionException );
1037
1049 virtual void setFieldComment( const QString &fieldName, const QString &schema, const QString &tableName, const QString &comment ) const SIP_THROW( QgsProviderConnectionException );
1050
1061 virtual void moveTableToSchema( const QString &sourceSchema, const QString &tableName, const QString &targetSchema ) const SIP_THROW( QgsProviderConnectionException );
1062
1063
1069#ifndef SIP_RUN
1070 virtual QList< Qgis::RelationshipCardinality > supportedRelationshipCardinalities() const;
1071#else
1072 SIP_PYOBJECT supportedRelationshipCardinalities() const SIP_TYPEHINT( List[Qgis.RelationshipCardinality] );
1073 % MethodCode
1074 // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
1075
1076 const QList< Qgis::RelationshipCardinality > cppRes = sipCpp->supportedRelationshipCardinalities();
1077
1078 PyObject *l = PyList_New( cppRes.size() );
1079
1080 if ( !l )
1081 sipIsErr = 1;
1082 else
1083 {
1084 for ( int i = 0; i < cppRes.size(); ++i )
1085 {
1086 PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
1087 sipType_Qgis_RelationshipCardinality );
1088
1089 if ( !eobj )
1090 {
1091 sipIsErr = 1;
1092 }
1093
1094 PyList_SetItem( l, i, eobj );
1095 }
1096
1097 if ( !sipIsErr )
1098 {
1099 sipRes = l;
1100 }
1101 else
1102 {
1103 Py_DECREF( l );
1104 }
1105 }
1106 % End
1107#endif
1108
1114#ifndef SIP_RUN
1115 virtual QList< Qgis::RelationshipStrength > supportedRelationshipStrengths() const;
1116#else
1117 SIP_PYOBJECT supportedRelationshipStrengths() const SIP_TYPEHINT( List[Qgis.RelationshipStrength] );
1118 % MethodCode
1119 // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
1120
1121 const QList< Qgis::RelationshipStrength > cppRes = sipCpp->supportedRelationshipStrengths();
1122
1123 PyObject *l = PyList_New( cppRes.size() );
1124
1125 if ( !l )
1126 sipIsErr = 1;
1127 else
1128 {
1129 for ( int i = 0; i < cppRes.size(); ++i )
1130 {
1131 PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
1132 sipType_Qgis_RelationshipStrength );
1133
1134 if ( !eobj )
1135 {
1136 sipIsErr = 1;
1137 }
1138
1139 PyList_SetItem( l, i, eobj );
1140 }
1141
1142 if ( !sipIsErr )
1143 {
1144 sipRes = l;
1145 }
1146 else
1147 {
1148 Py_DECREF( l );
1149 }
1150 }
1151 % End
1152#endif
1153
1159 virtual Qgis::RelationshipCapabilities supportedRelationshipCapabilities() const;
1160
1171 virtual QStringList relatedTableTypes() const;
1172
1185 virtual QList< QgsWeakRelation > relationships( const QString &schema = QString(), const QString &tableName = QString() ) const SIP_THROW( QgsProviderConnectionException );
1186
1193 virtual void addRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );
1194
1201 virtual void updateRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );
1202
1209 virtual void deleteRelationship( const QgsWeakRelation &relationship ) const SIP_THROW( QgsProviderConnectionException );
1210
1218 virtual QgsProviderSqlQueryBuilder *queryBuilder() const SIP_FACTORY;
1219
1240 virtual QList<QgsLayerMetadataProviderResult> searchLayerMetadata( const QgsMetadataSearchContext &searchContext, const QString &searchString = QString(), const QgsRectangle &geographicExtent = QgsRectangle(), QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException, QgsNotSupportedException );
1241
1242 protected:
1243
1245
1251 void checkCapability( Capability capability ) const;
1252
1258 void checkCapability( Qgis::DatabaseProviderConnectionCapability2 capability ) const;
1259
1261 QString sanitizeSqlForQueryLayer( const QString &sql ) const SIP_SKIP;
1262
1264
1266 Qgis::DatabaseProviderConnectionCapabilities2 mCapabilities2 = Qgis::DatabaseProviderConnectionCapabilities2() SIP_SKIP;
1267
1269 Qgis::SqlLayerDefinitionCapabilities mSqlLayerDefinitionCapabilities = Qgis::SqlLayerDefinitionCapabilities() SIP_SKIP;
1270 QString mProviderKey;
1271 QSet<QString> mIllegalFieldNames SIP_SKIP;
1272
1273};
1274
1276
1277#endif // QGSABSTRACTDATABASEPROVIDERCONNECTION_H
Provides global constants and enumerations for use throughout the application.
Definition qgis.h:54
QFlags< RelationshipCapability > RelationshipCapabilities
Relationship capabilities.
Definition qgis.h:4343
WkbType
The WKB type describes the number of dimensions a geometry has.
Definition qgis.h:256
@ NoGeometry
No geometry.
Provides common functionality for database based connections.
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.
An interface for data provider connections.
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:46
Result record of layer metadata provider search.
Custom exception class which is raised when an operation is not supported.
Custom exception class for provider connection related exceptions.
Provides an interface for provider-specific creation of SQL queries.
A rectangle specified with double values.
Base class for vector data providers.
Represents a vector layer which manages a vector based dataset.
Represent a QgsRelation with possibly unresolved layers or unmatched fields.
static Q_INVOKABLE 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 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_OUT
Definition qgis_sip.h:58
#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.
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.
Stores all information required to create a QgsVectorLayerExporter for the backend.
QStringList primaryKeyColumns
List of primary key column names. Note that some providers may ignore this if not supported.
QString schema
Optional schema for the new layer. May not be supported by all providers.
QString geometryColumn
Preferred name for the geometry column, if required. Note that some providers may ignore this if a sp...