Class: QgsAbstractDatabaseProviderConnection

class qgis.core.QgsAbstractDatabaseProviderConnection

Bases: QgsAbstractProviderConnection

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.

New in version 3.10.

QgsAbstractDatabaseProviderConnection(name: str) 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.

QgsAbstractDatabaseProviderConnection(uri: str, configuration: Dict[str, Any]) Creates a new connection from the given uri and configuration.

The connection is not automatically stored in the settings.

See also

store()

QgsAbstractDatabaseProviderConnection(QgsAbstractDatabaseProviderConnection)

Methods

addField

Adds a field.

capabilities

Returns connection capabilities

checkCapability

Checks if capability is supported.

createSchema

Creates a new schema with the specified name.

createSpatialIndex

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

createSqlVectorLayer

Creates and returns a (possibly invalid) vector layer based on the sql statement and optional options.

createVectorTable

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

deleteField

Deletes the field with the specified name.

deleteSpatialIndex

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).

dropRasterTable

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

dropSchema

Drops an entire schema with the specified name.

dropVectorTable

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

execSql

Executes raw sql and returns the (possibly empty) query results, optionally feedback can be provided.

executeSql

Executes raw sql and returns the (possibly empty) list of results in a multi-dimensional array, optionally feedback can be provided.

fields

Returns the fields of a table and schema.

geometryColumnCapabilities

Returns connection geometry column capabilities (Z, M, SinglePart, Curves).

nativeTypes

Returns a list of native types supported by the connection.

providerKey

Returns the provider key.

renameRasterTable

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

renameSchema

Renames a schema with the specified name.

renameVectorTable

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

schemas

Returns information about the existing schemas.

spatialIndexExists

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).

sqlDictionary

Returns a dictionary of SQL keywords supported by the provider.

sqlLayerDefinitionCapabilities

Returns SQL layer definition capabilities (Filters, GeometryColumn, PrimaryKeys).

sqlOptions

Returns the SQL layer options from a layerSource.

table

Returns information on a table in the given schema.

tableExists

Checks whether a table name exists in the given schema.

tableUri

Returns the URI string for the given table and schema.

tables

Returns information on the tables in the given schema.

vacuum

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

Attributes

AddField

Aspatial

CreateSchema

CreateSpatialIndex

CreateVectorTable

Curves

DeleteField

DeleteFieldCascade

DeleteSpatialIndex

DropRasterTable

DropSchema

DropVectorTable

ExecuteSql

Foreign

M

MaterializedView

Raster

RenameRasterTable

RenameSchema

RenameVectorTable

Schemas

SinglePart

Spatial

SpatialIndexExists

SqlLayers

TableExists

Tables

Vacuum

Vector

View

Z

staticMetaObject

AddField = 2097152
Aspatial = 2
class Capabilities
class Capabilities(Union[QgsAbstractDatabaseProviderConnection.Capabilities, QgsAbstractDatabaseProviderConnection.Capability])
class Capabilities(QgsAbstractDatabaseProviderConnection.Capabilities)

Bases: sip.wrapper

baseClass

alias of QgsAbstractDatabaseProviderConnection

class Capability

Bases: int

baseClass

alias of QgsAbstractDatabaseProviderConnection

CreateSchema = 64
CreateSpatialIndex = 65536
CreateVectorTable = 2
Curves = 16
DeleteField = 524288
DeleteFieldCascade = 1048576
DeleteSpatialIndex = 262144
DropRasterTable = 4
DropSchema = 128
DropVectorTable = 8
ExecuteSql = 512
Foreign = 64
class GeometryColumnCapabilities
class GeometryColumnCapabilities(Union[QgsAbstractDatabaseProviderConnection.GeometryColumnCapabilities, QgsAbstractDatabaseProviderConnection.GeometryColumnCapability])
class GeometryColumnCapabilities(QgsAbstractDatabaseProviderConnection.GeometryColumnCapabilities)

Bases: sip.wrapper

baseClass

alias of QgsAbstractDatabaseProviderConnection

class GeometryColumnCapability

Bases: int

baseClass

alias of QgsAbstractDatabaseProviderConnection

M = 4
MaterializedView = 32
class QueryResult
class QueryResult(QgsAbstractDatabaseProviderConnection.QueryResult)

Bases: sip.wrapper

columns(self) List[str]

Returns the column names.

Return type:

List[str]

fetchedRowCount(self) int

Returns the number of fetched rows.

See also

rowCount()

Return type:

int

hasNextRow(self) bool

Returns True if there are more rows to fetch.

See also

nextRow()

See also

rewind()

Return type:

bool

nextRow(self) List[Any]

Returns the next result row or an empty row if there are no rows left.

See also

hasNextRow()

See also

rewind()

Return type:

List[Any]

queryExecutionTime(self) float

Returns the query execution time in milliseconds.

Return type:

float

rowCount(self) int

Returns the number of rows returned by a SELECT query or Qgis.FeatureCountState.UnknownCount if unknown.

Return type:

int

rows(self, feedback: QgsFeedback = None) object

Returns the result rows by calling the iterator internally and fetching all the rows, an optional feedback can be used to interrupt the fetching loop.

Note

calling this function more than one time is not supported: the second call will always return an empty list.

Parameters:

feedback (QgsFeedback = None) –

Return type:

object

setQueryExecutionTime(self, queryExecutionTime: float)

Sets the query execution time to queryExecutionTime milliseconds.

Parameters:

queryExecutionTime (float) –

Raster = 8
RenameRasterTable = 32
RenameSchema = 256
RenameVectorTable = 16
Schemas = 4096
SinglePart = 8
Spatial = 32768
SpatialIndexExists = 131072
class SpatialIndexOptions
class SpatialIndexOptions(QgsAbstractDatabaseProviderConnection.SpatialIndexOptions)

Bases: sip.wrapper

geometryColumnName
SqlLayers = 8192
class SqlVectorLayerOptions
class SqlVectorLayerOptions(QgsAbstractDatabaseProviderConnection.SqlVectorLayerOptions)

Bases: sip.wrapper

disableSelectAtId
filter
geometryColumn
layerName
primaryKeyColumns
sql
TableExists = 16384
class TableFlag

Bases: int

baseClass

alias of QgsAbstractDatabaseProviderConnection

class TableFlags
class TableFlags(Union[QgsAbstractDatabaseProviderConnection.TableFlags, QgsAbstractDatabaseProviderConnection.TableFlag])
class TableFlags(QgsAbstractDatabaseProviderConnection.TableFlags)

Bases: sip.wrapper

baseClass

alias of QgsAbstractDatabaseProviderConnection

class TableProperty
class TableProperty(QgsAbstractDatabaseProviderConnection.TableProperty)

Bases: sip.wrapper

class GeometryColumnType
class GeometryColumnType(QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType)

Bases: sip.wrapper

crs
wkbType
addGeometryColumnType(self, type: QgsWkbTypes.Type, crs: QgsCoordinateReferenceSystem)

Appends the geometry column type with the given srid to the geometry column types list.

Parameters:
at(self, index: int) QgsAbstractDatabaseProviderConnection.TableProperty

Returns the table property corresponding to the geometry type at the given index.

Parameters:

index (int) –

Return type:

QgsAbstractDatabaseProviderConnection.TableProperty

comment(self) str

Returns the table comment.

Return type:

str

crsList(self) List[QgsCoordinateReferenceSystem]

Returns the list of CRSs supported by the geometry column.

Return type:

List[QgsCoordinateReferenceSystem]

defaultName(self) str

Returns the default name for the table entry.

This is usually the table name but in case there are multiple geometry columns, the geometry column name is appended to the table name.

Return type:

str

flags(self) QgsAbstractDatabaseProviderConnection.TableFlags

Returns the table flags.

Return type:

QgsAbstractDatabaseProviderConnection.TableFlags

geometryColumn(self) str

Returns the geometry column name.

Return type:

str

geometryColumnCount(self) int

Returns the number of geometry columns in the original table this entry refers to.

This information is used internally to build the defaultName().

Return type:

int

geometryColumnTypes(self) List[QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType]

Returns the list of geometry column types and CRSs.

The method returns a list of GeometryColumnType.

Return type:

List[QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType]

info(self) Dict[str, Any]

Returns additional information about the table.

Provider classes may use this property to store custom bits of information.

Return type:

Dict[str, Any]

maxCoordinateDimensions(self) int

Returns the maximum coordinate dimensions of the geometries of a vector table.

This information is calculated from the geometry columns types.

Return type:

int

primaryKeyColumns(self) List[str]

Returns the list of primary key column names.

Return type:

List[str]

schema(self) str

Returns the schema or an empty string for backends that do not support a schema.

Return type:

str

setComment(self, comment: str)

Sets the table comment.

Parameters:

comment (str) –

setFlag(self, flag: QgsAbstractDatabaseProviderConnection.TableFlag)

Sets a flag.

Parameters:

flag (QgsAbstractDatabaseProviderConnection.TableFlag) –

setFlags(self, flags: QgsAbstractDatabaseProviderConnection.TableFlags | QgsAbstractDatabaseProviderConnection.TableFlag)

Sets the table flags.

Parameters:

flags (Union[QgsAbstractDatabaseProviderConnection.TableFlags) –

setGeometryColumn(self, geometryColumn: str)

Sets the geometry column name to geometryColumn.

Parameters:

geometryColumn (str) –

setGeometryColumnCount(self, geometryColumnCount: int)

Sets the geometryColumnCount.

Parameters:

geometryColumnCount (int) –

setGeometryColumnTypes(self, geometryColumnTypes: Iterable[QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType])

Sets the geometry column types to geometryColumnTypes.

Parameters:

geometryColumnTypes (Iterable[QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType]) –

setInfo(self, info: Dict[str, Any])

Sets additional information about the table to info.

Provider classes may use this property to store custom bits of information.

Parameters:

info (Dict[str) –

setPrimaryKeyColumns(self, primaryKeyColumns: Iterable[str])

Sets the primary key column names to primaryKeyColumns.

Parameters:

primaryKeyColumns (Iterable[str]) –

setSchema(self, schema: str)

Sets the schema.

Parameters:

schema (str) –

setTableName(self, name: str)

Sets the table name to name.

See also

defaultName()

Parameters:

name (str) –

tableName(self) str

Returns the table name.

See also

defaultName()

Return type:

str

Tables = 2048
Vacuum = 1024
Vector = 4
View = 16
Z = 2
addField(self, field: QgsField, schema: str, tableName: str)

Adds a field.

Parameters:
  • field (QgsField) – specification of the new field

  • schema (str) – name of the schema (schema is ignored if not supported by the backend).

  • tableName (str) – name of the table

Note

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

Raises:

QgsProviderConnectionException – if any errors are encountered.

New in version 3.16.

capabilities(self) QgsAbstractDatabaseProviderConnection.Capabilities

Returns connection capabilities

Return type:

QgsAbstractDatabaseProviderConnection.Capabilities

checkCapability(self, capability: QgsAbstractDatabaseProviderConnection.Capability)

Checks if capability is supported.

Raises:

QgsProviderConnectionException – if the capability is not supported

Parameters:

capability (QgsAbstractDatabaseProviderConnection.Capability) –

createSchema(self, name: str)

Creates a new schema with the specified name.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:

name (str) –

createSpatialIndex(self, schema: str, name: str, options: QgsAbstractDatabaseProviderConnection.SpatialIndexOptions = QgsAbstractDatabaseProviderConnection.SpatialIndexOptions())

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:

QgsProviderConnectionException – if any errors are encountered.

New in version 3.14.

Parameters:
  • schema (str) –

  • name (str) –

  • options (QgsAbstractDatabaseProviderConnection.SpatialIndexOptions = QgsAbstractDatabaseProviderConnection.SpatialIndexOptions()) –

createSqlVectorLayer(self, options: QgsAbstractDatabaseProviderConnection.SqlVectorLayerOptions) QgsVectorLayer

Creates and returns a (possibly invalid) vector layer based on the sql statement and optional options.

Raises:

QgsProviderConnectionException – if any errors are encountered or if SQL layer creation is not supported.

New in version 3.22.

Parameters:

options (QgsAbstractDatabaseProviderConnection.SqlVectorLayerOptions) –

Return type:

QgsVectorLayer

createVectorTable(self, schema: str, name: str, fields: QgsFields, wkbType: QgsWkbTypes.Type, srs: QgsCoordinateReferenceSystem, overwrite: bool, options: Dict[str, Any])

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

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:
deleteField(self, fieldName: str, schema: str, tableName: str, force: bool = False)

Deletes the field with the specified name.

Parameters:
  • fieldName (str) – name of the field to be deleted

  • schema (str) – name of the schema (schema is ignored if not supported by the backend).

  • tableName (str) – name of the table

  • force (bool = False) – if True, a DROP CASCADE will drop all related objects

Note

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

Raises:

QgsProviderConnectionException – if any errors are encountered.

New in version 3.16.

deleteSpatialIndex(self, schema: str, name: str, geometryColumn: str)

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:

QgsProviderConnectionException – if any errors are encountered.

New in version 3.14.

Parameters:
  • schema (str) –

  • name (str) –

  • geometryColumn (str) –

dropRasterTable(self, schema: str, name: str)

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

Note

It is responsibility of the caller to handle open layers and registry entries.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:
  • schema (str) –

  • name (str) –

dropSchema(self, name: str, force: bool = False)

Drops an entire schema with the specified name.

Parameters:
  • name (str) – name of the schema to be dropped

  • force (bool = False) – if True, a DROP CASCADE will drop all related objects

Note

It is responsibility of the caller to handle open layers and registry entries.

Raises:

QgsProviderConnectionException – if any errors are encountered.

dropVectorTable(self, schema: str, name: str)

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

Note

It is responsibility of the caller to handle open layers and registry entries.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:
  • schema (str) –

  • name (str) –

execSql(self, sql: str, feedback: QgsFeedback = None) QgsAbstractDatabaseProviderConnection.QueryResult

Executes raw sql and returns the (possibly empty) query results, optionally feedback can be provided.

See also

executeSql()

Raises:

QgsProviderConnectionException – if any errors are encountered.

New in version 3.18.

Parameters:
Return type:

QgsAbstractDatabaseProviderConnection.QueryResult

executeSql(self, sql: str, feedback: QgsFeedback = None) object

Executes raw sql and returns the (possibly empty) list of results in a multi-dimensional array, optionally feedback can be provided.

See also

execSql()

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:
Return type:

object

fields(self, schema: str, table: str) QgsFields

Returns the fields of a table and schema.

Note

the default implementation creates a temporary vector layer, providers may choose to override this method for a greater efficiency of to overcome provider’s behavior when the layer does not expose all fields (GPKG for example hides geometry and primary key column).

Raises:

QgsProviderConnectionException – if any errors are encountered.

New in version 3.16.

Parameters:
  • schema (str) –

  • table (str) –

Return type:

QgsFields

geometryColumnCapabilities(self) QgsAbstractDatabaseProviderConnection.GeometryColumnCapabilities

Returns connection geometry column capabilities (Z, M, SinglePart, Curves).

New in version 3.16.

Return type:

QgsAbstractDatabaseProviderConnection.GeometryColumnCapabilities

nativeTypes(self) List[QgsVectorDataProvider.NativeType]

Returns a list of native types supported by the connection.

Raises:

QgsProviderConnectionException – if any errors are encountered.

New in version 3.16.

Return type:

List[QgsVectorDataProvider.NativeType]

providerKey(self) str

Returns the provider key.

New in version 3.16.

Return type:

str

renameRasterTable(self, schema: str, name: str, newName: str)

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

Note

It is responsibility of the caller to handle open layers and registry entries.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:
  • schema (str) –

  • name (str) –

  • newName (str) –

renameSchema(self, name: str, newName: str)

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.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:
  • name (str) –

  • newName (str) –

renameVectorTable(self, schema: str, name: str, newName: str)

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

Note

It is responsibility of the caller to handle open layers and registry entries.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:
  • schema (str) –

  • name (str) –

  • newName (str) –

schemas(self) List[str]

Returns information about the existing schemas.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Return type:

List[str]

spatialIndexExists(self, schema: str, name: str, geometryColumn: str) bool

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:

QgsProviderConnectionException – if any errors are encountered.

New in version 3.14.

Parameters:
  • schema (str) –

  • name (str) –

  • geometryColumn (str) –

Return type:

bool

sqlDictionary(self) Dict[Qgis.SqlKeywordCategory, List[List[str]]]

Returns a dictionary of SQL keywords supported by the provider. The default implementation returns an list of common reserved words under the “Keyword” and “Constant” categories.

Subclasses should add provider- and/or connection- specific words.

New in version 3.22.

Return type:

Dict[Qgis.SqlKeywordCategory, List[List[str]]]

sqlLayerDefinitionCapabilities(self) Qgis.SqlLayerDefinitionCapabilities

Returns SQL layer definition capabilities (Filters, GeometryColumn, PrimaryKeys).

New in version 3.22.

Return type:

Qgis.SqlLayerDefinitionCapabilities

sqlOptions(self, layerSource: str) QgsAbstractDatabaseProviderConnection.SqlVectorLayerOptions

Returns the SQL layer options from a layerSource.

Note

the default implementation returns a default constructed option object.

Raises:

QgsProviderConnectionException – if any errors are encountered or if SQL layer creation is not supported.

New in version 3.22.

Parameters:

layerSource (str) –

Return type:

QgsAbstractDatabaseProviderConnection.SqlVectorLayerOptions

staticMetaObject = <PyQt5.QtCore.QMetaObject object>
table(self, schema: str, table: str) QgsAbstractDatabaseProviderConnection.TableProperty

Returns information on a table in the given schema.

Raises:

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

Note

Not available in Python bindings

New in version 3.12.

Parameters:
  • schema (str) –

  • table (str) –

Return type:

QgsAbstractDatabaseProviderConnection.TableProperty

tableExists(self, schema: str, name: str) bool

Checks whether a table name exists in the given schema.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:
  • schema (str) –

  • name (str) –

Return type:

bool

tableUri(self, schema: str, name: str) str

Returns the URI string for the given table and schema.

Raises:

QgsProviderConnectionException – if any errors are encountered.

New in version 3.12.

Parameters:
  • schema (str) –

  • name (str) –

Return type:

str

tables(self, schema: str = '', flags: int = 0) List[QgsAbstractDatabaseProviderConnection.TableProperty]

Returns information on the tables in the given schema.

Parameters:
  • schema (str = '') – name of the schema (ignored if not supported by the backend)

  • flags (int = 0) – filter tables by flags, this option completely overrides search options stored in the connection

Raises:

QgsProviderConnectionException – if any errors are encountered.

Return type:

List[QgsAbstractDatabaseProviderConnection.TableProperty]

vacuum(self, schema: str, name: str)

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

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:
  • schema (str) –

  • name (str) –