Pilotes de bases de données SQL

Le module « Qt SQL » utilise des plugins de pilotes pour communiquer avec les différentes API de bases de données. L'API du module SQL de Qt étant indépendante de la base de données, tout le code spécifique à une base de données est contenu dans ces pilotes. Plusieurs pilotes sont fournis avec Qt, et d'autres peuvent être ajoutés. Le code source des pilotes est fourni et peut servir de modèle pour écrire vos propres pilotes.

Bases de données prises en charge

Le tableau ci-dessous répertorie les pilotes inclus avec Qt :

SQLite est le système de base de données en cours d'exécution qui bénéficie de la meilleure couverture de tests et de la meilleure prise en charge sur toutes les plateformes. Oracle via OCI, PostgreSQL et MySQL via ODBC ou un pilote natif ont été testés de manière approfondie sous Windows et Linux. L'exhaustivité de la prise en charge des autres systèmes dépend de la disponibilité et de la qualité des bibliothèques clientes.

Compilation des pilotes

Compiler Qt avec un pilote spécifique

Le script d'configure ation de Qt tente de détecter automatiquement les bibliothèques clientes disponibles sur votre machine. Exécutez la commande « configure -help » pour voir quels pilotes peuvent être compilés. Vous devriez obtenir un résultat similaire à celui-ci :

[...]

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]

[...]

Le script d’ configure ation ne peut pas détecter les bibliothèques et les fichiers d’en-tête nécessaires s’ils ne se trouvent pas dans les chemins d’accès standard ; il peut donc être nécessaire de spécifier ces chemins à l’aide soit de variables de chemin d’accès aux fichiers d’en-tête et aux bibliothèques spécifiques au pilote, soit des commandes CMAKE_INCLUDE_PATH et CMAKE_LIBRARY_PATH. Par exemple, si vos fichiers MySQL sont installés dans C:\mysql-connector-c-6.1.11-winx64 sous Windows, transmettez le paramètre suivant à la partie « double tiret » de la ligne de configuration :

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

Lorsque vous configurez les pilotes de la manière décrite ci-dessus, CMake ignore toute vérification de dépendance et utilise les chemins fournis tels quels. Cela s’avère particulièrement utile si le paquet fournit son propre ensemble de bibliothèques système qui ne doivent pas être reconnues par la routine de compilation.

Les détails relatifs à chaque pilote sont expliqués ci-dessous.

Compiler uniquement un pilote SQL spécifique

Il est possible de ne compiler qu'un pilote SQL spécifique lorsque Qt est déjà compilé ou installé sous forme de version binaire. Mais vous devez vous assurer d'installer exactement la même version des sources Qt (par exemple via Qt Maintenance Tool) ; sinon, vous risquez d'obtenir des erreurs de compilation dues à des API modifiées. Veillez également à configurer correctement l'environnement de compilation en exécutant l'invite de commande Qt appropriée dans le menu Démarrer de Windows.

Une exécution typique de ` qt-cmake ` (dans ce cas pour la configuration de MySQL) se présente comme suit :

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

Après la configuration avec ` qt-cmake`, compilez le pilote en exécutant ` ninja`.

Pour des raisons pratiques liées à la gestion des dépendances externes, seul le plugin SQLite est fourni avec les versions binaires de Qt. Les versions binaires de Qt pour Windows incluent également les plugins ODBC et PostgreSQL. Pour pouvoir ajouter des pilotes supplémentaires à l’installation de Qt sans avoir à recompiler l’ensemble de Qt, il est possible de configurer et de compiler le répertoire ` qtbase/src/plugins/sqldrivers ` en dehors d’un répertoire de compilation Qt complet. Notez qu’il n’est pas possible de configurer chaque pilote séparément, mais uniquement tous en même temps. Les pilotes peuvent toutefois être compilés séparément.

Spécificités des pilotes

QMYSQL pour MySQL ou MariaDB 5.6 et versions ultérieures

MariaDB est un fork de MySQL destiné à rester un logiciel libre et open source sous licence GNU General Public License. MariaDB vise à maintenir une compatibilité élevée avec MySQL, garantissant une remplaçabilité directe grâce à la parité binaire des bibliothèques et à une correspondance exacte avec les API et les commandes de MySQL. Par conséquent, les plugins pour MySQL et MariaDB sont regroupés en un seul plugin Qt.

Prise en charge des horodatages

Depuis Qt 6.8, les valeurs de type « QDateTime » sont converties en UTC avant leur insertion, puis reconverties à partir de l’UTC lors de leur récupération. Pour que cela fonctionne, le pilote définit le fuseau horaire de la connexion sur UTC lors de l’appel à open() (SET time_zone = '+00:00'). Comme MySQL ne stocke aucune information relative au fuseau horaire, cette information est perdue et toutes les valeurs de type « QDateTime » récupérées sont exprimées en UTC.

Prise en charge des procédures stockées QMYSQL

MySQL prend en charge les procédures stockées au niveau SQL, mais ne dispose d’aucune API permettant de contrôler les paramètres IN, OUT et INOUT. Par conséquent, les paramètres doivent être définis et lus à l’aide de commandes SQL plutôt qu’à l’aide de la fonction ` QSqlQuery::bindValue()`.

Exemple de procédure stockée :

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

Code source permettant d’accéder aux valeurs 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"

Serveur MySQL intégré

Le serveur MySQL intégré remplace directement la bibliothèque client standard. Grâce au serveur MySQL intégré, il n'est pas nécessaire de disposer d'un serveur MySQL pour utiliser les fonctionnalités de MySQL.

Pour utiliser le serveur MySQL intégré, il suffit de lier le plugin Qt à libmysqld au lieu de libmysqlclient. Pour ce faire, ajoutez -DMySQL_LIBRARY=<path/to/mysqld/>libmysqld.<so|lib|dylib> à la ligne de commande configure.

Veuillez vous reporter à la documentation MySQL, chapitre « libmysqld, la bibliothèque du serveur MySQL intégré », pour plus d’informations sur le serveur MySQL intégré.

Options de connexion

Le plugin Qt MySQL/MariaDB prend en charge les options de connexion suivantes :

Pour plus d'informations sur les options de connexion, veuillez vous reporter à la documentation MySQL relative à la fonction mysql_options().

Comment compiler le plugin QMYSQL sous Unix et macOS

Vous aurez besoin des fichiers d'en-tête MySQL / MariaDB, ainsi que de la bibliothèque partagée libmysqlclient.<so|dylib> / libmariadb.<so|dylib>. Selon votre distribution Linux, vous devrez peut-être installer un paquet généralement appelé « mysql-devel » ou « mariadb-devel ».

Indiquez à qt-cmake où se trouvent les fichiers d'en-tête et les bibliothèques partagées de MySQL / MariaDB (nous partons ici du principe que MySQL / MariaDB est installé dans /usr/local) puis lancez la compilation :

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 .

Comment compiler le plugin QMYSQL sous Windows

Vous devez vous procurer les fichiers d’installation de MySQL (par exemple, le programme d’installation Web de MySQL ou le connecteur C de MariaDB). Lancez le programme d’installation, sélectionnez l’installation personnalisée et installez le connecteur C de MySQL correspondant à votre installation de Qt (x86 ou x64). Une fois l’installation terminée, vérifiez que les fichiers nécessaires sont bien présents :

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

et pour MariaDB

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

Compilez le plugin comme suit (en supposant ici que <MySQL dir> correspond à 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 .

Lorsque vous distribuez votre application, n’oubliez pas d’inclure libmysql.dll / libmariadb.dll dans votre package d’installation. Ces fichiers doivent être placés dans le même dossier que l’exécutable de l’application. libmysql.dll nécessite en outre les bibliothèques d’exécution MSVC, qui peuvent être installées à l’aide de vcredist.exe

QOCI pour l'interface d'appel Oracle (OCI)

Le plugin Qt OCI prend en charge la connexion à une base de données Oracle en fonction de la version du client instantané utilisée. Cela dépend des fonctionnalités prises en charge par Oracle. Le plugin détectera automatiquement la version de la base de données et activera les fonctionnalités en conséquence.

Il est possible de se connecter à une base de données Oracle sans fichier tnsnames.ora. Pour cela, il faut que le SID de la base de données soit transmis au pilote en tant que nom de base de données et qu'un nom d'hôte soit fourni.

Authentification des utilisateurs OCI

Le plugin OCI de Qt prend en charge l'authentification à l'aide d'identifiants externes (OCI_CRED_EXT). En général, cela signifie que le serveur de base de données utilisera l'authentification utilisateur fournie par le système d'exploitation plutôt que son propre mécanisme d'authentification.

Laissez les champs nom d'utilisateur et mot de passe vides lors de l'établissement d'une connexion avec ` QSqlDatabase ` pour utiliser l'authentification par identifiants externes.

Prise en charge des BLOB/LOB OCI

La lecture et l'écriture d'objets binaires volumineux (BLOB) sont possibles, mais sachez que ce processus peut nécessiter beaucoup de mémoire. Vous devez utiliser une requête unidirectionnelle pour sélectionner des champs LOB (voir QSqlQuery::setForwardOnly()).

L'insertion de BLOB doit être effectuée soit à l'aide d'une requête préparée dans laquelle les BLOB sont liés à des espaces réservés, soit via QSqlTableModel, qui utilise en interne une requête préparée à cette fin.

Options de connexion

Le plugin Qt OCI prend en charge les options de connexion suivantes :

Comment compiler le plugin OCI sous Unix et macOS

Tout ce dont vous avez besoin, c'est du « - Basic » et du « Instant Client Package - SDK ».

Fichiers de bibliothèques Oracle requis pour compiler le pilote :

• libclntsh.<so|dylib> (toutes versions)

Indiquez à qt-cmake où trouver les fichiers d'en-tête et les bibliothèques partagées Oracle, puis lancez la compilation.

Nous partons du principe que vous avez installé les paquets RPM du SDK Instant Client Package (vous devrez adapter le numéro de version en conséquence) :

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 .

Comment compiler le plug-in OCI sous Windows

Il suffit généralement de choisir l'option « Programmeur » dans le programme d'installation d'Oracle Client à partir du CD d'installation d'Oracle Client pour compiler le plug-in. Pour certaines versions d'Oracle Client, vous devrez peut-être également sélectionner l'option « Call Interface (OCI) » si elle est disponible.

Compilez le plug-in comme suit (en partant du principe qu'Oracle Client est installé dans C:\oracle et que le SDK est installé dans 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 .

Lorsque vous exécutez votre application, vous devrez également ajouter le chemin d’accès oci.dll à votre variable d’environnement PATH:

set PATH=%PATH%;C:\oracle

QODBC pour la connectivité aux bases de données ouvertes (ODBC)

ODBC est une interface générique qui vous permet de vous connecter à plusieurs SGBD à l'aide d'une interface commune. Le pilote QODBC vous permet de vous connecter à un gestionnaire de pilotes ODBC et d'accéder aux sources de données disponibles. Notez que vous devez également installer et configurer les pilotes ODBC pour le gestionnaire de pilotes ODBC installé sur votre système. Le plugin QODBC vous permet ensuite d'utiliser ces sources de données dans vos applications Qt.

Sous Windows, un gestionnaire de pilotes ODBC est installé par défaut. Pour les systèmes Unix, certaines implémentations doivent être installées au préalable. Notez que chaque utilisateur final de votre application doit disposer d’un gestionnaire de pilotes ODBC, faute de quoi le plugin QODBC ne fonctionnera pas.

Lors de la connexion à une source de données ODBC, vous devez transmettre le nom de la source de données ODBC (DSN) à la fonction QSqlDatabase::setDatabaseName(), plutôt que le nom réel de la base de données. Il est également possible de transmettre un nom de fichier FILEDSN (*.dsn) ou une chaîne de commande ODBC complète. Lorsque vous transmettez une chaîne de pilote, vous devez vous assurer que tous les paramètres (nom d'utilisateur, mot de passe, etc.) sont correctement échappés. Si vous transmettez le nom d'utilisateur ou le mot de passe via les fonctions ` QSqlDatabase `, l'échappement est effectué par le plugin QODBC.

Le plugin QODBC nécessite un gestionnaire de pilotes compatible ODBC version 2.0 ou ultérieure. Certains pilotes ODBC prétendent être compatibles avec la version 2.0, mais n’offrent pas toutes les fonctionnalités nécessaires. Le plugin QODBC vérifie donc si la source de données peut être utilisée une fois la connexion établie, et refuse de fonctionner si cette vérification échoue. Si ce comportement ne vous convient pas, vous pouvez supprimer la ligne « #define ODBC_CHECK_DRIVER » du fichier « qsql_odbc.cpp ». Faites-le à vos propres risques !

Par défaut, Qt demande au pilote ODBC de se comporter comme un pilote ODBC 2.x. Cependant, pour certaines combinaisons gestionnaire de pilotes/pilote ODBC 3.x (par exemple, unixODBC/MaxDB ODBC), le fait de demander au pilote ODBC de se comporter comme un pilote 2.x peut entraîner un comportement inattendu du plugin du pilote. Pour éviter ce problème, configurez le pilote ODBC pour qu’il se comporte comme un pilote 3.x en exécutant ` setting the connect option ` "SQL_ATTR_ODBC_VERSION=SQL_OV_ODBC3" avant de lancer ` open your database connection`. Notez que cela affectera plusieurs aspects du comportement du pilote ODBC, par exemple les SQLSTATE. Avant de définir cette option de connexion, consultez votre documentation ODBC pour connaître les différences de comportement auxquelles vous pouvez vous attendre.

Si vous constatez un accès très lent à la source de données ODBC, assurez-vous que le traçage des appels ODBC est désactivé dans le gestionnaire de sources de données ODBC.

Certains pilotes ne prennent pas en charge les curseurs défilants. Dans ce cas, seules les requêtes en mode « QSqlQuery::setForwardOnly() » peuvent être exécutées correctement.

Prise en charge des horodatages

ODBC utilise TIMESTAMP_STRUCT, qui ne contient aucune information relative au fuseau horaire ou à tout autre élément similaire. De ce fait, la fonction QDateTime est utilisée sans tenir compte du fuseau horaire.

Prise en charge des procédures stockées ODBC

Avec Microsoft SQL Server, le jeu de résultats renvoyé par une procédure stockée qui utilise l'instruction `RETURN`, ou qui renvoie plusieurs jeux de résultats, ne sera accessible que si vous définissez le mode « forward only » de la requête sur « forward » à l'aide de la fonction ` QSqlQuery::setForwardOnly()`.

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

Prise en charge Unicode par ODBC

Le plugin QODBC utilisera l'API Unicode si la variable UNICODE est définie. Sur les systèmes Windows, c'est le comportement par défaut. Notez que le pilote ODBC et le SGBD doivent également prendre en charge Unicode.

Pour le pilote ODBC Oracle 9 (Windows), il est nécessaire de cocher l'option « Prise en charge SQL_WCHAR » dans le gestionnaire de pilotes ODBC, sinon Oracle convertira toutes les chaînes Unicode en représentation locale 8 bits.

Options de connexion

Le plugin ODBC de Qt prend en charge les options de connexion suivantes :

Pour plus d’informations sur les options de connexion, veuillez vous reporter à la documentation ODBC relative à la fonction SQLSetConnectAttr().

Comment compiler le plugin ODBC sous Unix et macOS

Il est recommandé d'utiliser unixODBC. Vous trouverez la dernière version ainsi que les pilotes ODBC sur http://www.unixodbc.org. Vous aurez besoin des fichiers d'en-tête et des bibliothèques partagées d'unixODBC.

Indiquez à l'qt-cmake où trouver les fichiers d'en-tête et les bibliothèques partagées d'unixODBC (on suppose ici qu'unixODBC est installé dans /usr/local/unixODBC) puis effectuez la compilation :

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 .

Comment compiler le plugin ODBC sous Windows

Les fichiers d'en-tête et d'inclusion ODBC devraient déjà être installés dans les répertoires appropriés. Il vous suffit de compiler le plugin comme suit :

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 pour PostgreSQL (version 7.3 et supérieure)

Le pilote QPSQL prend en charge la version 7.3 et les versions ultérieures du serveur PostgreSQL.

Pour plus d'informations sur PostgreSQL, rendez-vous sur http://www.postgresql.org.

Prise en charge des horodatages

Depuis Qt 6.8, les valeurs de type « QDateTime » sont converties en UTC avant leur insertion, puis reconverties à partir de l’UTC lors de leur récupération. Pour que cela fonctionne, le pilote définit le fuseau horaire de la connexion sur UTC lors de l'appel à open() (SET TIME ZONE 'UTC'). Bien que PostgreSQL dispose du type de colonne `timestamptz`, le fuseau horaire utilisé lors de l'insertion n'est pas conservé et, par conséquent, toutes les valeurs ` QDateTime ` récupérées sont exprimées en UTC.

Prise en charge Unicode par QPSQL

Le pilote QPSQL détecte automatiquement si la base de données PostgreSQL à laquelle vous vous connectez prend en charge Unicode ou non. Unicode est automatiquement utilisé si le serveur le prend en charge. Notez que le pilote ne prend en charge que l’encodage UTF-8. Si votre base de données utilise un autre encodage, le serveur doit être compilé avec la prise en charge de la conversion Unicode.

La prise en charge d’Unicode a été introduite dans la version 7.1 de PostgreSQL et ne fonctionnera que si le serveur et la bibliothèque cliente ont tous deux été compilés avec la prise en charge des caractères multioctets. Vous trouverez plus d’informations sur la configuration d’un serveur PostgreSQL prenant en charge les caractères multioctets dans le Guide de l’administrateur PostgreSQL, chapitre 5.

Sensibilité à la casse dans QPSQL

Les bases de données PostgreSQL ne tiennent compte de la distinction entre majuscules et minuscules que si le nom de la table ou du champ est placé entre guillemets lors de la création de la table. Ainsi, par exemple, une requête SQL telle que :

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

garantira que l'accès se fera avec la même casse que celle utilisée lors de la création. Si le nom de la table ou du champ n'est pas placé entre guillemets lors de la création, le nom réel de la table ou du champ sera en minuscules. Lorsque les fonctions ` QSqlDatabase::record()` ou ` QSqlDatabase::primaryIndex()` accèdent à une table ou à un champ qui n’était pas entre guillemets lors de sa création, le nom transmis à la fonction doit être en minuscules pour garantir qu’il soit trouvé. Par exemple :

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());

Prise en charge des requêtes « forward-only » dans QPSQL

Pour utiliser les requêtes en mode « forward-only », vous devez compiler le plugin QPSQL avec la bibliothèque cliente PostgreSQL version 9.2 ou ultérieure. Si le plugin est compilé avec une version antérieure, le mode « forward-only » ne sera pas disponible : l'appel à la fonction QSqlQuery::setForwardOnly() avec l'argument true n'aura aucun effet.

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

Lors de la navigation dans les résultats en mode « forward-only », le descripteur de QSqlResult peut changer. Les applications qui utilisent le descripteur de bas niveau du résultat SQL doivent obtenir un nouveau descripteur après chaque appel à l’une des fonctions de récupération de QSqlResult. Exemple :

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

Lors de la lecture des résultats d’une requête en mode « forward-only » avec PostgreSQL, la connexion à la base de données ne peut pas être utilisée pour exécuter d’autres requêtes. Il s’agit d’une limitation de la bibliothèque libpq. Exemple :

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
}

Ce problème ne se produira pas si query1 et query2 utilisent des connexions à la base de données différentes, ou si l'on exécute query2 après la boucle while.

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

Options de connexion

Le plugin Qt PostgreSQL prend en charge toutes les options de connexion spécifiées dans la documentation de la fonction connect() de PostgreSQL.

Comment compiler le plugin QPSQL sous Unix et macOS

Vous devez avoir installé la bibliothèque client PostgreSQL et les en-têtes correspondants.

Pour que qt-cmake puisse trouver les fichiers d'en-tête et les bibliothèques partagées de PostgreSQL, compilez le plugin de la manière suivante (en supposant que le client PostgreSQL soit installé dans /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 .

Comment compiler le plugin QPSQL sous Windows

Installez les bibliothèques de développement PostgreSQL adaptées à votre compilateur. En supposant que PostgreSQL soit installé dans C:\pgsql, compilez le plugin comme suit :

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 .

Les utilisateurs de MinGW peuvent consulter le document en ligne suivant : PostgreSQL MinGW/Native Windows.

Lorsque vous distribuez votre application, n'oubliez pas d'inclure le fichier libpq.dll dans votre package d'installation. Il doit être placé dans le même dossier que l'exécutable de l'application.

QDB2 pour IBM DB2 (version 7.1 et supérieures)

Le plugin Qt DB2 permet d'accéder aux bases de données IBM DB2. Il a été testé avec IBM DB2 v7.1 et 7.2. Vous devez installer la bibliothèque client de développement IBM DB2, qui contient les fichiers d'en-tête et les fichiers de bibliothèque nécessaires à la compilation du plugin QDB2.

Le pilote QDB2 prend en charge les requêtes préparées, la lecture et l'écriture de chaînes Unicode, ainsi que la lecture et l'écriture de BLOB.

Nous vous recommandons d'utiliser une requête unidirectionnelle lors de l'appel de procédures stockées dans DB2 (voir QSqlQuery::setForwardOnly()).

Options de connexion

Le plugin Qt IBM DB2 prend en charge les options de connexion suivantes :

Comment compiler le plugin QDB2 sous Unix et 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 .

Comment compiler le plugin QDB2 sous Windows

Les fichiers d'en-tête et d'inclusion DB2 devraient déjà être installés dans les répertoires appropriés. Il vous suffit de compiler le plugin comme suit :

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 pour SQLite (version 3 et supérieure)

Le plugin Qt SQLite permet d'accéder à des bases de données SQLite. SQLite est une base de données en mémoire, ce qui signifie qu'il n'est pas nécessaire de disposer d'un serveur de base de données. SQLite fonctionne à partir d'un seul fichier, qui doit être indiqué comme nom de la base de données lors de l'ouverture d'une connexion. Si le fichier n'existe pas, SQLite tentera de le créer. SQLite prend également en charge les bases de données en mémoire et les bases de données temporaires. Il suffit de passer respectivement « :memory: » ou une chaîne vide comme nom de base de données.

SQLite présente certaines restrictions concernant les utilisateurs multiples et les transactions multiples. Si vous essayez de lire ou d’écrire sur une ressource à partir de transactions différentes, votre application risque de se bloquer jusqu’à ce qu’une transaction soit validée ou annulée. Le pilote Qt SQLite réessaiera d’écrire sur une ressource verrouillée jusqu’à ce qu’il atteigne un délai d’expiration (voir « QSQLITE_BUSY_TIMEOUT » sur QSqlDatabase::setConnectOptions()).

Dans SQLite, toute colonne, à l’exception d’une colonne INTEGER PRIMARY KEY, peut être utilisée pour stocker n’importe quel type de valeur. Par exemple, une colonne déclarée comme INTEGER peut contenir une valeur entière dans une ligne et une valeur de type texte dans la suivante. Cela s’explique par le fait que SQLite associe le type d’une valeur à la valeur elle-même plutôt qu’à la colonne dans laquelle elle est stockée. Il en résulte que le type renvoyé par la fonction QSqlField::metaType() n’indique que le type recommandé pour le champ. Il ne faut pas en déduire le type réel et il convient de vérifier le type de chaque valeur individuellement.

Le pilote est verrouillé pour les mises à jour pendant l’exécution d’une requête `SELECT`. Cela peut poser des problèmes lors de l’utilisation de ` QSqlTableModel `, car les vues d’éléments de Qt récupèrent les données à la demande (à l’aide de `QSqlQuery::fetchMore()` dans le cas de ` QSqlTableModel`.

Vous trouverez des informations sur SQLite à l’adresse http://www.sqlite.org.

Prise en charge des horodatages

SQLite ne dispose pas d’un type de colonne spécifique pour les horodatums. Un horodatum ( QDateTime ) est stocké sous forme de chaîne de caractères, au format Qt::ISODateWithMs; ainsi, les informations relatives au fuseau horaire ( QDateTime ) sont conservées lors de l’insertion et de la consultation.

Options de connexion

Le plugin Qt SQLite prend en charge les options de connexion suivantes :

Comment compiler le plugin QSQLITE

La version 3 de SQLite est incluse dans Qt en tant que bibliothèque tierce. Elle peut être compilée en passant le paramètre « -DFEATURE_system_sqlite=OFF » à la ligne de commande « qt-cmake ».

Si vous ne souhaitez pas utiliser la bibliothèque SQLite incluse avec Qt, vous pouvez passer l'option -DFEATURE_system_sqlite=ON à la ligne de commande qt-cmake afin d'utiliser les bibliothèques SQLite du système d'exploitation. Cette approche est recommandée dans la mesure du possible, car elle réduit la taille de l'installation et supprime un composant pour lequel vous devez suivre les avis de sécurité.

Sous Unix et macOS (remplacez $SQLITE par le répertoire où se trouve 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 .

Sous Windows (en supposant que SQLite soit installé dans 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 .

Activer l’opérateur REGEXP

SQLite intègre un opérateur REGEXP. Cependant, l'implémentation nécessaire doit être fournie par l'utilisateur. Pour plus de commodité, une implémentation par défaut peut être activée via setting the connect option QSQLITE_ENABLE_REGEXP avant d'exécuter the database connection is opened. Une instruction SQL telle que « column REGEXP 'pattern' » se traduit alors essentiellement par le code Qt suivant

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

Pour améliorer les performances, les expressions régulières sont mises en cache en interne. Par défaut, la taille du cache est de 25, mais elle peut être modifiée via la valeur de l'option. Par exemple, en passant «QSQLITE_ENABLE_REGEXP=10 », la taille du cache est réduite à 10.

Compatibilité avec le format de fichier QSQLITE

Les versions mineures de SQLite peuvent parfois rompre la compatibilité ascendante du format de fichier. Par exemple, SQLite 3.3 peut lire les fichiers de base de données créés avec SQLite 3.2, mais les bases de données créées avec SQLite 3.3 ne peuvent pas être lues par SQLite 3.2. Veuillez vous reporter à la documentation SQLite et aux journaux des modifications pour obtenir des informations sur la compatibilité du format de fichier entre les versions.

Les versions mineures de Qt suivent généralement les versions mineures de SQLite, tandis que les versions de correctifs de Qt suivent les versions de correctifs de SQLite. Les versions de correctifs sont donc compatibles à la fois en amont et en aval.

Pour forcer SQLite à utiliser un format de fichier spécifique, il est nécessaire de compiler et de fournir votre propre plugin de base de données avec votre propre bibliothèque SQLite, comme illustré ci-dessus. Certaines versions de SQLite peuvent être forcées à écrire dans un format de fichier spécifique en définissant la directive ` SQLITE_DEFAULT_FILE_FORMAT ` lors de la compilation de SQLite.

QMIMER pour Mimer SQL version 11 et supérieures

Le plugin Qt Mimer SQL permet d’interagir avec le SGBDR Mimer SQL. Mimer SQL fournit des solutions de bases de données relationnelles compactes, évolutives et robustes, conformes aux normes internationales ISO SQL. Mimer SQL est disponible sous Windows, Linux, macOS et OpenVMS, ainsi que sur plusieurs plateformes embarquées telles que QNX, Android et Linux embarqué.

Mimer SQL prend entièrement en charge Unicode. Pour traiter des données Unicode, il faut utiliser les types de colonnes « National Character » (NCHAR), « National Character Varying » (NVARCHAR) ou « National Character Large Object » (NCLOB). Pour plus d’informations sur Mimer SQL et Unicode, consultez https://developer.mimer.com/features/multilingual-support

Prise en charge des horodatages

Mimer SQL ne tient pas compte des fuseaux horaires et la fonction « QDateTime » est utilisée sans tenir compte du fuseau horaire.

Prise en charge des procédures stockées QMIMER

Mimer SQL dispose de procédures stockées conformes à la norme SQL (PSM) et le plugin prend entièrement en charge les paramètres IN, OUT et INOUT, ainsi que les procédures de jeu de résultats.

Exemple de procédure stockée avec des paramètres INOUT et OUT :

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

Code source permettant d'accéder aux valeurs INOUT et 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();

Comment compiler le plugin QMIMER sous Unix et macOS

Vous avez besoin des fichiers d'en-tête et des bibliothèques partagées de Mimer SQL. Vous pouvez vous les procurer en installant l'une des versions de Mimer SQL disponibles sur 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 .

Comment compiler le plugin QMIMER sous Windows

Vous avez besoin des fichiers d'en-tête et des bibliothèques partagées de Mimer SQL. Pour les obtenir, installez l'une des versions de Mimer SQL disponibles à l'adresse 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 pour Borland InterBase

Le plugin Qt InterBase permet d’accéder aux bases de données InterBase et Firebird. InterBase peut être utilisé soit en mode client/serveur, soit sans serveur, auquel cas il fonctionne sur des fichiers locaux. Le fichier de base de données doit exister avant qu’une connexion puisse être établie. Firebird doit être utilisé avec une configuration serveur.

Notez qu'InterBase exige que vous indiquiez le chemin d'accès complet au fichier de base de données, qu'il soit stocké localement ou sur un autre serveur.

Prise en charge des horodatages

InterBase stocke les horodatages en UTC sans aucune information relative au fuseau horaire. De ce fait, la fonction ` QDateTime ` est utilisée sans tenir compte du fuseau horaire.

Depuis Firebird 4.0, la base de données prend en charge les horodatages avec fuseaux horaires. Les informations de fuseau horaire sont stockées séparément de l'horodatage afin de pouvoir être récupérées correctement ultérieurement. Consultez la documentation Firebird pour plus d'informations sur la gestion des horodatages.

Options de connexion

Le plugin Qt Borland InterBase prend en charge les options de connexion suivantes :

Comment compiler le plugin QIBASE

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

Vous avez besoin des en-têtes et des bibliothèques de développement InterBase/Firebird pour compiler ce plugin.

En raison d'incompatibilités de licence avec la GPL, les utilisateurs de l'édition open source de Qt ne sont pas autorisés à lier ce plugin aux éditions commerciales d'InterBase. Veuillez utiliser Firebird ou l'édition gratuite d'InterBase.

Procédures stockées QIBASE

InterBase/Firebird renvoient les valeurs OUT sous forme de jeu de résultats ; ainsi, lors de l'appel d'une procédure stockée, seules les valeurs IN doivent être liées via ` QSqlQuery::bindValue()`. Les valeurs RETURN/OUT peuvent être récupérées via ` QSqlQuery::value()`. Exemple :

QSqlQuery q;
q.exec("execute procedure my_procedure");
if (q.next())
    qDebug() << q.value(0); // outputs the first RETURN/OUT value

Comment compiler le plugin QIBASE sous Unix et macOS

Les instructions suivantes partent du principe qu'InterBase ou Firebird est installé dans le répertoire « /opt/interbase » :

Si vous utilisez 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 .

Vous pouvez également utiliser les variables CMake ` Interbase_INCLUDE_DIR ` et ` Interbase_LIBRARY ` pour spécifier directement le chemin d'inclusion et la bibliothèque.

Comment compiler le plugin QIBASE sous Windows

Les instructions suivantes partent du principe qu’InterBase ou Firebird est installé dans C:\interbase:

Si vous utilisez 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 .

Vous pouvez également utiliser les variables CMake ` Interbase_INCLUDE_DIR ` et ` Interbase_LIBRARY ` pour spécifier directement le chemin d'inclusion et la bibliothèque.

Notez que C:\interbase\bin doit se trouver dans PATH.

Dépannage

Vous devez toujours utiliser des bibliothèques clientes qui ont été compilées avec le même compilateur que celui que vous utilisez pour votre projet. Si vous ne disposez pas d’une distribution source pour compiler vous-même les bibliothèques clientes, vous devez vous assurer que la bibliothèque précompilée est compatible avec votre compilateur, sinon vous obtiendrez de nombreuses erreurs de « symboles non définis ».

Si la compilation d'un plugin réussit mais que celui-ci ne peut pas être chargé par la suite, suivez les étapes suivantes pour identifier la cause du problème :

1. Assurez-vous que le plugin se trouve dans le répertoire approprié. Vous pouvez utiliser QApplication::libraryPaths() pour déterminer où Qt recherche les plugins.
2. Assurez-vous que les bibliothèques clientes du SGBD sont disponibles sur le système. Sous Unix, exécutez la commande ` ldd ` et passez le nom du plugin en paramètre, par exemple ` ldd libqsqlmysql.so`. Vous recevrez un avertissement si l’une des bibliothèques clientes est introuvable. Sous Windows, vous pouvez utiliser le « Dependency Walker » de Visual Studio ou l’interface graphique « Dependencies » pour identifier les bibliothèques dépendantes. À l’aide de Qt Creator, vous pouvez mettre à jour la variable d’environnement « PATH » dans la section « Exécution » du panneau « Projet » afin d’y inclure le chemin d’accès au dossier contenant les bibliothèques clientes.
3. Lorsque vous utilisez MSVC, assurez-vous également que le plugin est compilé avec le type de compilation approprié. En raison des différences entre les runtimes MSVC pour le débogage et la version finale, une compilation Qt en mode débogage ne peut pas charger un plugin Qt en version finale, et inversement.
4. Exécutez l'exécutable Qt compilé avec la variable d'environnement QT_DEBUG_PLUGINS définie afin d'obtenir un débogage très détaillé lors du chargement des plugins.
5. Pour récupérer les messages de débogage éventuels provenant du sous-système SQL, activez la sortie en définissant la variable d’environnement ` QT_LOGGING_RULES ` sur ` qt.sql.*.debug=true`. N’oubliez pas d’activer la console lorsque vous travaillez sous Windows. Consultez Logging Rules pour une explication plus détaillée sur la manière de définir les règles de journalisation.

Assurez-vous d’avoir suivi le guide de déploiement des plug-ins.

Comment écrire votre propre pilote de base de données

QSqlDatabase est chargé de charger et de gérer les plugins de pilotes de base de données. Lorsqu'une base de données est ajoutée (voir QSqlDatabase::addDatabase()), le plugin de pilote approprié est chargé (à l'aide de QSqlDriverPlugin). QSqlDatabase s'appuie sur le plugin de pilote pour fournir des interfaces permettant d'QSqlDriver et QSqlResult.

QSqlDriver est une classe de base abstraite qui définit les fonctionnalités d’un pilote de base de données SQL. Cela inclut des fonctions telles que QSqlDriver::open() et QSqlDriver::close(). QSqlDriver est chargé de se connecter à une base de données, de mettre en place l’environnement approprié, etc. De plus, QSqlDriver peut créer des objets QSqlQuery adaptés à l’API spécifique de la base de données. QSqlDatabase transmet directement bon nombre de ses appels de fonction à QSqlDriver, qui fournit l’implémentation concrète.

QSqlResult est une classe de base abstraite qui définit les fonctionnalités d’une requête de base de données SQL. Cela inclut des instructions telles que SELECT, UPDATE, ALTER et TABLE. QSqlResult contient des fonctions telles que QSqlResult::next() et QSqlResult::value(). QSqlResult est chargé d’envoyer les requêtes à la base de données, de renvoyer les données de résultat, etc. QSqlQuery transfère la plupart de ses appels de fonction directement à QSqlResult, qui fournit l’implémentation concrète.

QSqlDriver et QSqlResult sont étroitement liées. Lors de l’implémentation d’un pilote Qt SQL, ces deux classes doivent être sous-classées et les méthodes virtuelles abstraites de chaque classe doivent être implémentées.

Pour implémenter un pilote Qt SQL sous forme de plugin (afin qu’il soit reconnu et chargé par la bibliothèque Qt lors de l’exécution), le pilote doit utiliser la macro Q_PLUGIN_METADATA(). Consultez la section « Comment créer des plugins Qt » pour plus d’informations à ce sujet. Vous pouvez également découvrir comment cela est réalisé dans les plugins SQL fournis avec Qt à l’adresse QTDIR/qtbase/src/plugins/sqldrivers.

Le code suivant peut servir de squelette pour un pilote 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); }
};