QGIS API Documentation  3.15.0-Master (a49cb7c9f3)
Classes | Public Types | Public Member Functions | Protected Attributes | List of all members
QgsAbstractDatabaseProviderConnection Class Reference

The QgsAbstractDatabaseProviderConnection class provides common functionality for DB based connections. More...

#include <qgsabstractdatabaseproviderconnection.h>

Inheritance diagram for QgsAbstractDatabaseProviderConnection:
Inheritance graph
[legend]

Classes

struct  SpatialIndexOptions
 Contains extra options relating to spatial index creation. More...
 
struct  TableProperty
 The TableProperty class represents a database table or view. More...
 

Public Types

enum  Capability {
  CreateVectorTable = 1 << 1, DropRasterTable = 1 << 2, DropVectorTable = 1 << 3, RenameVectorTable = 1 << 4,
  RenameRasterTable = 1 << 5, CreateSchema = 1 << 6, DropSchema = 1 << 7, RenameSchema = 1 << 8,
  ExecuteSql = 1 << 9, Vacuum = 1 << 10, Tables = 1 << 11, Schemas = 1 << 12,
  SqlLayers = 1 << 13, TableExists = 1 << 14, Spatial = 1 << 15, CreateSpatialIndex = 1 << 16,
  SpatialIndexExists = 1 << 17, DeleteSpatialIndex = 1 << 18, DeleteField = 1 << 19, CreateField = 1 << 20
}
 The Capability enum represent the operations supported by the connection. More...
 
enum  TableFlag {
  Aspatial = 1 << 1, Vector = 1 << 2, Raster = 1 << 3, View = 1 << 4,
  MaterializedView = 1 << 5, Foreign = 1 << 6
}
 Flags for table properties. More...
 

Public Member Functions

 QgsAbstractDatabaseProviderConnection (const QString &name)
 Creates a new connection with name by reading its configuration from the settings. More...
 
 QgsAbstractDatabaseProviderConnection (const QString &uri, const QVariantMap &configuration)
 Creates a new connection from the given uri and configuration. More...
 
Capabilities capabilities () const
 Returns connection capabilities. More...
 
virtual void createSchema (const QString &name) const SIP_THROW(QgsProviderConnectionException)
 Creates a new schema with the specified name. More...
 
virtual void createSpatialIndex (const QString &schema, const QString &name, const QgsAbstractDatabaseProviderConnection::SpatialIndexOptions &options=QgsAbstractDatabaseProviderConnection::SpatialIndexOptions()) const SIP_THROW(QgsProviderConnectionException)
 Creates a spatial index for the database table with given schema and name (schema is ignored if not supported by the backend). More...
 
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)
 Creates an empty table with name in the given schema (schema is ignored if not supported by the backend). More...
 
virtual void deleteSpatialIndex (const QString &schema, const QString &name, const QString &geometryColumn) const SIP_THROW(QgsProviderConnectionException)
 Deletes the existing spatial index for the database table with given schema, name and geometryColumn (schema and geometryColumn are ignored if not supported by the backend). More...
 
virtual void dropRasterTable (const QString &schema, const QString &name) const SIP_THROW(QgsProviderConnectionException)
 Drops a raster table with given schema (schema is ignored if not supported by the backend) and name. More...
 
virtual void dropSchema (const QString &name, bool force=false) const SIP_THROW(QgsProviderConnectionException)
 Drops an entire schema with the specified name. More...
 
virtual void dropVectorTable (const QString &schema, const QString &name) const SIP_THROW(QgsProviderConnectionException)
 Drops a vector (or aspatial) table with given schema (schema is ignored if not supported by the backend) and name. More...
 
virtual QList< QList< QVariant > > executeSql (const QString &sql) const SIP_THROW(QgsProviderConnectionException)
 Executes raw sql and returns the (possibly empty) list of results in a multi-dimensional array. More...
 
virtual QgsFields fields (const QString &schema, const QString &table) const SIP_THROW(QgsProviderConnectionException)
 Returns the fields of a table and schema. More...
 
QString providerKey () const
 Returns the provider key. More...
 
virtual void renameRasterTable (const QString &schema, const QString &name, const QString &newName) const SIP_THROW(QgsProviderConnectionException)
 Renames a raster table with given schema (schema is ignored if not supported by the backend) and name. More...
 
virtual void renameSchema (const QString &name, const QString &newName) const SIP_THROW(QgsProviderConnectionException)
 Renames a schema with the specified name. More...
 
virtual void renameVectorTable (const QString &schema, const QString &name, const QString &newName) const SIP_THROW(QgsProviderConnectionException)
 Renames a vector or aspatial table with given schema (schema is ignored if not supported by the backend) and name. More...
 
virtual QStringList schemas () const SIP_THROW(QgsProviderConnectionException)
 Returns information about the existing schemas. More...
 
virtual bool spatialIndexExists (const QString &schema, const QString &name, const QString &geometryColumn) const SIP_THROW(QgsProviderConnectionException)
 Determines whether a spatial index exists for the database table with given schema, name and geometryColumn (schema and geometryColumn are ignored if not supported by the backend). More...
 
virtual QgsAbstractDatabaseProviderConnection::TableProperty table (const QString &schema, const QString &table) const
 Returns information on a table in the given schema. More...
 
virtual bool tableExists (const QString &schema, const QString &name) const SIP_THROW(QgsProviderConnectionException)
 Checks whether a table name exists in the given schema. More...
 
virtual QList< QgsAbstractDatabaseProviderConnection::TablePropertytables (const QString &schema=QString(), const QgsAbstractDatabaseProviderConnection::TableFlags &flags=nullptr) const
 Returns information on the tables in the given schema. More...
 
QList< QgsAbstractDatabaseProviderConnection::TablePropertytablesInt (const QString &schema=QString(), const int flags=0) const SIP_THROW(QgsProviderConnectionException)
 Returns information on the tables in the given schema. More...
 
virtual QString tableUri (const QString &schema, const QString &name) const SIP_THROW(QgsProviderConnectionException)
 Returns the URI string for the given table and schema. More...
 
virtual void vacuum (const QString &schema, const QString &name) const SIP_THROW(QgsProviderConnectionException)
 Vacuum the database table with given schema and name (schema is ignored if not supported by the backend). More...
 
- Public Member Functions inherited from QgsAbstractProviderConnection
 QgsAbstractProviderConnection (const QString &name)
 Creates a new connection with name by reading its configuration from the settings. More...
 
 QgsAbstractProviderConnection (const QString &uri, const QVariantMap &configuration)
 Creates a new connection from the given uri and configuration. More...
 
virtual ~QgsAbstractProviderConnection ()=default
 
QVariantMap configuration () const
 Returns the connection configuration parameters. More...
 
virtual QIcon icon () const
 Returns an icon representing the connection. More...
 
virtual void remove (const QString &name) const =0
 Deletes the connection from the settings. More...
 
void setConfiguration (const QVariantMap &configuration)
 Sets the connection configuration. More...
 
void setUri (const QString &uri)
 Sets the connection data source URI to uri. More...
 
virtual void store (const QString &name) const =0
 Stores the connection in the settings. More...
 
QString uri () const
 Returns the connection data source URI string representation. More...
 

Protected Attributes

Capabilities mCapabilities = nullptr
 
QString mProviderKey
 

Detailed Description

The QgsAbstractDatabaseProviderConnection class provides common functionality for DB based connections.

This class performs low level DB operations without asking the user for confirmation or handling currently opened layers and the registry entries, it is responsibility of the client code to keep layers in sync. The class methods will throw exceptions in case the requested operation is not supported or cannot be performed without errors.

Since
QGIS 3.10

Definition at line 40 of file qgsabstractdatabaseproviderconnection.h.

Member Enumeration Documentation

◆ Capability

The Capability enum represent the operations supported by the connection.

Enumerator
CreateVectorTable 

Can CREATE a vector (or aspatial) table/layer.

DropRasterTable 

Can DROP a raster table/layer.

DropVectorTable 

Can DROP a vector (or aspatial) table/layer.

RenameVectorTable 

Can RENAME a vector (or aspatial) table/layer.

RenameRasterTable 

Can RENAME a raster table/layer.

CreateSchema 

Can CREATE a schema.

DropSchema 

Can DROP a schema.

RenameSchema 

Can RENAME a schema.

ExecuteSql 

Can execute raw SQL queries (without returning results)

Vacuum 

Can run vacuum.

Tables 

Can list tables.

Schemas 

Can list schemas (if not set, the connection does not support schemas)

SqlLayers 

Can create vector layers from SQL SELECT queries.

TableExists 

Can check if table exists.

Spatial 

The connection supports spatial tables.

CreateSpatialIndex 

The connection can create spatial indices.

SpatialIndexExists 

The connection can determine if a spatial index exists.

DeleteSpatialIndex 

The connection can delete spatial indices for tables.

DeleteField 

Can delete an existing field.

CreateField 

Can add a new field.

Definition at line 276 of file qgsabstractdatabaseproviderconnection.h.

◆ TableFlag

Flags for table properties.

Flags can be useful for filtering the tables returned from tables().

Enumerator
Aspatial 

Aspatial table (it does not contain any geometry column)

Vector 

Vector table (it does contain one geometry column)

Raster 

Raster table.

View 

View table.

MaterializedView 

Materialized view table.

Foreign 

Foreign data wrapper.

Definition at line 53 of file qgsabstractdatabaseproviderconnection.h.

Constructor & Destructor Documentation

◆ QgsAbstractDatabaseProviderConnection() [1/2]

QgsAbstractDatabaseProviderConnection::QgsAbstractDatabaseProviderConnection ( const QString &  name)

Creates a new connection with name by reading its configuration from the settings.

If a connection with this name cannot be found, an empty connection will be returned.

Definition at line 22 of file qgsabstractdatabaseproviderconnection.cpp.

◆ QgsAbstractDatabaseProviderConnection() [2/2]

QgsAbstractDatabaseProviderConnection::QgsAbstractDatabaseProviderConnection ( const QString &  uri,
const QVariantMap &  configuration 
)

Creates a new connection from the given uri and configuration.

The connection is not automatically stored in the settings.

See also
store()

Definition at line 28 of file qgsabstractdatabaseproviderconnection.cpp.

Member Function Documentation

◆ capabilities()

QgsAbstractDatabaseProviderConnection::Capabilities QgsAbstractDatabaseProviderConnection::capabilities ( ) const

Returns connection capabilities.

Definition at line 33 of file qgsabstractdatabaseproviderconnection.cpp.

◆ createSchema()

void QgsAbstractDatabaseProviderConnection::createSchema ( const QString &  name) const
virtual

Creates a new schema with the specified name.

Exceptions
QgsProviderConnectionException

Definition at line 115 of file qgsabstractdatabaseproviderconnection.cpp.

◆ createSpatialIndex()

void QgsAbstractDatabaseProviderConnection::createSpatialIndex ( const QString &  schema,
const QString &  name,
const QgsAbstractDatabaseProviderConnection::SpatialIndexOptions options = QgsAbstractDatabaseProviderConnection::SpatialIndexOptions() 
) const
virtual

Creates a spatial index for the database table with given schema and name (schema is ignored if not supported by the backend).

The options argument can be used to provide extra options controlling the spatial index creation.

Raises a QgsProviderConnectionException if any errors are encountered.

Exceptions
QgsProviderConnectionException
Since
QGIS 3.14

Definition at line 141 of file qgsabstractdatabaseproviderconnection.cpp.

◆ createVectorTable()

void QgsAbstractDatabaseProviderConnection::createVectorTable ( const QString &  schema,
const QString &  name,
const QgsFields fields,
QgsWkbTypes::Type  wkbType,
const QgsCoordinateReferenceSystem srs,
bool  overwrite,
const QMap< QString, QVariant > *  options 
) const
virtual

Creates an empty table with name in the given schema (schema is ignored if not supported by the backend).

Raises a QgsProviderConnectionException if any errors are encountered.

Exceptions
QgsProviderConnectionException

Definition at line 62 of file qgsabstractdatabaseproviderconnection.cpp.

◆ deleteSpatialIndex()

void QgsAbstractDatabaseProviderConnection::deleteSpatialIndex ( const QString &  schema,
const QString &  name,
const QString &  geometryColumn 
) const
virtual

Deletes the existing spatial index for the database table with given schema, name and geometryColumn (schema and geometryColumn are ignored if not supported by the backend).

Raises a QgsProviderConnectionException if any errors are encountered.

Exceptions
QgsProviderConnectionException
Since
QGIS 3.14

Definition at line 146 of file qgsabstractdatabaseproviderconnection.cpp.

◆ dropRasterTable()

void QgsAbstractDatabaseProviderConnection::dropRasterTable ( const QString &  schema,
const QString &  name 
) const
virtual

Drops a raster table with given schema (schema is ignored if not supported by the backend) and name.

Raises a QgsProviderConnectionException if any errors are encountered.

Note
it is responsibility of the caller to handle open layers and registry entries.
Exceptions
QgsProviderConnectionException

Definition at line 110 of file qgsabstractdatabaseproviderconnection.cpp.

◆ dropSchema()

void QgsAbstractDatabaseProviderConnection::dropSchema ( const QString &  name,
bool  force = false 
) const
virtual

Drops an entire schema with the specified name.

Raises a QgsProviderConnectionException if any errors are encountered.

Parameters
namename of the schema to be dropped
forceif true, a DROP CASCADE will drop all related objects
Note
it is responsibility of the caller to handle open layers and registry entries.
Exceptions
QgsProviderConnectionException

Definition at line 120 of file qgsabstractdatabaseproviderconnection.cpp.

◆ dropVectorTable()

void QgsAbstractDatabaseProviderConnection::dropVectorTable ( const QString &  schema,
const QString &  name 
) const
virtual

Drops a vector (or aspatial) table with given schema (schema is ignored if not supported by the backend) and name.

Raises a QgsProviderConnectionException if any errors are encountered.

Note
it is responsibility of the caller to handle open layers and registry entries.
Exceptions
QgsProviderConnectionException

Definition at line 91 of file qgsabstractdatabaseproviderconnection.cpp.

◆ executeSql()

QList< QList< QVariant > > QgsAbstractDatabaseProviderConnection::executeSql ( const QString &  sql) const
virtual

Executes raw sql and returns the (possibly empty) list of results in a multi-dimensional array.

Raises a QgsProviderConnectionException if any errors are encountered.

Exceptions
QgsProviderConnectionException

Definition at line 130 of file qgsabstractdatabaseproviderconnection.cpp.

◆ fields()

QgsFields QgsAbstractDatabaseProviderConnection::fields ( const QString &  schema,
const QString &  table 
) const
virtual

Returns the fields of a table and schema.

Raises a QgsProviderConnectionException if any errors are encountered.

Note
the default implementation creates a temporary vector layer, providers may choose to override this method for a greater efficiency.
Since
QGIS 3.16
Exceptions
QgsProviderConnectionException

Definition at line 221 of file qgsabstractdatabaseproviderconnection.cpp.

◆ providerKey()

QString QgsAbstractDatabaseProviderConnection::providerKey ( ) const

Returns the provider key.

Since
QGIS 3.16

◆ renameRasterTable()

void QgsAbstractDatabaseProviderConnection::renameRasterTable ( const QString &  schema,
const QString &  name,
const QString &  newName 
) const
virtual

Renames a raster table with given schema (schema is ignored if not supported by the backend) and name.

Raises a QgsProviderConnectionException if any errors are encountered.

Note
it is responsibility of the caller to handle open layers and registry entries.
Exceptions
QgsProviderConnectionException

Definition at line 86 of file qgsabstractdatabaseproviderconnection.cpp.

◆ renameSchema()

void QgsAbstractDatabaseProviderConnection::renameSchema ( const QString &  name,
const QString &  newName 
) const
virtual

Renames a schema with the specified name.

Raises a QgsProviderConnectionException if any errors are encountered.

Note
it is responsibility of the caller to handle open layers and registry entries.
Exceptions
QgsProviderConnectionException

Definition at line 125 of file qgsabstractdatabaseproviderconnection.cpp.

◆ renameVectorTable()

void QgsAbstractDatabaseProviderConnection::renameVectorTable ( const QString &  schema,
const QString &  name,
const QString &  newName 
) const
virtual

Renames a vector or aspatial table with given schema (schema is ignored if not supported by the backend) and name.

Raises a QgsProviderConnectionException if any errors are encountered.

Note
it is responsibility of the caller to handle open layers and registry entries.
Exceptions
QgsProviderConnectionException

Definition at line 81 of file qgsabstractdatabaseproviderconnection.cpp.

◆ schemas()

QStringList QgsAbstractDatabaseProviderConnection::schemas ( ) const
virtual

Returns information about the existing schemas.

Raises a QgsProviderConnectionException if any errors are encountered.

Exceptions
QgsProviderConnectionException

Definition at line 186 of file qgsabstractdatabaseproviderconnection.cpp.

◆ spatialIndexExists()

bool QgsAbstractDatabaseProviderConnection::spatialIndexExists ( const QString &  schema,
const QString &  name,
const QString &  geometryColumn 
) const
virtual

Determines whether a spatial index exists for the database table with given schema, name and geometryColumn (schema and geometryColumn are ignored if not supported by the backend).

Raises a QgsProviderConnectionException if any errors are encountered.

Exceptions
QgsProviderConnectionException
Since
QGIS 3.14

Definition at line 151 of file qgsabstractdatabaseproviderconnection.cpp.

◆ table()

QgsAbstractDatabaseProviderConnection::TableProperty QgsAbstractDatabaseProviderConnection::table ( const QString &  schema,
const QString &  table 
) const
virtual

Returns information on a table in the given schema.

Raises a QgsProviderConnectionException if any errors are encountered or if the table does not exist.

Exceptions
QgsProviderConnectionException
Note
Not available in Python bindings
Since
QGIS 3.12

Definition at line 164 of file qgsabstractdatabaseproviderconnection.cpp.

◆ tableExists()

bool QgsAbstractDatabaseProviderConnection::tableExists ( const QString &  schema,
const QString &  name 
) const
virtual

Checks whether a table name exists in the given schema.

Raises a QgsProviderConnectionException if any errors are encountered.

Exceptions
QgsProviderConnectionException

Definition at line 96 of file qgsabstractdatabaseproviderconnection.cpp.

◆ tables()

QList< QgsAbstractDatabaseProviderConnection::TableProperty > QgsAbstractDatabaseProviderConnection::tables ( const QString &  schema = QString(),
const QgsAbstractDatabaseProviderConnection::TableFlags &  flags = nullptr 
) const
virtual

Returns information on the tables in the given schema.

Raises a QgsProviderConnectionException if any errors are encountered.

Parameters
schemaname of the schema (ignored if not supported by the backend)
flagsfilter tables by flags, this option completely overrides search options stored in the connection
Exceptions
QgsProviderConnectionException
Note
Not available in Python bindings

Definition at line 157 of file qgsabstractdatabaseproviderconnection.cpp.

◆ tablesInt()

QList< QgsAbstractDatabaseProviderConnection::TableProperty > QgsAbstractDatabaseProviderConnection::tablesInt ( const QString &  schema = QString(),
const int  flags = 0 
) const

Returns information on the tables in the given schema.

Raises a QgsProviderConnectionException if any errors are encountered.

Parameters
schemaname of the schema (ignored if not supported by the backend)
flagsfilter tables by flags, this option completely overrides search options stored in the connection
Exceptions
QgsProviderConnectionException

Definition at line 180 of file qgsabstractdatabaseproviderconnection.cpp.

◆ tableUri()

QString QgsAbstractDatabaseProviderConnection::tableUri ( const QString &  schema,
const QString &  name 
) const
virtual

Returns the URI string for the given table and schema.

Raises a QgsProviderConnectionException if any errors are encountered.

Exceptions
QgsProviderConnectionException
Since
QGIS 3.12

Definition at line 38 of file qgsabstractdatabaseproviderconnection.cpp.

◆ vacuum()

void QgsAbstractDatabaseProviderConnection::vacuum ( const QString &  schema,
const QString &  name 
) const
virtual

Vacuum the database table with given schema and name (schema is ignored if not supported by the backend).

Raises a QgsProviderConnectionException if any errors are encountered.

Exceptions
QgsProviderConnectionException

Definition at line 136 of file qgsabstractdatabaseproviderconnection.cpp.

Member Data Documentation

◆ mCapabilities

Capabilities QgsAbstractDatabaseProviderConnection::mCapabilities = nullptr
protected

Definition at line 526 of file qgsabstractdatabaseproviderconnection.h.

◆ mProviderKey

QString QgsAbstractDatabaseProviderConnection::mProviderKey
protected

Definition at line 527 of file qgsabstractdatabaseproviderconnection.h.


The documentation for this class was generated from the following files: