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

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

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

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

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

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

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

Компоновка драйверов

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

[...]

Database options:

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

[...]

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

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

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

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

QMYSQL для MySQL 4 и выше

Поддержка хранимых процедур 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");
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, а также общая библиотека libmysqlclient.so. В зависимости от вашей дистрибуции Linux, вам может потребоваться установить пакет, обычно называемый «mysql-devel».

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

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

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

Вам нужно получить установочные файлы MySQL. Запустите SETUP.EXE и выберите «Пользовательская установка». Установите модуль «Библиотеки и файлы заголовков». Скомпонуйте плагин следующим образом (здесь предполагается, что MySQL установлен в C:\MySQL):

cd %QTDIR%\qtbase\src\plugins\sqldrivers
qmake -- MYSQL_INCDIR=C:/MySQL/include "MYSQL_LIBDIR=C:/MYSQL/MySQL Server <version>/lib/opt"
nmake sub-mysql

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

QOCI для Oracle Call Interface (OCI)

Плагин Qt OCI поддерживает Oracle 9i, 10g и более поздние версии. После подключения к серверу 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

Для Oracle 10g вам нужно только «Пакет Instant Client — базовый» и «Пакет Instant Client — SDK». Для Oracle до версии 10g вам потребуются стандартные клиентские пакеты Oracle и пакеты SDK.

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

• libclntsh.so (все версии)
• libwtc9.so (только Oracle 9)

Укажите qmake путь к заголовочным файлам и общим библиотекам Oracle и запустите make:

Для Oracle версии 9:

cd $QTDIR/qtbase/src/plugins/sqldrivers
qmake -- "OCI_INCDIR=$ORACLE_HOME/rdbms/public" OCI_LIBDIR=$ORACLE_HOME/lib "OCI_LIBS=-lclntsh -lwtc9"
make sub-oci

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

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
make sub-oci

Примечание: Если вы используете пакет Oracle Instant Client, вам потребуется установить LD_LIBRARY_PATH при сборке плагина OCI SQL и при запуске приложения, использующего плагин OCI SQL. Вы можете избежать этого, установив 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 с компакт-диска обычно достаточно для сборки плагина. Для некоторых версий клиента Oracle может потребоваться также выбрать опцию «Интерфейс вызова (OCI)», если она доступна.

Скомпонуйте плагин следующим образом (здесь предполагается, что клиент Oracle установлен в 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 заявляют о совместимости с версией 2.0, но не предоставляют всех необходимых функций. Поэтому плагин QODBC проверяет, можно ли использовать источник данных после установления соединения, и отказывается работать, если проверка завершится неудачно. Если вам не нравится такое поведение, вы можете удалить строку #define ODBC_CHECK_DRIVER из файла qsql_odbc.cpp. Делайте это на свой страх и риск!

По умолчанию Qt сообщает драйверу ODBC вести себя как драйвер ODBC 2.x. Однако для некоторых комбинаций драйвер-менеджер/драйвер ODBC 3.x (например, 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("QODBC3");
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 only в 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.

Некоторые менеджеры драйверов и драйверы не поддерживают UNICODE. Чтобы использовать плагин QODBC с такими драйверами, он должен быть скомпилирован с определённым Q_ODBC_VERSION_2.

Для драйвера 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());

Поддержка BLOB QPSQL

Двоичные большие объекты поддерживаются через тип поля BYTEA в сервере PostgreSQL версии >= 7.1.

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

Для использования запросов forward-only необходимо скомпилировать плагин QPSQL с библиотекой клиента PostreSQL версии 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 QMYSQL3 QODBC QODBC3 QPSQL QPSQL7
Could not create database object

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

QSqlQuery query(db);
query.setForwardOnly(true);
query.exec("SELECT * FROM table");
while (query.next()) {
    // Handle changes in every iteration of the loop
    QVariant 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(db);
query1.setForwardOnly(true);
query1.exec("select * FROM table1");
while (query1.next()) {
    value = query1.value(0).toInt();
    if (value == 1) {
        QSqlQuery query2(db);
        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

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

QTDS для Sybase Adaptive Server

Примечание: TDS больше не используется MS Sql Server и заменён ODBC. QTDS устарел с Qt 4.7.

Невозможно установить порт с помощью QSqlDatabase::setPort() из-за ограничений в библиотеке клиента Sybase. Обратитесь к документации Sybase за информацией о том, как настроить файл конфигурации клиента Sybase для подключения к базам данных на нестандартных портах.

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

В Unix доступны две библиотеки, поддерживающие протокол TDS:

• FreeTDS, свободная реализация протокола TDS (http://www.freetds.org).
• Sybase Open Client, доступен по адресу https://support.sap.com.

Независимо от используемой библиотеки, требуется общий объект libsybdb.so. Установите переменную среды SYBASE для указания каталога установки библиотеки клиента и выполните qmake:

cd $QTDIR/qtbase/src/plugins/sqldrivers
qmake -- TDS_PREFIX=$SYBASE
make sub-tds

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

Вы можете использовать библиотеку DB-Library, предоставленную Microsoft, или Sybase Open Client (https://support.sap.com). Конфигурация попытается найти NTWDBLIB.LIB для компиляции плагина:

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

По умолчанию на Windows используется библиотека Microsoft. Если вы хотите принудительно использовать Sybase Open Client, вам необходимо определить Q_USE_SYBASE в %QTDIR%\qtbase\src\plugins\sqldrivers\tds\qsql_tds.cpp.

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

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

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

QSQLITE2 для SQLite версии 2

Плагин Qt SQLite 2 предлагается для совместимости. В случае возможности, используйте плагин версии 3 вместо него. Инструкции по сборке для версии 3 также применимы к версии 2.

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

Включение оператора 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 может использоваться как клиент-сервер или без сервера, в этом случае он работает с локальными файлами. Файл базы данных должен существовать перед установлением подключения. Firebird должен использоваться с конфигурацией сервера.

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

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");
db.open();

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

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

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

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

QSqlQuery q;
q.exec("execute procedure my_procedure");
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

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

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

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

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

Отладка

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

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

• Убедитесь, что плагин находится в правильной директории. Вы можете использовать QApplication::libraryPaths() для определения того, где Qt ищет плагины.
• Убедитесь, что клиентские библиотеки СУБД доступны в системе. В 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() {}
    QSqlResult *createResult() const override { return new XyzResult(this); }
};