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¶
Base classes¶
An interface for data provider connections. |
Enums
Flags for table properties. |
Abstract Methods
Returns a list of native types supported by the connection. |
|
Represents capabilities of the database provider connection when importing table data. |
Methods
Returns connection capabilities. |
|
Returns extended connection capabilities. |
|
Checks if capability is supported. |
|
Returns a list of field domain names present on the provider. |
|
Returns the provider key. |
|
Returns information about the existing schemas. |
|
Returns a list of relationship cardinalities which are supported by the provider. |
|
Returns a list of relationship strengths which are supported by the provider. |
|
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.
Adds a field. |
|
Adds a new field domain to the database. |
|
Adds a new field relationship to the database. |
|
Creates a new schema with the specified name. |
|
Creates a spatial index for the database table with given schema and name (schema is ignored if not supported by the backend). |
|
Creates and returns a (possibly invalid) vector layer based on a SQL statement and options. |
|
Creates a URI for use with |
|
Creates an empty table with name in the given schema (schema is ignored if not supported by the backend). |
|
Returns the default name to use for a geometry column for the connection. |
|
Returns the default name to use for a primary key column for the connection. |
|
Deletes the field with the specified name. |
|
Deletes an existing relationship in the database. |
|
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). |
|
Drops a raster table with given schema (schema is ignored if not supported by the backend) and name. |
|
Drops an entire schema with the specified name. |
|
Drops a vector (or aspatial) table with given schema (schema is ignored if not supported by the backend) and name. |
|
Executes raw sql and returns the (possibly empty) query results, optionally feedback can be provided. |
|
Executes raw sql and returns the (possibly empty) list of results in a multi-dimensional array, optionally feedback can be provided. |
|
Returns the field domain with the specified name from the provider. |
|
Returns the fields of a table and schema. |
|
Returns connection geometry column capabilities (Z, M, SinglePart, Curves). |
|
Returns a list of field names which are considered illegal by the connection and should not be used when creating or altering fields. |
|
Move table to a different schema. |
|
Returns a SQL query builder for the connection, which provides an interface for provider-specific creation of SQL queries. |
|
Returns a list of the related table types supported by the database format. |
|
Returns a list of relationships detected in the database. |
|
Renames an existing field. |
|
Renames a raster table with given schema (schema is ignored if not supported by the backend) and name. |
|
Renames a schema with the specified name. |
|
Renames a vector or aspatial table with given schema (schema is ignored if not supported by the backend) and name. |
|
Search the stored layer metadata in the connection, optionally limiting the search to the metadata identifier, title, abstract, keywords and categories. |
|
Sets the alias for the existing field with the specified name. |
|
Sets the comment for the existing field with the specified name. |
|
Sets the field domain name for the existing field with the specified name. |
|
Sets the comment for the existing table with the specified name. |
|
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). |
|
Returns a dictionary of SQL keywords supported by the provider. |
|
Returns SQL layer definition capabilities (Filters, GeometryColumn, PrimaryKeys). |
|
Returns the SQL layer options from a layerSource. |
|
Returns a list of field domain types which are supported by the provider. |
|
Returns the relationship capabilities supported by the provider. |
|
Returns information on a table in the given schema. |
|
Checks whether a table name exists in the given schema. |
|
Returns the URI string for the given table and schema. |
|
Updates an existing relationship in the database. |
|
Vacuum the database table with given schema and name (schema is ignored if not supported by the backend). |
|
Validates the SQL query options to determine if it is possible to create a vector layer based on a SQL statement and options. |
Attributes
- 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
andconfiguration
.The connection is not automatically stored in the settings.
See also
store()
- Parameters:
uri (Optional[str])
configuration (Dict[str, Any])
- __init__(a0: QgsAbstractDatabaseProviderConnection)
- Parameters:
- 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()
andnextRow()
or by callingrows()
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
- Return type:
int
- hasNextRow(self) bool ¶
Returns
True
if there are more rows to fetch.See also
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
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.See also
- 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 tableView
: View tableMaterializedView
: Materialized view tableForeign
: Foreign data wrapperIncludeSystemTables
: Include system tablesAdded 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 givensrid
to the geometry column types list.- Parameters:
type (Qgis.WkbType)
- at(self, index: int) QgsAbstractDatabaseProviderConnection.TableProperty ¶
Returns the table property corresponding to the geometry type at the given
index
.- Parameters:
index (int)
- Return type:
- 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:
- 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.
See also
- Return type:
str
- flags(self) QgsAbstractDatabaseProviderConnection.TableFlags ¶
Returns the table flags.
- Return type:
- 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.
See also
- 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:
- 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
- Parameters:
name (Optional[str])
- tableName(self) str ¶
Returns the table name.
See also
- 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
- Return type:
- capabilities2(self) Qgis.DatabaseProviderConnectionCapabilities2 [source]¶
Returns extended connection capabilities.
See also
Added in version 3.32.
- Return type:
- 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
andname
(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.
See also
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 tableoptions
for the backend.- Parameters:
options (QgsAbstractDatabaseProviderConnection.VectorLayerExporterOptions) -> (str) – defines the desired destination table details
- Returns:
destination URI for use with
QgsVectorLayerExporter
providerOptions: a map of options to pass to
createVectorTable()
or the provider’s createEmptyTable method.
- 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 givenschema
(schema is ignored if not supported by the backend).- Raises:
QgsProviderConnectionException – if any errors are encountered.
- Parameters:
schema (Optional[str])
name (Optional[str])
fields (QgsFields)
wkbType (Qgis.WkbType)
overwrite (bool)
options (Optional[Dict[Optional[str], Any]])
- 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
andgeometryColumn
(schema
andgeometryColumn
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) andname
.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) andname
.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, optionallyfeedback
can be provided.See also
- Raises:
QgsProviderConnectionException – if any errors are encountered.
Added in version 3.18.
- Parameters:
sql (Optional[str])
feedback (Optional[QgsFeedback] = None)
- Return type:
- 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, optionallyfeedback
can be provided.See also
- 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.
See also
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
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
andschema
.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:
- virtual geometryColumnCapabilities(self) QgsAbstractDatabaseProviderConnection.GeometryColumnCapabilities [source]¶
Returns connection geometry column capabilities (Z, M, SinglePart, Curves).
Added in version 3.16.
- 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:
- 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]
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/ortableName
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) andname
.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 aQgsProviderConnectionException
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) andname
.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 searchsearchString
limit the search to metadata having an extent intersectinggeographicExtent
, an optionalfeedback
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:
- Returns:
a (possibly empty) list of
QgsLayerMetadataProviderResult
, throws aQgsProviderConnectionException
if any error occurred during the search.- Raises:
Added in version 3.28.
- Parameters:
searchContext (QgsMetadataSearchContext)
searchString (Optional[str] = '')
geographicExtent (
QgsRectangle
= QgsRectangle())feedback (Optional[QgsFeedback] = None)
- 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
andgeometryColumn
(schema
andgeometryColumn
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:
- 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:
- 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:
- 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:
- 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:
- virtual table(self, schema: str | None, table: str | None, feedback: QgsFeedback | None = None) QgsAbstractDatabaseProviderConnection.TableProperty [source]¶
Returns information on a
table
in the givenschema
.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:
- virtual tableExists(self, schema: str | None, name: str | None) bool [source]¶
Checks whether a table
name
exists in the givenschema
.- 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:
- virtual tableUri(self, schema: str | None, name: str | None) str [source]¶
Returns the URI string for the given
table
andschema
.- 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:
- 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
andname
(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 andoptions
.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.
See also
Added in version 3.44.