Драйверы баз данных SQL

Модуль Qt SQL использует драйверы плагины для взаимодействия с различными API баз данных. Поскольку API модуля SQL Qt независим от базы данных, весь код, специфичный для базы данных, содержится в этих драйверах. Qt поставляется с несколькими драйверами, и можно добавить другие. Исходный код драйвера предоставляется и может использоваться в качестве модели для создания собственных драйверов.

Поддерживаемые базы данных

В таблице ниже перечислены драйверы, включенные в Qt:

SQLite — это инпроцессная система баз данных с лучшим охватом тестирования и поддержкой на всех платформах. Oracle через OCI, PostgreSQL и MySQL через ODBC или родной драйвер хорошо протестированы в Windows и Linux. Полное соответствие поддержки других систем зависит от доступности и качества библиотек клиентов.

Примечание: Для компиляции плагина драйвера вам нужна соответствующая библиотека клиента для вашей системы управления базами данных (СУБД). Это обеспечивает доступ к API, экспонируемому СУБД, и обычно поставляется с ней. Большинство программ установки также позволяют устанавливать «библиотеки разработки», и именно они вам нужны. Эти библиотеки отвечают за низкоуровневое взаимодействие с СУБД. Также убедитесь, что установлены правильные библиотеки базы данных для вашей архитектуры Qt (32 или 64 бита).

Примечание: При использовании Qt на условиях открытого исходного кода, но с проприетарной базой данных, проверьте совместимость лицензии библиотеки клиента с LGPL.

Компиляция драйверов

Компиляция Qt с указанием конкретного драйвера

Сценарий Qt configure пытается автоматически обнаружить доступные библиотеки клиента на вашем компьютере. Запустите configure -help, чтобы увидеть, какие драйверы можно скомпилировать. Вы должны получить вывод, подобный этому:

[...]

Database options:

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

[...]

Сценарий configure не может обнаружить необходимые библиотеки и файлы заголовков, если они не находятся в стандартных путях, поэтому может потребоваться указать эти пути, используя параметры командной строки *_INCDIR=, *_LIBDIR= или *_PREFIX=. Например, если ваши файлы MySQL установлены в /usr/local/mysql (или в C:/Program Files/MySQL/MySQL Connector C 6.1 в Windows), то передайте следующий параметр в конфигурацию: MYSQL_PREFIX=/usr/local/mysql (или MYSQL_PREFIX="C:/Program Files/MySQL/MySQL Connector C 6.1" для Windows). Подробности для каждого драйвера описаны ниже.

Примечание: Если что-то пойдет не так, и вы хотите, чтобы qmake повторно проверил доступные драйверы, удалите config.cache в <QTDIR>/qtbase/src/plugins/sqldrivers — в противном случае qmake не будет искать доступные драйверы повторно. Если во время этапа qmake возникла ошибка, откройте config.log, чтобы узнать, что пошло не так.

Компиляция только определенного драйвера SQL

Типичный запуск qmake (в данном случае для конфигурации MySQL) выглядит следующим образом:

C:\Qt5\5.13.2\Src\qtbase\src\plugins\sqldrivers>qmake -version
QMake version 3.1
Using Qt version 5.13.2 in C:/Qt5/5.13.2/mingw73_64/lib
C:\Qt5\5.13.2\Src\qtbase\src\plugins\sqldrivers>qmake -- MYSQL_INCDIR="C:/Program Files/MySQL/MySQL Connector C 6.1/include" MYSQL_LIBDIR="C:/Program Files/MySQL/MySQL Connector C 6.1/lib"
Info: creating stash file C:\Qt5\5.13.2\Src\qtbase\src\plugins\sqldrivers\.qmake.stash

Running configuration tests...
Checking for DB2 (IBM)... no
Checking for InterBase... no
Checking for MySQL... yes
Checking for OCI (Oracle)... no
Checking for ODBC... yes
Checking for PostgreSQL... no
Done running configuration tests.

Configure summary:

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

Qt is now configured for building. Just run 'mingw32-make'.
Once everything is built, you must run 'mingw32-make install'.
Qt will be installed into 'C:\Qt5\5.13.2\mingw73_64'.

Prior to reconfiguration, make sure you remove any leftovers from the previous build.

Примечание: Как упоминалось в Компиляция Qt с определенным драйвером, посмотрите в config.log, если драйвер не был найден, и начните заново, удалив config.cache.

Из-за практических соображений, связанных с внешними зависимостями, только плагин SQLite3 поставляется с бинарными сборками Qt. Чтобы добавить дополнительные драйверы в установку Qt без перекомпиляции всего Qt, можно настроить и скомпилировать директорию qtbase/src/plugins/sqldrivers вне директории полной сборки Qt. Обратите внимание, что настроить каждый драйвер по отдельности нельзя, только все сразу. Однако драйверы можно скомпилировать по отдельности. Если сборка Qt настроена с помощью -prefix, необходимо также установить плагины после их компиляции. Например:

cd $QTDIR/qtbase/src/plugins/sqldrivers/mysql
make install

Подробности по драйверам

QMYSQL для MySQL или MariaDB 5.6 и выше

MariaDB — это вилка MySQL, предназначенная для сохранения статуса свободно распространяемого и открытого программного обеспечения по лицензии GNU General Public License. MariaDB стремится поддерживать высокую совместимость с MySQL, обеспечивая возможность прямой замены с парадигмой бинарных библиотек и точное соответствие API и командам MySQL. Поэтому плагин для MySQL и MariaDB объединён в один плагин Qt.

Поддержка хранимых процедур QMYSQL

MySQL 5 имеет поддержку хранимых процедур на уровне SQL, но не имеет API для управления параметрами IN, OUT и INOUT. Поэтому параметры должны устанавливаться и считываться с помощью команд SQL вместо QSqlQuery::bindValue().

Пример хранимой процедуры:

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

Исходный код для доступа к значениям 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"

Примечание: @outval1 и @outval2 — переменные, локальные для текущего соединения, и не будут затронуты запросами, отправленными с другого хоста или соединения.

Встроенный сервер MySQL

Встроенный сервер MySQL — это прямая замена обычной библиотеке клиента. При использовании встроенного сервера MySQL не требуется сервер MySQL для использования функциональности MySQL.

Для использования встроенного сервера MySQL просто свяжите плагин Qt с libmysqld вместо libmysqlclient. Это можно сделать, добавив MYSQL_LIBS=-lmysqld в строку конфигурации.

Для получения дополнительной информации об встроенном сервере MySQL обратитесь к документации MySQL, глава «libmysqld, библиотека встроенного сервера MySQL».

Как скомпилировать плагин QMYSQL на Unix и macOS

Вам потребуются файлы заголовков MySQL/MariaDB, а также общая библиотека libmysqlclient.so / libmariadb.so. В зависимости от вашей дистрибуции Linux, вам может потребоваться установить пакет, обычно называемый «mysql-devel» или «mariadb-devel».

Укажите qmake, где находятся файлы заголовков и общие библиотеки MySQL/MariaDB (здесь предполагается, что MySQL/MariaDB установлен в /usr/local), и запустите make:

cd $QTDIR/qtbase/src/plugins/sqldrivers
qmake -- MYSQL_PREFIX=/usr/local
make sub-mysql

Как скомпилировать плагин QMYSQL в Windows

Вам нужны файлы установки MySQL (например, mysql-installer-web-community-8.0.18.0.msi) или mariadb-connector-c-3.1.5-win64.msi. Запустите установщик, выберите пользовательскую установку и установите MySQL C Connector, соответствующий вашей установке Qt (x86 или x64). После установки проверьте, что необходимые файлы находятся там:

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

и для MariaDB

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

Примечание: начиная с MySQL 8.0.19, C Connector больше не предлагается как самостоятельный устанавливаемый компонент. Вместо этого вы можете получить mysql.h и libmysql.*, установив полный сервер MySQL (только x64) или MariaDB C Connector.

Скомпилируйте плагин следующим образом (здесь предполагается, что <MySQL dir> является C:/Program Files/MySQL/MySQL Connector C 6.1):

cd %QTDIR%\qtbase\src\plugins\sqldrivers
qmake -- MYSQL_INCDIR="C:/Program Files/MySQL/MySQL Connector C 6.1/include" MYSQL_LIBDIR="C:/Program Files/MySQL/MySQL Connector C 6.1/lib"
nmake sub-mysql
nmake install

Если вы не используете компилятор Microsoft, замените nmake на mingw32-make выше.

При распространении вашего приложения не забудьте включить libmysql.dll / libmariadb.dll в пакет установки. Он должен быть размещён в той же папке, что и исполняемый файл приложения. Для libmysql.dll также необходимы библиотеки времени выполнения MSVC, которые можно установить с помощью vcredist.exe

QOCI для Oracle Call Interface (OCI)

Плагин Qt OCI поддерживает подключение к базе данных Oracle, как определено версией используемого instant client. Это зависит от того, какую версию поддерживает Oracle. Плагин автоматически обнаружит версию базы данных и включит соответствующие функции.

Возможно подключение к базе данных Oracle без файла tnsnames.ora. Это требует, чтобы SID базы данных передавался драйверу как имя базы данных, и указывался хост.

Аутентификация пользователя OCI

Плагин Qt OCI поддерживает аутентификацию с использованием внешних учетных данных (OCI_CRED_EXT). Обычно это означает, что сервер базы данных будет использовать аутентификацию, предоставленную операционной системой, вместо собственного механизма аутентификации.

Оставьте поля имени пользователя и пароля пустыми при открытии соединения с QSqlDatabase, чтобы использовать аутентификацию с внешними учетными данными.

Поддержка OCI BLOB/LOB

Бинарные большие объекты (BLOB) могут читаться и записываться, но имейте в виду, что этот процесс может потребовать много памяти. Вы должны использовать только что читаемые запросы для выбора полей LOB (см. QSqlQuery::setForwardOnly()).

Вставка BLOB должна выполняться с использованием либо подготовленного запроса, где BLOB привязаны к заполнителям, либо QSqlTableModel, который использует подготовленный запрос для этого внутри.

Как скомпилировать плагин OCI на Unix и macOS

Вам нужен «Instant Client Package — Basic» и «Instant Client Package — SDK».

Файлы библиотек Oracle, необходимые для компиляции драйвера:

• libclntsh.so (все версии)

Укажите qmake, где находятся файлы заголовков и общие библиотеки Oracle, и запустите make:

Предполагается, что вы установили пакеты RPM Instant Client Package SDK (вам нужно соответствующим образом скорректировать номер версии):

cd $QTDIR/qtbase/src/plugins/sqldrivers
qmake -- OCI_INCDIR=/usr/include/oracle/11.2/client OCI_LIBDIR=/usr/lib/oracle/11.2/client/lib
make sub-oci

Примечание: Если вы используете пакет Oracle Instant Client, вам нужно будет установить LD_LIBRARY_PATH при компиляции плагина SQL OCI и при запуске приложения, использующего плагин SQL OCI. Вы можете избежать этой необходимости, задав RPATH и указав все библиотеки для ссылки. Вот пример:

configure OCI_INCDIR=/usr/include/oracle/10.1.0.3/client OCI_LIBDIR=/usr/lib/oracle/10.1.0.3/client/lib -R /usr/lib/oracle/10.1.0.3/client/lib OCI_LIBS="-lclntsh -lnnz10"
make

Если вы хотите вручную собрать плагин OCI с помощью этого метода, процедура выглядит следующим образом:

cd $QTDIR/qtbase/src/plugins/sqldrivers
qmake -- OCI_INCDIR=/usr/include/oracle/10.1.0.3/client OCI_LIBDIR=/usr/lib/oracle/10.1.0.3/client/lib OCI_LIBS="-Wl,-rpath,/usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10"
make sub-oci

Как собрать плагин OCI в Windows

Обычно достаточно выбрать опцию "Программист" в установщике Oracle Client с компакт-диска установки Oracle Client. Для некоторых версий Oracle Client может потребоваться также выбрать опцию "Интерфейс вызовов (OCI)", если она доступна.

Соберите плагин следующим образом (предполагается, что Oracle Client установлен в C:\oracle):

cd %QTDIR%\qtbase\src\plugins\sqldrivers
qmake -- OCI_INCDIR=c:/oracle/oci/include OCI_LIBDIR=c:/oracle/oci/lib/msvc
nmake sub-oci

Если вы не используете компилятор Microsoft, замените nmake на mingw32-make в строке выше.

При запуске приложения вам также потребуется добавить путь oci.dll в переменную среды PATH:

set PATH=%PATH%;c:\oracle\bin

QODBC для Open Database Connectivity (ODBC)

ODBC — это общий интерфейс, позволяющий подключаться к нескольким СУБД с использованием одного интерфейса. Драйвер QODBC позволяет подключаться к менеджеру драйверов ODBC и получать доступ к доступным источникам данных. Обратите внимание, что вам также необходимо установить и настроить драйверы ODBC для менеджера драйверов ODBC, установленного на вашей системе. Затем плагин QODBC позволяет использовать эти источники данных в ваших приложениях Qt.

Примечание: Вместо драйвера ODBC следует использовать родной драйвер, если он доступен. Поддержка ODBC может использоваться как резервный вариант для совместимых баз данных, если родной драйвер недоступен.

В Windows менеджер драйверов ODBC должен быть установлен по умолчанию. Для систем Unix существуют некоторые реализации, которые необходимо установить предварительно. Обратите внимание, что каждый конечный пользователь вашего приложения должен иметь установленный менеджер драйверов ODBC, в противном случае плагин QODBC работать не будет.

При подключении к источнику данных ODBC вы должны передать имя источника данных ODBC в функцию QSqlDatabase::setDatabaseName(), а не фактическое имя базы данных.

Плагину QODBC необходим менеджер драйверов ODBC версии 2.0 или выше, совместимый с ODBC. Некоторые драйверы ODBC заявляют о совместимости с версией 2.0, но не предоставляют всех необходимых функций. Поэтому плагин QODBC проверяет, можно ли использовать источник данных после установления соединения, и отказывается работать, если проверка завершается неудачно. Если вам не нравится такое поведение, вы можете удалить строку #define ODBC_CHECK_DRIVER из файла qsql_odbc.cpp. Делайте это на свой страх и риск!

По умолчанию Qt инструктирует драйвер ODBC вести себя как драйвер ODBC 2.x. Однако для некоторых комбинаций driver-manager/ODBC 3.x-driver (например, unixODBC/MaxDB ODBC), если инструктировать драйвер ODBC вести себя как драйвер 2.x, может привести к неожиданному поведению плагина драйвера. Чтобы избежать этой проблемы, инструктируйте драйвер ODBC вести себя как драйвер 3.x, установив параметр подключения "SQL_ATTR_ODBC_VERSION=SQL_OV_ODBC3" перед открытием соединения с базой данных. Обратите внимание, что это повлияет на несколько аспектов поведения драйвера ODBC, например, на SQLSTATE. Перед настройкой этого параметра подключения проконсультируйтесь с документацией ODBC по различиям в поведении.

При использовании базы данных SAP HANA подключение должно быть установлено с параметром "SCROLLABLERESULT=TRUE", так как драйвер HANA ODBC по умолчанию не предоставляет прокручиваемые результаты, например:

QSqlDatabase db = QSqlDatabase::addDatabase("QODBC");
QString connectString = QStringLiteral(
    "DRIVER=/path/to/installation/libodbcHDB.so;"
    "SERVERNODE=hostname:port;"
    "UID=USER;"
    "PWD=PASSWORD;"
    "SCROLLABLERESULT=true");
db.setDatabaseName(connectString);

Если вы столкнулись с очень медленным доступом к источнику данных ODBC, убедитесь, что отслеживание вызовов ODBC отключено в менеджере источников данных ODBC.

Некоторые драйверы не поддерживают прокручиваемые курсоры. В этом случае можно успешно использовать только запросы в режиме forwardOnly.

Поддержка хранимых процедур ODBC

В Microsoft SQL Server результат набора данных, возвращаемый хранимой процедурой, использующей оператор return или возвращающей несколько наборов результатов, будет доступен только в том случае, если вы установите режим forward только запроса в forward с помощью QSqlQuery::setForwardOnly().

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

Примечание: Значение, возвращаемое оператором return хранимой процедуры, игнорируется.

Поддержка Unicode ODBC

Плагин QODBC будет использовать API Unicode, если определено UNICODE. В системах Windows NT это значение по умолчанию. Обратите внимание, что драйвер ODBC и СУБД также должны поддерживать Unicode.

Для драйвера Oracle 9 ODBC (Windows) необходимо проверить поддержку "SQL_WCHAR" в менеджере драйверов ODBC, иначе Oracle преобразует все строки Unicode в локальные 8-битные.

Как собрать плагин ODBC на Unix и macOS

Рекомендуется использовать unixODBC. Вы можете найти последнюю версию и драйверы ODBC по адресу http://www.unixodbc.org. Вам понадобятся заголовочные файлы и общие библиотеки unixODBC.

Укажите qmake, где найти заголовочные файлы и общие библиотеки unixODBC (предполагается, что unixODBC установлен в /usr/local/unixODBC), и запустите make:

cd $QTDIR/qtbase/src/plugins/sqldrivers
qmake -- ODBC_PREFIX=/usr/local/unixODBC
make sub-odbc

Как собрать плагин ODBC в Windows

Заголовочные и включаемые файлы ODBC должны быть уже установлены в соответствующих каталогах. Вам просто нужно собрать плагин следующим образом:

cd %QTDIR%\qtbase\src\plugins\sqldrivers
qmake
nmake sub-odbc

Если вы не используете компилятор Microsoft, замените nmake на mingw32-make в строке выше.

QPSQL для PostgreSQL (Версия 7.3 и выше)

Драйвер QPSQL поддерживает версию 7.3 и выше сервера PostgreSQL.

Дополнительную информацию о PostgreSQL вы найдете по адресу http://www.postgresql.org.

Поддержка Unicode QPSQL

Драйвер QPSQL автоматически определяет, поддерживает ли база данных PostgreSQL, к которой вы подключаетесь, Unicode или нет. Unicode используется автоматически, если сервер его поддерживает. Обратите внимание, что драйвер поддерживает только кодировку UTF-8. Если ваша база данных использует другую кодировку, сервер должен быть скомпилирован с поддержкой преобразования Unicode.

Поддержка Unicode была введена в PostgreSQL версии 7.1, и она будет работать только в том случае, если как сервер, так и клиентская библиотека были скомпилированы с поддержкой многобайтовых символов. Более подробную информацию о настройке многобайтового сервера PostgreSQL можно найти в руководстве администратора PostgreSQL, глава 5.

Регистрозависимость QPSQL

Базы данных PostgreSQL будут учитывать регистрозависимость только в том случае, если имя таблицы или поля заключено в кавычки при создании таблицы. Например, запрос SQL:

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

обеспечит доступ с тем же регистром, который использовался. Если имя таблицы или поля не заключено в кавычки при создании, фактическое имя таблицы или поля будет в нижнем регистре. Когда QSqlDatabase::record() или QSqlDatabase::primaryIndex() обращаются к таблице или полю, которое не было заключено в кавычки при создании, имя, передаваемое в функцию, должно быть в нижнем регистре, чтобы оно было найдено. Например:

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

Поддержка запросов в режиме forward-only QPSQL

Для использования запросов в режиме forward-only необходимо скомпилировать плагин QPSQL с библиотекой клиента PostgreSQL версии 9.2 или выше. Если плагин скомпилирован со старой версией, то режим forward-only будет недоступен — вызов QSqlQuery::setForwardOnly() с true не повлияет.

Предупреждение: Если вы скомпилируете плагин QPSQL с PostgreSQL версии 9.2 или выше, то вы должны распространять ваше приложение с libpq версии 9.2 или выше. В противном случае загрузка плагина QPSQL завершится сбоем с сообщением:

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

При перемещении по результатам в режиме forward-only дескриптор QSqlResult может измениться. Приложения, использующие низкоуровневый дескриптор результата SQL, должны получить новый дескриптор после каждого вызова любой из функций извлечения QSqlResult. Пример:

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

При чтении результатов запроса в режиме forward-only с PostgreSQL подключение к базе данных не может использоваться для выполнения других запросов. Это ограничение библиотеки libpq. Пример:

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
}

Эта проблема не возникнет, если query1 и query2 используют разные подключения к базе данных или если мы выполняем query2 после цикла while.

Примечание: Некоторые методы QSqlDatabase, такие как tables(), primaryIndex(), неявно выполняют запросы SQL, поэтому их также нельзя использовать при перемещении по результатам запроса в режиме forward-only.

Примечание: QPSQL выведет следующее предупреждение, если обнаружит потерю результатов запроса:

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

Как собрать плагин QPSQL на Unix и macOS

Вам нужна установленная библиотека и заголовочные файлы клиента PostgreSQL.

Чтобы указать qmake, где найти заголовочные файлы и общие библиотеки PostgreSQL, выполните qmake следующим образом (предполагается, что клиент PostgreSQL установлен в /usr):

cd $QTDIR/qtbase/src/plugins/sqldrivers
qmake -- PSQL_INCDIR=/usr/include/pgsql
make sub-psql

Как собрать плагин QPSQL в Windows

Установите соответствующие библиотеки разработчика PostgreSQL для вашего компилятора. Предполагая, что PostgreSQL установлен в C:\psql, выполните сборку плагина следующим образом:

cd %QTDIR%\qtbase\src\plugins\sqldrivers
qmake -- PSQL_INCDIR=C:/psql/include PSQL_LIBDIR=C:/psql/lib/ms
nmake sub-psql
nmake install

Пользователи MinGW могут ознакомиться со следующим онлайн-документом: PostgreSQL MinGW/Native Windows.

При распространении вашего приложения не забудьте включить libpq.dll в пакет установки. Он должен быть помещен в ту же папку, что и исполняемый файл приложения.

QDB2 для IBM DB2 (Версия 7.1 и выше)

Плагин Qt DB2 позволяет получить доступ к базам данных IBM DB2. Он был протестирован с IBM DB2 v7.1 и 7.2. Вы должны установить клиентскую библиотеку разработки IBM DB2, которая содержит заголовочные и библиотечные файлы, необходимые для компиляции плагина QDB2.

Драйвер QDB2 поддерживает подготовленные запросы, чтение/запись строк Unicode и чтение/запись BLOB.

Рекомендуется использовать запрос в режиме forward-only при вызове хранимых процедур в DB2 (см. QSqlQuery::setForwardOnly()).

Как собрать плагин QDB2 на Unix и macOS

cd $QTDIR/qtbase/src/plugins/sqldrivers
qmake -- DB2_PREFIX=$DB2DIR
make sub-db2

Как собрать плагин QDB2 в Windows

Заголовочные и включаемые файлы DB2 должны быть уже установлены в соответствующих каталогах. Вам просто нужно собрать плагин следующим образом:

cd %QTDIR%\qtbase\src\plugins\sqldrivers
qmake -- DB2_PREFIX="<DB2 home>/sqllib"
nmake sub-db2
nmake install

Если вы не используете компилятор Microsoft, замените nmake на mingw32-make в строке выше.

QSQLITE для SQLite (Версия 3 и выше)

Плагин Qt SQLite позволяет получать доступ к базам данных SQLite. SQLite — это баз данных, работающая в одном процессе, что означает, что сервер базы данных не нужен. SQLite работает с одним файлом, который должен быть указан как имя базы данных при открытии подключения. Если файл не существует, SQLite попытается его создать. SQLite также поддерживает базы данных в памяти и временные базы данных. Для этого в качестве имени базы данных достаточно передать соответственно ":memory:" или пустую строку.

SQLite имеет некоторые ограничения в отношении нескольких пользователей и нескольких транзакций. Если вы пытаетесь читать/записывать в ресурс из разных транзакций, ваше приложение может зависнуть до тех пор, пока одна транзакция не будет подтверждена или отменена. Драйвер Qt SQLite будет пытаться перезаписать заблокированный ресурс до тех пор, пока не достигнет таймаута (см. QSQLITE_BUSY_TIMEOUT в QSqlDatabase::setConnectOptions()).

В SQLite любой столбец, за исключением столбца INTEGER PRIMARY KEY, может хранить любой тип значения. Например, столбец, объявленный как INTEGER, может содержать целое число в одной строке и текстовое значение в следующей. Это происходит потому, что SQLite связывает тип значения со значением, а не со столбцом, в котором оно хранится. Следствием этого является то, что тип, возвращаемый QSqlField::type(), указывает только рекомендуемый тип поля. Не следует делать никаких предположений о фактическом типе на основе этого, и следует проверять тип отдельных значений.

Драйвер заблокирован для обновлений во время выполнения запроса select. Это может вызвать проблемы при использовании QSqlTableModel, потому что виджеты элементов Qt извлекают данные по мере необходимости (с помощью QSqlQuery::fetchMore() в случае QSqlTableModel).

Вы можете найти информацию о SQLite по адресу http://www.sqlite.org.

Как скомпилировать плагин QSQLITE

SQLite версия 3 включена в Qt в качестве сторонней библиотеки. Ее можно скомпилировать, передав параметр -qt-sqlite в скрипт конфигурации.

Если вы не хотите использовать библиотеку SQLite, включенную в Qt, вы можете передать -system-sqlite в скрипт конфигурации, чтобы использовать библиотеки SQLite операционной системы. Это рекомендуется всякий раз, когда это возможно, так как это уменьшает размер установки и удаляет один компонент, за которым вам нужно отслеживать сообщения о безопасности.

В Unix и macOS (замените $SQLITE на каталог, где находится SQLite):

cd $QTDIR/qtbase/src/plugins/sqldrivers
qmake -- -system-sqlite SQLITE3_PREFIX=$SQLITE
make sub-sqlite

В Windows:

cd %QTDIR%\qtbase\src\plugins\sqldrivers
qmake -- -system-sqlite SQLITE3_PREFIX=C:/SQLITE
nmake sub-sqlite
nmake install

Включение оператора REGEXP

SQLite поставляется с операцией REGEXP. Однако необходимую реализацию должен предоставить пользователь. Для удобства можно включить реализацию по умолчанию, установив параметр подключения QSQLITE_ENABLE_REGEXP перед открытием подключения к базе данных. Затем оператор SQL, подобный "column REGEXP 'pattern'", по сути, расширяется до кода Qt

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

Для повышения производительности регулярные выражения кэшируются в памяти. По умолчанию размер кэша составляет 25, но его можно изменить с помощью значения параметра. Например, передача "QSQLITE_ENABLE_REGEXP=10" уменьшает размер кэша до 10.

Совместимость форматов файлов QSQLITE

SQLite в некоторых небольших версиях может нарушать совместимость формата файлов с последующими версиями. Например, SQLite 3.3 может читать файлы баз данных, созданные с помощью SQLite 3.2, но базы данных, созданные с помощью SQLite 3.3, не могут быть прочитаны SQLite 3.2. Обратитесь к документации и журналам изменений SQLite для получения информации о совместимости формата файлов между версиями.

Небольшие версии Qt обычно следуют за небольшими версиями SQLite, а исправления Qt — за исправлениями SQLite. Исправления поэтому совместимы как с более ранними, так и с более поздними версиями.

Для принудительного использования определенного формата файла SQLite необходимо скомпилировать и распространять свой собственный плагин базы данных со своей собственной библиотекой SQLite, как показано выше. Некоторые версии SQLite можно заставить записывать определенный формат файла, задав макрос SQLITE_DEFAULT_FILE_FORMAT при компиляции SQLite.

QIBASE для Borland InterBase

Плагин Qt InterBase позволяет получать доступ к базам данных InterBase и Firebird. InterBase может использоваться как клиент-сервер или без сервера, в котором случае он работает с локальными файлами. Файл базы данных должен существовать до установления соединения.

Обратите внимание, что InterBase требует указать полный путь к файлу базы данных, независимо от того, хранится ли он локально или на другом сервере.

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

Для компиляции этого плагина необходимы заголовочные файлы и библиотеки InterBase/Firebird.

Из-за несовместимости лицензий с GPL пользователям Qt Open Source Edition не разрешается связывать этот плагин с коммерческими изданиями InterBase. Используйте Firebird или бесплатное издание InterBase.

Поддержка Юникода и кодировка текста QIBASE

По умолчанию драйвер подключается к базе данных, используя UNICODE_FSS. Это можно изменить, задав параметр ISC_DPB_LC_CTYPE с помощью QSqlDatabase::setConnectOptions() перед открытием подключения.

// connect to database using the Latin-1 character set
db.setConnectOptions("ISC_DPB_LC_CTYPE=Latin1");
if (db.open())
    qDebug("The database connection is open.");

Если Qt не поддерживает заданную кодировку, драйвер выведет сообщение об ошибке и подключится к базе данных, используя UNICODE_FSS.

Обратите внимание, что если кодировка текста, заданная при подключении к базе данных, не совпадает с кодировкой в базе данных, могут возникнуть проблемы с транслитерацией.

Хранимые процедуры QIBASE

InterBase/Firebird возвращают значения OUT как набор результатов, поэтому при вызове хранимых процедур необходимо привязать только значения IN через QSqlQuery::bindValue(). Значения RETURN/OUT можно получить с помощью QSqlQuery::value(). Пример:

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

Как скомпилировать плагин QIBASE в Unix и macOS

Предполагается, что InterBase или Firebird установлены в /opt/interbase:

Если вы используете InterBase:

cd $QTDIR/qtbase/src/plugins/sqldrivers
qmake -- IBASE_PREFIX=/opt/interbase
make sub-ibase

Если вы используете Firebird, библиотеку Firebird необходимо задать явно:

cd $QTDIR/qtbase/src/plugins/sqldrivers
qmake -- IBASE_PREFIX=/opt/interbase IBASE_LIBS=-lfbclient
make sub-ibase

Как скомпилировать плагин QIBASE в Windows

Предполагается, что InterBase или Firebird установлены в C:\interbase:

Если вы используете InterBase:

cd %QTDIR%\qtbase\src\plugins\sqldrivers
qmake -- IBASE_INCDIR=C:/interbase/include
nmake sub-ibase
nmake install

Если вы используете Firebird, библиотеку Firebird необходимо задать явно:

cd %QTDIR%\qtbase\src\plugins\sqldrivers
qmake -- IBASE_INCDIR=C:/interbase/include IBASE_LIBS=-lfbclient
nmake sub-ibase
nmake install

Если вы не используете компилятор Microsoft, замените nmake на mingw32-make в строке выше.

Обратите внимание, что C:\interbase\bin должен находиться в PATH.

Устранение неполадок

Вы всегда должны использовать библиотеки клиентов, скомпилированные с тем же компилятором, что и ваш проект. Если вы не можете получить исходное распределение для самостоятельной компиляции библиотек клиентов, вы должны убедиться, что предварительно скомпилированная библиотека совместима с вашим компилятором, в противном случае у вас возникнет множество ошибок "неопределенные символы". Некоторые компиляторы имеют инструменты для преобразования библиотек, например, Borland поставляет инструмент COFF2OMF.EXE для преобразования библиотек, сгенерированных с помощью Microsoft Visual C++.

Если компиляция плагина завершится успешно, но его нельзя загрузить, убедитесь, что выполнены следующие требования:

• Убедитесь, что плагин находится в правильной папке. Вы можете использовать QApplication::libraryPaths() для определения того, где Qt ищет плагины.
• Убедитесь, что библиотеки клиентов DBMS доступны в системе. В Unix выполните команду ldd и передайте имя плагина в качестве параметра, например, ldd libqsqlmysql.so. Вы получите предупреждение, если какая-либо из библиотек клиентов не найдена. В Windows вы можете использовать средство просмотра зависимостей Visual Studio. В Qt Creator вы можете обновить переменную среды PATH в разделе Запуск панели Проект, чтобы включить путь к папке, содержащей библиотеки клиентов.
• Скомпилируйте Qt с определенным QT_DEBUG_COMPONENT для получения очень подробного отладки при загрузке плагинов.

Убедитесь, что вы следуете руководству по развёртыванию плагинов.

Как написать свой собственный драйвер базы данных

QSqlDatabase отвечает за загрузку и управление плагинами драйверов баз данных. Когда база данных добавляется (см. QSqlDatabase::addDatabase()), загружается соответствующий плагин драйвера (используя QSqlDriverPlugin). QSqlDatabase полагается на плагин драйвера для предоставления интерфейсов для QSqlDriver и QSqlResult.

QSqlDriver — это абстрактный базовый класс, который определяет функциональность драйвера SQL базы данных. Это включает функции, такие как QSqlDriver::open() и QSqlDriver::close(). QSqlDriver отвечает за подключение к базе данных, установление соответствующей среды и т. д. Кроме того, QSqlDriver может создавать объекты QSqlQuery, подходящие для конкретного API базы данных. QSqlDatabase перенаправляет многие вызовы своих функций непосредственно в QSqlDriver, который обеспечивает конкретное реализацию.

QSqlResult — это абстрактный базовый класс, который определяет функциональность запроса к SQL базе данных. Это включает такие операторы, как SELECT, UPDATE и ALTER TABLE. QSqlResult содержит функции, такие как QSqlResult::next() и QSqlResult::value(). QSqlResult отвечает за отправку запросов в базу данных, возврат данных результатов и т. д. QSqlQuery перенаправляет многие вызовы своих функций непосредственно в QSqlResult, который обеспечивает конкретное реализацию.

QSqlDriver и QSqlResult тесно связаны. При реализации драйвера Qt SQL оба этих класса должны быть подклассами, и абстрактные виртуальные методы в каждом классе должны быть реализованы.

Для реализации драйвера Qt SQL как плагина (чтобы его распознавала и загружала библиотека Qt во время выполнения), драйвер должен использовать макрос Q_PLUGIN_METADATA(). Подробнее об этом см. в Руководство по созданию плагинов Qt. Вы также можете узнать, как это делается в плагинах SQL, которые поставляются с Qt в QTDIR/qtbase/src/plugins/sqldrivers.

Следующий код можно использовать в качестве шаблона для драйвера 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); }
};