Controladores de bases de datos SQL

El módulo Qt SQL utiliza plugins de controladores para comunicarse con las diferentes APIs de bases de datos. Dado que la API del módulo SQL de Qt es independiente de la base de datos, todo el código específico de la base de datos está contenido en estos controladores. Con Qt se suministran varios controladores, a los que se pueden añadir otros. El código fuente del controlador se suministra y puede utilizarse como modelo para escribir sus propios controladores.

Bases de datos compatibles

La siguiente tabla enumera los controladores incluidos con Qt:

SQLite es el sistema de base de datos en proceso con la mejor cobertura de pruebas y soporte en todas las plataformas. Oracle a través de OCI, PostgreSQL y MySQL mediante ODBC o un controlador nativo están bien probados en Windows y Linux. La integridad del soporte para otros sistemas depende de la disponibilidad y calidad de las bibliotecas cliente.

Creación de los controladores

Compilar Qt con un controlador específico

El script Qt configure intenta detectar automáticamente las librerías cliente disponibles en tu máquina. Ejecute configure -help para ver qué controladores se pueden construir. Deberías obtener una salida similar a esta:

[...]

Database options:

  -sql-<driver> ........ Enable SQL <driver> plugin. Supported drivers:
                         db2 ibase mysql oci odbc psql sqlite
                         [all auto]
  -sqlite .............. Select used sqlite [system/qt]

[...]

El script configure no puede detectar las librerías y archivos de inclusión necesarios si no están en las rutas estándar, por lo que puede ser necesario especificar estas rutas utilizando variables de ruta de inclusión y librería específicas del controlador o CMAKE_INCLUDE_PATH y CMAKE_LIBRARY_PATH. Por ejemplo, si sus archivos MySQL están instalados en C:\mysql-connector-c-6.1.11-winx64 en Windows, entonces pase el siguiente parámetro a la parte de doble guión de la línea configure:

C:\Qt\6.0.0\Src\configure.bat -sql-mysql -- -DMySQL_ROOT="C:\mysql-8.0.22-winx64"
Configure summary:

...
Qt Sql Drivers:
  DB2 (IBM) .............................. no
  InterBase .............................. no
  Mimer SQL .............................. yes
  MySql .................................. yes
  OCI (Oracle) ........................... no
  ODBC ................................... yes
  PostgreSQL ............................. no
  SQLite ................................. yes
    Using system provided SQLite ......... no
...

Cuando configure los controladores de la forma descrita anteriormente, CMake omitirá cualquier comprobación de dependencias y utilizará las rutas proporcionadas tal cual. Esto es especialmente útil si el paquete proporciona su propio conjunto de bibliotecas del sistema que no deben ser reconocidas por la rutina de compilación.

Las particularidades de cada controlador se explican a continuación.

Compilar sólo un controlador SQL específico

Es posible compilar sólo un controlador SQL específico cuando Qt ya está compilado o instalado como versión binaria. Pero tienes que asegurarte de instalar exactamente la misma versión de los fuentes de Qt (por ejemplo a través de Qt Maintenance Tool) - de lo contrario podrías obtener errores de compilación debido a apis cambiados. También asegúrate de configurar correctamente el entorno de compilación ejecutando el símbolo del sistema Qt apropiado en el menú Inicio de Windows.

Una ejecución típica de qt-cmake (en este caso para configurar para MySQL) tiene este aspecto:

C:\Qt\6.0.0\mingw81_64\bin\qt-cmake -G Ninja C:\Qt\6.0.0\Src\qtbase\src\plugins\sqldrivers -DMySQL_INCLUDE_DIR="C:\mysql-8.0.22-winx64\include" -DMySQL_LIBRARY="C:\mysql-8.0.22-winx64\lib\libmysql.lib" -DCMAKE_INSTALL_PREFIX="C:\Qt\6.0.0\mingw81_64"
Configure summary:

Qt Sql Drivers:
  DB2 (IBM) .............................. no
  InterBase .............................. no
  Mimer SQL .............................. yes
  MySql .................................. yes
  OCI (Oracle) ........................... no
  ODBC ................................... yes
  PostgreSQL ............................. no
  SQLite ................................. yes
    Using system provided SQLite ......... no

-- Configuring done
-- Generating done
-- Build files have been written to: C:/build-qt6-sqldrivers

Después de configurar con qt-cmake, construya el controlador ejecutando ninja.

Debido a los aspectos prácticos de tratar con dependencias externas, sólo el plugin SQLite se entrega con las compilaciones binarias de Qt. Las versiones binarias de Qt para Windows también incluyen los plugins ODBC y PostgreSQL. Para poder añadir controladores adicionales a la instalación de Qt sin reconstruir todo Qt, es posible configurar y construir el directorio qtbase/src/plugins/sqldrivers fuera de un directorio de construcción completo de Qt. Tenga en cuenta que no es posible configurar cada controlador por separado, sólo todos ellos a la vez. Sin embargo, los controladores se pueden construir por separado.

Controladores específicos

QMYSQL para MySQL o MariaDB 5.6 y superior

MariaDB es una bifurcación de MySQL destinada a permanecer como software libre y de código abierto bajo la Licencia Pública General GNU. MariaDB pretende mantener una alta compatibilidad con MySQL, asegurando una capacidad de reemplazo drop-in con paridad binaria de librerías y coincidencia exacta con las APIs y comandos de MySQL. Por lo tanto el plugin para MySQL y MariaDB se combinan en un plugin Qt.

Soporte Timestamp

Desde Qt 6.8, los valores de QDateTime se convierten a UTC antes de la inserción y de nuevo a UTC durante la recuperación. Para que esto funcione, el controlador establece la zona horaria de la conexión a UTC durante open() (SET time_zone = '+00:00'). Como MySQL no almacena ninguna información de zona horaria, esta información se pierde y todos los valores recuperados de QDateTime son UTC.

Soporte de procedimientos almacenados QMYSQL

MySQL tiene soporte para procedimientos almacenados a nivel SQL, pero no tiene API para controlar los parámetros IN, OUT e INOUT. Por lo tanto, los parámetros tienen que ser establecidos y leídos usando comandos SQL en lugar de QSqlQuery::bindValue().

Ejemplo de procedimiento almacenado:

create procedure qtestproc (OUT param1 INT, OUT param2 INT)
BEGIN
    set param1 = 42;
    set param2 = 43;
END

Código fuente para acceder a los valores OUT:

QSqlQuery q; q.exec("call qtestproc (@outval1, @outval2)"); q.exec("select @outval1, @outval2");if (q.next())    qDebug() << q.value(0) << q.value(1); // outputs "42" and "43"

Servidor MySQL integrado

El servidor MySQL embebido es un reemplazo directo de la librería cliente normal. Con el servidor MySQL incrustado, no se requiere un servidor MySQL para utilizar la funcionalidad MySQL.

Para usar el servidor MySQL embebido, simplemente enlace el plugin Qt a libmysqld en lugar de libmysqlclient. Esto puede hacerse añadiendo -DMySQL_LIBRARY=<path/to/mysqld/>libmysqld.<so|lib|dylib> a la línea de comandos de configuración.

Por favor, consulte la documentación de MySQL, capítulo "libmysqld, the Embedded MySQL Server Library" para más información sobre el servidor MySQL embebido.

Opciones de conexión

El plugin Qt MySQL/MariaDB acepta las siguientes opciones de conexión:

Para información más detallada acerca de las opciones de conexión por favor refiérase a la documentación de MySQL mysql_options().

Cómo construir el plugin QMYSQL en Unix y macOS

Necesita los archivos de cabecera de MySQL / MariaDB, así como la biblioteca compartida libmysqlclient.<so|dylib> / libmariadb.<so|dylib>. Dependiendo de tu distribución de Linux, puede que necesites instalar un paquete que normalmente se llama "mysql-devel" o "mariadb-devel".

Dígale a qt-cmake dónde encontrar los archivos de cabecera de MySQL / MariaDB y las bibliotecas compartidas (aquí se asume que MySQL / MariaDB está instalado en /usr/local) y compile:

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_source_directory>/qtbase/src/plugins/sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>/<platform> -DMySQL_ROOT="/usr/local/mysql"
cmake --build .
cmake --install .

Cómo Construir el Plugin QMYSQL en Windows

Necesita obtener los archivos de instalación de MySQL (p.e. MySQL web installer o MariaDB C Connector). Ejecuta el instalador, selecciona instalación personalizada e instala el Conector C de MySQL que coincida con tu instalación de Qt (x86 o x64). Después de la instalación comprueba que están los archivos necesarios:

• <MySQL dir>/lib/libmysql.lib
• <MySQL dir>/lib/libmysql.dll
• <MySQL dir>/include/mysql.h

y para MariaDB

• <MariaDB dir>/lib/libmariadb.lib
• <MariaDB dir>/lib/libmariadb.dll
• <MariaDB dir>/include/mysql.h

Construya el plugin como sigue (aquí se asume que <MySQL dir> es C:\mysql-8.0.22-winx64):

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_installation_path>\Src\qtbase\src\plugins\sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>\<platform> -DMySQL_ROOT="C:\mysql-8.0.22-winx64"
cmake --build .
cmake --install .

Cuando distribuyas tu aplicación, recuerda incluir libmysql.dll / libmariadb.dll en tu paquete de instalación. Debe colocarse en la misma carpeta que el ejecutable de la aplicación. libmysql.dll necesita además las librerías de ejecución MSVC que pueden instalarse con vcredist.exe

QOCI para la interfaz de llamada de Oracle (OCI)

El plugin Qt OCI soporta la conexión a bases de datos Oracle según lo determine la versión del cliente instantáneo utilizado. Esto depende de lo que Oracle indique que soporta. El plugin autodetectará la versión de la base de datos y habilitará las características en consecuencia.

Es posible conectarse a una base de datos Oracle sin un archivo tnsnames.ora. Esto requiere que el SID de la base de datos se pase al controlador como el nombre de la base de datos, y que se proporcione un nombre de host.

Autenticación de usuarios OCI

El plugin Qt OCI soporta autenticación usando credenciales externas (OCI_CRED_EXT). Normalmente, esto significa que el servidor de base de datos utilizará la autenticación de usuario proporcionada por el sistema operativo en lugar de su propio mecanismo de autenticación.

Deja el nombre de usuario y la contraseña vacíos cuando abras una conexión con QSqlDatabase para usar la autenticación por credenciales externas.

Soporte OCI BLOB/LOB

Los objetos binarios de gran tamaño (BLOB) pueden leerse y escribirse, pero ten en cuenta que este proceso puede requerir mucha memoria. Debe utilizar una consulta forward only para seleccionar campos LOB (consulte QSqlQuery::setForwardOnly()).

La inserción de BLOBs debe realizarse utilizando una consulta preparada en la que los BLOBs estén vinculados a marcadores de posición o QSqlTableModel, que utiliza una consulta preparada para hacerlo internamente.

Opciones de conexión

El plugin Qt OCI acepta las siguientes opciones de conexión:

Cómo construir el plugin OCI en Unix y macOS

Todo lo que necesitas es el " - Basic" y el "Instant Client Package - SDK".

Archivos de biblioteca de Oracle necesarios para construir el controlador:

• libclntsh.<so|dylib> (todas las versiones)

Indique a qt-cmake dónde encontrar los archivos de cabecera y las bibliotecas compartidas de Oracle y compilarlos.

Suponemos que ha instalado los paquetes RPM del SDK de paquetes de cliente instantáneo (debe ajustar el número de versión en consecuencia):

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_source_directory>/qtbase/src/plugins/sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>/<platform> -DOracle_ROOT="/usr/include/oracle/21/client64"
cmake --build .
cmake --install .

Cómo compilar el plugin OCI en Windows

Elegir la opción "Programmer" en el instalador de Oracle Client del CD de instalación de Oracle Client suele ser suficiente para compilar el plugin. Para algunas versiones de Oracle Client, también puede ser necesario seleccionar la opción "Call Interface (OCI)" si está disponible.

Cree el plugin de la siguiente manera (aquí se asume que Oracle Client está instalado en C:\oracle y SDK está instalado en C:\oracle\sdk):

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_installation_path>\Src\qtbase\src\plugins\sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>\<platform> -DOracle_ROOT="C:\oracle"
cmake --build .
cmake --install .

Cuando ejecute su aplicación, también necesitará añadir la ruta oci.dll a su variable de entorno PATH:

set PATH=%PATH%;C:\oracle

QODBC para Open Database Connectivity (ODBC)

ODBC es una interfaz general que permite conectarse a múltiples DBMS utilizando una interfaz común. El controlador QODBC permite conectarse a un gestor de controladores ODBC y acceder a las fuentes de datos disponibles. Tenga en cuenta que también debe instalar y configurar los controladores ODBC para el gestor de controladores ODBC instalado en su sistema. El plugin QODBC te permite utilizar estas fuentes de datos en tus aplicaciones Qt.

En Windows, se instala por defecto un gestor de controladores ODBC. Para los sistemas Unix, existen algunas implementaciones que deben instalarse primero. Tenga en cuenta que todos los usuarios finales de su aplicación deben tener instalado un gestor de controladores ODBC; de lo contrario, el complemento QODBC no funcionará.

Cuando se conecte a una fuente de datos ODBC, debe pasar el nombre de la fuente de datos ODBC (DSN) a la función QSqlDatabase::setDatabaseName(), en lugar del nombre real de la base de datos. También es posible pasar un nombre de archivo FILEDSN (*.dsn) o una cadena de controlador ODBC completa. Al pasar una cadena de controlador debe asegurarse de que todos los parámetros (nombre de usuario, contraseña, ...) se escapan correctamente. Pasando el nombre de usuario o la contraseña a través de las funciones QSqlDatabase, el escape lo realiza el plugin QODBC.

El plugin QODBC necesita un controlador ODBC compatible con la versión 2.0 o superior. Algunos controladores ODBC dicen ser compatibles con la versión 2.0, pero no ofrecen toda la funcionalidad necesaria. Por ello, el plugin QODBC comprueba si la fuente de datos puede utilizarse después de establecer una conexión, y se niega a funcionar si la comprobación falla. Si no le gusta este comportamiento, puede eliminar la línea #define ODBC_CHECK_DRIVER del archivo qsql_odbc.cpp. Hágalo bajo su propia responsabilidad.

Por defecto, Qt indica al controlador ODBC que se comporte como un controlador ODBC 2.x. Sin embargo, para algunas combinaciones driver-manager/ODBC 3.x-driver (e.g., unixODBC/MaxDB ODBC), decirle al driver ODBC que se comporte como un driver 2.x puede causar que el plugin del driver tenga un comportamiento inesperado. Para evitar este problema, indique al controlador ODBC que se comporte como un controlador 3.x mediante setting the connect option "SQL_ATTR_ODBC_VERSION=SQL_OV_ODBC3" antes de open your database connection. Tenga en cuenta que esto afectará a varios aspectos del comportamiento del controlador ODBC, por ejemplo, los SQLSTATE. Antes de configurar esta opción de conexión, consulte su documentación ODBC sobre las diferencias de comportamiento que puede esperar.

Si experimenta un acceso muy lento a la fuente de datos ODBC, asegúrese de que el rastreo de llamadas ODBC está desactivado en el gestor de fuentes de datos ODBC.

Algunos controladores no admiten cursores desplazables. En ese caso, sólo se pueden utilizar con éxito las consultas en modo QSqlQuery::setForwardOnly().

Soporte de marcas de tiempo

ODBC utiliza TIMESTAMP_STRUCT que no tiene información sobre ninguna zona horaria o similar. Debido a esto, se utiliza QDateTime sin respetar en absoluto la zona horaria.

Soporte para procedimientos almacenados ODBC

Con Microsoft SQL Server, el conjunto de resultados devuelto por un procedimiento almacenado que utiliza la sentencia return, o devuelve múltiples conjuntos de resultados, sólo será accesible si se establece el modo forward only de la consulta a forward utilizando QSqlQuery::setForwardOnly().

// STORED_PROC uses the return statement or returns multiple result sets
QSqlQuery query;
query.setForwardOnly(true);
query.exec("{call STORED_PROC}");

Soporte Unicode ODBC

El complemento QODBC utilizará la API Unicode si se define UNICODE. En los sistemas basados en Windows, este es el valor predeterminado. Tenga en cuenta que el controlador ODBC y el SGBD también deben soportar Unicode.

Para el controlador ODBC de Oracle 9 (Windows), es necesario marcar "SQL_WCHAR support" en el gestor del controlador ODBC, de lo contrario Oracle convertirá todas las cadenas Unicode a la representación local de 8 bits.

Opciones de conexión

El complemento Qt ODBC admite las siguientes opciones de conexión:

Para información más detallada sobre las opciones de conexión, por favor consulte la documentación ODBC de SQLSetConnectAttr().

Cómo crear el complemento ODBC en Unix y macOS

Se recomienda utilizar unixODBC. Puedes encontrar la última versión y los drivers ODBC en http://www.unixodbc.org. Necesitas los archivos de cabecera unixODBC y las librerías compartidas.

Indique a qt-cmake dónde encontrar los ficheros de cabecera unixODBC y las librerías compartidas (aquí se asume que unixODBC está instalado en /usr/local/unixODBC) y compile:

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_source_directory>/qtbase/src/plugins/sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>/<platform> -DODBC_INCLUDE_DIR="/usr/local/unixODBC/include" -DODBC_LIBRARY="/usr/local/unixODBC/lib/libodbc.<so|dylib>"
cmake --build .
cmake --install .

Cómo construir el plugin ODBC en Windows

La cabecera ODBC y los archivos de inclusión ya deberían estar instalados en los directorios correctos. Sólo tienes que compilar el plugin de la siguiente manera:

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_installation_path>\Src\qtbase\src\plugins\sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>\<platform>
cmake --build .
cmake --install .

QPSQL para PostgreSQL (Versión 7.3 y superiores)

El controlador QPSQL soporta la versión 7.3 y superiores del servidor PostgreSQL.

Para más información sobre PostgreSQL visite http://www.postgresql.org.

Soporte Timestamp

Desde Qt 6.8, los valores de QDateTime se convierten a UTC antes de la inserción y de nuevo a UTC durante la recuperación. Para que esto funcione, el controlador establece la zona horaria de la conexión a UTC durante open() (SET TIME ZONE 'UTC'). Aunque PostgreSQL tiene el tipo de columna `timestamptz`, la zona horaria utilizada durante la inserción no se conserva y por lo tanto todos los valores recuperados de QDateTime son UTC.

Soporte QPSQL Unicode

El controlador QPSQL detecta automáticamente si la base de datos PostgreSQL a la que se está conectando soporta Unicode o no. Unicode se utiliza automáticamente si el servidor lo soporta. Tenga en cuenta que el controlador sólo soporta la codificación UTF-8. Si su base de datos utiliza cualquier otra codificación, el servidor debe estar compilado con soporte de conversión Unicode.

El soporte Unicode fue introducido en la versión 7.1 de PostgreSQL y sólo funcionará si tanto el servidor como la librería cliente han sido compilados con soporte multibyte. Puede encontrar más información sobre cómo configurar un servidor PostgreSQL con soporte multibyte en la Guía del Administrador de PostgreSQL, Capítulo 5.

Sensibilidad a mayúsculas y minúsculas en QPSQL

Las bases de datos PostgreSQL sólo respetarán la distinción entre mayúsculas y minúsculas si el nombre de la tabla o del campo se entrecomilla cuando se crea la tabla. Así, por ejemplo, una consulta SQL como:

CREATE TABLE "testTable" ("id" INTEGER);

se asegurará de que se puede acceder con el mismo caso que se utilizó. Si el nombre de la tabla o del campo no se entrecomilla cuando se crea, el nombre real de la tabla o del campo se escribirá en minúsculas. Cuando QSqlDatabase::record() o QSqlDatabase::primaryIndex() acceden a una tabla o campo que no estaba entrecomillado cuando se creó, el nombre pasado a la función debe estar en minúsculas para garantizar que se encuentra. Por ejemplo:

QString tableString("testTable");
QSqlQuery q;
// Create table query is not quoted, therefore it is mapped to lower case
q.exec(QString("CREATE TABLE %1 (id INTEGER)").arg(tableString));
// Call toLower() on the string so that it can be matched
QSqlRecord rec = database.record(tableString.toLower());

Soporte de consultas QPSQL Forward-only

Para utilizar consultas de sólo avance, debe construir el complemento QPSQL con la biblioteca cliente PostreSQL versión 9.2 o posterior. Si el complemento se construye con una versión anterior, el modo sólo hacia adelante no estará disponible - llamar a QSqlQuery::setForwardOnly() con true no tendrá ningún efecto.

QSqlDatabase: QPSQL driver not loaded
QSqlDatabase: available drivers: QSQLITE QMYSQL QMARIADB QODBC QPSQL
Could not create database object

Mientras se navega por los resultados en modo forward-only, el handle de QSqlResult puede cambiar. Las aplicaciones que utilizan el manejador de bajo nivel del resultado SQL deben obtener un nuevo manejador después de cada llamada a cualquiera de las funciones de obtención de QSqlResult. Ejemplo:

QSqlQuery query;
QVariant v;
query.setForwardOnly(true);
query.exec("SELECT * FROM table");
while (query.next()) {
    // Handle changes in every iteration of the loop
    v = query.result()->handle();

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

Mientras se leen los resultados de una consulta forward-only con PostgreSQL, la conexión a la base de datos no puede utilizarse para ejecutar otras consultas. Esta es una limitación de la librería libpq. Ejemplo:

int value;
QSqlQuery query1;
query1.setForwardOnly(true);
query1.exec("select * FROM table1");
while (query1.next()) {
    value = query1.value(0).toInt();
    if (value == 1) {
        QSqlQuery query2;
        query2.exec("update table2 set col=2");  // WRONG: This will discard all results of
    }                                            // query1, and cause the loop to quit
}

Este problema no ocurrirá si query1 y query2 utilizan conexiones de base de datos diferentes, o si ejecutamos query2 después del bucle while.

QPSQLDriver::getResult: Query results lost - probably discarded on executing another SQL query.

Opciones de conexión

El plugin Qt PostgreSQL respeta todas las opciones de conexión especificadas en la documentación de connect() PostgreSQL.

Cómo construir el plugin QPSQL en Unix y macOS

Necesita tener instalada la librería cliente PostgreSQL y las cabeceras.

Para hacer que qt-cmake encuentre los archivos de cabecera PostgreSQL y las bibliotecas compartidas, construya el plugin de la siguiente manera (asumiendo que el cliente PostgreSQL está instalado en /usr/local/pgsql):

mkdir build-psql-driver
cd build-psql-driver

qt-cmake -G Ninja <qt_source_directory>/qtbase/src/plugins/sqldrivers-DCMAKE_INSTALL_PREFIX=<qt_installation_path>/<platform> -DPostgreSQL_ROOT="/usr/local/pgsql"
cmake --build .
cmake --install .

Cómo construir el plugin QPSQL en Windows

Instale las librerías de desarrollo PostgreSQL apropiadas para su compilador. Asumiendo que PostgreSQL fue instalado en C:\pgsql, construya el plugin como sigue:

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_installation_path>\Src\qtbase\src\plugins\sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>\<platform> -DPostgreSQL_ROOT="C:\pgsql"
cmake --build .
cmake --install .

Los usuarios de MinGW pueden consultar el siguiente documento en línea: PostgreSQL MinGW/Nativo Windows.

Cuando distribuya su aplicación, recuerde incluir libpq.dll en su paquete de instalación. Debe colocarse en la misma carpeta que el ejecutable de la aplicación.

QDB2 para IBM DB2 (versión 7.1 y superiores)

El plugin Qt DB2 permite acceder a bases de datos IBM DB2. Ha sido probado con IBM DB2 v7.1 y 7.2. Debe instalar la biblioteca cliente de desarrollo de IBM DB2, que contiene los archivos de cabecera y biblioteca necesarios para compilar el plugin QDB2.

El controlador QDB2 admite consultas preparadas, lectura/escritura de cadenas Unicode y lectura/escritura de BLOB.

Sugerimos utilizar una consulta preparada al llamar a procedimientos almacenados en DB2 (véase QSqlQuery::setForwardOnly()).

Opciones de conexión

El plugin Qt IBM DB2 acepta las siguientes opciones de conexión:

Cómo construir el plugin QDB2 en Unix y macOS

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_source_directory>/qtbase/src/plugins/sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>/<platform> -DDB2_ROOT="/usr/local/db2"
cmake --build .
cmake --install .

Cómo construir el plugin QDB2 en Windows

Los archivos de cabecera y de inclusión de DB2 ya deberían estar instalados en los directorios correctos. Sólo tienes que construir el plugin de la siguiente manera:

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_installation_path>\Src\qtbase\src\plugins\sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>\<platform> -DDB2_ROOT="C:\db2"
cmake --build .
cmake --install .

QSQLITE para SQLite (Versión 3 y superiores)

El plugin Qt SQLite permite acceder a bases de datos SQLite. SQLite es una base de datos en proceso, lo que significa que no es necesario disponer de un servidor de bases de datos. SQLite opera sobre un único archivo, que debe establecerse como nombre de la base de datos al abrir una conexión. Si el archivo no existe, SQLite intentará crearlo. SQLite también soporta bases de datos en memoria y temporales. Basta con pasar respectivamente ":memory:" o una cadena vacía como nombre de la base de datos.

SQLite tiene algunas restricciones en cuanto a usuarios múltiples y transacciones múltiples. Si intentas leer/escribir en un recurso desde diferentes transacciones, tu aplicación podría congelarse hasta que una de las transacciones haga commit o roll back. El controlador SQLite de Qt volverá a intentar escribir en un recurso bloqueado hasta que se agote el tiempo de espera (véase QSQLITE_BUSY_TIMEOUT en QSqlDatabase::setConnectOptions()).

En SQLite cualquier columna, con la excepción de una columna INTEGER PRIMARY KEY, puede ser utilizada para almacenar cualquier tipo de valor. Por ejemplo, una columna declarada como INTEGER puede contener un valor entero en una fila y un valor de texto en la siguiente. Esto se debe a que SQLite asocia el tipo de un valor con el propio valor y no con la columna en la que se almacena. Una consecuencia de esto es que el tipo devuelto por QSqlField::metaType() sólo indica el tipo recomendado del campo. No se debe asumir el tipo real y se debe comprobar el tipo de los valores individuales.

El controlador se bloquea para actualizaciones mientras se ejecuta una selección. Esto puede causar problemas cuando se utiliza QSqlTableModel porque las vistas de elementos de Qt obtienen datos cuando es necesario (con QSqlQuery::fetchMore() en el caso de QSqlTableModel).

Puedes encontrar información sobre SQLite en http://www.sqlite.org.

Soporte Timestamp

SQLite no tiene un tipo de columna timestamp especial. Una QDateTime se almacena como cadena, formateada en Qt::ISODateWithMs y por lo tanto la información de la zona horaria QDateTime se conserva durante la inserción y selección.

Opciones de conexión

El plugin Qt SQLite acepta las siguientes opciones de conexión:

Cómo construir el plugin QSQLITE

SQLite versión 3 se incluye como una librería de terceros dentro de Qt. Se puede construir pasando el parámetro -DFEATURE_system_sqlite=OFF a la línea de comandos qt-cmake.

Si no desea utilizar la librería SQLite incluida con Qt, puede pasar -DFEATURE_system_sqlite=ON a la línea de comandos qt-cmake para utilizar las librerías SQLite del sistema operativo. Esto se recomienda siempre que sea posible, ya que reduce el tamaño de la instalación y elimina un componente para el que es necesario realizar un seguimiento de los avisos de seguridad.

En Unix y macOS (sustituya $SQLITE por el directorio donde reside SQLite):

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_source_directory>/qtbase/src/plugins/sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>/<platform> -DFEATURE_system_sqlite=ON -DCMAKE_INCLUDE_PATH="$SQLITE/include" -DCMAKE_LIBRARY_PATH="$SQLITE/lib"
cmake --build .
cmake --install .

En Windows (suponiendo que SQLite esté instalado en C:\SQLITE):

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_installation_path>\Src\qtbase\src\plugins\sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>\<platform> -DFEATURE_system_sqlite=ON -DCMAKE_INCLUDE_PATH="C:\SQLITE\include" -DCMAKE_LIBRARY_PATH="C:\SQLITE\lib"
cmake --build .
cmake --install .

Activar el operador REGEXP

SQLite viene con una operación REGEXP. Sin embargo, la implementación necesaria debe ser proporcionada por el usuario. Para mayor comodidad se puede habilitar una implementación por defecto en setting the connect option QSQLITE_ENABLE_REGEXP antes de the database connection is opened. Entonces una sentencia SQL como "column REGEXP 'pattern'" básicamente se expande al código Qt

column.contains(QRegularExpression("pattern"));

Para mejorar el rendimiento, las expresiones regulares se almacenan internamente en caché. Por defecto el tamaño de la caché es 25, pero puede cambiarse a través del valor de la opción. Por ejemplo pasando "QSQLITE_ENABLE_REGEXP=10" se reduce el tamaño de la caché a 10.

Compatibilidad con formatos de archivo QSQLITE

Las versiones menores de SQLite a veces rompen la compatibilidad de formatos de archivo. Por ejemplo, SQLite 3.3 puede leer archivos de bases de datos creados con SQLite 3.2, pero las bases de datos creadas con SQLite 3.3 no pueden ser leídas por SQLite 3.2. Consulte la documentación de SQLite y los registros de cambios para obtener información sobre la compatibilidad de formatos de archivo entre versiones.

Las versiones menores de Qt normalmente siguen a las versiones menores de SQLite, mientras que las versiones de parches de Qt siguen a las versiones de parches de SQLite. Por lo tanto, los parches son compatibles con versiones anteriores y posteriores.

Para forzar a SQLite a usar un formato de archivo específico, es necesario construir y enviar su propio plugin de base de datos con su propia librería SQLite como se ilustra arriba. Algunas versiones de SQLite pueden ser forzadas a escribir un formato de archivo específico estableciendo la definición SQLITE_DEFAULT_FILE_FORMAT cuando se construye SQLite.

QMIMER para Mimer SQL versión 11 y superiores

El plugin Qt Mimer SQL permite trabajar con el RDBMS Mimer SQL. Mimer SQL proporciona soluciones de bases de datos relacionales pequeñas, escalables y robustas que se ajustan a los estándares internacionales ISO SQL. Mimer SQL está disponible en Windows, Linux, macOS y OpenVMS, así como en varias plataformas embebidas como QNX, Android y Linux embebido.

Mimer SQL es totalmente compatible con Unicode. Para trabajar con datos Unicode se deben utilizar los tipos de columna National Character (NCHAR), National Character Varying (NVARCHAR), o National Character Large Object (NCLOB). Para más información sobre Mimer SQL y unicode, consulte https://developer.mimer.com/features/multilingual-support

Soporte de marcas de tiempo

MimerSQL no sabe nada acerca de las zonas horarias y QDateTime se utiliza sin honrar la zona horaria en absoluto.

Soporte de Procedimientos Almacenados QMIMER

Mimer SQL tiene procedimientos almacenados de acuerdo al estandar SQL (PSM) y el plugin soporta completamente parametros IN, OUT, INOUT asi como procedimientos resultset.

Ejemplo de procedimiento almacenado con parámetros INOUT y OUT:

create procedure inout_proc (INOUT param1 INT, OUT param2 INT)
BEGIN
    set param1 = param1 * 2;
    set param2 = param1 * param1;
END

Código fuente para acceder a los valores INOUT y OUT:

    QSqlDatabase db;
    QSqlQuery query;
    int i1 = 10, i2 = 0;
    query.prepare("call qtestproc(?, ?)");
    query.bindValue(0, i1, QSql::InOut);
    query.bindValue(1, i2, QSql::Out);
    query.exec();

Cómo construir el plugin QMIMER en Unix y macOS

Necesitas los ficheros de cabecera y las librerías compartidas de Mimer SQL. Consíguelos instalando cualquiera de las variantes de Mimer SQL que se encuentran en https://developer.mimer.com.

mkdir build-sqldrivers
cd build-sqldrivers

qt-cmake -G Ninja <qt_installation_path>\Src\qtbase\src\plugins\sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>\<platform> -DMimer_INCLUDE_DIR="/usr/include" -DMimer_LIBRARIES="/usr/lib/libmimer.so"
cmake --build .
cmake --install .

Cómo construir el plugin QMIMER en Windows

Necesitas los archivos de cabecera y las librerías compartidas de Mimer SQL. Consíguelos instalando cualquiera de las variantes de Mimer SQL que se encuentran en https://developer.mimer.com.

mkdir build-sqldrivers
cd build-sqldrivers

qt-cmake -G Ninja <qt_installation_path>\Src\qtbase\src\plugins\sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>\<platform> -DMimer_INCLUDE_DIR="C:\Program Files\Mimer SQL Experience 11.0\dev\include" -DMimer_LIBRARIES="C:\Program Files\Mimer SQL Experience 11.0\dev\lib\amd64\mimapi64.lib|C:\Program Files\Mimer SQL Experience 11.0\dev\lib\x86\mimapi32.lib"
cmake --build .
cmake --install .

QIBASE para Borland InterBase

El plugin Qt InterBase permite acceder a las bases de datos InterBase y Firebird. InterBase puede utilizarse como cliente/servidor o sin servidor, en cuyo caso opera sobre ficheros locales. El fichero de base de datos debe existir antes de poder establecer una conexión. Firebird debe utilizarse con una configuración de servidor.

Tenga en cuenta que InterBase requiere que especifique la ruta completa al archivo de base de datos, independientemente de que esté almacenado localmente o en otro servidor.

Soporte de marcas de tiempo

Interbase almacena las marcas de tiempo en UTC sin ninguna información de zona horaria. Debido a esto, el QDateTime se utiliza sin honrar la zona horaria en absoluto.

Desde Firebird 4.0, la base de datos soporta marcas de tiempo con zonas horarias. La información de la zona horaria se almacena separada de la marca de tiempo para que pueda ser recuperada correctamente más tarde. Consulte la documentación de Firebird para más información sobre el manejo de marcas de tiempo.

Opciones de conexión

El plugin Qt Borland InterBase acepta las siguientes opciones de conexión:

Cómo construir el plugin QIBASE

QSqlDatabase db;
db.setHostName("MyServer");
db.setDatabaseName("C:\\test.gdb");

Necesitas las cabeceras y librerías de desarrollo de InterBase/Firebird para construir este plugin.

Debido a incompatibilidades de licencia con la GPL, los usuarios de Qt Open Source Edition no pueden enlazar este plugin con las ediciones comerciales de InterBase. Por favor, utilice Firebird o la edición gratuita de InterBase.

Procedimientos almacenados de QIBASE

InterBase/Firebird devuelven valores OUT como conjunto de resultados, por lo que cuando se llama a un procedimiento almacenado, sólo los valores IN necesitan ser vinculados a través de QSqlQuery::bindValue(). Los valores RETURN/OUT pueden ser recuperados a través de QSqlQuery::value(). Ejemplo:

QSqlQuery q; q.exec("ejecutar procedimiento mi_procedimiento");if (q.next())    qDebug() << q.value(0); // outputs the first RETURN/OUT value

Cómo construir el plugin QIBASE en Unix y macOS

Lo siguiente asume que InterBase o Firebird está instalado en /opt/interbase:

Si está usando InterBase:

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_source_directory>/qtbase/src/plugins/sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>/<platform> -DInterbase_ROOT="/opt/interbase/"
cmake --build .
cmake --install .

Opcionalmente, utilice las variables CMake Interbase_INCLUDE_DIR y Interbase_LIBRARY para especificar la ruta de inclusión y la biblioteca directamente.

Cómo construir el plugin QIBASE en Windows

Lo siguiente asume que InterBase o Firebird está instalado en C:\interbase:

Si está usando InterBase:

mkdir build-sqldrivers
cd build-sqldrivers
qt-cmake -G Ninja <qt_installation_path>\Src\qtbase\src\plugins\sqldrivers -DCMAKE_INSTALL_PREFIX=<qt_installation_path>\<platform> -DInterbase_ROOT="C:\interbase"
cmake --build .
cmake --install .

Opcionalmente, utilice las variables CMake Interbase_INCLUDE_DIR y Interbase_LIBRARY para especificar la ruta de inclusión y la biblioteca directamente.

Tenga en cuenta que C:\interbase\bin debe estar en el directorio PATH.

Solución de problemas

Siempre debe utilizar bibliotecas cliente que hayan sido compiladas con el mismo compilador que esté utilizando para su proyecto. Si no puede conseguir una distribución de fuentes para compilar las bibliotecas cliente usted mismo, debe asegurarse de que la biblioteca precompilada es compatible con su compilador, de lo contrario obtendrá muchos errores de "símbolos indefinidos".

Si la compilación de un plugin tiene éxito pero no se puede cargar después, comprueba los siguientes pasos para encontrar al culpable:

1. Asegúrate de que el plugin está en el directorio correcto. Puedes usar QApplication::libraryPaths() para determinar donde busca Qt los plugins.
2. Asegúrate de que las librerías cliente del SGBD están disponibles en el sistema. En Unix, ejecute el comando ldd y pase el nombre del plugin como parámetro, por ejemplo ldd libqsqlmysql.so. Recibirá una advertencia si no se encuentra alguna de las bibliotecas cliente. En Windows, puede utilizar el navegador de dependencias de Visual Studio o la interfaz gráfica de usuario de dependencias para encontrar las bibliotecas dependientes. Con Qt Creator, puede actualizar la variable de entorno PATH en la sección Ejecutar del panel Proyecto para incluir la ruta a la carpeta que contiene las bibliotecas cliente.
3. Cuando utilices MSVC, asegúrate también de que el plugin está compilado con el tipo de compilación correcto. Debido a los diferentes tiempos de ejecución de MSVC para depuración y liberación, una compilación de depuración Qt no puede cargar un plugin de liberación Qt y viceversa.
4. Ejecute el ejecutable Qt compilado con la variable de entorno QT_DEBUG_PLUGINS establecida para obtener una salida de depuración muy detallada al cargar plugins.
5. Para recuperar posibles mensajes de depuración del subsistema SQL, habilita la salida estableciendo la variable de entorno QT_LOGGING_RULES en qt.sql.*.debug=true. No olvide habilitar la consola cuando trabaje en Windows. Consulte Logging Rules para obtener una explicación más detallada sobre cómo establecer reglas de registro.

Asegúrate de que has seguido la guía de Despliegue de Plugins.

Cómo escribir su propio controlador de base de datos

QSqlDatabase es responsable de cargar y gestionar los plugins del controlador de base de datos. Cuando se añade una base de datos (ver QSqlDatabase::addDatabase()), se carga el plugin controlador apropiado (usando QSqlDriverPlugin). QSqlDatabase depende del plugin controlador para proporcionar interfaces para QSqlDriver y QSqlResult.

QSqlDriver es una clase base abstracta que define la funcionalidad de un controlador de base de datos SQL. Esto incluye funciones como QSqlDriver::open() y QSqlDriver::close(). QSqlDriver es responsable de conectarse a una base de datos, establecer el entorno adecuado, etc. Además, QSqlDriver puede crear objetos QSqlQuery apropiados para la API de base de datos concreta. QSqlDatabase reenvía muchas de sus llamadas a funciones directamente a QSqlDriver, que proporciona la implementación concreta.

QSqlResult es una clase base abstracta que define la funcionalidad de una consulta a una base de datos SQL. Incluye sentencias como SELECT, UPDATE, y ALTER TABLE . QSqlResult contiene funciones como QSqlResult::next() y QSqlResult::value(). QSqlResult es responsable de enviar consultas a la base de datos, devolver datos de resultados, etc. QSqlQuery reenvía muchas de sus llamadas a funciones directamente a QSqlResult que proporciona la implementación concreta.

QSqlDriver y QSqlResult están estrechamente relacionados. Cuando se implementa un controlador Qt SQL, ambas clases deben ser subclasificadas y los métodos virtuales abstractos de cada clase deben ser implementados.

Para implementar un controlador Qt SQL como un plugin (de modo que sea reconocido y cargado por la biblioteca Qt en tiempo de ejecución), el controlador debe utilizar la macro Q_PLUGIN_METADATA(). Lea Cómo crear plugins Q t para más información sobre esto. También puede comprobar cómo se hace esto en los plugins SQL que se proporcionan con Qt en QTDIR/qtbase/src/plugins/sqldrivers.

El siguiente código puede usarse como esqueleto para un controlador SQL:

class XyzResult : public QSqlResult
{
public:
    XyzResult(const QSqlDriver *driver)
        : QSqlResult(driver) {}
    ~XyzResult() {}

protected:
    QVariant data(int /* index */) override { return QVariant(); }
    bool isNull(int /* index */) override { return false; }
    bool reset(const QString & /* query */) override { return false; }
    bool fetch(int /* index */) override { return false; }
    bool fetchFirst() override { return false; }
    bool fetchLast() override { return false; }
    int size() override { return 0; }
    int numRowsAffected() override { return 0; }
    QSqlRecord record() const override { return QSqlRecord(); }
};

class XyzDriver : public QSqlDriver
{
public:
    XyzDriver() {}
    ~XyzDriver() {}

    bool hasFeature(DriverFeature /* feature */) const override { return false; }
    bool open(const QString & /* db */, const QString & /* user */,
              const QString & /* password */, const QString & /* host */,
              int /* port */, const QString & /* options */) override
        { return false; }
    void close() override {}
    QSqlResult *createResult() const override { return new XyzResult(this); }
};