Pilotes de base 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. Comme l'API du module Qt SQL est indépendante de la base de données, tout le code spécifique à la base de données est contenu dans ces pilotes. Plusieurs pilotes sont fournis avec Qt, et d'autres pilotes peuvent être ajoutés. Le code source des pilotes est fourni et peut être utilisé comme modèle pour écrire vos propres pilotes.

Bases de données prises en charge

Le tableau ci-dessous dresse la liste des pilotes fournis avec Qt :

SQLite est le système de base de données en cours de traitement qui offre la meilleure couverture de test et le meilleur support sur toutes les plates-formes. Oracle via OCI, PostgreSQL et MySQL via ODBC ou un pilote natif sont bien testés sous Windows et Linux. L'exhaustivité du support pour les autres systèmes dépend de la disponibilité et de la qualité des bibliothèques clients.

Création des pilotes

Compiler Qt avec un pilote spécifique

Le script Qt configure tente de détecter automatiquement les bibliothèques client disponibles sur votre machine. Exécutez configure -help pour voir quels pilotes peuvent être construits. 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 configure ne peut pas détecter les bibliothèques et les fichiers d'inclusion 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 d'accès à l'aide de variables de chemin d'accès aux bibliothèques et aux fichiers d'inclusion spécifiques au pilote ou à l'aide de 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, passez 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 des pilotes de la manière décrite ci-dessus, CMake ne vérifie pas les dépendances et utilise les chemins fournis tels quels. Ceci est particulièrement utile si le paquetage fournit son propre ensemble de bibliothèques système qui ne doivent pas être reconnues par la routine de construction.

Les particularités de chaque pilote sont expliquées ci-dessous.

Compiler uniquement un pilote SQL spécifique

Il est possible de ne compiler qu'un pilote SQL spécifique lorsque Qt SQL est déjà construit ou installé en version binaire. Mais vous devez vous assurer d'installer exactement la même version des sources de Qt (par exemple via Qt Maintenance Tool) - sinon vous risquez d'obtenir des erreurs de compilation dues à des apis modifiées. Veillez également à configurer correctement l'environnement de construction 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 configurer MySQL) ressemble à ceci :

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 avoir configuré avec qt-cmake, construire le pilote en exécutant ninja.

En raison des aspects pratiques de la gestion des dépendances externes, seul le plugin SQLite est livré 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 complet de Qt. Notez qu'il n'est pas possible de configurer chaque pilote séparément, mais seulement tous en même temps. Les pilotes peuvent cependant être construits séparément.

Spécificités des pilotes

QMYSQL pour MySQL ou MariaDB 5.6 et supérieur

MariaDB est un dérivé de MySQL destiné à rester un logiciel libre et open-source sous la licence publique générale GNU. MariaDB a pour but de maintenir une grande compatibilité avec MySQL, en assurant une capacité de remplacement direct avec une parité binaire de bibliothèque et une correspondance exacte avec les API et les commandes de MySQL. Par conséquent, les plugins pour MySQL et MariaDB sont combinés en un seul plugin Qt.

Prise en charge de l'horodatage

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

Support des procédures stockées QMYSQL

MySQL supporte les procédures stockées au niveau SQL, mais n'a pas d'API pour 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 au lieu de 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 pour 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é est un remplacement direct de la bibliothèque client normale. Avec le serveur MySQL intégré, un serveur MySQL n'est pas nécessaire 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 en ajoutant -DMySQL_LIBRARY=<path/to/mysqld/>libmysqld.<so|lib|dylib> à la ligne de commande configure.

Veuillez vous référer à la documentation MySQL, chapitre "libmysqld, the Embedded MySQL Server Library" pour plus d'informations sur le serveur MySQL intégré.

Options de connexion

Le plugin Qt MySQL/MariaDB honore les options de connexion suivantes :

Pour plus d'informations sur les options de connexion, veuillez vous référer à la documentation MySQL mysql_options().

Comment construire le plugin QMYSQL sur Unix et macOS

Vous avez besoin des fichiers d'en-tête MySQL / MariaDB, ainsi que de la bibliothèque partagée libmysqlclient.<so|dylib> / libmariadb.<so|dylib>. En fonction de votre distribution Linux, vous pouvez avoir besoin d'installer un paquetage qui s'appelle généralement "mysql-devel" ou "mariadb-devel".

Indiquez à qt-cmake où trouver les fichiers d'en-tête MySQL / MariaDB et les bibliothèques partagées (on suppose ici que MySQL / MariaDB est installé sur /usr/local) et construisez :

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 construire le plugin QMYSQL sous Windows

Vous devez obtenir les fichiers d'installation de MySQL (par exemple, MySQL web installer ou MariaDB C Connector). Lancez le programme d'installation, sélectionnez l'installation personnalisée et installez le MySQL C Connector qui correspond à votre installation de Qt (x86 ou x64). Après l'installation, vérifiez que les fichiers nécessaires sont 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

Construisez le plugin comme suit (on suppose ici que <MySQL dir> est 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 paquet d'installation. Il doit être placé dans le même dossier que l'exécutable de l'application. libmysql.dll a également besoin des bibliothèques d'exécution MSVC qui peuvent être installées avec vcredist.exe.

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

Le plugin Qt OCI prend en charge la connexion à la base de données Oracle en fonction de la version du client instantané utilisé. Cela dépend de ce qu'Oracle indique supporter. Le plugin détecte automatiquement la version de la base de données et active les fonctionnalités en conséquence.

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

Authentification de l'utilisateur OCI

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

Laissez le nom d'utilisateur et le mot de passe vides lors de l'ouverture d'une connexion avec QSqlDatabase pour utiliser l'authentification par références externes.

Support OCI BLOB/LOB

Il est possible de lire et d'écrire des objets binaires de grande taille (BLOB), mais il faut savoir que ce processus peut nécessiter beaucoup de mémoire. Vous devez utiliser une requête forward only pour sélectionner les champs LOB (voir QSqlQuery::setForwardOnly()).

L'insertion de BLOB doit se faire soit à l'aide d'une requête préparée dans laquelle les BLOB sont liés à des espaces réservés, soit à l'aide de QSqlTableModel, qui utilise une requête préparée pour effectuer cette opération en interne.

Options de connexion

Le plugin Qt OCI accepte les options de connexion suivantes :

Comment construire le plugin OCI sur Unix et macOS

Tout ce dont vous avez besoin est le " - Basic" et le "Instant Client Package - SDK".

Les fichiers de la bibliothèque Oracle nécessaires à la construction du pilote :

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

Indiquer à qt-cmake où trouver les fichiers d'en-tête et les bibliothèques partagées Oracle et les compiler.

Nous supposons que vous avez installé les paquets RPM du SDK Instant Client Package (vous devez ajuster 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 construire le plugin OCI sous Windows

Le choix de l'option "Programmer" dans le programme d'installation du client Oracle à partir du CD d'installation du client Oracle est généralement suffisant pour construire le plugin. Pour certaines versions du client Oracle, vous devrez peut-être aussi sélectionner l'option "Call Interface (OCI)" si elle est disponible.

Construisez le plugin comme suit (on suppose ici que le client Oracle est installé sur C:\oracle et que le SDK est installé sur 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 devez également ajouter le chemin oci.dll à votre variable d'environnement PATH:

set PATH=%PATH%;C:\oracle

QODBC pour Open Database Connectivity (ODBC)

ODBC est une interface générale 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 avoir un gestionnaire de pilote ODBC installé, sinon 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 complète de pilote ODBC. Lorsque vous passez une chaîne de pilote, vous devez vous assurer que tous les paramètres (nom d'utilisateur, mot de passe, ...) sont correctement échappés. En passant le nom d'utilisateur ou le mot de passe par les fonctions QSqlDatabase, l'échappement est effectué par le plugin QODBC.

Le plugin QODBC a besoin d'un gestionnaire de pilote ODBC compatible avec la version 2.0 ou ultérieure. Certains pilotes ODBC prétendent être conformes à 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 après l'établissement d'une connexion et refuse de fonctionner si la vérification échoue. Si vous n'aimez pas ce comportement, vous pouvez supprimer la ligne #define ODBC_CHECK_DRIVER du fichier qsql_odbc.cpp. Faites-le à vos risques et périls !

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

Si l'accès à la source de données ODBC est très lent, assurez-vous que le suivi 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éroulants. Dans ce cas, seules les requêtes en mode QSqlQuery::setForwardOnly() peuvent être utilisées avec succès.

Prise en charge de l'horodatage

ODBC utilise TIMESTAMP_STRUCT qui ne contient aucune information sur le fuseau horaire ou autre. C'est pourquoi le site QDateTime est utilisé sans tenir compte du fuseau horaire.

Support des procédures stockées ODBC

Avec Microsoft SQL Server, l'ensemble de résultats renvoyés par une procédure stockée qui utilise l'instruction return ou renvoie plusieurs ensembles de résultats ne sera accessible que si vous avez défini le mode forward only de la requête à forward en utilisant 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 de l'Unicode par ODBC

Le plugin QODBC utilisera l'API Unicode si UNICODE est défini. Sur les systèmes Windows, c'est la valeur par défaut. Notez que le pilote ODBC et le SGBD doivent également supporter l'Unicode.

Pour le pilote ODBC Oracle 9 (Windows), il est nécessaire de cocher la case "SQL_WCHAR support" dans le gestionnaire du pilote ODBC, sinon Oracle convertira toutes les chaînes Unicode en représentation locale 8 bits.

Options de connexion

Le plugin Qt ODBC accepte les options de connexion suivantes :

Pour plus d'informations sur les options de connexion, veuillez vous référer à la documentation ODBC SQLSetConnectAttr().

Comment construire le plugin ODBC sur Unix et macOS

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

Indiquez à qt-cmake où trouver les fichiers d'en-tête unixODBC et les bibliothèques partagées (on suppose ici que unixODBC est installé sur /usr/local/unixODBC) et construisez-les :

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 construire le plugin ODBC sous Windows

Les fichiers d'en-tête et d'inclusion ODBC devraient déjà être installés dans les bons répertoires. 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 plus)

Le pilote QPSQL supporte la version 7.3 et plus du serveur PostgreSQL.

Pour plus d'informations sur PostgreSQL, visitez le site http://www.postgresql.org.

Support de l'horodatage

Depuis la version 6.8 de Qt XML, les valeurs de QDateTime sont converties en UTC avant l'insertion et de nouveau en UTC lors de la récupération. Pour que cela fonctionne, le pilote définit le fuseau horaire de la connexion à UTC pendant open() (SET TIME ZONE 'UTC'). Bien que PostgreSQL ait le type de colonne `timestamptz`, le fuseau horaire utilisé lors de l'insertion n'est pas préservé et donc toutes les valeurs récupérées de QDateTime sont UTC.

Support Unicode de QPSQL

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

Le support Unicode a été introduit dans la version 7.1 de PostgreSQL et ne fonctionnera que si le serveur et la bibliothèque client ont été compilés avec le support multibyte. Plus d'informations sur la façon de configurer un serveur PostgreSQL supportant le multibyte peuvent être trouvées dans le Guide de l'Administrateur PostgreSQL, Chapitre 5.

Sensibilité à la casse de QPSQL

Les bases de données PostgreSQL ne respectent la sensibilité à la casse que si le nom de la table ou du champ est cité lors de la création de la table. Ainsi, par exemple, une requête SQL telle que :

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

garantira qu'il sera possible d'y accéder avec la même casse que celle utilisée. Si le nom de la table ou du champ n'est pas cité lors de sa création, le nom réel de la table ou du champ sera en minuscules. Lorsque QSqlDatabase::record() ou QSqlDatabase::primaryIndex() accède à 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 s'assurer qu'il est 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());

QPSQL Prise en charge des requêtes en aval uniquement

Pour utiliser les requêtes forward-only, vous devez compiler le plugin QPSQL avec la bibliothèque client PostreSQL version 9.2 ou ultérieure. Si le plugin est construit avec une version plus ancienne, le mode forward-only ne sera pas disponible - appeler QSqlQuery::setForwardOnly() avec 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 handle de QSqlResult peut changer. Les applications qui utilisent le handle de bas niveau du résultat SQL doivent obtenir un nouveau handle 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 : la connexion à la base de données ne peut pas être utilisée pour exécuter d'autres requêtes :

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 la requête 1 et la requête 2 utilisent des connexions de base de données différentes, ou si nous exécutons la requête 2 après la boucle while.

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

Options de connexion

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

Comment construire le plugin QPSQL sur Unix et macOS

Vous devez installer la bibliothèque et les en-têtes du client PostgreSQL.

Pour que qt-cmake trouve 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é sur /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 construire le plugin QPSQL sous Windows

Installez les bibliothèques de développement PostgreSQL appropriées pour votre compilateur. En supposant que PostgreSQL a été installé dans C:\pgsql, construisez 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 libpq.dll dans votre paquetage 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érieure)

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 du client de développement IBM DB2, qui contient les fichiers d'en-tête et de bibliothèque nécessaires à la compilation du plugin QDB2.

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

Nous suggérons l'utilisation d'une requête directe lors de l'appel de procédures stockées dans DB2 (voir QSqlQuery::setForwardOnly()).

Options de connexion

Le plugin Qt IBM DB2 accepte les options de connexion suivantes :

Comment construire le plugin QDB2 sur 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 créer le plugin QDB2 sous Windows

Les fichiers d'en-tête et d'inclusion de DB2 devraient déjà être installés dans les bons répertoires. 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 plus)

Le plugin Qt SQLite permet d'accéder aux bases de données SQLite. SQLite est une base de données en cours de traitement, ce qui signifie qu'il n'est pas nécessaire d'avoir un serveur de base de données. SQLite fonctionne sur un seul fichier, qui doit être défini comme nom de la base de données lors de l'ouverture d'une connexion. Si le fichier n'existe pas, SQLite essaiera de le créer. SQLite supporte également 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 a quelques restrictions concernant les utilisateurs multiples et les transactions multiples. Si vous essayez de lire/écrire sur une ressource à partir de différentes transactions, votre application peut se bloquer jusqu'à ce qu'une transaction soit validée ou annulée. Le pilote Qt SQLite tentera à nouveau d'écrire sur une ressource verrouillée jusqu'à ce qu'il atteigne un délai d'attente (voir QSQLITE_BUSY_TIMEOUT à 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 texte dans la suivante. Cela est dû au 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. En conséquence, le type renvoyé par QSqlField::metaType() indique uniquement 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 des valeurs individuelles.

Le pilote est bloqué pour les mises à jour pendant l'exécution d'une sélection. 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 au fur et à mesure (avec QSqlQuery::fetchMore() dans le cas de QSqlTableModel).

Vous trouverez des informations sur SQLite sur http://www.sqlite.org.

Prise en charge de l'horodatage

SQLite ne dispose pas d'un type de colonne d'horodatage spécial. Une colonne QDateTime est stockée sous forme de chaîne, formatée en Qt::ISODateWithMs et, par conséquent, les informations relatives au fuseau horaire QDateTime sont préservées lors de l'insertion et de la sélection.

Options de connexion

Le plugin Qt SQLite accepte les options de connexion suivantes :

Comment construire le plugin QSQLITE

SQLite version 3 est une bibliothèque tierce incluse dans Qt. Il peut être construit 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 dans Qt XML, vous pouvez passer le paramètre -DFEATURE_system_sqlite=ON à la ligne de commande qt-cmake pour utiliser les bibliothèques SQLite du système d'exploitation. Cette solution 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ù réside 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 est livré avec une opération REGEXP. Cependant, l'implémentation nécessaire doit être fournie par l'utilisateur. Par commodité, une implémentation par défaut peut être activée par setting the connect option QSQLITE_ENABLE_REGEXP avant the database connection is opened. Une instruction SQL telle que "column REGEXP 'pattern'" se traduit alors par le code Qt SQL suivant

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

Pour de meilleures 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 par la valeur de l'option. Par exemple, passer "QSQLITE_ENABLE_REGEXP=10" réduit la taille du cache à 10.

Compatibilité des formats de fichiers QSQLITE

Les versions mineures de SQLite rompent parfois la compatibilité avec les formats de fichiers. 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 référer à la documentation de SQLite et aux journaux de modifications pour obtenir des informations sur la compatibilité des formats de fichiers 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 avec le passé et avec l'avenir.

Pour forcer SQLite à utiliser un format de fichier spécifique, il est nécessaire de construire et d'expédier 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 un format de fichier spécifique en définissant le paramètre SQLITE_DEFAULT_FILE_FORMAT lors de la construction de SQLite.

QMIMER pour Mimer SQL version 11 et supérieure

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

Mimer SQL supporte entièrement l'Unicode. Pour travailler avec des données Unicode, les types de colonnes National Character (NCHAR), National Character Varying (NVARCHAR), ou National Character Large Object (NCLOB) doivent être utilisés. Pour plus d'informations sur Mimer SQL et l'unicode, voir https://developer.mimer.com/features/multilingual-support.

Prise en charge des horodatages

MimerSQL ne connaît pas les fuseaux horaires et QDateTime est utilisé sans tenir compte du fuseau horaire.

Support des procédures stockées QMIMER

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

Exemple de procédure stockée avec les 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 pour 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 construire 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 les obtenir en installant n'importe quelle variante de Mimer SQL à 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="/usr/include" -DMimer_LIBRARIES="/usr/lib/libmimer.so"
cmake --build .
cmake --install .

Comment construire le plugin QMIMER sous Windows

Vous avez besoin des fichiers d'en-tête et des bibliothèques partagées de Mimer SQL. Vous les obtiendrez en installant l'une des variantes 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é en tant que client/serveur ou 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 vous demande de spécifier le chemin d'accès complet au fichier de base de données, qu'il soit stocké localement ou sur un autre serveur.

Support de l'horodatage

Interbase stocke les horodatages en UTC sans aucune information sur le fuseau horaire. C'est pourquoi le site QDateTime est utilisé sans tenir compte du fuseau horaire.

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

Options de connexion

Le plugin Qt Borland InterBase accepte les options de connexion suivantes :

Comment construire 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 construire ce plugin.

En raison d'incompatibilités de licence avec la GPL, les utilisateurs de Qt Open Source Edition 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 des valeurs OUT en tant qu'ensemble de résultats, donc 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 construire le plugin QIBASE sur Unix et macOS

Ce qui suit suppose qu'InterBase ou Firebird est installé sur /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 .

En option, utilisez les variables CMake Interbase_INCLUDE_DIR et Interbase_LIBRARY pour spécifier directement le chemin d'inclusion et la bibliothèque.

Comment construire le plugin QIBASE sous Windows

Ce qui suit suppose qu'InterBase ou Firebird est installé à l'adresse 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 .

En option, utilisez 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 le répertoire PATH.

Résolution des problèmes

Vous devez toujours utiliser des bibliothèques client qui ont été compilées avec le même compilateur que celui que vous utilisez pour votre projet. Si vous ne pouvez pas obtenir une distribution des sources 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 type "symboles non définis".

Si la compilation d'un plugin réussit mais qu'il ne peut pas être chargé par la suite, suivez les étapes suivantes pour trouver le coupable :

1. Assurez-vous que le plugin se trouve dans le bon répertoire. Vous pouvez utiliser QApplication::libraryPaths() pour déterminer où Qt recherche les plugins.
2. Assurez-vous que les bibliothèques client 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 obtiendrez un avertissement si l'une des bibliothèques client n'a pas été trouvée. Sous Windows, vous pouvez utiliser l'outil de recherche de dépendances de Visual Studio ou l'interface graphique Dependencies pour trouver les bibliothèques dépendantes. Avec Qt Creator, vous pouvez mettre à jour la variable d'environnement PATH dans la section Run du panneau Project pour inclure le chemin d'accès au dossier contenant les bibliothèques clientes.
3. Si vous utilisez MSVC, assurez-vous également que le plugin est construit avec le bon type de construction. En raison des différents temps d'exécution de MSVC pour le débogage et la mise à jour, une compilation de Qt pour le débogage ne peut pas charger un plugin Qt pour la mise à jour et vice versa.
4. Exécutez l'exécutable Qt compilé avec la variable d'environnement QT_DEBUG_PLUGINS pour obtenir une sortie de débogage très verbeuse lors du chargement des plugins.
5. Pour récupérer les éventuels messages de débogage 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. Voir 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 plugins.

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

QSqlDatabase est responsable du chargement et de la gestion des plugins du pilote 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 à QSqlDriver et QSqlResult.

QSqlDriver est une classe de base abstraite qui définit la fonctionnalité d'un pilote de base de données SQL. Elle comprend des fonctions telles que QSqlDriver::open() et QSqlDriver::close(). QSqlDriver est responsable de la connexion à une base de données, de l'établissement de l'environnement approprié, etc. En outre, QSqlDriver peut créer des objets QSqlQuery adaptés à l'API particulière de la base de données. QSqlDatabase transmet un grand nombre de ses appels de fonction directement à QSqlDriver, qui fournit l'implémentation concrète.

QSqlResult est une classe de base abstraite qui définit la fonctionnalité d'une requête de base de données SQL. Elle comprend des instructions telles que SELECT, UPDATE, et ALTER TABLE . QSqlResult contient des fonctions telles que QSqlResult::next() et QSqlResult::value(). QSqlResult est responsable de l'envoi des requêtes à la base de données, du retour des données de résultat, etc. QSqlQuery transmet un grand nombre de ses appels de fonction directement à QSqlResult, qui fournit l'implémentation concrète.

QSqlDriver et QSqlResult sont étroitement liés. 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 en tant que plugin (afin qu'il soit reconnu et chargé par la bibliothèque Qt au moment de l'exécution), le pilote doit utiliser la macro Q_PLUGIN_METADATA(). Lisez Comment créer des plugins Qt pour plus d'informations à ce sujet. Vous pouvez également vérifier comment cela est fait dans les plugins Qt SQL fournis avec Qt à l'adresse QTDIR/qtbase/src/plugins/sqldrivers.

Le code suivant peut être utilisé comme 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); }
};