qgsabstractdatabaseproviderconnection.sip.in

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/providers/qgsabstractdatabaseproviderconnection.h           *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/




class QgsAbstractDatabaseProviderConnection : QgsAbstractProviderConnection
{
%Docstring(signature="appended")
The :py:class:`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.

.. versionadded:: 3.10
%End

%TypeHeaderCode
#include "qgsabstractdatabaseproviderconnection.h"
%End
  public:
    static const QMetaObject staticMetaObject;

  public:

    enum TableFlag
    {
      Aspatial,
      Vector,
      Raster,
      View,
      MaterializedView,
      Foreign,
    };

    typedef QFlags<QgsAbstractDatabaseProviderConnection::TableFlag> TableFlags;


    struct QueryResult
    {

        QStringList columns() const;
%Docstring
Returns the column names.
%End

        QList<QList<QVariant> > rows( QgsFeedback *feedback = 0 );
%Docstring
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.
%End

        bool hasNextRow() const;
%Docstring
Returns ``True`` if there are more rows to fetch.

.. seealso:: :py:func:`nextRow`

.. seealso:: :py:func:`rewind`
%End

        QList<QVariant> nextRow() const;
%Docstring
Returns the next result row or an empty row if there are no rows left.

.. seealso:: :py:func:`hasNextRow`

.. seealso:: :py:func:`rewind`
%End

        long long fetchedRowCount( ) const;
%Docstring
Returns the number of fetched rows.

.. seealso:: :py:func:`rowCount`
%End

        long long rowCount( ) const;
%Docstring
Returns the number of rows returned by a SELECT query or Qgis.FeatureCountState.UnknownCount if unknown.

.. seealso:: :py:func:`fetchedRowCount`
%End


        // Python iterator
        QueryResult *__iter__();
%MethodCode
        sipRes = sipCpp;
%End

        SIP_PYOBJECT __next__();
%MethodCode
        QList<QVariant> result;
        Py_BEGIN_ALLOW_THREADS
        result = sipCpp->nextRow( );
        Py_END_ALLOW_THREADS
        if ( ! result.isEmpty() )
        {
          const sipTypeDef *qvariantlist_type = sipFindType( "QList<QVariant>" );
          sipRes = sipConvertFromNewType( new QList<QVariant>( result ), qvariantlist_type, Py_None );
        }
        else
        {
          PyErr_SetString( PyExc_StopIteration, "" );
        }
%End






        double queryExecutionTime( );
%Docstring
Returns the query execution time in milliseconds.
%End

        void setQueryExecutionTime( double queryExecutionTime );
%Docstring
Sets the query execution time to ``queryExecutionTime`` milliseconds.
%End


    };

    struct SqlVectorLayerOptions
    {
      QString sql; //!< The SQL expression that defines the SQL (query) layer
      QString filter; //!< Additional subset string (provider-side filter), not all data providers support this feature: check support with SqlLayerDefinitionCapability::Filters capability
      QString layerName; //!< Optional name for the new layer
      QStringList primaryKeyColumns; //!< List of primary key column names
      QString geometryColumn; //!< Name of the geometry column
      bool disableSelectAtId;
    };

    struct TableProperty
    {

        SIP_PYOBJECT __repr__();
%MethodCode
        QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty: '%1'>" ).arg( sipCpp->tableName() );
        sipRes = PyUnicode_FromString( str.toUtf8().constData() );
%End

        struct GeometryColumnType
        {
          SIP_PYOBJECT __repr__();
%MethodCode
          QString str = QStringLiteral( "<QgsAbstractDatabaseProviderConnection.TableProperty.GeometryColumnType: '%1, %2'>" ).arg( QgsWkbTypes::displayString( sipCpp->wkbType ), sipCpp->crs.authid() );
          sipRes = PyUnicode_FromString( str.toUtf8().constData() );
%End
          QgsWkbTypes::Type wkbType;
          QgsCoordinateReferenceSystem crs;

          bool operator==( const GeometryColumnType &other ) const;
        };

      public:

        QString tableName() const;
%Docstring
Returns the table name.

.. seealso:: :py:func:`defaultName`
%End

        void setTableName( const QString &name );
%Docstring
Sets the table name to ``name``.

.. seealso:: :py:func:`defaultName`
%End

        void addGeometryColumnType( const QgsWkbTypes::Type &type, const QgsCoordinateReferenceSystem &crs );
%Docstring
Appends the geometry column ``type`` with the given ``srid`` to the geometry column types list.
%End

        QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> geometryColumnTypes() const;
%Docstring
Returns the list of geometry column types and CRSs.

The method returns a list of GeometryColumnType.
%End

        void setGeometryColumnTypes( const QList<QgsAbstractDatabaseProviderConnection::TableProperty::GeometryColumnType> &geometryColumnTypes );
%Docstring
Sets the geometry column types to ``geometryColumnTypes``.
%End

        QString defaultName() const;
%Docstring
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.

.. seealso:: :py:func:`geometryColumnCount`
%End

        TableProperty at( int index ) const;
%Docstring
Returns the table property corresponding to the geometry type at
the given ``index``.
%End

        QString schema() const;
%Docstring
Returns the schema or an empty string for backends that do not support a schema.
%End

        void setSchema( const QString &schema );
%Docstring
Sets the ``schema``.
%End

        QString geometryColumn() const;
%Docstring
Returns the geometry column name.
%End

        void setGeometryColumn( const QString &geometryColumn );
%Docstring
Sets the geometry column name to ``geometryColumn``.
%End

        QStringList primaryKeyColumns() const;
%Docstring
Returns the list of primary key column names.
%End

        void setPrimaryKeyColumns( const QStringList &primaryKeyColumns );
%Docstring
Sets the primary key column names to ``primaryKeyColumns``.
%End

        QList<QgsCoordinateReferenceSystem> crsList() const;
%Docstring
Returns the list of CRSs supported by the geometry column.
%End

        TableFlags flags() const;
%Docstring
Returns the table flags.
%End

        void setFlags( const TableFlags &flags );
%Docstring
Sets the table ``flags``.
%End

        QString comment() const;
%Docstring
Returns the table comment.
%End

        void setComment( const QString &comment );
%Docstring
Sets the table ``comment``.
%End

        QVariantMap info() const;
%Docstring
Returns additional information about the table.

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

        void setInfo( const QVariantMap &info );
%Docstring
Sets additional information about the table to ``info``.

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

        int geometryColumnCount() const;
%Docstring
Returns the number of geometry columns in the original table this entry refers to.

This information is used internally to build the :py:func:`defaultName`.
%End

        void setGeometryColumnCount( int geometryColumnCount );
%Docstring
Sets the ``geometryColumnCount``.
%End

        void setFlag( const TableFlag &flag );
%Docstring
Sets a ``flag``.
%End

        int maxCoordinateDimensions() const;
%Docstring
Returns the maximum coordinate dimensions of the geometries of a vector table.

This information is calculated from the geometry columns types.

.. seealso:: :py:func:`geometryColumnTypes`
%End

        bool operator==( const QgsAbstractDatabaseProviderConnection::TableProperty &other ) const;

    };

    struct SpatialIndexOptions
    {
      QString geometryColumnName;
    };

    enum Capability
    {
      CreateVectorTable,
      DropRasterTable,
      DropVectorTable,
      RenameVectorTable,
      RenameRasterTable,
      CreateSchema,
      DropSchema,
      RenameSchema,
      ExecuteSql,
      Vacuum,
      Tables,
      Schemas,
      SqlLayers,
      TableExists,
      Spatial,
      CreateSpatialIndex,
      SpatialIndexExists,
      DeleteSpatialIndex,
      DeleteField,
      DeleteFieldCascade,
      AddField,
    };
    typedef QFlags<QgsAbstractDatabaseProviderConnection::Capability> Capabilities;


    enum GeometryColumnCapability
    {
      Z,
      M,
      SinglePart,
      Curves
    };

    typedef QFlags<QgsAbstractDatabaseProviderConnection::GeometryColumnCapability> GeometryColumnCapabilities;


    QgsAbstractDatabaseProviderConnection( const QString &name );
%Docstring
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.
%End

    QgsAbstractDatabaseProviderConnection( const QString &uri, const QVariantMap &configuration );
%Docstring
Creates a new connection from the given ``uri`` and ``configuration``.

The connection is not automatically stored in the settings.

.. seealso:: :py:func:`store`
%End



    Capabilities capabilities() const;
%Docstring
Returns connection capabilities
%End

    virtual GeometryColumnCapabilities geometryColumnCapabilities();
%Docstring
Returns connection geometry column capabilities (Z, M, SinglePart, Curves).

.. versionadded:: 3.16
%End

    virtual Qgis::SqlLayerDefinitionCapabilities sqlLayerDefinitionCapabilities();
%Docstring
Returns SQL layer definition capabilities (Filters, GeometryColumn, PrimaryKeys).

.. versionadded:: 3.22
%End


    virtual QString tableUri( const QString &schema, const QString &name ) const throw( QgsProviderConnectionException );
%Docstring
Returns the URI string for the given ``table`` and ``schema``.

:raises QgsProviderConnectionException: if any errors are encountered.

.. versionadded:: 3.12
%End

    virtual void createVectorTable( const QString &schema, const QString &name, const QgsFields &fields, QgsWkbTypes::Type wkbType, const QgsCoordinateReferenceSystem &srs, bool overwrite, const QMap<QString, QVariant> *options ) const throw( QgsProviderConnectionException );
%Docstring
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.
%End

    virtual bool tableExists( const QString &schema, const QString &name ) const throw( QgsProviderConnectionException );
%Docstring
Checks whether a table ``name`` exists in the given ``schema``.

:raises QgsProviderConnectionException: if any errors are encountered.
%End

    virtual void dropVectorTable( const QString &schema, const QString &name ) const throw( QgsProviderConnectionException );
%Docstring
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.
%End

    virtual void dropRasterTable( const QString &schema, const QString &name ) const throw( QgsProviderConnectionException );
%Docstring
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.
%End

    virtual void renameVectorTable( const QString &schema, const QString &name, const QString &newName ) const throw( QgsProviderConnectionException );
%Docstring
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.
%End

    virtual void renameRasterTable( const QString &schema, const QString &name, const QString &newName ) const throw( QgsProviderConnectionException );
%Docstring
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.
%End

    virtual void createSchema( const QString &name ) const throw( QgsProviderConnectionException );
%Docstring
Creates a new schema with the specified ``name``.

:raises QgsProviderConnectionException: if any errors are encountered.
%End

    virtual void dropSchema( const QString &name, bool force = false ) const throw( QgsProviderConnectionException );
%Docstring
Drops an entire schema with the specified name.

:param name: name of the schema to be dropped
:param force: 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.
%End

    virtual void deleteField( const QString &fieldName, const QString &schema, const QString &tableName, bool force = false ) const throw( QgsProviderConnectionException );
%Docstring
Deletes the field with the specified name.

:param fieldName: name of the field to be deleted
:param schema: name of the schema (schema is ignored if not supported by the backend).
:param tableName: name of the table
:param force: 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.

.. versionadded:: 3.16
%End

    virtual void addField( const QgsField &field, const QString &schema, const QString &tableName ) const throw( QgsProviderConnectionException );
%Docstring
Adds a field.

:param field: specification of the new field
:param schema: name of the schema (schema is ignored if not supported by the backend).
:param tableName: 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.

.. versionadded:: 3.16
%End

    virtual void renameSchema( const QString &name, const QString &newName ) const throw( QgsProviderConnectionException );
%Docstring
Renames a schema with the specified ``name``.
Raises a :py:class:`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.
%End

    virtual QList<QList<QVariant>> executeSql( const QString &sql, QgsFeedback *feedback = 0 ) const throw( QgsProviderConnectionException );
%Docstring
Executes raw ``sql`` and returns the (possibly empty) list of results in a multi-dimensional array, optionally ``feedback`` can be provided.

.. seealso:: :py:func:`execSql`

:raises QgsProviderConnectionException: if any errors are encountered.
%End

    virtual QgsVectorLayer *createSqlVectorLayer( const SqlVectorLayerOptions &options ) const throw( QgsProviderConnectionException ) /Factory/;
%Docstring
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.

.. versionadded:: 3.22
%End

    virtual QueryResult execSql( const QString &sql, QgsFeedback *feedback = 0 ) const throw( QgsProviderConnectionException );
%Docstring
Executes raw ``sql`` and returns the (possibly empty) query results, optionally ``feedback`` can be provided.

.. seealso:: :py:func:`executeSql`

:raises QgsProviderConnectionException: if any errors are encountered.

.. versionadded:: 3.18
%End

    virtual void vacuum( const QString &schema, const QString &name ) const throw( QgsProviderConnectionException );
%Docstring
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.
%End

    virtual void createSpatialIndex( const QString &schema, const QString &name, const QgsAbstractDatabaseProviderConnection::SpatialIndexOptions &options = QgsAbstractDatabaseProviderConnection::SpatialIndexOptions() ) const throw( QgsProviderConnectionException );
%Docstring
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.

.. versionadded:: 3.14
%End

    virtual bool spatialIndexExists( const QString &schema, const QString &name, const QString &geometryColumn ) const throw( QgsProviderConnectionException );
%Docstring
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.

.. versionadded:: 3.14
%End

    virtual void deleteSpatialIndex( const QString &schema, const QString &name, const QString &geometryColumn ) const throw( QgsProviderConnectionException );
%Docstring
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.

.. versionadded:: 3.14
%End


    virtual QgsAbstractDatabaseProviderConnection::TableProperty table( const QString &schema, const QString &table ) const throw( QgsProviderConnectionException );
%Docstring
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

.. versionadded:: 3.12
%End

    QList<QgsAbstractDatabaseProviderConnection::TableProperty> tablesInt( const QString &schema = QString(), const int flags = 0 ) const throw( QgsProviderConnectionException ) /PyName=tables/;
%Docstring
Returns information on the tables in the given schema.

:param schema: name of the schema (ignored if not supported by the backend)
:param flags: filter tables by flags, this option completely overrides search options stored in the connection

:raises QgsProviderConnectionException: if any errors are encountered.
%End



    virtual QStringList schemas() const throw( QgsProviderConnectionException );
%Docstring
Returns information about the existing schemas.

:raises QgsProviderConnectionException: if any errors are encountered.
%End

    virtual QgsFields fields( const QString &schema, const QString &table ) const throw( QgsProviderConnectionException );
%Docstring
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.

.. versionadded:: 3.16
%End

    virtual QList< QgsVectorDataProvider::NativeType > nativeTypes() const throw( QgsProviderConnectionException ) = 0;
%Docstring
Returns a list of native types supported by the connection.

:raises QgsProviderConnectionException: if any errors are encountered.

.. versionadded:: 3.16
%End

    QString providerKey() const;
%Docstring
Returns the provider key.

.. versionadded:: 3.16
%End

    virtual QMultiMap<Qgis::SqlKeywordCategory, QStringList> sqlDictionary();
%Docstring
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.

.. versionadded:: 3.22
%End

  protected:


    void checkCapability( Capability capability ) const;
%Docstring
Checks if ``capability`` is supported.

:raises QgsProviderConnectionException: if the capability is not supported
%End


};

QFlags<QgsAbstractDatabaseProviderConnection::Capability> operator|(QgsAbstractDatabaseProviderConnection::Capability f1, QFlags<QgsAbstractDatabaseProviderConnection::Capability> f2);


/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/providers/qgsabstractdatabaseproviderconnection.h           *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/