SQLデータベースドライバ

Qt SQL モジュールは、異なるデータベース API と通信するためにドライバプラグインを使用します。Qt の SQL モジュール API はデータベースに依存しないので、データベース固有のコードはすべてこれらのドライバに含まれています。Qt にはいくつかのドライバが付属しており、他のドライバを追加することもできます。ドライバのソースコードは提供されており、独自のドライバを書くためのモデルとして使用することができます。

サポートされているデータベース

Qt に含まれるドライバの一覧を下表に示します：

SQLite は、すべてのプラットフォームで最高のテストカバレッジとサポートを提供するインプロセスデータベースシステムです。OCI経由のOracle、PostgreSQL、およびODBCまたはネイティブドライバ経由のMySQLは、WindowsおよびLinuxで十分にテストされています。その他のシステムに対するサポートの完全性は、クライアント・ライブラリの可用性と品質に依存する。

ドライバのビルド

特定のドライバでQtをコンパイルする

Qtconfigure スクリプトは、あなたのマシンで利用可能なクライアントライブラリを自動的に検出しようとします。configure -help を実行して、ビルドできるドライバを確認してください。以下のような出力が得られるはずです：

[...]

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]

[...]

configure スクリプトは、必要なライブラリやインクルードファイルが標準パスにない場合は検出できないため、ドライバ固有のインクルード・パス変数やライブラリ・パス変数、またはCMAKE_INCLUDE_PATH やCMAKE_LIBRARY_PATH を使用してパスを指定する必要があります。たとえば、MySQL ファイルが Windows のC:\mysql-connector-c-6.1.11-winx64 にインストールされている場合、configure 行のダブルダッシュ部分に次のパラメータを渡します：

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

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

上記の方法でドライバを設定すると、CMake は依存関係のチェックをスキップし、提供されたパスをそのまま使用します。これは、パッケージがビルドルーチンで認識されるべきでないシステムライブラリのセットを独自に提供している場合に特に便利です。

各ドライバの詳細については、以下で説明します。

特定の SQL ドライバのみをコンパイルする

Qt が既にビルドされているか、バイナリ版としてインストールされている場合、特定の SQL ドライバのみをコンパイルすることができます。しかし、Qt のソースと全く同じバージョンをインストールする必要があります（例えば、Qt Maintenance Tool を使って）。また、Windows のスタートメニューから適切な Qt コマンドプロンプトを実行して、ビルド環境を適切にセットアップしてください。

典型的なqt-cmake （この場合はMySQL用に設定する）の実行は次のようになります：

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

外部依存関係を処理する現実的な問題から、SQLite プラグインのみが Qt のバイナリビルドに同梱されています。Qt for Windows のバイナリビルドには、ODBC と PostgreSQL プラグインも含まれています。Qt のすべてを再ビルドすることなく、Qt のインストールにドライバを追加できるように、Qt のビルドディレクトリの外側にqtbase/src/plugins/sqldrivers ディレクトリを設定し、ビルドすることができます。各ドライバを個別に設定することはできません。ドライバを個別にビルドすることは可能です。

ドライバーの仕様

MySQL または MariaDB 5.6 以上の QMYSQL

MariaDBはMySQLのフォークであり、GNU General Public Licenseの下でフリーかつオープンソースソフトウェアとして存続することを目的としています。MariaDBはMySQLとの高い互換性を維持することを意図しており、ライブラリのバイナリ・パリティとMySQLのAPIおよびコマンドとの完全な一致により、ドロップイン置換機能を保証しています。そのため、MySQL と MariaDB のプラグインは 1 つの Qt プラグインにまとめられています。

QMYSQL ストアドプロシージャのサポート

MySQL は SQL レベルでストアドプロシージャをサポートしていますが、IN, OUT, INOUT パラメータを制御する API はありません。そのため、パラメータはQSqlQuery::bindValue() ではなく SQL コマンドを使用して設定および読み込む必要があります。

ストアド・プロシージャの例

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"

組み込み MySQL サーバ

MySQL 組み込みサーバは、通常のクライアントライブラリのドロップイン置き換えです。組み込み MySQL サーバでは、MySQL の機能を使用するために MySQL サーバは必要ありません。

組み込み MySQL サーバを使用するには、Qt プラグインをlibmysqlclient の代わりにlibmysqld にリンクするだけです。これは configure コマンドラインに-DMySQL_LIBRARY=<path/to/mysqld/>libmysqld.<so|lib|dylib> を追加することで実行できます。

MySQL組み込みサーバーの詳細については、MySQLドキュメントの "libmysqld, the Embedded MySQL Server Library "の章を参照してください。

接続オプション

Qt MySQL/MariaDB プラグインは以下の接続オプションをサポートしています：

接続オプションの詳細については、mysql_options()MySQL ドキュメント を参照ください。

UnixおよびmacOSでのQMYSQLプラグインの構築方法

MySQL / MariaDBヘッダファイルと共有ライブラリlibmysqlclient.<so|dylib> /libmariadb.<so|dylib> が必要です。お使いのLinuxディストリビューションによっては、通常 "mysql-devel "または "mariadb-devel "と呼ばれるパッケージをインストールする必要があります。

MySQL / MariaDB のヘッダーファイルと共有ライブラリがどこにあるかをqt-cmake に伝え（ここでは MySQL / MariaDB が/usr/local にインストールされているものとする）、ビルドする：

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 .

Windows での QMYSQL プラグインのビルド方法

MySQLのインストールファイルを入手する必要がある（MySQL Webインストーラや MariaDB C Connectorなど）。インストーラを実行し、カスタムインストールを選択し、Qt のインストール（x86 または x64）に合った MySQL C Connector をインストールする。インストール後、必要なファイルがあるか確認してください：

• <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 dir> が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 .

アプリケーションを配布する場合、libmysql.dll/libmariadb.dllをインストールパッケージに含めることを忘れないでください。libmysql.dllはさらに、vcredist.exeでインストールできるMSVCランタイム・ライブラリが必要です。

オラクル・コール・インターフェイス（OCI）用のQOCI

Qt OCI プラグインは、使用するインスタントクライアントのバージョンに応じて、Oracle データベースへの接続をサポートします。これは、Oracle が何をサポートしているかに依存します。プラグインはデータベースのバージョンを自動検出し、それに応じて機能を有効にします。

tnsnames.ora ファイルがなくても Oracle データベースに接続できます。この場合、データベースのSIDをデータベース名としてドライバに渡し、ホスト名を指定する必要があります。

OCIユーザー認証

Qt OCI プラグインは、外部認証情報 (OCI_CRED_EXT) を使用した認証をサポートしています。通常、これはデータベースサーバーが独自の認証メカニズムではなく、オペレーティングシステムが提供するユーザー認証を使用することを意味します。

QSqlDatabase で接続を開く際、ユーザー名とパスワードは空のままにしておくと、外部認証による認証が使用されます。

OCI BLOB/LOB サポート

バイナリ・ラージ・オブジェクト（BLOB）の読み取りと書き込みが可能ですが、この処理には大量のメモリが必要になる可能性があることに注意してください。LOBフィールドを選択するには、前方のみのクエリを使用する必要があります（QSqlQuery::setForwardOnly （）を参照）。

BLOBの挿入は、BLOBがプレースホルダーにバインドされているプリペアド・クエリーか、QSqlTableModel 。

接続オプション

Qt OCI プラグインは、以下の接続オプションをサポートしています：

UnixとmacOSでのOCIプラグインのビルド方法

必要なものは、" - Basic "と "Instant Client Package - SDK "だけです。

ドライバのビルドに必要なOracleライブラリファイル

• libclntsh.<so|dylib> (すべてのバージョン）

Oracle のヘッダーファイルと共有ライブラリの場所をqt-cmake に伝え、ビルドします。

インスタント・クライアント・パッケージSDKのRPMパッケージをインストールしたと仮定します（バージョン番号を適宜調整する必要があります）：

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 .

Windows での OCI プラグインのビルド方法

プラグインをビルドするには、Oracle Client インストール CD の Oracle Client Installer で "Programmer" オプションを選択するだけで、通常は十分です。Oracle Clientのバージョンによっては、"Call Interface (OCI) "オプションが利用できる場合は、それを選択する必要があります。

プ ラ グ イ ンは以下の よ う に構築 し ます （ こ こ では Oracle Client がC:\oracle に、 SDK が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 .

アプリケーションを実行する際、PATH 環境変数にoci.dll のパスを追加する必要もあります：

set PATH=%PATH%;C:\oracle

QODBC for Open Database Connectivity (ODBC)

ODBCは、共通のインターフェースを使用して複数のDBMSに接続できる一般的なインターフェースです。QODBCドライバを使用すると、ODBCドライバマネージャに接続し、利用可能なデータソースにアクセスすることができます。また、システムにインストールされているODBCドライバマネージャ用のODBCドライバをインストールし、設定する必要があることに注意してください。QODBC プラグインを使用すると、Qt アプリケーションでこれらのデータソースを使用することができます。

Windowsでは、ODBCドライバ・マネージャがデフォルトでインストールされています。Unixシステムでは、最初にインストールしなければならない実装がいくつかあります。アプリケーションのすべてのエンドユーザは、ODBCドライバマネージャをインストールする必要があります。

ODBCデータソースに接続する際には、実際のデータベース名ではなく、ODBCデータソースの名前（DSN）をQSqlDatabase::setDatabaseName() 関数に渡す必要があります。FILEDSN (*.dsn) ファイル名や ODBC ドライバ文字列を渡すこともできます。ドライバ文字列を渡す場合は、すべてのパラメータ（ユーザ名、パスワード、...）が適切にエスケープされていることを確認する必要があります。ユーザ名やパスワードをQSqlDatabase 関数を通して渡すと、QODBC プラグインによってエスケープが行われます。

QODBCプラグインは、ODBC準拠のドライバ・マネージャ・バージョン2.0以降を必要とします。いくつかのODBCドライバはバージョン2.0準拠を謳っていますが、必要な機能をすべて提供しているわけではありません。そのためQODBCプラグインは、接続が確立された後にデータソースが使用可能かどうかをチェックし、チェックに失敗した場合は動作を拒否します。この動作が気に入らない場合は、ファイルqsql_odbc.cpp から#define ODBC_CHECK_DRIVER 行を削除してください。これは自己責任で行ってください！

デフォルトでは、Qt は ODBC 2.x ドライバとして動作するように ODBC ドライバに指示します。しかし、ドライバ・マネージャと ODBC 3.x ドライバの組み合わせによっては（例えばunixODBC/MaxDB ODBC）、ODBC ドライバに 2.x ドライバとして動作するように指示すると、ドライバ・プラグインが予期しない動作をすることがあります。この問題を回避するには、open your database connection の前に、setting the connect option "SQL_ATTR_ODBC_VERSION=SQL_OV_ODBC3" によって、ODBCドライバに3.xドライバとして動作するように指示してください。これは、SQLSTATEなど、ODBCドライバの動作の複数の側面に影響を与えることに注意してください。この接続オプションを設定する前に、予想される動作の違いについてODBCのドキュメントを参照してください。

ODBCデータソースのアクセスが非常に遅い場合は、ODBCデータソースマネージャでODBCコールトレースがオフになっていることを確認してください。

一部のドライバはスクロール可能なカーソルをサポートしていません。その場合、QSqlQuery::setForwardOnly()モードのクエリーしか正常に使用できません。

ODBCストアド・プロシージャのサポート

Microsoft SQL Serverでは、return文を使用するストアド・プロシージャ、または複数の結果セットを返すストアド・プロシージャが返す結果セットには、QSqlQuery::setForwardOnly （）を使用してクエリの前方のみモードを前方に設定した場合のみアクセスできます。

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

ODBC Unicode サポート

UNICODE が定義されている場合、QODBC プラグインは Unicode API を使用します。Windows ベースのシステムでは、これがデフォルトです。ODBCドライバとDBMSもUnicodeをサポートしていなければならないことに注意してください。

Oracle 9 ODBCドライバ（Windows）では、ODBCドライバ・マネージャで "SQL_WCHAR support "をチェックする必要があります。

接続オプション

Qt ODBC プラグインは以下の接続オプションをサポートしています：

接続オプションの詳細については、SQLSetConnectAttr()ODBC ドキュメントを参照してください。

Unix および macOS での ODBC プラグインのビルド方法

unixODBC を使用することを推奨します。最新バージョンと ODBC ドライバはhttp://www.unixodbc.org にあります。unixODBCヘッダーファイルと共有ライブラリーが必要です。

qt-cmake 、unixODBCヘッダーファイルと共有ライブラリがどこにあるか教えてください（ここでは、unixODBCが/usr/local/unixODBC にインストールされているものとします）：

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 .

WindowsでODBCプラグインをビルドする方法

ODBCヘッダーファイルとインクルードファイルはすでに適切なディレクトリにインストールされているはずです。以下のようにプラグインをビルドするだけです：

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 .

PostgreSQL用QPSQL（バージョン7.3以上）

QPSQLドライバはバージョン7.3以上のPostgreSQLサーバをサポートしています。

PostgreSQL の詳細については、http://www.postgresql.org を参照してください。

QPSQL Unicode サポート

QPSQL ドライバは、接続先の PostgreSQL データベースが Unicode をサポートしているかどうかを自動的に検出します。サーバーがUnicodeをサポートしている場合は、Unicodeが自動的に使用されます。ドライバは UTF-8 エンコードのみをサポートしていることに注意してください。データベースが他のエンコードを使用している場合は、サーバーがUnicode変換サポート付きでコンパイルされている必要があります。

UnicodeのサポートはPostgreSQLバージョン7.1で導入されましたが、サーバとクライアントライブラリの両方がマルチバイトをサポートしてコンパイルされている場合にのみ動作します。マルチバイト対応のPostgreSQLサーバの設定方法についての詳細は、PostgreSQL管理者ガイドの第5章を参照してください。

QPSQLの大文字と小文字の区別

PostgreSQLデータベースは、テーブル作成時にテーブル名やフィールド名が引用符で囲まれている場合にのみ大文字小文字を区別します。そのため、例えば、以下のようなSQL問い合わせがあります：

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

のようなSQL問い合わせは、使用されたのと同じ大文字と小文字でアクセスできることを保証します。テーブル名やフィールド名が作成時に引用符で囲まれていない場合、実際のテーブル名やフィールド名は小文字になります。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());

QPSQL 順方向のみのクエリのサポート

順方向のみの問い合わせを使用するには、PostreSQLクライアントライブラリバージョン9.2以降でQPSQLプラグインを構築する必要があります。それ以前のバージョンでプラグインを構築した場合、前方排他モードは使用できません -true でQSqlQuery::setForwardOnly() を呼び出しても効果はありません。

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

フォワード専用モードで結果をナビゲートしている間に、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...
        }
    }
}

例: 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が異なるデータベース接続を使用している場合や、whileループの後にquery2を実行する場合には発生しません。

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

接続オプション

Qt PostgreSQL プラグインは、connect()PostgreSQL ドキュメントで指定されているすべての接続オプションに従います。

Unix および macOS での QPSQL プラグインのビルド方法

PostgreSQLクライアントライブラリとヘッダをインストールする必要があります。

qt-cmake 、PostgreSQLのヘッダーファイルと共有ライブラリを見つけられるようにするには、以下の方法でプラグインをビルドします（PostgreSQLクライアントが/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 .

Windows上でのQPSQLプラグインの構築方法

ご使用のコンパイラに適したPostgreSQL開発者ライブラリをインストールしてください。PostgreSQL がC:\pgsql にインストールされていると仮定して、以下のようにプラグインをビルドします：

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 .

MinGWのユーザーは、以下のオンラインドキュメントを参照してください：PostgreSQL MinGW/Native Windowsを参照してください。

アプリケーションを配布する場合、libpq.dllをインストールパッケージに含める ことを忘れないでください。libpq.dllは、アプリケーション実行ファイルと同じフォルダに配置する必要があります。

QDB2 for IBM DB2 (バージョン7.1以上)

Qt DB2 プラグインは IBM DB2 データベースへのアクセスを可能にします。IBM DB2 v7.1 および 7.2 でテスト済みです。QDB2 プラグインのコンパイルに必要なヘッダファイルやライブラリファイルを含む IBM DB2 開発クライアントライブラリをインストールする必要があります。

QDB2 ドライバは、プリペアドクエリ、Unicode 文字列の読み書き、BLOB の読み書きをサポートしています。

DB2 のストアドプロシージャをコールする際には、フォワードのみのクエリを使用することを推奨します (QSqlQuery::setForwardOnly() を参照ください)。

接続オプション

Qt IBM DB2 プラグインは以下の接続オプションをサポートしています：

UnixおよびmacOSでのQDB2プラグインのビルド方法

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_INCLUDE_DIR="/usr/local/db2/include" -DDB2_LIBRARY="/usr/local/db2/lib/libdb2.<so|dylib>"
cmake --build .
cmake --install .

WindowsでのQDB2プラグインのビルド方法

DB2のヘッダーファイルとインクルードファイルはすでに適切なディレクトリにインストールされているはずです。以下のようにプラグインをビルドするだけです：

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_INCLUDE_DIR="C:\db2\include" -DDB2_LIBRARY="C:\db2\lib\db2.lib"
cmake --build .
cmake --install .

SQLite 用 QSQLITE (バージョン 3 以上)

Qt SQLite プラグインは SQLite データベースへのアクセスを可能にします。SQLite はインプロセスデータベースであり、データベースサーバを用意する必要がありません。SQLite は単一のファイルで動作し、接続を開くときにデータベース名として設定する必要があります。ファイルが存在しない場合、SQLite はそのファイルを作成しようとします。SQLiteはインメモリデータベースとテンポラリデータベースもサポートしています。データベース名にはそれぞれ ":memory:" または空の文字列を渡します。

SQLite には複数ユーザや複数トランザクションに関する制限があります。異なるトランザクションからリソースを読み書きしようとすると、1 つのトランザクションがコミットするかロールバックするまでアプリケーションがフリーズする可能性があります。Qt SQLite ドライバは、タイムアウトになるまで、ロックされたリソースへの書き込みを再試行します（QSQLITE_BUSY_TIMEOUT QSqlDatabase::setConnectOptions () を参照してください）。

SQLite では、INTEGER PRIMARY KEY カラムを除いて、どのようなカラムでもどのような型の値でも格納することができます。例えば、INTEGERとして宣言されたカラムは、ある行では整数値を格納し、次の行ではテキスト値を格納することができます。これは、SQLiteが値の型を、格納されている列ではなく、値自体に関連付けるためです。この結果、QSqlField::type() によって返される型はフィールドの推奨される型のみを示します。このことから実際の型を推測してはならず、個々の値の型をチェックする必要があります。

selectが実行されている間、ドライバは更新のためにロックされます。Qt のアイテムビューは必要に応じてデータをフェッチするため（QSqlTableModel の場合は QSqlQuery::fetchMore() を使用）、QSqlTableModel を使用する際に問題が発生する可能性があります。

SQLite に関する情報はhttp://www.sqlite.org を参照してください。

接続オプション

Qt SQLite プラグインは以下の接続オプションをサポートしています：

QSQLITE プラグインのビルド方法

SQLiteバージョン3はQtのサードパーティライブラリとして含まれています。qt-cmake コマンドラインに-DFEATURE_system_sqlite=OFF パラメータを渡すことでビルドできます。

Qt に含まれている SQLite ライブラリを使いたくない場合は、qt-cmake コマンドラインに-DFEATURE_system_sqlite=ON を渡すことで、オペレーティングシステムの SQLite ライブラリを使うことができます。インストールサイズが小さくなり、セキュリティ勧告を追跡する必要があるコンポーネントを1つ削除できるので、可能な限りこの方法をお勧めします。

UnixとmacOSの場合（$SQLITE を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 .

Windows の場合（SQLite が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 .

REGEXP 演算子を有効にする

SQLiteにはREGEXP演算が付属しています。しかし、必要な実装はユーザが提供しなければなりません。便宜上、デフォルトの実装を有効にするには、the database connection is opened の前にsetting the connect option QSQLITE_ENABLE_REGEXP を指定します。そうすると、"column REGEXP 'pattern'"のようなSQL文は、基本的に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 をビルドするときにSQLITE_DEFAULT_FILE_FORMAT 定義を設定することで、特定のファイルフォーマットを強制的に書き込ませることができます。

Mimer SQLバージョン11以降のQMIMER

Qt Mimer SQL プラグインを使用すると、Mimer SQL RDBMS を使用できます。Mimer SQLは、国際的なISO SQL標準に準拠した、スモールフットプリントでスケーラブルかつ堅牢なリレーショナルデータベースソリューションを提供します。Mimer SQLは、Windows、Linux、macOS、OpenVMSだけでなく、QNX、Android、embedded Linuxなどの組み込みプラットフォームでも使用できます。

Mimer SQLはUnicodeを完全にサポートしています。Unicodeデータを扱うには、カラムタイプNational Character（NCHAR）、National Character Varying（NVARCHAR）、またはNational Character Large Object（NCLOB）を使用する必要があります。Mimer SQLとUnicodeの詳細については、https://developer.mimer.com/features/multilingual-supportを参照してください。

QMIMERストアドプロシージャのサポート

Mimer SQLには標準SQL（PSM）に準拠したストアドプロシージャがあり、プラグインは結果セットプロシージャと同様にIN、OUT、INOUTパラメータを完全にサポートしています。

INOUTおよびOUTパラメータを持つストアドプロシージャの例

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

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

UnixおよびmacOSでのQMIMERプラグインのビルド方法

Mimer SQLのヘッダーファイルと共有ライブラリが必要です。これらは、https://developer.mimer.com にあるMimer SQLの亜種のいずれかをインストールして入手してください。

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 .

Windows上でQMIMERプラグインをビルドする方法

Mimer SQLヘッダーファイルと共有ライブラリが必要です。これらは、https://developer.mimer.com にあるMimer SQLの亜種のいずれかをインストールして入手してください。

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 for Borland InterBase

Qt InterBase プラグインを使用すると、InterBase および Firebird データベースにアクセスできます。InterBase は、クライアント/サーバとして使用することもできますし、サーバなしでローカルファイルを操作することもできます。接続を確立する前にデータベースファイルが存在する必要があります。Firebird はサーバー構成で使用する必要があります。

InterBaseでは、データベースファイルがローカルに保存されていても、他のサーバに保存されていても、データベースファイルへのフルパスを指定する必要があることに注意してください。

接続オプション

Qt Borland InterBase プラグインは、以下の接続オプションをサポートしています：

QIBASEプラグインのビルド方法

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

このプラグインをビルドするには、InterBase/Firebirdの開発ヘッダとライブラリが必要です。

GPLとのライセンス非互換性のため、Qtオープンソース版のユーザはこのプラグインをInterBaseの商用版にリンクすることはできません。Firebird または無償版の InterBase を使用してください。

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

UnixとmacOSでのQIBASEプラグインの構築方法

以下は、InterBase または Firebird が/opt/interbase にインストールされていることを前提としています：

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 .

オプションとして、CMake 変数Interbase_INCLUDE_DIR とInterbase_LIBRARY を使用して、インクルードパスとライブラリを直接指定します。

WindowsでのQIBASEプラグインのビルド方法

以下は、InterBase または Firebird がC:\interbase にインストールされていることを前提としています：

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 .

オプションとして、CMake 変数Interbase_INCLUDE_DIR とInterbase_LIBRARY を使用して、インクルードパスとライブラリを直接指定します。

C:\interbase\bin はPATH の中になければならないことに注意してください。

トラブルシューティング

クライアント・ライブラリは、常にプロジェクトで使用しているものと同じコンパイラでコンパイルされたものを使用してください。クライアント・ライブラリを自分でコンパイルするためのソース配布物を入手できない場合は、コンパイル済みのライブラリがあなたのコンパイラと互換性があることを確認する必要があります。

プラグインのコンパイルは成功したが、その後ロードできない場合は、次の手順をチェックして原因を突き止めてください：

1. プラグインが正しいディレクトリにあることを確認してください。QApplication::libraryPaths() を使って、Qt がプラグインを探す場所を特定することができます。
2. DBMS のクライアント・ライブラリがシステム上で利用可能であることを確認してください。Unix では、ldd というコマンドを実行し、プラグインの名前をldd libqsqlmysql.so のようにパラメータとして渡します。クライアント・ライブラリが見つからない場合は警告が表示されます。Windows では、Visual Studio の依存関係ウォーカーまたは依存関係 GUI を使用して、依存するライブラリを見つけることができます。Qt Creator では、ProjectパネルのRunセクションにあるPATH 環境変数を更新して、クライアント・ライブラリを含むフォルダのパスを含めることができます。
3. MSVC を使用する場合は、プラグインが正しいビルドタイプでビルドされていることも確認してください。MSVCのランタイムがデバッグとリリースで異なるため、QtのデバッグビルドではQtのリリースプラグインを読み込むことができません。
4. 環境変数QT_DEBUG_PLUGINS を設定してコンパイルした Qt 実行ファイルを実行すると、プラグインをロードするときに非常に冗長なデバッグ出力が得られます。
5. SQL サブシステムから可能なデバッグメッセージを取得するには、環境変数QT_LOGGING_RULES をqt.sql.*.debug=true に設定して出力を有効にしてください。Windows上で作業する場合は、コンソールを有効にすることを忘れないでください。ロギング・ルールの設定方法の詳細については、Logging Rules を参照してください。

プラグインのデプロイのガイドに従っていることを確認してください。

独自のデータベースドライバの書き方

QSqlDatabase はデータベースドライバプラグインのロードと管理を担当します。データベースが追加されると ( () を参照)、適切なドライバプラグインが ( を使用して) ロードされます。 は、 と のインタフェースを提供するドライバプラグインに依存します。QSqlDatabase::addDatabase QSqlDriverPlugin QSqlDatabase QSqlDriver QSqlResult

QSqlDriver はSQLデータベース・ドライバの機能を定義する抽象基底クラスです。これには () や () などの関数が含まれます。 はデータベースへの接続、適切な環境の構築などを担当します。さらに、 は、特定のデータベース API に適した オブジェクトを作成することができます。 は、多くの関数呼び出しを、具体的な実装を提供する に直接転送します。QSqlDriver::open QSqlDriver::close QSqlDriver QSqlDriver QSqlQuery QSqlDatabase QSqlDriver

QSqlResult は SQL データベース・クエリの機能を定義する抽象ベース・クラスです。これには、 、 、 、 などの文が含まれます。 には、QSqlResult::next() や QSqlResult::value() などの関数が含まれます。 は、データベースへのクエリの送信、結果データのリターンなどを担当します。 は、その関数呼び出しの多くを、具体的な実装を提供する に直接転送します。SELECT UPDATE ALTER TABLE QSqlResult QSqlResult QSqlQuery QSqlResult

QSqlDriver と は密接につながっています。Qt SQL ドライバを実装する場合、これらのクラスをサブクラス化し、各クラスの抽象仮想メソッドを実装する必要があります。QSqlResult

Qt SQL ドライバをプラグインとして実装する（実行時に Qt ライブラリに認識されロードされるようにする）には、Q_PLUGIN_METADATA() マクロを使用する必要があります。これについては、Qtプラグインの作成方法を参照してください。また、QTDIR/qtbase/src/plugins/sqldrivers で Qt と一緒に提供されている SQL プラグインで、これがどのように行われているかを確認することもできます。

以下のコードは 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); }
};