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 |
- Lista de todos los miembros, incluidos los heredados
- QSqlDriver forma parte de las clases de bases de datos.
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
(since 6.8)numericalPrecisionPolicy : QSql::NumericalPrecisionPolicy
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()`.
| Constante | Valor | Descripción |
|---|---|---|
QSqlDriver::Transactions | 0 | Si el controlador admite transacciones SQL. |
QSqlDriver::QuerySize | 1 | Si 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::BLOB | 2 | Si el controlador admite campos de objetos binarios de gran tamaño (BLOB). |
QSqlDriver::Unicode | 3 | Si el controlador admite cadenas Unicode, siempre que el servidor de la base de datos también las admita. |
QSqlDriver::PreparedQueries | 4 | Si el controlador admite la ejecución de consultas preparadas. |
QSqlDriver::NamedPlaceholders | 5 | Si el controlador admite el uso de marcadores de posición con nombre. |
QSqlDriver::PositionalPlaceholders | 6 | Si el controlador admite el uso de marcadores de posición posicionales. |
QSqlDriver::LastInsertId | 7 | Si el controlador admite la devolución del ID de la última fila modificada. |
QSqlDriver::BatchOperations | 8 | Si el controlador admite operaciones por lotes; véase QSqlQuery::execBatch() |
QSqlDriver::SimpleLocking | 9 | Si el controlador no permite un bloqueo de escritura en una tabla mientras otras consultas tienen un bloqueo de lectura sobre ella. |
QSqlDriver::LowPrecisionNumbers | 10 | Si el controlador permite recuperar valores numéricos con baja precisión. |
QSqlDriver::EventNotifications | 11 | Si el controlador admite notificaciones de eventos de la base de datos. |
QSqlDriver::FinishQuery | 12 | Si el controlador puede realizar alguna limpieza de recursos de bajo nivel cuando se llama a QSqlQuery::finish(). |
QSqlDriver::MultipleResultSets | 13 | Si el controlador puede acceder a múltiples conjuntos de resultados devueltos por sentencias por lotes o procedimientos almacenados. |
QSqlDriver::CancelQuery | 14 | Si 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.
| Constante | Valor | Descripción |
|---|---|---|
QSqlDriver::FieldName | 0 | Un nombre de campo SQL |
QSqlDriver::TableName | 1 | Un nombre de tabla SQL |
enum QSqlDriver::NotificationSource
Esta enumeración contiene una lista de fuentes de notificaciones SQL.
| Constante | Valor | Descripción |
|---|---|---|
QSqlDriver::UnknownSource | 0 | Se desconoce la fuente de notificación |
QSqlDriver::SelfSource | 1 | La fuente de notificación es esta conexión |
QSqlDriver::OtherSource | 2 | La 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.
| Constante | Valor | Descripción |
|---|---|---|
QSqlDriver::WhereStatement | 0 | Una instrucción SQL de tipo « WHERE » (por ejemplo, ` WHERE f = 5`). |
QSqlDriver::SelectStatement | 1 | Una instrucción SQL de tipo « SELECT » (p. ej., SELECT f FROM t). |
QSqlDriver::UpdateStatement | 2 | Una instrucción SQL de tipo « UPDATE » (p. ej., UPDATE TABLE t set f = 1). |
QSqlDriver::InsertStatement | 3 | Una instrucción SQL de tipo « INSERT » (p. ej., INSERT INTO t (f) values (1)). |
QSqlDriver::DeleteStatement | 4 | Una 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.