SQL データベースドライバ

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

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

以下の表に、Qtに同梱されているドライバの一覧を示します：

SQLiteは、すべてのプラットフォームにおいて最もテストが網羅されており、サポート体制が充実したインプロセス・データベースシステムです。OCI経由のOracle、PostgreSQL、およびODBCまたはネイティブドライバ経由のMySQLは、WindowsおよびLinux上で十分にテストされています。その他のシステムに対するサポートの充実度は、クライアントライブラリの入手可能性と品質に依存します。

ドライバのビルド

特定のドライバを使用してQtをコンパイルする

Qt XMLの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 sqlite [system/qt]

[...]

configure スクリプトは、必要なライブラリやインクルードファイルが標準パスにない場合、それらを検出できません。そのため、ドライバ固有のインクルードパスおよびライブラリパス変数、あるいはCMAKE_INCLUDE_PATH やCMAKE_LIBRARY_PATH を使用して、これらのパスを指定する必要がある場合があります。たとえば、WindowsでMySQLファイルが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 SQLドライバのみをコンパイルすることが可能です。Qt SQLドライバのみをコンパイルすることが可能です。Qt SQLドライバのみをコンパイルすることが可能です ただし、Qtのソースコードは（例えばQt Maintenance Tool 経由で）まったく同じバージョンをインストールしていることを確認する必要があります。そうしないと、APIの変更によりコンパイルエラーが発生する可能性があります。また、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

qt-cmake による設定が完了したら、ninja を実行してドライバをビルドしてください。

外部依存関係の取り扱い上の実用的な理由から、QtのバイナリビルドにはSQLiteプラグインのみが同梱されています。Windows向けのQtバイナリビルドには、ODBCおよびPostgreSQLプラグインも含まれています。 Qt全体を再ビルドせずにQtインストールにドライバーを追加できるようにするため、qtbase/src/plugins/sqldrivers ディレクトリを、Qtのフルビルドディレクトリの外で設定・ビルドすることが可能です。各ドライバーを個別に設定することはできず、すべてをまとめて設定する必要がある点に注意してください。ただし、ドライバー自体は個別にビルドすることは可能です。

ドライバに関する詳細

MySQL または MariaDB 5.6 以降用の QMYSQL

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

タイムスタンプのサポート

Qt 6.8 以降、QDateTime の値は挿入前にUTCに変換され、取得時にはUTCから元の値に戻されます。 これを機能させるため、ドライバは `open()` 実行時に接続のタイムゾーンを UTC に設定します (`SET time_zone = '+00:00'`)。MySQL はタイムゾーン情報を保存しないため、この情報は失われ、取得されるすべての `QDateTime ` 値は UTC になります。

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、組み込み MySQL サーバーライブラリ」の章を参照してください。

接続オプション

Qt MySQL/MariaDB プラグインは、以下の接続オプションに対応しています：

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

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

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

qt-cmake に、MySQL / MariaDB のヘッダーファイルと共有ライブラリの場所を指定し（ここでは、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コネクタ）を入手する必要があります。インストーラを実行し、「カスタムインストール」を選択して、お使いのQtインストール環境（x86またはx64）に適合するMySQL Cコネクタをインストールしてください。インストール後、必要なファイルが存在することを確認してください：

• <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 にはさらに MSVC ランタイムライブラリが必要ですが、これはvcredist.exeを使用してインストールできます。

Oracle Call Interface (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> （全バージョン）

qt-cmake に、Oracle のヘッダーファイルと共有ライブラリの場所を指定してビルドを行ってください。

ここでは、Instant Client Package 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 インストーラを起動し、「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

Open Database Connectivity (ODBC) 用の QODBC

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

Windows では、ODBC ドライバマネージャーがデフォルトでインストールされています。Unix システムの場合、一部の実装では事前にインストールを行う必要があります。アプリケーションのエンドユーザー全員が ODBC ドライバマネージャーをインストールしている必要があります。そうでない場合、QODBC プラグインは動作しません。

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ドライバに対して、ODBC 2.xドライバとして動作するよう指示します。 しかし、一部のドライバマネージャと 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ドライバとして動作するよう指示してください。なお、これによりODBCドライバの動作のさまざまな側面（例：SQLSTATE）に影響が及ぶことに注意してください。この接続オプションを設定する前に、予想される動作の違いについて、ODBCのドキュメントを参照してください。

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

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

タイムスタンプのサポート

ODBCでは、タイムゾーンやそれに類する情報を一切含まないTIMESTAMP_STRUCTを使用しています。このため、QDateTime はタイムゾーンを一切考慮せずに使用されます。

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 サポート」にチェックを入れる必要があります。そうしないと、Oracle はすべての Unicode 文字列をローカルの 8 ビット表現に変換してしまいます。

接続オプション

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 ドライバは、PostgreSQL サーバーのバージョン 7.3 以降に対応しています。

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

タイムスタンプのサポート

Qt 6.8 以降、QDateTime の値は、挿入時にUTCに変換され、取得時にはUTCから元の値に戻されます。 これを機能させるため、ドライバは open() の実行時に接続のタイムゾーンを UTC に設定します (SET TIME ZONE 'UTC')。PostgreSQL には `timestamptz` 列型がありますが、挿入時に使用されたタイムゾーンは保持されないため、取得されるすべてのQDateTime 値は UTC となります。

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

のように記述すれば、作成時に使用されたのと同じ大文字・小文字の区別でアクセスできるようになります。作成時にテーブル名やフィールド名が引用符で囲まれていない場合、実際のテーブル名やフィールド名は小文字になります。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 による前方のみクエリのサポート

フォワードオンリークエリを使用するには、PostgreSQL クライアントライブラリバージョン 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プラグインは、PostgreSQLのconnect()ドキュメントで指定されているすべての接続オプションに対応しています。

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 を必ず含めるようにしてください。このファイルは、アプリケーションの実行ファイルと同じフォルダに配置する必要があります。

IBM DB2 用 QDB2 (バージョン 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_ROOT="/usr/local/db2"
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_ROOT="C:\db2"
cmake --build .
cmake --install .

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

Qt SQLite プラグインを使用すると、SQLite データベースにアクセスできます。SQLite はインプロセス型データベースであるため、データベースサーバーを用意する必要はありません。SQLite は単一のファイル上で動作し、接続を開く際にはそのファイルをデータベース名として指定する必要があります。ファイルが存在しない場合、SQLite はそのファイルを作成しようとします。 SQLiteは、インメモリデータベースや一時データベースもサポートしています。データベース名として、それぞれ「:memory:」または空の文字列を指定するだけで利用できます。

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

SQLite では、INTEGER PRIMARY KEY 列を除き、どの列でも任意の型の値を格納できます。たとえば、INTEGER として宣言された列には、ある行では整数値が、次の行ではテキスト値が格納されることがあります。 これは、SQLiteが値の型を、値が格納されているカラムではなく、値そのものと関連付けているためです。この結果、QSqlField::metaType()が返す型は、そのフィールドの推奨される型を示すに過ぎません。これに基づいて実際の型を推測してはならず、個々の値の型を個別に確認する必要があります。

SELECT文の実行中は、ドライバが更新に対してロックされます。Qtのアイテムビューは必要なときにデータを取得するため（QSqlTableModel の場合、QSqlQuery::fetchMore()を使用）、QSqlTableModel を使用する際に問題が発生する可能性があります。

SQLite に関する情報は、http://www.sqlite.org で確認できます。

タイムスタンプのサポート

SQLiteには、タイムスタンプ専用の列型はありません。QDateTime は文字列として格納され、Qt::ISODateWithMs の形式でフォーマットされるため、挿入および選択の際にもQDateTime のタイムゾーン情報が保持されます。

接続オプション

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演算子が備わっています。ただし、必要な実装はユーザーが用意する必要があります。利便性のため、setting the connect option QSQLITE_ENABLE_REGEXP でthe database connection is opened の前にデフォルトの実装を有効にすることができます。そうすると、「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、組み込み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 を参照してください。

タイムスタンプのサポート

Mimer SQL はタイムゾーンを認識せず、QDateTime はタイムゾーンを一切考慮せずに使用されます。

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 .

Borland InterBase 用の QIBASE

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

InterBaseでは、データベースファイルがローカルに保存されているか、別のサーバーに保存されているかに関わらず、データベースファイルへのフルパスを指定する必要がある点に注意してください。

タイムスタンプのサポート

InterBaseは、タイムゾーン情報を一切含めずに、タイムスタンプをUTCで保存します。このため、QDateTime はタイムゾーンを一切考慮せずに使用されます。

Firebird 4.0以降、このデータベースはタイムゾーン付きのタイムスタンプをサポートしています。タイムゾーン情報はタイムスタンプとは別に保存されるため、後で適切に取得することができます。タイムスタンプの処理に関する詳細については、Firebirdのドキュメントを参照してください。

接続オプション

Qt Borland InterBase プラグインは、以下の接続オプションに対応しています：

QIBASEプラグインの構築方法

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

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

GPLとのライセンス上の互換性の問題により、Qt Open Source Editionをご利用の方は、このプラグインをInterBaseの商用エディションにリンクすることはできません。FirebirdまたはInterBaseの無料版をご利用ください。

QIBASE ストアドプロシージャ

InterBase/FirebirdはOUT値を結果セットとして返すため、ストアドプロシージャを呼び出す際には、QSqlQuery::bindValue() を通じてIN値をバインドするだけで済みます。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 プラグインのビルド方法

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

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 の Dependency Walker またはDependencies GUIを使用して、依存ライブラリを確認できます。Qt Creator を使用すると、プロジェクトパネルの [実行] セクションにある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 データベースドライバの機能を定義する抽象基底クラスです。これには、QSqlDriver::open() やQSqlDriver::close() などの関数が含まれます。QSqlDriver は、データベースへの接続や適切な環境の構築などを担当します。さらに、QSqlDriver は、特定のデータベース API に適したQSqlQuery オブジェクトを作成することができます。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 プラグインの作成方法」を参照してください。また、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); }
};