Branch data Line data Source code
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 : :
19 : : #include "qgsabstractproviderconnection.h"
20 : : #include "qgscoordinatereferencesystem.h"
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 : :
30 : : /**
31 : : * \brief The QgsAbstractDatabaseProviderConnection class provides common functionality
32 : : * for DB based connections.
33 : : *
34 : : * This class performs low level DB operations without asking
35 : : * the user for confirmation or handling currently opened layers and the registry
36 : : * entries, it is responsibility of the client code to keep layers in sync.
37 : : * The class methods will throw exceptions in case the requested operation
38 : : * is not supported or cannot be performed without errors.
39 : : *
40 : : * \ingroup core
41 : : * \since QGIS 3.10
42 : : */
43 : 0 : class CORE_EXPORT QgsAbstractDatabaseProviderConnection : public QgsAbstractProviderConnection
44 : : {
45 : :
46 : : Q_GADGET
47 : :
48 : : public:
49 : :
50 : : /**
51 : : * Flags for table properties.
52 : : *
53 : : * Flags can be useful for filtering the tables returned
54 : : * from tables().
55 : : */
56 : : enum TableFlag
57 : : {
58 : : Aspatial = 1 << 1, //!< Aspatial table (it does not contain any geometry column)
59 : : Vector = 1 << 2, //!< Vector table (it does contain one geometry column)
60 : : Raster = 1 << 3, //!< Raster table
61 : : View = 1 << 4, //!< View table
62 : : MaterializedView = 1 << 5, //!< Materialized view table
63 : : Foreign = 1 << 6, //!< Foreign data wrapper
64 : : };
65 : :
66 : : Q_ENUM( TableFlag )
67 : : Q_DECLARE_FLAGS( TableFlags, TableFlag )
68 : : Q_FLAG( TableFlags )
69 : :
70 : : /**
71 : : * The QueryResult class represents the result of a query executed by execSql()
72 : : *
73 : : * It encapsulates an iterator over the result rows and a list of the column names.
74 : : *
75 : : * Rows can be retrieved by iterating over the result with hasNextRow() and nextRow()
76 : : * or by calling rows() that will internally iterate over the results and return
77 : : * the whole result list.
78 : : *
79 : : *
80 : : * \since QGIS 3.18
81 : : */
82 : 0 : struct CORE_EXPORT QueryResult
83 : : {
84 : :
85 : : /**
86 : : * Returns the column names
87 : : */
88 : : QStringList columns() const;
89 : :
90 : : /**
91 : : * Returns the result rows by calling the iterator internally and fetching
92 : : * all the rows, an optional \a feedback can be used to interrupt the fetching loop.
93 : : *
94 : : * \note calling this function more than one time is not supported: the second
95 : : * call will always return an empty list.
96 : : */
97 : : QList<QList<QVariant> > rows( QgsFeedback *feedback = nullptr );
98 : :
99 : : /**
100 : : * Returns TRUE if there are more rows to fetch
101 : : *
102 : : * \see nextRow()
103 : : * \see rewind()
104 : : */
105 : : bool hasNextRow() const;
106 : :
107 : : /**
108 : : * Returns the next result row or an empty row if there are no rows left
109 : : *
110 : : * \see hasNextRow()
111 : : * \see rewind()
112 : : */
113 : : QList<QVariant> nextRow() const;
114 : :
115 : : /**
116 : : * Returns the number of fetched rows
117 : : *
118 : : * \see rowCount()
119 : : */
120 : : qlonglong fetchedRowCount( ) const;
121 : :
122 : :
123 : : #ifdef SIP_RUN
124 : : // Python iterator
125 : : QueryResult *__iter__();
126 : : % MethodCode
127 : : sipRes = sipCpp;
128 : : % End
129 : :
130 : : SIP_PYOBJECT __next__();
131 : : % MethodCode
132 : : QList<QVariant> result;
133 : : Py_BEGIN_ALLOW_THREADS
134 : : result = sipCpp->nextRow( );
135 : : Py_END_ALLOW_THREADS
136 : : if ( ! result.isEmpty() )
137 : : {
138 : : const sipTypeDef *qvariantlist_type = sipFindType( "QList<QVariant>" );
139 : : sipRes = sipConvertFromNewType( new QList<QVariant>( result ), qvariantlist_type, Py_None );
140 : : }
141 : : else
142 : : {
143 : : PyErr_SetString( PyExc_StopIteration, "" );
144 : : }
145 : : % End
146 : : #endif
147 : :
148 : : ///@cond private
149 : :
150 : : /**
151 : : * The QueryResultIterator struct is an abstract interface for provider query result iterators.
152 : : * Providers must implement their own concrete iterator over query results.
153 : : *
154 : : */
155 : 0 : struct CORE_EXPORT QueryResultIterator SIP_SKIP
156 : : {
157 : : QVariantList nextRow();
158 : : bool hasNextRow() const;
159 : : qlonglong fetchedRowCount();
160 : 0 : virtual ~QueryResultIterator() = default;
161 : :
162 : : private:
163 : :
164 : : virtual QVariantList nextRowPrivate() = 0;
165 : : virtual bool hasNextRowPrivate() const = 0;
166 : 0 : mutable qlonglong mFetchedRowCount = 0;
167 : : mutable QMutex mMutex;
168 : :
169 : : };
170 : :
171 : : /**
172 : : * Appends \a columnName to the list of column names.
173 : : * \note Not available in Python bindings
174 : : */
175 : : void appendColumn( const QString &columnName ) SIP_SKIP;
176 : :
177 : : /**
178 : : * Constructs a QueryResult object from an \a iterator
179 : : * \note Not available in Python bindings
180 : : */
181 : : QueryResult( std::shared_ptr<QueryResultIterator> iterator ) SIP_SKIP;
182 : :
183 : : /**
184 : : * Default constructor, used to return empty results
185 : : * \note Not available in Python bindings
186 : : */
187 : 0 : QueryResult( ) = default SIP_SKIP;
188 : :
189 : : ///@endcond private
190 : :
191 : : private:
192 : :
193 : : mutable std::shared_ptr<QueryResultIterator> mResultIterator;
194 : : QStringList mColumns;
195 : :
196 : : };
197 : :
198 : :
199 : : /**
200 : : * The TableProperty class represents a database table or view.
201 : : *
202 : : * In case the table is a vector spatial table and it has multiple
203 : : * geometry columns, separate entries for each geometry column must
204 : : * be created.
205 : : *
206 : : * In case the table is a vector spatial table and the geometry column
207 : : * can contain multiple geometry types and/or CRSs, a clone of the property
208 : : * for the individual geometry type/CRS can be retrieved with at(i)
209 : : */
210 : 0 : struct CORE_EXPORT TableProperty
211 : : {
212 : :
213 : : #ifdef SIP_RUN
214 : : SIP_PYOBJECT __repr__();
215 : : % MethodCode
216 : : QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty: '%1'>" ).arg( sipCpp->tableName() );
217 : : sipRes = PyUnicode_FromString( str.toUtf8().constData() );
218 : : % End
219 : : #endif
220 : :
221 : : /**
222 : : * The GeometryColumnType struct represents the combination
223 : : * of geometry type and CRS for the table geometry column.
224 : : */
225 : 0 : struct CORE_EXPORT GeometryColumnType
226 : : {
227 : : #ifdef SIP_RUN
228 : : SIP_PYOBJECT __repr__();
229 : : % MethodCode
230 : : QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType: '%1, %2'>" ).arg( QgsWkbTypes::displayString( sipCpp->wkbType ), sipCpp->crs.authid() );
231 : : sipRes = PyUnicode_FromString( str.toUtf8().constData() );
232 : : % End
233 : : #endif
234 : : QgsWkbTypes::Type wkbType;
235 : : QgsCoordinateReferenceSystem crs;
236 : :
237 : 0 : inline bool operator==( const GeometryColumnType &other ) const
238 : : {
239 : 0 : return this->crs == other.crs && this->wkbType == other.wkbType;
240 : : }
241 : : };
242 : :
243 : : public:
244 : :
245 : : /**
246 : : * Returns the table name
247 : : * \see defaultName()
248 : : */
249 : : QString tableName() const;
250 : :
251 : : /**
252 : : * Sets the table name to \a name
253 : : * \see defaultName()
254 : : */
255 : : void setTableName( const QString &name );
256 : :
257 : : /**
258 : : * Appends the geometry column \a type with the given \a srid to the geometry column types list
259 : : */
260 : : void addGeometryColumnType( const QgsWkbTypes::Type &type, const QgsCoordinateReferenceSystem &crs );
261 : :
262 : : /**
263 : : * Returns the list of geometry column types and CRSs.
264 : : * The method returns a list of GeometryColumnType
265 : : */
266 : : QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> geometryColumnTypes() const;
267 : :
268 : : /**
269 : : * Sets the geometry column types to \a geometryColumnTypes
270 : : */
271 : : void setGeometryColumnTypes( const QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> &geometryColumnTypes );
272 : :
273 : : /**
274 : : * Returns the default name for the table entry
275 : : *
276 : : * It is usually the table name but in case there are multiple geometry
277 : : * columns, the geometry column name is appended to the table name.
278 : : * \see geometryColumnCount()
279 : : */
280 : : QString defaultName() const;
281 : :
282 : : /**
283 : : * Returns the table property corresponding to the geometry type at
284 : : * the given \a index
285 : : */
286 : : TableProperty at( int index ) const;
287 : :
288 : : /**
289 : : * Returns the schema or an empty string for backends that do not support a schema
290 : : */
291 : : QString schema() const;
292 : :
293 : : /**
294 : : * Sets the \a schema
295 : : */
296 : : void setSchema( const QString &schema );
297 : :
298 : : /**
299 : : * Returns the geometry column name
300 : : */
301 : : QString geometryColumn() const;
302 : :
303 : : /**
304 : : * Sets the geometry column name to \a geometryColumn
305 : : */
306 : : void setGeometryColumn( const QString &geometryColumn );
307 : :
308 : : /**
309 : : * Returns the list of primary key column names
310 : : */
311 : : QStringList primaryKeyColumns() const;
312 : :
313 : : /**
314 : : * Sets the primary key column names to \a primaryKeyColumns
315 : : */
316 : : void setPrimaryKeyColumns( const QStringList &primaryKeyColumns );
317 : :
318 : : /**
319 : : * Returns the list of CRSs supported by the geometry column
320 : : */
321 : : QList<QgsCoordinateReferenceSystem> crsList() const;
322 : :
323 : : /**
324 : : * Returns the table flags
325 : : */
326 : : TableFlags flags() const;
327 : :
328 : : /**
329 : : * Sets the table \a flags
330 : : */
331 : : void setFlags( const TableFlags &flags );
332 : :
333 : : /**
334 : : * Returns the table comment
335 : : */
336 : : QString comment() const;
337 : :
338 : : /**
339 : : * Sets the table \a comment
340 : : */
341 : : void setComment( const QString &comment );
342 : :
343 : : /**
344 : : * Returns additional information about the table
345 : : *
346 : : * Provider classes may use this property
347 : : * to store custom bits of information.
348 : : */
349 : : QVariantMap info() const;
350 : :
351 : : /**
352 : : * Sets additional information about the table to \a info
353 : : *
354 : : * Provider classes may use this property
355 : : * to store custom bits of information.
356 : : */
357 : : void setInfo( const QVariantMap &info );
358 : :
359 : : /**
360 : : * Returns the number of geometry columns in the original table this entry refers to
361 : : *
362 : : * This information is used internally to build the \see defaultName()
363 : : */
364 : : int geometryColumnCount() const;
365 : :
366 : : /**
367 : : * Sets the \a geometryColumnCount
368 : : */
369 : : void setGeometryColumnCount( int geometryColumnCount );
370 : :
371 : : /**
372 : : * Sets a \a flag
373 : : */
374 : : void setFlag( const TableFlag &flag );
375 : :
376 : : /**
377 : : * Returns the maximum coordinate dimensions of the geometries of a vector table.
378 : : * This information is calculated from the geometry columns types.
379 : : * \see geometryColumnTypes()
380 : : */
381 : : int maxCoordinateDimensions() const;
382 : :
383 : : bool operator==( const QgsAbstractDatabaseProviderConnection::TableProperty &other ) const;
384 : :
385 : : private:
386 : :
387 : : //! Holds the list of geometry wkb types and srids supported by the table
388 : : QList<GeometryColumnType> mGeometryColumnTypes;
389 : : //! Table schema
390 : : QString mSchema;
391 : : //! Table name
392 : : QString mTableName;
393 : : //! Name of the geometry column
394 : : QString mGeometryColumn;
395 : : //! The number of geometry columns in the table
396 : : int mGeometryColumnCount;
397 : : //! PK columns
398 : : QStringList mPkColumns;
399 : : TableFlags mFlags;
400 : : QString mComment;
401 : : //! Additional unstructured information about the table
402 : : QVariantMap mInfo;
403 : : };
404 : :
405 : : /**
406 : : * The Capability enum represents the operations supported by the connection
407 : : */
408 : : enum Capability
409 : : {
410 : : CreateVectorTable = 1 << 1, //!< Can CREATE a vector (or aspatial) table/layer
411 : : DropRasterTable = 1 << 2, //!< Can DROP a raster table/layer
412 : : DropVectorTable = 1 << 3, //!< Can DROP a vector (or aspatial) table/layer
413 : : RenameVectorTable = 1 << 4, //!< Can RENAME a vector (or aspatial) table/layer
414 : : RenameRasterTable = 1 << 5, //!< Can RENAME a raster table/layer
415 : : CreateSchema = 1 << 6, //!< Can CREATE a schema
416 : : DropSchema = 1 << 7, //!< Can DROP a schema
417 : : RenameSchema = 1 << 8, //!< Can RENAME a schema
418 : : ExecuteSql = 1 << 9, //!< Can execute raw SQL queries (without returning results)
419 : : Vacuum = 1 << 10, //!< Can run vacuum
420 : : Tables = 1 << 11, //!< Can list tables
421 : : Schemas = 1 << 12, //!< Can list schemas (if not set, the connection does not support schemas)
422 : : SqlLayers = 1 << 13, //!< Can create vector layers from SQL SELECT queries
423 : : TableExists = 1 << 14, //!< Can check if table exists
424 : : Spatial = 1 << 15, //!< The connection supports spatial tables
425 : : CreateSpatialIndex = 1 << 16, //!< The connection can create spatial indices
426 : : SpatialIndexExists = 1 << 17, //!< The connection can determine if a spatial index exists
427 : : DeleteSpatialIndex = 1 << 18, //!< The connection can delete spatial indices for tables
428 : : DeleteField = 1 << 19, //!< Can delete an existing field/column
429 : : DeleteFieldCascade = 1 << 20, //!< Can delete an existing field/column with cascade
430 : : AddField = 1 << 21, //!< Can add a new field/column
431 : : };
432 : 0 : Q_ENUM( Capability )
433 : : Q_DECLARE_FLAGS( Capabilities, Capability )
434 : : Q_FLAG( Capabilities )
435 : :
436 : : /**
437 : : * The GeometryColumnCapability enum represents the geomery column features supported by the connection
438 : : * \since QGIS 3.16
439 : : */
440 : : enum GeometryColumnCapability
441 : : {
442 : : Z = 1 << 1, //! Supports Z dimension
443 : : M = 1 << 2, //! Supports M dimension
444 : : SinglePart = 1 << 3, //! Multi and single part types are distinct types
445 : : Curves = 1 << 4 //! Supports curves
446 : : };
447 : :
448 : : Q_ENUM( GeometryColumnCapability )
449 : : Q_DECLARE_FLAGS( GeometryColumnCapabilities, GeometryColumnCapability )
450 : : Q_FLAG( GeometryColumnCapabilities )
451 : :
452 : : /**
453 : : * Creates a new connection with \a name by reading its configuration from the settings.
454 : : * If a connection with this name cannot be found, an empty connection will be returned.
455 : : */
456 : : QgsAbstractDatabaseProviderConnection( const QString &name );
457 : :
458 : : /**
459 : : * Creates a new connection from the given \a uri and \a configuration.
460 : : * The connection is not automatically stored in the settings.
461 : : * \see store()
462 : : */
463 : : QgsAbstractDatabaseProviderConnection( const QString &uri, const QVariantMap &configuration );
464 : :
465 : :
466 : : // Public interface
467 : :
468 : : /**
469 : : * Returns connection capabilities
470 : : */
471 : : Capabilities capabilities() const;
472 : :
473 : : /**
474 : : * Returns connection geomerty column capabilities (Z, M, SinglePart, Curves)
475 : : * \since QGIS 3.16
476 : : */
477 : : virtual GeometryColumnCapabilities geometryColumnCapabilities();
478 : :
479 : : // Operations interface
480 : :
481 : : /**
482 : : * Returns the URI string for the given \a table and \a schema.
483 : : * Raises a QgsProviderConnectionException if any errors are encountered.
484 : : * \throws QgsProviderConnectionException
485 : : * \since QGIS 3.12
486 : : */
487 : : virtual QString tableUri( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
488 : :
489 : : /**
490 : : * Creates an empty table with \a name in the given \a schema (schema is ignored if not supported by the backend).
491 : : * Raises a QgsProviderConnectionException if any errors are encountered.
492 : : * \throws QgsProviderConnectionException
493 : : */
494 : : 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 );
495 : :
496 : : /**
497 : : * Checks whether a table \a name exists in the given \a schema.
498 : : * Raises a QgsProviderConnectionException if any errors are encountered.
499 : : * \throws QgsProviderConnectionException
500 : : */
501 : : virtual bool tableExists( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
502 : :
503 : : /**
504 : : * Drops a vector (or aspatial) table with given \a schema (schema is ignored if not supported by the backend) and \a name.
505 : : * Raises a QgsProviderConnectionException if any errors are encountered.
506 : : * \note it is responsibility of the caller to handle open layers and registry entries.
507 : : * \throws QgsProviderConnectionException
508 : : */
509 : : virtual void dropVectorTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
510 : :
511 : : /**
512 : : * Drops a raster table with given \a schema (schema is ignored if not supported by the backend) and \a name.
513 : : * Raises a QgsProviderConnectionException if any errors are encountered.
514 : : * \note it is responsibility of the caller to handle open layers and registry entries.
515 : : * \throws QgsProviderConnectionException
516 : : */
517 : : virtual void dropRasterTable( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
518 : :
519 : : /**
520 : : * Renames a vector or aspatial table with given \a schema (schema is ignored if not supported by the backend) and \a name.
521 : : * Raises a QgsProviderConnectionException if any errors are encountered.
522 : : * \note it is responsibility of the caller to handle open layers and registry entries.
523 : : * \throws QgsProviderConnectionException
524 : : */
525 : : virtual void renameVectorTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
526 : :
527 : : /**
528 : : * Renames a raster table with given \a schema (schema is ignored if not supported by the backend) and \a name.
529 : : * Raises a QgsProviderConnectionException if any errors are encountered.
530 : : * \note it is responsibility of the caller to handle open layers and registry entries.
531 : : * \throws QgsProviderConnectionException
532 : : */
533 : : virtual void renameRasterTable( const QString &schema, const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
534 : :
535 : : /**
536 : : * Creates a new schema with the specified \a name
537 : : * \throws QgsProviderConnectionException
538 : : */
539 : : virtual void createSchema( const QString &name ) const SIP_THROW( QgsProviderConnectionException );
540 : :
541 : : /**
542 : : * Drops an entire schema with the specified name.
543 : : * Raises a QgsProviderConnectionException if any errors are encountered.
544 : : * \param name name of the schema to be dropped
545 : : * \param force if TRUE, a DROP CASCADE will drop all related objects
546 : : * \note it is responsibility of the caller to handle open layers and registry entries.
547 : : * \throws QgsProviderConnectionException
548 : : */
549 : : virtual void dropSchema( const QString &name, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
550 : :
551 : : /**
552 : : * Deletes the field with the specified name.
553 : : * Raises a QgsProviderConnectionException if any errors are encountered.
554 : : * \param fieldName name of the field to be deleted
555 : : * \param schema name of the schema (schema is ignored if not supported by the backend).
556 : : * \param tableName name of the table
557 : : * \param force if TRUE, a DROP CASCADE will drop all related objects
558 : : * \note it is responsibility of the caller to handle open layers and registry entries.
559 : : * \throws QgsProviderConnectionException
560 : : * \since QGIS 3.16
561 : : */
562 : : virtual void deleteField( const QString &fieldName, const QString &schema, const QString &tableName, bool force = false ) const SIP_THROW( QgsProviderConnectionException );
563 : :
564 : : /**
565 : : * Adds a field
566 : : * Raises a QgsProviderConnectionException if any errors are encountered.
567 : : * \param field specification of the new field
568 : : * \param schema name of the schema (schema is ignored if not supported by the backend).
569 : : * \param tableName name of the table
570 : : * \note it is responsibility of the caller to handle open layers and registry entries.
571 : : * \throws QgsProviderConnectionException
572 : : * \since QGIS 3.16
573 : : */
574 : : virtual void addField( const QgsField &field, const QString &schema, const QString &tableName ) const SIP_THROW( QgsProviderConnectionException );
575 : :
576 : :
577 : : /**
578 : : * Renames a schema with the specified \a name.
579 : : * Raises a QgsProviderConnectionException if any errors are encountered.
580 : : * \note it is responsibility of the caller to handle open layers and registry entries.
581 : : * \throws QgsProviderConnectionException
582 : : */
583 : : virtual void renameSchema( const QString &name, const QString &newName ) const SIP_THROW( QgsProviderConnectionException );
584 : :
585 : : /**
586 : : * Executes raw \a sql and returns the (possibly empty) list of results in a multi-dimensional array, optionally \a feedback can be provided.
587 : : * Raises a QgsProviderConnectionException if any errors are encountered.
588 : : * \see execSql()
589 : : * \throws QgsProviderConnectionException
590 : : */
591 : : virtual QList<QList<QVariant>> executeSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
592 : :
593 : : /**
594 : : * Executes raw \a sql and returns the (possibly empty) query results, optionally \a feedback can be provided.
595 : : * Raises a QgsProviderConnectionException if any errors are encountered.
596 : : * \see executeSql()
597 : : * \throws QgsProviderConnectionException
598 : : * \since QGIS 3.18
599 : : */
600 : : virtual QueryResult execSql( const QString &sql, QgsFeedback *feedback = nullptr ) const SIP_THROW( QgsProviderConnectionException );
601 : :
602 : : /**
603 : : * Vacuum the database table with given \a schema and \a name (schema is ignored if not supported by the backend).
604 : : * Raises a QgsProviderConnectionException if any errors are encountered.
605 : : * \throws QgsProviderConnectionException
606 : : */
607 : : virtual void vacuum( const QString &schema, const QString &name ) const SIP_THROW( QgsProviderConnectionException );
608 : :
609 : : /**
610 : : * Contains extra options relating to spatial index creation.
611 : : *
612 : : * \since QGIS 3.14
613 : : */
614 : : struct CORE_EXPORT SpatialIndexOptions
615 : : {
616 : : //! Specifies the name of the geometry column to create the index for
617 : : QString geometryColumnName;
618 : : };
619 : :
620 : : /**
621 : : * Creates a spatial index for the database table with given \a schema and \a name (schema is ignored if not supported by the backend).
622 : : *
623 : : * The \a options argument can be used to provide extra options controlling the spatial index creation.
624 : : *
625 : : * Raises a QgsProviderConnectionException if any errors are encountered.
626 : : * \throws QgsProviderConnectionException
627 : : * \since QGIS 3.14
628 : : */
629 : : virtual void createSpatialIndex( const QString &schema, const QString &name, const QgsAbstractDatabaseProviderConnection::SpatialIndexOptions &options = QgsAbstractDatabaseProviderConnection::SpatialIndexOptions() ) const SIP_THROW( QgsProviderConnectionException );
630 : :
631 : : /**
632 : : * Determines whether a spatial index exists for the database table with given \a schema, \a name and \a geometryColumn (\a schema and \a geometryColumn are
633 : : * ignored if not supported by the backend).
634 : : *
635 : : * Raises a QgsProviderConnectionException if any errors are encountered.
636 : : * \throws QgsProviderConnectionException
637 : : * \since QGIS 3.14
638 : : */
639 : : virtual bool spatialIndexExists( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
640 : :
641 : : /**
642 : : * Deletes the existing spatial index for the database table with given \a schema, \a name and \a geometryColumn (\a schema and \a geometryColumn are
643 : : * ignored if not supported by the backend).
644 : : *
645 : : * Raises a QgsProviderConnectionException if any errors are encountered.
646 : : * \throws QgsProviderConnectionException
647 : : * \since QGIS 3.14
648 : : */
649 : : virtual void deleteSpatialIndex( const QString &schema, const QString &name, const QString &geometryColumn ) const SIP_THROW( QgsProviderConnectionException );
650 : :
651 : : /**
652 : : * Returns information on the tables in the given schema.
653 : : * Raises a QgsProviderConnectionException if any errors are encountered.
654 : : * \param schema name of the schema (ignored if not supported by the backend)
655 : : * \param flags filter tables by flags, this option completely overrides search options stored in the connection
656 : : * \throws QgsProviderConnectionException
657 : : * \note Not available in Python bindings
658 : : */
659 : : virtual QList<QgsAbstractDatabaseProviderConnection::TableProperty> tables( const QString &schema = QString(), const QgsAbstractDatabaseProviderConnection::TableFlags &flags = QgsAbstractDatabaseProviderConnection::TableFlags() ) const SIP_SKIP;
660 : :
661 : : /**
662 : : * Returns information on a \a table in the given \a schema.
663 : : * Raises a QgsProviderConnectionException if any errors are encountered or if the table does not exist.
664 : : * \throws QgsProviderConnectionException
665 : : * \note Not available in Python bindings
666 : : * \since QGIS 3.12
667 : : */
668 : : virtual QgsAbstractDatabaseProviderConnection::TableProperty table( const QString &schema, const QString &table ) const SIP_THROW( QgsProviderConnectionException );
669 : :
670 : : /**
671 : : * Returns information on the tables in the given schema.
672 : : * Raises a QgsProviderConnectionException if any errors are encountered.
673 : : * \param schema name of the schema (ignored if not supported by the backend)
674 : : * \param flags filter tables by flags, this option completely overrides search options stored in the connection
675 : : * \throws QgsProviderConnectionException
676 : : */
677 : : QList<QgsAbstractDatabaseProviderConnection::TableProperty> tablesInt( const QString &schema = QString(), const int flags = 0 ) const SIP_THROW( QgsProviderConnectionException ) SIP_PYNAME( tables );
678 : :
679 : :
680 : : // TODO: return more schema information and not just the name
681 : :
682 : : /**
683 : : * Returns information about the existing schemas.
684 : : * Raises a QgsProviderConnectionException if any errors are encountered.
685 : : * \throws QgsProviderConnectionException
686 : : */
687 : : virtual QStringList schemas() const SIP_THROW( QgsProviderConnectionException );
688 : :
689 : : /**
690 : : * Returns the fields of a \a table and \a schema.
691 : : * Raises a QgsProviderConnectionException if any errors are encountered.
692 : : * \note the default implementation creates a temporary vector layer, providers may
693 : : * choose to override this method for a greater efficiency.
694 : : * \throws QgsProviderConnectionException
695 : : * \since QGIS 3.16
696 : : */
697 : : virtual QgsFields fields( const QString &schema, const QString &table ) const SIP_THROW( QgsProviderConnectionException );
698 : :
699 : : /**
700 : : * Returns a list of native types supported by the connection.
701 : : * \throws QgsProviderConnectionException
702 : : * \since QGIS 3.16
703 : : */
704 : : virtual QList< QgsVectorDataProvider::NativeType > nativeTypes() const SIP_THROW( QgsProviderConnectionException ) = 0;
705 : :
706 : : /**
707 : : * Returns the provider key
708 : : * \since QGIS 3.16
709 : : */
710 : : QString providerKey() const;
711 : :
712 : : protected:
713 : :
714 : : ///@cond PRIVATE
715 : :
716 : : /**
717 : : * Checks if \a capability is supported and throws and exception if it's not
718 : : * \throws QgsProviderConnectionException
719 : : */
720 : : void checkCapability( Capability capability ) const;
721 : : ///@endcond
722 : :
723 : : Capabilities mCapabilities = Capabilities() SIP_SKIP;
724 : : GeometryColumnCapabilities mGeometryColumnCapabilities = GeometryColumnCapabilities() SIP_SKIP;
725 : : QString mProviderKey;
726 : :
727 : : };
728 : :
729 : : Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAbstractDatabaseProviderConnection::Capabilities )
730 : :
731 : : #endif // QGSABSTRACTDATABASEPROVIDERCONNECTION_H
|
