En esta página

QSqlDriver Class

La clase QSqlDriver es una clase base abstracta que permite acceder a bases de datos SQL específicas. Más información...

Encabezado: #include <QSqlDriver>
CMake: find_package(Qt6 REQUIRED COMPONENTS Sql)
target_link_libraries(mytarget PRIVATE Qt6::Sql)
qmake: QT += sql
Heredado de: QObject

Tipos públicos

enum DriverFeature { Transactions, QuerySize, BLOB, Unicode, PreparedQueries, …, CancelQuery }
enum IdentifierType { FieldName, TableName }
enum NotificationSource { UnknownSource, SelfSource, OtherSource }
enum StatementType { WhereStatement, SelectStatement, UpdateStatement, InsertStatement, DeleteStatement }

Propiedades

Funciones públicas

QSqlDriver(QObject *parent = nullptr)
virtual ~QSqlDriver()
virtual bool beginTransaction()
virtual void close() = 0
virtual bool commitTransaction()
(since 6.9) QString connectionName() const
virtual QSqlResult *createResult() const = 0
virtual QString escapeIdentifier(const QString &identifier, QSqlDriver::IdentifierType type) const
virtual QString formatValue(const QSqlField &field, bool trimStrings = false) const
virtual QVariant handle() const
virtual bool hasFeature(QSqlDriver::DriverFeature feature) const = 0
virtual bool isIdentifierEscaped(const QString &identifier, QSqlDriver::IdentifierType type) const
virtual bool isOpen() const
bool isOpenError() const
QSqlError lastError() const
(since 6.0) virtual int maximumIdentifierLength(QSqlDriver::IdentifierType type) const
QSql::NumericalPrecisionPolicy numericalPrecisionPolicy() const
virtual bool open(const QString &db, const QString &user = QString(), const QString &password = QString(), const QString &host = QString(), int port = -1, const QString &options = QString()) = 0
virtual QSqlIndex primaryIndex(const QString &tableName) const
virtual QSqlRecord record(const QString &tableName) const
virtual bool rollbackTransaction()
void setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)
virtual QString sqlStatement(QSqlDriver::StatementType type, const QString &tableName, const QSqlRecord &rec, bool preparedStatement) const
virtual QString stripDelimiters(const QString &identifier, QSqlDriver::IdentifierType type) const
virtual bool subscribeToNotification(const QString &name)
virtual QStringList subscribedToNotifications() const
virtual QStringList tables(QSql::TableType tableType) const
virtual bool unsubscribeFromNotification(const QString &name)

Señales

void notification(const QString &name, QSqlDriver::NotificationSource source, const QVariant &payload)

Funciones protegidas

virtual void setLastError(const QSqlError &error)
virtual void setOpen(bool open)
virtual void setOpenError(bool error)

Descripción detallada

Esta clase no debe utilizarse directamente. Utiliza en su lugar ` QSqlDatabase `.

Si desea crear sus propios controladores SQL, puede crear una subclase de esta clase y reimplementar sus funciones virtuales puras y aquellas funciones virtuales que necesite. Consulte «Cómo escribir su propio controlador de base de datos » para obtener más información.

Véase también QSqlDatabase y QSqlResult.

Documentación sobre los tipos de miembros

enum QSqlDriver::DriverFeature

Esta enumeración contiene una lista de las funciones que un controlador puede admitir. Utiliza ` hasFeature()` para comprobar si una función es compatible o no. Algunas funciones dependen del servidor de base de datos, por lo que solo pueden determinarse correctamente una vez que se haya establecido con éxito la conexión a la base de datos mediante ` QSqlDatabase::open()`.

ConstanteValorDescripción
QSqlDriver::Transactions0Si el controlador admite transacciones SQL.
QSqlDriver::QuerySize1Si la base de datos es capaz de informar del tamaño de una consulta. Tenga en cuenta que algunas bases de datos no admiten la devolución del tamaño (es decir, el número de filas devueltas) de una consulta; en ese caso, QSqlQuery::size() devolverá -1.
QSqlDriver::BLOB2Si el controlador admite campos de objetos binarios de gran tamaño (BLOB).
QSqlDriver::Unicode3Si el controlador admite cadenas Unicode, siempre que el servidor de la base de datos también las admita.
QSqlDriver::PreparedQueries4Si el controlador admite la ejecución de consultas preparadas.
QSqlDriver::NamedPlaceholders5Si el controlador admite el uso de marcadores de posición con nombre.
QSqlDriver::PositionalPlaceholders6Si el controlador admite el uso de marcadores de posición posicionales.
QSqlDriver::LastInsertId7Si el controlador admite la devolución del ID de la última fila modificada.
QSqlDriver::BatchOperations8Si el controlador admite operaciones por lotes; véase QSqlQuery::execBatch()
QSqlDriver::SimpleLocking9Si el controlador no permite un bloqueo de escritura en una tabla mientras otras consultas tienen un bloqueo de lectura sobre ella.
QSqlDriver::LowPrecisionNumbers10Si el controlador permite recuperar valores numéricos con baja precisión.
QSqlDriver::EventNotifications11Si el controlador admite notificaciones de eventos de la base de datos.
QSqlDriver::FinishQuery12Si el controlador puede realizar alguna limpieza de recursos de bajo nivel cuando se llama a QSqlQuery::finish().
QSqlDriver::MultipleResultSets13Si el controlador puede acceder a múltiples conjuntos de resultados devueltos por sentencias por lotes o procedimientos almacenados.
QSqlDriver::CancelQuery14Si el controlador permite cancelar una consulta en ejecución.

Se puede encontrar más información sobre las características compatibles en la documentación del controladorQt SQL .

Véase también ` hasFeature()`.

enum QSqlDriver::IdentifierType

Esta enumeración contiene una lista de tipos de identificadores SQL.

ConstanteValorDescripción
QSqlDriver::FieldName0Un nombre de campo SQL
QSqlDriver::TableName1Un nombre de tabla SQL

enum QSqlDriver::NotificationSource

Esta enumeración contiene una lista de fuentes de notificaciones SQL.

ConstanteValorDescripción
QSqlDriver::UnknownSource0Se desconoce la fuente de notificación
QSqlDriver::SelfSource1La fuente de notificación es esta conexión
QSqlDriver::OtherSource2La fuente de la notificación es otra conexión

enum QSqlDriver::StatementType

Esta enumeración contiene una lista de los tipos de sentencias (o cláusulas) SQL que el controlador puede crear.

ConstanteValorDescripción
QSqlDriver::WhereStatement0Una instrucción SQL de tipo « WHERE » (por ejemplo, ` WHERE f = 5`).
QSqlDriver::SelectStatement1Una instrucción SQL de tipo « SELECT » (p. ej., SELECT f FROM t).
QSqlDriver::UpdateStatement2Una instrucción SQL de tipo « UPDATE » (p. ej., UPDATE TABLE t set f = 1).
QSqlDriver::InsertStatement3Una instrucción SQL de tipo « INSERT » (p. ej., INSERT INTO t (f) values (1)).
QSqlDriver::DeleteStatement4Una instrucción SQL ` DELETE ` (por ejemplo, ` DELETE FROM t`).

Véase también sqlStatement().

Documentación de la propiedad

[since 6.8] numericalPrecisionPolicy : QSql::NumericalPrecisionPolicy

Esta propiedad define la política de precisión para la conexión a la base de datos.

Nota: La configuración de la política de precisión no afecta a ninguna consulta activa en ese momento.

Esta enumeración se introdujo en Qt 6.8.

Funciones de acceso:

QSql::NumericalPrecisionPolicy numericalPrecisionPolicy() const
void setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)

Véase también QSql::NumericalPrecisionPolicy, QSqlQuery::numericalPrecisionPolicy y QSqlDatabase::numericalPrecisionPolicy.

Documentación de las funciones miembro

[explicit] QSqlDriver::QSqlDriver(QObject *parent = nullptr)

Crea un nuevo controlador con el parent especificado.

[virtual noexcept] QSqlDriver::~QSqlDriver()

Destruye el objeto y libera los recursos asignados.

[virtual] bool QSqlDriver::beginTransaction()

Esta función se invoca para iniciar una transacción. Si se realiza correctamente, devuelve «true»; en caso contrario, devuelve «false». La implementación por defecto no realiza ninguna acción y devuelve « false ».

Véanse también ` commitTransaction()` y ` rollbackTransaction()`.

[pure virtual] void QSqlDriver::close()

Las clases derivadas deben reimplementar esta función virtual pura para cerrar la conexión a la base de datos. Devuelve «true» si se realiza correctamente y «false» en caso de error.

Véase también open() y setOpen().

[virtual] bool QSqlDriver::commitTransaction()

Esta función se invoca para confirmar una transacción. Si se realiza correctamente, devuelve «true»; en caso contrario, devuelve «false». La implementación por defecto no hace nada y devuelve « false ».

Véase también ` beginTransaction()` y ` rollbackTransaction()`.

[since 6.9] QString QSqlDriver::connectionName() const

Devuelve el nombre de la conexión a la base de datos con la que se creó el controlador mediante ` QSqlDatabase::addDatabase()`

Esta función se introdujo en Qt 6.9.

[pure virtual] QSqlResult *QSqlDriver::createResult() const

Crea un resultado SQL vacío en la base de datos. Las clases derivadas deben reimplementar esta función y devolver al llamante un objeto ` QSqlResult ` adecuado para su base de datos.

[virtual] QString QSqlDriver::escapeIdentifier(const QString &identifier, QSqlDriver::IdentifierType type) const

Devuelve el valor « identifier » con los caracteres escapados según las reglas de la base de datos. « identifier » puede ser tanto un nombre de tabla como un nombre de campo, dependiendo de « type ».

La implementación predeterminada no realiza ninguna acción.

Véase también isIdentifierEscaped().

[virtual] QString QSqlDriver::formatValue(const QSqlField &field, bool trimStrings = false) const

Devuelve una representación en forma de cadena del valor « field » de la base de datos. Se utiliza, por ejemplo, al crear sentencias INSERT y UPDATE.

La implementación predeterminada devuelve el valor formateado como cadena según las siguientes reglas:

  • Si ` field ` es un dato de tipo carácter, el valor se devuelve entre comillas simples, lo cual es adecuado para muchas bases de datos SQL. Cualquier carácter de comilla simple incrustado se escapa (se sustituye por dos comillas simples). Si ` trimStrings ` es verdadero (el valor por defecto es falso), se eliminan todos los espacios en blanco al final del campo.
  • Si ` field ` son datos de fecha y hora, el valor se formatea según el formato ISO y se encierra entre comillas simples. Si los datos de fecha y hora no son válidos, se devuelve «NULL».
  • Si field son datos de bytearray y el controlador puede editar campos binarios, el valor se formatea como una cadena hexadecimal.
  • Para cualquier otro tipo de campo, se llama a toString() sobre su valor y se devuelve el resultado de esta operación.

Véase también QVariant::toString().

[virtual] QVariant QSqlDriver::handle() const

Devuelve el identificador de base de datos de bajo nivel envuelto en un objeto ` QVariant ` o una variante no válida si no existe ningún identificador.

Advertencia: Utiliza esto con mucho cuidado y solo si sabes lo que estás haciendo.

Advertencia: El identificador devuelto aquí puede convertirse en un puntero obsoleto si se modifica la conexión (por ejemplo, si se cierra la conexión).

Advertencia: El identificador puede ser NULL si la conexión aún no está abierta.

El identificador devuelto aquí depende de la base de datos; debes consultar el nombre del tipo de la variante antes de acceder a ella.

Este ejemplo recupera el identificador de una conexión a SQLite:

QSqlDatabase db = QSqlDatabase::database();
QVariant v = db.driver()->handle();
if (v.isValid() && (qstrcmp(v.typeName(), "sqlite3*") == 0)) {
    // v.data() returns a pointer to the handle
    sqlite3 *handle = *static_cast<sqlite3 **>(v.data());
    if (handle) {
        // ...
    }
}

Este fragmento de código devuelve el identificador para PostgreSQL o MySQL:

if (qstrcmp(v.typeName(), "PGconn*") == 0) {
    PGconn *handle = *static_cast<PGconn **>(v.data());
    if (handle) {
        // ...
    }
}

if (qstrcmp(v.typeName(), "MYSQL*") == 0) {
    MYSQL *handle = *static_cast<MYSQL **>(v.data());
    if (handle) {
        // ...
    }
}

Véase también ` QSqlResult::handle()`.

[pure virtual] bool QSqlDriver::hasFeature(QSqlDriver::DriverFeature feature) const

Devuelve ` true ` si el controlador admite la característica ` feature`; en caso contrario, devuelve ` false`.

Ten en cuenta que algunas bases de datos deben llamar a ` open()` antes de que se pueda determinar esto.

Véase también DriverFeature.

[virtual] bool QSqlDriver::isIdentifierEscaped(const QString &identifier, QSqlDriver::IdentifierType type) const

Devuelve si ` identifier ` está escapado según las reglas de la base de datos. ` identifier ` puede ser tanto un nombre de tabla como un nombre de campo, dependiendo de ` type`.

Reimplementa esta función si deseas proporcionar tu propia implementación en tu subclase de ` QSqlDriver `,

Véase también stripDelimiters() y escapeIdentifier().

[virtual] bool QSqlDriver::isOpen() const

Devuelve « true » si la conexión a la base de datos está abierta; en caso contrario, devuelve «false».

bool QSqlDriver::isOpenError() const

Devuelve « true » si se ha producido un error al establecer la conexión con la base de datos; en caso contrario, devuelve « false ».

QSqlError QSqlDriver::lastError() const

Devuelve un objeto ` QSqlError ` que contiene información sobre el último error que se ha producido en la base de datos.

Véase también setLastError().

[virtual, since 6.0] int QSqlDriver::maximumIdentifierLength(QSqlDriver::IdentifierType type) const

Devuelve la longitud máxima del identificador « type » según la configuración de la base de datos. Devuelve INT_MAX por defecto si la base de datos no tiene un límite máximo.

Esta función se introdujo en Qt 6.0.

[signal] void QSqlDriver::notification(const QString &name, QSqlDriver::NotificationSource source, const QVariant &payload)

Esta señal se emite cuando la base de datos envía una notificación de evento a la que el controlador está suscrito. name identifica la notificación de evento, source indica la fuente de la señal y payload contiene los datos adicionales que, opcionalmente, se envían junto con la notificación.

Véase también subscribeToNotification().

QSql::NumericalPrecisionPolicy QSqlDriver::numericalPrecisionPolicy() const

Devuelve la propiedad `numericalPrecisionPolicy`.

Nota: Funcióngetter para la propiedad «numericalPrecisionPolicy».

Véase también ` setNumericalPrecisionPolicy()`.

[pure virtual] bool QSqlDriver::open(const QString &db, const QString &user = QString(), const QString &password = QString(), const QString &host = QString(), int port = -1, const QString &options = QString())

Las clases derivadas deben reimplementar esta función virtual pura para abrir una conexión a la base de datos en db, utilizando el nombre de usuario user, la contraseña password, el servidor host, el puerto port y las opciones de conexión options.

La función debe devolver «true» si se ejecuta correctamente y «false» si falla.

Véase también setOpen().

[virtual] QSqlIndex QSqlDriver::primaryIndex(const QString &tableName) const

Devuelve el índice primario de la tabla tableName. Devuelve un objeto de tipo ` QSqlIndex ` vacío si la tabla no tiene índice primario. La implementación por defecto devuelve un índice vacío.

[virtual] QSqlRecord QSqlDriver::record(const QString &tableName) const

Devuelve un objeto ` QSqlRecord ` que contiene los nombres de los campos de la tabla ` tableName`. Si dicha tabla no existe, se devuelve un registro vacío. La implementación por defecto devuelve un registro vacío.

[virtual] bool QSqlDriver::rollbackTransaction()

Esta función se invoca para revertir una transacción. Si se ejecuta correctamente, devuelve «true»; en caso contrario, devuelve «false». La implementación por defecto no realiza ninguna acción y devuelve « false ».

Véase también ` beginTransaction()` y ` commitTransaction()`.

[virtual protected] void QSqlDriver::setLastError(const QSqlError &error)

Esta función se utiliza para establecer el valor del último error, error, que se produjo en la base de datos.

Véase también lastError().

void QSqlDriver::setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)

Establece « numericalPrecisionPolicy » en « precisionPolicy ».

Nota: Funciónde asignación para la propiedad numericalPrecisionPolicy.

Véase también numericalPrecisionPolicy().

[virtual protected] void QSqlDriver::setOpen(bool open)

Esta función establece el estado de apertura de la base de datos en « open ». Las clases derivadas pueden utilizar esta función para informar del estado de « open()».

Véanse también open() y setOpenError().

[virtual protected] void QSqlDriver::setOpenError(bool error)

Esta función establece el estado de error de apertura de la base de datos en « error ». Las clases derivadas pueden utilizar esta función para informar del estado de « open()». Ten en cuenta que, si « error » es verdadero, el estado de apertura de la base de datos se establece en «cerrado» (es decir, « isOpen()» devuelve « false »).

Véase también isOpenError(), open() y setOpen().

[virtual] QString QSqlDriver::sqlStatement(QSqlDriver::StatementType type, const QString &tableName, const QSqlRecord &rec, bool preparedStatement) const

Devuelve una instrucción SQL de tipo type para la tabla tableName con los valores de rec. Si preparedStatement es verdadero, la cadena contendrá marcadores de posición en lugar de valores.

El indicador generado en cada campo de rec determina si el campo se incluye en la instrucción generada.

Este método se puede utilizar para manipular tablas sin tener que preocuparse por los dialectos SQL dependientes de la base de datos. En el caso de las sentencias no preparadas, los valores se escaparán correctamente.

En la instrucción WHERE, cada campo no nulo de ` rec ` especifica una condición de filtro de igualdad con el valor del campo o, si está preparada, un marcador de posición. Sin embargo, esté preparada o no, un campo nulo especifica la condición `IS NULL` y nunca introduce un marcador de posición. La aplicación no debe intentar vincular datos al campo nulo durante la ejecución. El campo debe establecerse en algún valor no nulo si se desea un marcador de posición. Además, dado que los campos no nulos especifican condiciones de igualdad y que el valor NULL de SQL no es igual a nada, ni siquiera a sí mismo, por lo general no resulta útil vincular un valor nulo a un marcador de posición.

[virtual] QString QSqlDriver::stripDelimiters(const QString &identifier, QSqlDriver::IdentifierType type) const

Devuelve el objeto ` identifier ` sin los delimitadores iniciales y finales; ` identifier ` puede ser tanto un nombre de tabla como un nombre de campo, dependiendo de ` type`. Si ` identifier ` no tiene caracteres delimitadores iniciales ni finales, se devuelve ` identifier ` sin modificaciones.

Reimplementa esta función si deseas proporcionar tu propia implementación en tu subclase de ` QSqlDriver `,

Véase también isIdentifierEscaped().

[virtual] bool QSqlDriver::subscribeToNotification(const QString &name)

Esta función se invoca para suscribirse a las notificaciones de eventos de la base de datos. ` name ` identifica la notificación de evento.

Si se realiza correctamente, devuelve «true»; en caso contrario, devuelve «false».

La base de datos debe estar abierta cuando se invoca esta función. Cuando se cierra la base de datos llamando a ` close()`, todas las suscripciones a notificaciones de eventos se cancelan automáticamente. Tenga en cuenta que llamar a ` open()` sobre una base de datos ya abierta puede provocar implícitamente que se llame a ` close()`, lo que hará que el controlador se dé de baja de todas las notificaciones de eventos.

Cuando la base de datos envía una notificación de evento identificada por name, se emite la señal notification().

Reimplementa esta función si deseas proporcionar soporte para notificaciones de eventos en tu propia subclase de QSqlDriver,

Véanse también unsubscribeFromNotification(), subscribedToNotifications() y QSqlDriver::hasFeature().

[virtual] QStringList QSqlDriver::subscribedToNotifications() const

Devuelve una lista con los nombres de las notificaciones de eventos a las que estás suscrito actualmente.

Reimplementa esta función si deseas proporcionar soporte para notificaciones de eventos en tu propia subclase de ` QSqlDriver `,

Véase también ` subscribeToNotification()` y ` unsubscribeFromNotification()`.

[virtual] QStringList QSqlDriver::tables(QSql::TableType tableType) const

Devuelve una lista con los nombres de las tablas de la base de datos. La implementación por defecto devuelve una lista vacía.

El argumento ` tableType ` describe qué tipos de tablas deben devolverse. Por motivos de compatibilidad binaria, la cadena contiene el valor de la enumeración `QSql::TableTypes` como texto. Una cadena vacía debe tratarse como ` QSql::Tables ` para garantizar la compatibilidad con versiones anteriores.

[virtual] bool QSqlDriver::unsubscribeFromNotification(const QString &name)

Esta función se invoca para darse de baja de las notificaciones de eventos de la base de datos. ` name ` identifica la notificación de evento.

Si se ejecuta correctamente, devuelve «true»; en caso contrario, devuelve «false».

La base de datos debe estar abierta cuando se invoque a esta función. Todas las suscripciones a notificaciones de eventos se cancelan automáticamente al invocar la función close().

Tras llamar a esta función, la señal ` notification()` ya no se emitirá cuando la base de datos publique una notificación de evento identificada por ` name `.

Reimplementa esta función si deseas proporcionar compatibilidad con las notificaciones de eventos en tu propia subclase de ` QSqlDriver `,

Véase también ` subscribeToNotification()` y ` subscribedToNotifications()`.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.