Class: QgsAbstractDatabaseProviderConnection

Provides common functionality for database 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.

Added in version 3.10.

Note

This is an abstract class, with methods which must be implemented by a subclass.

The following methods must be implemented: nativeTypes(), QgsAbstractProviderConnection.remove(), QgsAbstractProviderConnection.store(), tableImportCapabilities()

Class Hierarchy

Inheritance diagram of qgis.core.QgsAbstractDatabaseProviderConnection

Base classes

QgsAbstractProviderConnection

An interface for data provider connections.

Enums

TableFlag

Flags for table properties.

Abstract Methods

nativeTypes

Returns a list of native types supported by the connection.

tableImportCapabilities

Represents capabilities of the database provider connection when importing table data.

Methods

capabilities

Returns connection capabilities.

capabilities2

Returns extended connection capabilities.

checkCapability

Checks if capability is supported.

fieldDomainNames

Returns a list of field domain names present on the provider.

providerKey

Returns the provider key.

schemas

Returns information about the existing schemas.

supportedRelationshipCardinalities

Returns a list of relationship cardinalities which are supported by the provider.

supportedRelationshipStrengths

Returns a list of relationship strengths which are supported by the provider.

tables

Returns information on the tables in the given schema.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsAbstractDatabaseProviderConnection. See the FAQ for more details.

addField

Adds a field.

addFieldDomain

Adds a new field domain to the database.

addRelationship

Adds a new field relationship to the database.

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 a SQL statement and options.

createVectorLayerExporterDestinationUri

Creates a URI for use with QgsVectorLayerExporter corresponding to given destination table options for the backend.

createVectorTable

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

defaultGeometryColumnName

Returns the default name to use for a geometry column for the connection.

defaultPrimaryKeyColumnName

Returns the default name to use for a primary key column for the connection.

deleteField

Deletes the field with the specified name.

deleteRelationship

Deletes an existing relationship in the database.

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.

fieldDomain

Returns the field domain with the specified name from the provider.

fields

Returns the fields of a table and schema.

geometryColumnCapabilities

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

illegalFieldNames

Returns a list of field names which are considered illegal by the connection and should not be used when creating or altering fields.

moveTableToSchema

Move table to a different schema.

queryBuilder

Returns a SQL query builder for the connection, which provides an interface for provider-specific creation of SQL queries.

relatedTableTypes

Returns a list of the related table types supported by the database format.

relationships

Returns a list of relationships detected in the database.

renameField

Renames an existing field.

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.

searchLayerMetadata

Search the stored layer metadata in the connection, optionally limiting the search to the metadata identifier, title, abstract, keywords and categories.

setFieldAlias

Sets the alias for the existing field with the specified name.

setFieldComment

Sets the comment for the existing field with the specified name.

setFieldDomainName

Sets the field domain name for the existing field with the specified name.

setTableComment

Sets the comment for the existing table with the specified name.

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.

supportedFieldDomainTypes

Returns a list of field domain types which are supported by the provider.

supportedRelationshipCapabilities

Returns the relationship capabilities supported by the provider.

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.

updateRelationship

Updates an existing relationship in the database.

vacuum

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

validateSqlVectorLayer

Validates the SQL query options to determine if it is possible to create a vector layer based on a SQL statement and options.

Attributes

AddField

AddFieldDomain

AddRelationship

CreateSchema

CreateSpatialIndex

CreateVectorTable

Curves

DeleteField

DeleteFieldCascade

DeleteRelationship

DeleteSpatialIndex

DropRasterTable

DropSchema

DropVectorTable

ExecuteSql

ListFieldDomains

M

MoveTableToSchema

PolyhedralSurfaces

RenameField

RenameRasterTable

RenameSchema

RenameVectorTable

RetrieveFieldDomain

RetrieveRelationships

Schemas

SetFieldDomain

SingleLineString

SinglePart

SinglePoint

SinglePolygon

Spatial

SpatialIndexExists

SqlLayers

TableExists

Tables

UpdateRelationship

Vacuum

Z

class qgis.core.QgsAbstractDatabaseProviderConnection[source]

Bases: QgsAbstractProviderConnection

__init__(name: str | None)

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.

Parameters:

name (Optional[str])

__init__(uri: str | None, 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()

Parameters:
  • uri (Optional[str])

  • configuration (Dict[str, Any])

__init__(a0: QgsAbstractDatabaseProviderConnection)
Parameters:

a0 (QgsAbstractDatabaseProviderConnection)

AddField = 2097152
AddFieldDomain = 33554432
AddRelationship = 268435456
class Capabilities
class Capabilities(f: QgsAbstractDatabaseProviderConnection.Capabilities | QgsAbstractDatabaseProviderConnection.Capability)
class Capabilities(a0: QgsAbstractDatabaseProviderConnection.Capabilities)

Bases: object

class Capability

Bases: int

CreateSchema = 64
CreateSpatialIndex = 65536
CreateVectorTable = 2
Curves = 16
DeleteField = 524288
DeleteFieldCascade = 1048576
DeleteRelationship = 1073741824
DeleteSpatialIndex = 262144
DropRasterTable = 4
DropSchema = 128
DropVectorTable = 8
ExecuteSql = 512
class GeometryColumnCapabilities
class GeometryColumnCapabilities(f: QgsAbstractDatabaseProviderConnection.GeometryColumnCapabilities | QgsAbstractDatabaseProviderConnection.GeometryColumnCapability)
class GeometryColumnCapabilities(a0: QgsAbstractDatabaseProviderConnection.GeometryColumnCapabilities)

Bases: object

class GeometryColumnCapability

Bases: int

ListFieldDomains = 4194304
M = 4
MoveTableToSchema = -2147483648
PolyhedralSurfaces = 256
class QueryResult

Bases: object

The QueryResult class represents the result of a query executed by execSql()

It encapsulates an iterator over the result rows and a list of the column names.

Rows can be retrieved by iterating over the result with hasNextRow() and nextRow() or by calling rows() that will internally iterate over the results and return the whole result list.

Added in version 3.18.

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 = None) Any

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 (Optional[QgsFeedback] = None)

Return type:

Any

setQueryExecutionTime(self, queryExecutionTime: float)

Sets the query execution time to queryExecutionTime milliseconds.

Parameters:

queryExecutionTime (float)

RenameField = 67108864
RenameRasterTable = 32
RenameSchema = 256
RenameVectorTable = 16
RetrieveFieldDomain = 8388608
RetrieveRelationships = 134217728
Schemas = 4096
SetFieldDomain = 16777216
SingleLineString = 64
SinglePart = 8
SinglePoint = 32
SinglePolygon = 128
Spatial = 32768
SpatialIndexExists = 131072
class SpatialIndexOptions

Bases: object

The SpatialIndexOptions contains extra options relating to spatial index creation.

Added in version 3.14.

geometryColumnName: str

Specifies the name of the geometry column to create the index for

SqlLayers = 8192
class SqlVectorLayerOptions

Bases: object

The SqlVectorLayerOptions stores all information required to create a SQL (query) layer.

See also

createSqlVectorLayer()

Added in version 3.22.

disableSelectAtId: bool

If SelectAtId is disabled (default is false), not all data providers support this feature: check support with SqlLayerDefinitionCapability.SelectAtId capability

filter: str

Additional subset string (provider-side filter), not all data providers support this feature: check support with SqlLayerDefinitionCapability.Filters capability

geometryColumn: str

Name of the geometry column

layerName: str

Optional name for the new layer

primaryKeyColumns: List[str]

List of primary key column names

sql: str

The SQL expression that defines the SQL (query) layer

TableExists = 16384
class TableFlag(*values)

Bases: IntEnum

Flags for table properties.

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

  • 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

  • IncludeSystemTables: Include system tables

    Added in version 3.30.

class TableFlags
class TableFlags(f: QgsAbstractDatabaseProviderConnection.TableFlags | QgsAbstractDatabaseProviderConnection.TableFlag)
class TableFlags(a0: QgsAbstractDatabaseProviderConnection.TableFlags)

Bases: object

class TableProperty

Bases: object

The TableProperty class represents a database table or view.

In case the table is a vector spatial table and it has multiple geometry columns, separate entries for each geometry column must be created.

In case the table is a vector spatial table and the geometry column can contain multiple geometry types and/or CRSs, a clone of the property for the individual geometry type/CRS can be retrieved with at(i)

class GeometryColumnType

Bases: object

The GeometryColumnType struct represents the combination of geometry type and CRS for the table geometry column.

crs
wkbType
addGeometryColumnType(self, type: Qgis.WkbType, 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 | None)

Sets the table comment.

Parameters:

comment (Optional[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, QgsAbstractDatabaseProviderConnection.TableFlag])

setGeometryColumn(self, geometryColumn: str | None)

Sets the geometry column name to geometryColumn.

Parameters:

geometryColumn (Optional[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, Any])

setPrimaryKeyColumns(self, primaryKeyColumns: Iterable[str | None])

Sets the primary key column names to primaryKeyColumns.

Parameters:

primaryKeyColumns (Iterable[Optional[str]])

setSchema(self, schema: str | None)

Sets the schema.

Parameters:

schema (Optional[str])

setTableName(self, name: str | None)

Sets the table name to name.

See also

defaultName()

Parameters:

name (Optional[str])

tableName(self) str

Returns the table name.

See also

defaultName()

Return type:

str

Tables = 2048
UpdateRelationship = 536870912
Vacuum = 1024
class VectorLayerExporterOptions

Bases: object

Stores all information required to create a QgsVectorLayerExporter for the backend.

See also

createVectorLayerExporterDestinationUri()

Added in version 3.44.

geometryColumn: str

Preferred name for the geometry column, if required. Note that some providers may ignore this if a specific geometry column name is required.

layerName: str

Name for the new layer

primaryKeyColumns: List[str]

List of primary key column names. Note that some providers may ignore this if not supported.

schema: str

Optional schema for the new layer. May not be supported by all providers.

wkbType: Qgis.WkbType

WKB type for destination layer geometry

Z = 2
virtual addField(self, field: QgsField, schema: str | None, tableName: str | None)[source]

Adds a field.

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

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

  • tableName (Optional[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.

Added in version 3.16.

virtual addFieldDomain(self, domain: QgsFieldDomain, schema: str | None)[source]

Adds a new field domain to the database.

Parameters:
  • domain (QgsFieldDomain) – field domain to add

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

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.26.

virtual addRelationship(self, relationship: QgsWeakRelation)[source]

Adds a new field relationship to the database.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.30.

Parameters:

relationship (QgsWeakRelation)

capabilities(self) QgsAbstractDatabaseProviderConnection.Capabilities[source]

Returns connection capabilities.

See also

capabilities2()

Return type:

QgsAbstractDatabaseProviderConnection.Capabilities

capabilities2(self) Qgis.DatabaseProviderConnectionCapabilities2[source]

Returns extended connection capabilities.

See also

capabilities()

Added in version 3.32.

Return type:

Qgis.DatabaseProviderConnectionCapabilities2

checkCapability(self, capability: QgsAbstractDatabaseProviderConnection.Capability)[source]

Checks if capability is supported.

Raises:

QgsProviderConnectionException – if the capability is not supported

Parameters:

capability (QgsAbstractDatabaseProviderConnection.Capability)

checkCapability(self, capability: Qgis.DatabaseProviderConnectionCapability2)[source]

Checks if capability is supported.

Raises:

QgsProviderConnectionException – if the capability is not supported

Parameters:

capability (Qgis.DatabaseProviderConnectionCapability2)

virtual createSchema(self, name: str | None)[source]

Creates a new schema with the specified name.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:

name (Optional[str])

virtual createSpatialIndex(self, schema: str | None, name: str | None, options: QgsAbstractDatabaseProviderConnection.SpatialIndexOptions = QgsAbstractDatabaseProviderConnection.SpatialIndexOptions())[source]

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.

Added in version 3.14.

Parameters:
  • schema (Optional[str])

  • name (Optional[str])

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

virtual createSqlVectorLayer(self, options: QgsAbstractDatabaseProviderConnection.SqlVectorLayerOptions) QgsVectorLayer | None[source]

Creates and returns a (possibly invalid) vector layer based on a SQL statement and options.

The validateSqlVectorLayer() method can be used in advance to test whether the options are valid for the provider, and retrieve a user-friendly explanation if not.

Raises:

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

Added in version 3.22.

Parameters:

options (QgsAbstractDatabaseProviderConnection.SqlVectorLayerOptions)

Return type:

Optional[QgsVectorLayer]

virtual createVectorLayerExporterDestinationUri(self, options: QgsAbstractDatabaseProviderConnection.VectorLayerExporterOptions)[source]

Creates a URI for use with QgsVectorLayerExporter corresponding to given destination table options for the backend.

Parameters:

options (QgsAbstractDatabaseProviderConnection.VectorLayerExporterOptions) -> (str) – defines the desired destination table details

Returns:

Raises:

QgsProviderConnectionException – if any errors are encountered.

virtual createVectorTable(self, schema: str | None, name: str | None, fields: QgsFields, wkbType: Qgis.WkbType, srs: QgsCoordinateReferenceSystem, overwrite: bool, options: Dict[str | None, Any] | None)[source]

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:
virtual defaultGeometryColumnName(self) str[source]

Returns the default name to use for a geometry column for the connection.

The returned name will match common practice for the database backend.

The base class method returns “geom”.

Added in version 3.44.

Return type:

str

virtual defaultPrimaryKeyColumnName(self) str[source]

Returns the default name to use for a primary key column for the connection.

The returned name will match common practice for the database backend.

The base class method returns “pk”.

Added in version 3.44.

Return type:

str

virtual deleteField(self, fieldName: str | None, schema: str | None, tableName: str | None, force: bool = False)[source]

Deletes the field with the specified name.

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

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

  • tableName (Optional[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.

Added in version 3.16.

virtual deleteRelationship(self, relationship: QgsWeakRelation)[source]

Deletes an existing relationship in the database.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.30.

Parameters:

relationship (QgsWeakRelation)

virtual deleteSpatialIndex(self, schema: str | None, name: str | None, geometryColumn: str | None)[source]

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.

Added in version 3.14.

Parameters:
  • schema (Optional[str])

  • name (Optional[str])

  • geometryColumn (Optional[str])

virtual dropRasterTable(self, schema: str | None, name: str | None)[source]

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 (Optional[str])

  • name (Optional[str])

virtual dropSchema(self, name: str | None, force: bool = False)[source]

Drops an entire schema with the specified name.

Parameters:
  • name (Optional[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.

virtual dropVectorTable(self, schema: str | None, name: str | None)[source]

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 (Optional[str])

  • name (Optional[str])

virtual execSql(self, sql: str | None, feedback: QgsFeedback | None = None) QgsAbstractDatabaseProviderConnection.QueryResult[source]

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.

Added in version 3.18.

Parameters:
  • sql (Optional[str])

  • feedback (Optional[QgsFeedback] = None)

Return type:

QgsAbstractDatabaseProviderConnection.QueryResult

virtual executeSql(self, sql: str | None, feedback: QgsFeedback | None = None) Any

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:
  • sql (Optional[str])

  • feedback (Optional[QgsFeedback] = None)

Return type:

Any

virtual fieldDomain(self, name: str | None) QgsFieldDomain | None[source]

Returns the field domain with the specified name from the provider.

The caller takes ownership of the return object. Will return None if no matching field domain is found.

This is supported on providers with the Capability.RetrieveFieldDomain capability only.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.26.

Parameters:

name (Optional[str])

Return type:

Optional[QgsFieldDomain]

fieldDomainNames(self) List[str][source]

Returns a list of field domain names present on the provider.

This is supported on providers with the Capability.ListFieldDomains capability only.

Raises:

QgsProviderConnectionException – if any errors are encountered.

See also

fieldDomain()

Added in version 3.26.

Return type:

List[str]

virtual fields(self, schema: str | None, table: str | None, feedback: QgsFeedback | None = None) QgsFields[source]

Returns the fields of a table and schema.

Since QGIS 3.32 the optional feedback argument can be used to cancel the request.

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.

Added in version 3.16.

Parameters:
  • schema (Optional[str])

  • table (Optional[str])

  • feedback (Optional[QgsFeedback] = None)

Return type:

QgsFields

virtual geometryColumnCapabilities(self) QgsAbstractDatabaseProviderConnection.GeometryColumnCapabilities[source]

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

Added in version 3.16.

Return type:

QgsAbstractDatabaseProviderConnection.GeometryColumnCapabilities

virtual illegalFieldNames(self) Set[str]

Returns a list of field names which are considered illegal by the connection and should not be used when creating or altering fields.

Added in version 3.30.

Return type:

Set[str]

virtual moveTableToSchema(self, sourceSchema: str | None, tableName: str | None, targetSchema: str | None)[source]

Move table to a different schema.

Parameters:
  • sourceSchema (Optional[str]) – name of the source schema.

  • tableName (Optional[str]) – name of the table.

  • targetSchema (Optional[str]) – name of the target schema to move table to.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.44.

abstract nativeTypes(self) List[QgsVectorDataProvider.NativeType]

Returns a list of native types supported by the connection.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.16.

Return type:

List[QgsVectorDataProvider.NativeType]

providerKey(self) str[source]

Returns the provider key.

Added in version 3.16.

Return type:

str

virtual queryBuilder(self) QgsProviderSqlQueryBuilder | None[source]

Returns a SQL query builder for the connection, which provides an interface for provider-specific creation of SQL queries.

The caller takes ownership of the returned object.

Added in version 3.28.

Return type:

Optional[QgsProviderSqlQueryBuilder]

virtual relatedTableTypes(self) List[str][source]

Returns a list of the related table types supported by the database format.

The related table type is a free-form string representing the type of related features, where the exact interpretation is format dependent. For instance, table types from GeoPackage relationships will directly reflect the categories from the GeoPackage related tables extension (i.e. “media”, “simple attributes”, “features”, “attributes” and “tiles”).

Added in version 3.30.

Return type:

List[str]

virtual relationships(self, schema: str | None = '', tableName: str | None = '') List[QgsWeakRelation]

Returns a list of relationships detected in the database.

This is supported on providers with the Capability.RetrieveRelationships capability only.

If a schema and/or tableName are specified, then only relationships where the specified table forms the left (or “parent” / “referenced”) side of the relationship are retrieved.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.28.

Parameters:
  • schema (Optional[str] = '')

  • tableName (Optional[str] = '')

Return type:

List[QgsWeakRelation]

virtual renameField(self, schema: str | None, tableName: str | None, name: str | None, newName: str | None)[source]

Renames an existing field.

Parameters:
  • schema (Optional[str]) – name of the schema (schema is ignored if not supported by the backend).

  • tableName (Optional[str]) – name of the table

  • name (Optional[str]) – current name of field

  • newName (Optional[str]) – new name for field

Note

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

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.28.

virtual renameRasterTable(self, schema: str | None, name: str | None, newName: str | None)[source]

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 (Optional[str])

  • name (Optional[str])

  • newName (Optional[str])

virtual renameSchema(self, name: str | None, newName: str | None)[source]

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 (Optional[str])

  • newName (Optional[str])

virtual renameVectorTable(self, schema: str | None, name: str | None, newName: str | None)[source]

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 (Optional[str])

  • name (Optional[str])

  • newName (Optional[str])

schemas(self) List[str][source]

Returns information about the existing schemas.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Return type:

List[str]

virtual searchLayerMetadata(self, searchContext: QgsMetadataSearchContext, searchString: str | None = '', geographicExtent: QgsRectangle = QgsRectangle(), feedback: QgsFeedback | None = None) List[QgsLayerMetadataProviderResult]

Search the stored layer metadata in the connection, optionally limiting the search to the metadata identifier, title, abstract, keywords and categories. searchContext context for the search searchString limit the search to metadata having an extent intersecting geographicExtent, an optional feedback can be used to monitor and control the search process.

The default implementation raises a QgsNotSupportedException, data providers may implement the search functionality.

A QgsProviderConnectionException is raised in case of errors happening during the search for providers that implement the search functionality.

Return type:

List[QgsLayerMetadataProviderResult]

Returns:

a (possibly empty) list of QgsLayerMetadataProviderResult, throws a QgsProviderConnectionException if any error occurred during the search.

Raises:

Added in version 3.28.

Parameters:
virtual setFieldAlias(self, fieldName: str | None, schema: str | None, tableName: str | None, alias: str | None)[source]

Sets the alias for the existing field with the specified name.

Parameters:
  • fieldName (Optional[str]) – name of the field to be modified

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

  • tableName (Optional[str]) – name of the table

  • alias (Optional[str]) – alias to set for the field. Set to an empty string to remove a previously set alias.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.32.

virtual setFieldComment(self, fieldName: str | None, schema: str | None, tableName: str | None, comment: str | None)[source]

Sets the comment for the existing field with the specified name.

Parameters:
  • fieldName (Optional[str]) – name of the field to be modified

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

  • tableName (Optional[str]) – name of the table

  • comment (Optional[str]) – comment to set for the field. Set to an empty string to remove a previously set comment.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.32.

virtual setFieldDomainName(self, fieldName: str | None, schema: str | None, tableName: str | None, domainName: str | None)[source]

Sets the field domain name for the existing field with the specified name.

Parameters:
  • fieldName (Optional[str]) – name of the field to be modified

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

  • tableName (Optional[str]) – name of the table

  • domainName (Optional[str]) – name of the domain to set for the field. Must be an existing field domain (see fieldDomainNames()). Set to an empty string to remove a previously set domain.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.26.

virtual setTableComment(self, schema: str | None, tableName: str | None, comment: str | None)[source]

Sets the comment for the existing table with the specified name.

Parameters:
  • schema (Optional[str]) – name of the schema (schema is ignored if not supported by the backend).

  • tableName (Optional[str]) – name of the table

  • comment (Optional[str]) – comment to set for the table. Set to an empty string to remove a previously set comment.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.44.

virtual spatialIndexExists(self, schema: str | None, name: str | None, geometryColumn: str | None) bool[source]

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.

Added in version 3.14.

Parameters:
  • schema (Optional[str])

  • name (Optional[str])

  • geometryColumn (Optional[str])

Return type:

bool

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

Added in version 3.22.

Return type:

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

virtual sqlLayerDefinitionCapabilities(self) Qgis.SqlLayerDefinitionCapabilities[source]

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

Added in version 3.22.

Return type:

Qgis.SqlLayerDefinitionCapabilities

virtual sqlOptions(self, layerSource: str | None) QgsAbstractDatabaseProviderConnection.SqlVectorLayerOptions[source]

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.

Added in version 3.22.

Parameters:

layerSource (Optional[str])

Return type:

QgsAbstractDatabaseProviderConnection.SqlVectorLayerOptions

virtual supportedFieldDomainTypes(self) List[Qgis.FieldDomainType]

Returns a list of field domain types which are supported by the provider.

Added in version 3.28.

Return type:

List[Qgis.FieldDomainType]

virtual supportedRelationshipCapabilities(self) Qgis.RelationshipCapabilities[source]

Returns the relationship capabilities supported by the provider.

Added in version 3.30.

Return type:

Qgis.RelationshipCapabilities

supportedRelationshipCardinalities(self) List[Qgis.RelationshipCardinality][source]

Returns a list of relationship cardinalities which are supported by the provider.

Added in version 3.30.

Return type:

List[Qgis.RelationshipCardinality]

supportedRelationshipStrengths(self) List[Qgis.RelationshipStrength][source]

Returns a list of relationship strengths which are supported by the provider.

Added in version 3.30.

Return type:

List[Qgis.RelationshipStrength]

virtual table(self, schema: str | None, table: str | None, feedback: QgsFeedback | None = None) QgsAbstractDatabaseProviderConnection.TableProperty[source]

Returns information on a table in the given schema.

Since QGIS 3.32 the optional feedback argument can be used to cancel the request.

Raises:

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

Note

Not available in Python bindings

Added in version 3.12.

Parameters:
  • schema (Optional[str])

  • table (Optional[str])

  • feedback (Optional[QgsFeedback] = None)

Return type:

QgsAbstractDatabaseProviderConnection.TableProperty

virtual tableExists(self, schema: str | None, name: str | None) bool[source]

Checks whether a table name exists in the given schema.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Parameters:
  • schema (Optional[str])

  • name (Optional[str])

Return type:

bool

abstract tableImportCapabilities(self) Qgis.DatabaseProviderTableImportCapabilities[source]

Represents capabilities of the database provider connection when importing table data.

Added in version 3.44.

Return type:

Qgis.DatabaseProviderTableImportCapabilities

virtual tableUri(self, schema: str | None, name: str | None) str[source]

Returns the URI string for the given table and schema.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.12.

Parameters:
  • schema (Optional[str])

  • name (Optional[str])

Return type:

str

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

Returns information on the tables in the given schema.

Parameters:
  • schema (Optional[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]

virtual updateRelationship(self, relationship: QgsWeakRelation)[source]

Updates an existing relationship in the database.

Raises:

QgsProviderConnectionException – if any errors are encountered.

Added in version 3.30.

Parameters:

relationship (QgsWeakRelation)

virtual vacuum(self, schema: str | None, name: str | None)[source]

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 (Optional[str])

  • name (Optional[str])

virtual validateSqlVectorLayer(self, options: QgsAbstractDatabaseProviderConnection.SqlVectorLayerOptions)[source]

Validates the SQL query options to determine if it is possible to create a vector layer based on a SQL statement and options.

The base class method returns True and does not do any checks.

Parameters:

options (QgsAbstractDatabaseProviderConnection.SqlVectorLayerOptions) -> (bool) – SQL statement and options

Returns:

  • True if the SQL is valid for the provider.

  • message: a translated, user-friendly explanation if the SQL is not valid for the provider.

Raises:

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

Added in version 3.44.