En esta página

Ejecución de sentencias SQL

La clase ` QSqlQuery ` proporciona una interfaz para ejecutar sentencias SQL y navegar por el conjunto de resultados de una consulta.

Las clases ` QSqlQueryModel ` y ` QSqlTableModel `, descritas en la siguiente sección, proporcionan una interfaz de nivel superior para acceder a las bases de datos. Si no estás familiarizado con SQL, quizá te interese pasar directamente a la siguiente sección («Uso de las clases del modelo SQL»).

Ejecución de una consulta

Para ejecutar una instrucción SQL, basta con crear un objeto ` QSqlQuery ` y llamar a ` QSqlQuery::exec()` de la siguiente manera:

    QSqlQuery query;
    query.exec("SELECT name, salary FROM employee WHERE salary > 50000");

El constructor de ` QSqlQuery ` acepta un objeto ` QSqlDatabase ` opcional que especifica qué conexión a la base de datos se debe utilizar. En el ejemplo anterior, no especificamos ninguna conexión, por lo que se utiliza la conexión predeterminada.

Si se produce un error, exec() devuelve false. El error queda entonces disponible como QSqlQuery::lastError().

QSqlQuery permite acceder al conjunto de resultados un registro a la vez. Tras la llamada a ` exec()`, el puntero interno de ` QSqlQuery` se sitúa una posición antes del primer registro. Debemos llamar una vez a ` QSqlQuery::next()` para avanzar hasta el primer registro y, a continuación, volver a llamar repetidamente a ` next()` para acceder a los demás registros, hasta que devuelva ` false`. A continuación se muestra un bucle típico que recorre todos los registros en orden:

   while (query.next()) {
        QString name = query.value(0).toString();
        int salary = query.value(1).toInt();
        qDebug() << name << salary;
    }

La función QSqlQuery::value() devuelve el valor de un campo del registro actual. Los campos se especifican como índices que comienzan en cero. ` QSqlQuery::value()` devuelve un ` QVariant`, un tipo que puede contener diversos tipos de datos de C++ y del núcleo de Qt, tales como ` int`, ` QString` y ` QByteArray`. Los distintos tipos de la base de datos se asignan automáticamente a su equivalente más cercano en Qt. En el fragmento de código, llamamos a ` QVariant::toString()` y ` QVariant::toInt()` para convertir variantes en ` QString ` y ` int`.

Para obtener una visión general de los tipos recomendados para su uso con las bases de datos compatibles con Qt, consulta esta tabla.

Puede navegar por el conjunto de datos utilizando QSqlQuery::next(), QSqlQuery::previous(), QSqlQuery::first(), QSqlQuery::last() y QSqlQuery::seek(). El índice de la fila actual se obtiene mediante QSqlQuery::at(), y el número total de filas del conjunto de resultados está disponible como QSqlQuery::size() para las bases de datos que lo admitan.

Para determinar si un controlador de base de datos admite una característica determinada, utilice la función ` QSqlDriver::hasFeature()`. En el siguiente ejemplo, llamamos a ` QSqlQuery::size()` para determinar el tamaño de un conjunto de resultados; si la base de datos subyacente admite esa característica, se utiliza dicha función; de lo contrario, nos desplazamos hasta el último registro y utilizamos la posición de la consulta para saber cuántos registros hay.

    QSqlQuery query;
    int numRows;
    query.exec("SELECT name, salary FROM employee WHERE salary > 50000");

    QSqlDatabase defaultDB = QSqlDatabase::database();
    if (defaultDB.driver()->hasFeature(QSqlDriver::QuerySize)) {
        numRows = query.size();
    } else {
        // this can be very slow
        query.last();
        numRows = query.at() + 1;
    }

Si se navega dentro de un conjunto de resultados y se utilizan next() y seek() únicamente para avanzar, se puede llamar a QSqlQuery::setForwardOnly(true) antes de llamar a exec(). Se trata de una optimización sencilla que acelerará significativamente la consulta al trabajar con conjuntos de resultados de gran tamaño.

Inserción, actualización y eliminación de registros

QSqlQuery puede ejecutar sentencias SQL arbitrarias, no solo sentencias ` SELECT`. El siguiente ejemplo inserta un registro en una tabla utilizando ` INSERT`:

    QSqlQuery query;
    query.exec("INSERT INTO employee (id, name, salary) "
               "VALUES (1001, 'Thad Beaumont', 65000)");

Si deseas insertar muchos registros a la vez, suele ser más eficiente separar la consulta de los valores reales que se van a insertar. Esto se puede hacer utilizando marcadores de posición. Qt admite dos sintaxis de marcadores de posición: el enlace por nombre y el enlace posicional. A continuación se muestra un ejemplo de enlace por nombre:

    QSqlQuery query;
    query.prepare("INSERT INTO employee (id, name, salary) "
                  "VALUES (:id, :name, :salary)");
    query.bindValue(":id", 1001);
    query.bindValue(":name", "Thad Beaumont");
    query.bindValue(":salary", 65000);
    query.exec();

A continuación se muestra un ejemplo de enlace posicional:

    QSqlQuery query;
    query.prepare("INSERT INTO employee (id, name, salary) "
                  "VALUES (?, ?, ?)");
    query.addBindValue(1001);
    query.addBindValue("Thad Beaumont");
    query.addBindValue(65000);
    query.exec();

Ambas sintaxis funcionan con todos los controladores de bases de datos que proporciona Qt. Si la base de datos admite la sintaxis de forma nativa, Qt simplemente reenvía la consulta al SGBD; de lo contrario, Qt simula la sintaxis de los marcadores de posición mediante el preprocesamiento de la consulta. La consulta real que acaba ejecutando el SGBD está disponible como QSqlQuery::executedQuery().

Al insertar varios registros, solo es necesario llamar a ` QSqlQuery::prepare()` una vez. A continuación, se llama a ` bindValue()` o ` addBindValue()`, seguido de ` exec()` tantas veces como sea necesario.

Además del rendimiento, una ventaja de los marcadores de posición es que permiten especificar fácilmente valores arbitrarios sin tener que preocuparse por el escape de caracteres especiales.

Actualizar un registro es similar a insertarlo en una tabla:

    QSqlQuery query;
    query.exec("UPDATE employee SET salary = 70000 WHERE id = 1003");

También puedes utilizar el enlace por nombre o por posición para asociar los parámetros a los valores reales.

Por último, he aquí un ejemplo de una instrucción « DELETE »:

    QSqlQuery query;
    query.exec("DELETE FROM employee WHERE id = 1007");

Transacciones

Si el motor de base de datos subyacente admite transacciones, la función ` QSqlDriver::hasFeature` (QSqlDriver::Transactions) devolverá «true». Puedes utilizar ` QSqlDatabase::transaction()` para iniciar una transacción, seguida de los comandos SQL que desees ejecutar en el contexto de la transacción y, a continuación, ` QSqlDatabase::commit()` o ` QSqlDatabase::rollback()`. Al utilizar transacciones, debes iniciar la transacción antes de crear la consulta.

Ejemplo:

    QSqlDatabase::database().transaction();
    QSqlQuery query;
    query.exec("SELECT id FROM employee WHERE name = 'Torild Halvorsen'");
    if (query.next()) {
        int employeeId = query.value(0).toInt();
        query.exec("INSERT INTO project (id, name, ownerid) "
                   "VALUES (201, 'Manhattan Project', "
                   + QString::number(employeeId) + ')');
    }
    QSqlDatabase::database().commit();

Las transacciones pueden utilizarse para garantizar que una operación compleja sea atómica (por ejemplo, buscar una clave foránea y crear un registro), o para proporcionar un medio de cancelar un cambio complejo a mitad del proceso.

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