QSqlDatabase Class

メンバ関数のドキュメント

QSqlDatabase::QSqlDatabase()

空で無効な QSqlDatabase オブジェクトを作成します。有効な QSqlDatabase オブジェクトを取得するには、addDatabase()、removeDatabase()、およびdatabase() を使用してください。

[explicit protected] QSqlDatabase::QSqlDatabase(QSqlDriver *driver)

指定されたdriver を使用して、データベース接続を作成します。

[explicit protected] QSqlDatabase::QSqlDatabase(const QString &type)

type で指定されたドライバを使用する QSqlDatabase 接続を作成します。type が認識されない場合、データベース接続は機能しません。

現在利用可能なドライバの種類は次のとおりです：

独自のカスタムドライバを含む、その他のサードパーティ製ドライバを動的にロードすることができます。

「SQL データベースドライバ」、「registerSqlDriver()」、および「drivers()」も参照してください 。

QSqlDatabase::QSqlDatabase(const QSqlDatabase &other)

other のコピーを作成します。

[noexcept] QSqlDatabase::~QSqlDatabase()

オブジェクトを破棄し、割り当てられたリソースをすべて解放します。

close()も参照してください 。

[static] QSqlDatabase QSqlDatabase::addDatabase(const QString &type, const QString &connectionName = defaultConnectionName())

type ドライバーと接続名connectionName を使用して、データベース接続のリストにデータベースを追加します。connectionName という名前のデータベース接続がすでに存在する場合、その接続は削除されます。

データベース接続はconnectionName によって参照されます。新しく追加されたデータベース接続が返されます。

type が利用できない場合、または読み込めなかった場合、isValid() はfalse を返します。

connectionName が指定されていない場合、新しい接続がアプリケーションのデフォルトの接続となり、その後、接続名引数なしでdatabase()を呼び出すと、デフォルトの接続が返されます。ここでconnectionName が指定されている場合は、database(connectionName)を使用して接続を取得してください。

接続を使用する前に、初期化する必要があります。例えば、setDatabaseName()、setUserName()、setPassword()、setHostName()、setPort()、setConnectOptions() のいずれかまたはすべてを呼び出し、最後にopen() を呼び出してください。

注： この関数はスレッドセーフです。

関連項目： database()、removeDatabase()、および「スレッドとSQLモジュール」。

[static] QSqlDatabase QSqlDatabase::addDatabase(QSqlDriver *driver, const QString &connectionName = defaultConnectionName())

このオーバーロードは、自分でインスタンス化したdriver を使用してデータベース接続を確立したい場合に便利です。これは、独自に開発したデータベースドライバの場合もあれば、Qtのドライバの1つを自分でインスタンス化する必要がある場合もあるでしょう。 この場合、ドライバーのコードをアプリケーションに組み込むことをお勧めします。たとえば、独自の QPSQL ドライバーを使用して、次のように PostgreSQL への接続を作成できます。

PGconn *con = PQconnectdb("host=server user=bart password=simpson dbname=springfield");
QPSQLDriver *drv = new QPSQLDriver(con);
QSqlDatabase db = QSqlDatabase::addDatabase(drv); // becomes the new default connection
QSqlQuery query;
query.exec("SELECT NAME, ID FROM STAFF");

上記のコードは、PostgreSQL接続を設定し、QPSQLDriverオブジェクトをインスタンス化します。 次に、addDatabase() を呼び出して、その接続を既知の接続に追加し、Qt SQL クラスから利用できるようにします。接続ハンドル（または一連のハンドル）を使用してドライバをインスタンス化する場合、Qt はデータベース接続がすでに開かれているものとみなします。

アプリケーションをデータベースクライアントライブラリに対してリンクする必要があることに注意してください。クライアントライブラリがリンカーの検索パスに含まれていることを確認し、.pro ファイルに次のような行を追加してください:

unix:LIBS += -lpq
win32:LIBS += libpqdll.lib

ここで説明した方法は、提供されているすべてのドライバで機能します。唯一の違いは、ドライバのコンストラクタの引数です。以下に、Qt に含まれるドライバ、そのソースコードファイル、およびコンストラクタの引数をまとめた表を示します：

drivers()も参照してください 。

[static] QSqlDatabase QSqlDatabase::cloneDatabase(const QSqlDatabase &other, const QString &connectionName)

データベース接続 `other ` を複製し、`connectionName` として保存します。元のデータベースの設定（例：`databaseName()`、`hostName()` など）はすべてコピーされます。other が無効なデータベースの場合は何も行いません。新しく作成されたデータベース接続を返します。

注：この関数は再入可能です。

[static] QSqlDatabase QSqlDatabase::cloneDatabase(const QString &other, const QString &connectionName)

データベース接続 `other ` を複製し、`connectionName` として保存します。元のデータベースの設定（例：`databaseName()`、`hostName()` など）はすべてコピーされます。`other ` が無効なデータベースの場合は、何も行いません。新しく作成されたデータベース接続を返します。

このオーバーロードは、other で表されるデータベースが使用しているスレッドとは別のスレッドでデータベースを複製する場合に役立ちます。

void QSqlDatabase::close()

データベース接続を閉じ、取得したリソースをすべて解放し、そのデータベースで使用されている既存のQSqlQuery オブジェクトをすべて無効化します。

この操作は、このQSqlDatabase オブジェクトのコピーにも影響します。

removeDatabase()も参照してください 。

bool QSqlDatabase::commit()

ドライバがトランザクションをサポートしており、transaction() が開始されている場合、トランザクションをデータベースにコミットします。操作が成功した場合は、true を返します。それ以外の場合は、false を返します。

エラーに関する情報を取得するには、lastError() を呼び出してください。

QSqlQuery::isActive()、QSqlDriver::hasFeature()、およびrollback()も参照してください 。

QString QSqlDatabase::connectOptions() const

この接続に使用される接続オプションの文字列を返します。この文字列は空の場合もあります。

setConnectOptions()も参照してください 。

QString QSqlDatabase::connectionName() const

接続名を返します。空の場合もあります。

関連項目 ：addDatabase()

[static] QStringList QSqlDatabase::connectionNames()

すべての接続の名前を含むリストを返します。

注： この関数はスレッドセーフです。

関連項目: ` contains()`、`database()`、および「スレッドとSQLモジュール」。

[static] bool QSqlDatabase::contains(const QString &connectionName = defaultConnectionName())

データベース接続のリストに `connectionName` が含まれている場合は `true ` を返し、そうでない場合は `false` を返します。

注： この関数はスレッドセーフです。

関連項目: connectionNames(),database(), および「スレッドと SQL モジュール」。

[static] QSqlDatabase QSqlDatabase::database(const QString &connectionName = defaultConnectionName(), bool open = true)

connectionName という名前のデータベース接続を返します。このデータベース接続は、事前にaddDatabase()で追加されている必要があります。open がtrue（デフォルト）で、かつデータベース接続がまだ開かれていない場合は、この時点で接続が開かれます。connectionName が指定されていない場合は、デフォルトの接続が使用されます。connectionName がデータベースのリストに存在しない場合、無効な接続が返されます。

注： この関数はスレッドセーフです。

関連項目： isOpen() および「スレッドと SQL モジュール」。

QString QSqlDatabase::databaseName() const

接続先のデータベース名を返します。空の場合もあります。

関連項目： setDatabaseName()。

QSqlDriver *QSqlDatabase::driver() const

データベース接続へのアクセスに使用されるデータベースドライバを返します。

addDatabase() およびdrivers()も参照してください 。

QString QSqlDatabase::driverName() const

接続のドライバ名を返します。

addDatabase() およびdriver()も参照してください 。

[static] QStringList QSqlDatabase::drivers()

利用可能なすべてのデータベースドライバのリストを返します。

registerSqlDriver()も参照してください 。

QString QSqlDatabase::hostName() const

接続のホスト名を返します。空の場合もあります。

setHostName()も参照してください 。

[static] bool QSqlDatabase::isDriverAvailable(const QString &name)

name という名前のドライバが利用可能な場合はtrue を返し、そうでない場合はfalse を返します。

drivers()も参照してください 。

bool QSqlDatabase::isOpen() const

データベース接続が現在開かれている場合は `true ` を返し、そうでない場合は `false` を返します。

bool QSqlDatabase::isOpenError() const

データベース接続の確立にエラーが発生した場合は `true ` を返し、そうでない場合は `false` を返します。エラー情報は、lastError() 関数を使用して取得できます。

bool QSqlDatabase::isValid() const

QSqlDatabase に有効なドライバが存在する場合、true を返します。

例：

QSqlDatabase db;
qDebug() << db.isValid();    // Returns false

db=QSqlDatabase::database("sales");
qDebug() << db.isValid();    // Returns \c true if "sales" connection exists

QSqlDatabase::removeDatabase("sales");
qDebug() << db.isValid();    // Returns false

QSqlError QSqlDatabase::lastError() const

データベースで最後に発生したエラーに関する情報を返します。

個々のクエリに関連して発生したエラーは、QSqlQuery::lastError() によって報告されます。

QSqlError およびQSqlQuery::lastError()も参照してください 。

[since 6.8] bool QSqlDatabase::moveToThread(QThread *targetThread)

QSqlDatabase およびその関連ドライバのスレッドアフィニティを変更します。この関数が成功すると、true を返します。イベント処理は、targetThread で継続されます。

この操作を行う際には、このインスタンスにQSqlQuery がバインドされていないことを確認する必要があります。そうしないと、QSqlDatabase が指定されたスレッドに移動されず、関数はfalse を返します。

関連するドライバはQObject から派生しているため、QObject を別のスレッドに移動する際のすべての制約が、この関数にも適用されます。

この関数は Qt 6.8 で導入されました。

QObject::moveToThread() および「スレッドと SQL モジュール」も参照してください 。

QSql::NumericalPrecisionPolicy QSqlDatabase::numericalPrecisionPolicy() const

numericalPrecisionPolicy を返します。

関連項目： setNumericalPrecisionPolicy()。

bool QSqlDatabase::open()

現在の接続設定を使用してデータベース接続を開きます。成功した場合はtrue を返し、失敗した場合はfalse を返します。エラー情報はlastError()を使用して取得できます。

関連項目： lastError()、setDatabaseName()、setUserName()、setPassword()、setHostName()、setPort()、およびsetConnectOptions()。

bool QSqlDatabase::open(const QString &user, const QString &password)

指定されたuser 名とpassword を使用して、データベース接続を開きます。成功した場合はtrue を返し、失敗した場合はfalse を返します。エラー情報はlastError()関数を使用して取得できます。

この関数は、渡されたパスワードを保存しません。代わりに、パスワードは接続を開くためにドライバに直接渡され、その後破棄されます。

lastError()も参照してください 。

QString QSqlDatabase::password() const

接続のパスワードを返します。setPassword() でパスワードが設定されていない場合、open() の呼び出しでパスワードが指定されていた場合、またはパスワードが使用されていない場合は、空の文字列が返されます。

setPassword()も参照してください 。

int QSqlDatabase::port() const

接続のポート番号を返します。ポート番号が設定されていない場合、この値は未定義となります。

setPort()も参照してください 。

QSqlIndex QSqlDatabase::primaryIndex(const QString &tablename) const

テーブル `tablename` の主キーを返します。主キーが存在しない場合は、空の `QSqlIndex ` が返されます。

関連項目: tables() およびrecord()。

QSqlRecord QSqlDatabase::record(const QString &tablename) const

tablename という名前のテーブル（またはビュー）に含まれるすべてのフィールド名が格納されたQSqlRecord を返します。レコード内のフィールドの表示順序は未定義です。該当するテーブル（またはビュー）が存在しない場合は、空のレコードが返されます。

[static] void QSqlDatabase::registerSqlDriver(const QString &name, QSqlDriverCreatorBase *creator)

この関数は、SQLフレームワーク内に「name 」という新しいSQLドライバを登録します。これは、カスタムSQLドライバがあり、それをプラグインとしてコンパイルしたくない場合に便利です。

例：

QSqlDatabase::registerSqlDriver("MYDRIVER", new QSqlDriverCreator<QSqlDriver>);
QVERIFY(QSqlDatabase::drivers().contains("MYDRIVER"));
QSqlDatabase db = QSqlDatabase::addDatabase("MYDRIVER");
QVERIFY(db.isValid());

QSqlDatabase creator ポインタの所有権を取得するため、自分で削除してはいけません。

drivers()も参照してください 。

[static] void QSqlDatabase::removeDatabase(const QString &connectionName)

データベース接続「connectionName 」をデータベース接続のリストから削除します。

例：

// WRONG
QSqlDatabase db = QSqlDatabase::database("sales");
QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db);
QSqlDatabase::removeDatabase("sales"); // will output a warning
// "db" is now a dangling invalid database connection,
// "query" contains an invalid result set

正しい方法：

{
    QSqlDatabase db = QSqlDatabase::database("sales");
    QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db);
}
// Both "db" and "query" are destroyed because they are out of scope
QSqlDatabase::removeDatabase("sales"); // correct

addDatabase() の呼び出し時に接続名を指定せずに作成された可能性のあるデフォルトの接続を削除するには、database() によって返されたデータベースに対してconnectionName() を呼び出すことで、デフォルトの接続名を取得できます。なお、デフォルトのデータベースが作成されていない場合、無効なデータベースが返されることに注意してください。

注： この関数はスレッドセーフです。

関連項目: database()、connectionName()、および「スレッドとSQLモジュール」。

bool QSqlDatabase::rollback()

ドライバがトランザクションをサポートしており、transaction() が開始されている場合、データベース上のトランザクションをロールバックします。操作が成功した場合は、true を返します。それ以外の場合は、false を返します。

エラーに関する情報を取得するには、lastError() を呼び出してください。

QSqlQuery::isActive()、QSqlDriver::hasFeature()、およびcommit()も参照してください 。

void QSqlDatabase::setConnectOptions(const QString &options = QString())

データベース固有のoptions を設定します。これは接続を開く前に実行する必要があります。そうしないと、効果がありません。別の方法として、接続を閉じ、QSqlDatabase::setConnectOptions()を呼び出し、open()で接続を再度開くこともできます。

options の文字列形式は、オプション名または「オプション=値」のペアをセミコロンで区切ったリストです。オプションは使用するデータベースクライアントによって異なり、各プラグインについては「SQLデータベースドライバ」ページで説明されています。

例：

db.setConnectOptions("SSL_KEY=client-key.pem;SSL_CERT=client-cert.pem;SSL_CA=ca-cert.pem;CLIENT_IGNORE_SPACE=1"); // use an SSL connection to the server
if (!db.open()) {
    db.setConnectOptions(); // clears the connect option string
    // ...
}
// ...
// PostgreSQL connection
db.setConnectOptions("requiressl=1"); // enable PostgreSQL SSL connections
if (!db.open()) {
    db.setConnectOptions(); // clear options
    // ...
}
// ...
// ODBC connection
db.setConnectOptions("SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLY;SQL_ATTR_TRACE=SQL_OPT_TRACE_ON"); // set ODBC options
if (!db.open()) {
    db.setConnectOptions(); // don't try to set this option
    // ...
}
}

各オプションの詳細については、クライアントライブラリのドキュメントを参照してください。

connectOptions()も参照してください 。

void QSqlDatabase::setDatabaseName(const QString &name)

接続のデータベース名を `name` に設定します。この設定を有効にするには、接続が `opened` される前にデータベース名を設定しておく必要があります。あるいは、接続に対して `close()` を実行し、データベース名を設定してから、再度 `open()` を呼び出すこともできます。

QSQLITE ドライバの場合、指定されたデータベース名が存在しないときは、QSQLITE_OPEN_READONLY オプションが設定されていない限り、ファイルが自動的に作成されます。

さらに、name を":memory:" に設定すると、アプリケーションの実行中にのみ利用可能な一時データベースが作成されます。

QOCI (Oracle) ドライバの場合、データベース名は TNS サービス名となります。

QODBC ドライバの場合、name は、DSN、DSN ファイル名（この場合、ファイルの拡張子は.dsn である必要があります）、または接続文字列のいずれかになります。

たとえば、Microsoft Access ユーザーは、ODBC マネージャーで DSN エントリを作成する代わりに、次の接続文字列を使用して「.mdb 」ファイルを直接開くことができます。

// ...
QSqlDatabase db = QSqlDatabase::addDatabase("QODBC");
db.setDatabaseName("DRIVER={Microsoft Access Driver (*.mdb, *.accdb)};FIL={MS Access};DBQ=myaccessfile.mdb");
if (db.open()) {
    // success!
}
// ...

デフォルト値はありません。

関連項目： databaseName()、setUserName()、setPassword()、setHostName()、setPort()、setConnectOptions()、およびopen()。

void QSqlDatabase::setHostName(const QString &host)

接続のホスト名をhost に設定します。この設定を有効にするには、接続がopenedになる前にホスト名を設定しておく必要があります。あるいは、接続に対してclose() を実行し、ホスト名を設定してから、再度open() を呼び出すこともできます。

デフォルト値はありません。

関連項目： hostName()、setUserName()、setPassword()、setDatabaseName()、setPort()、setConnectOptions()、およびopen()。

void QSqlDatabase::setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)

numericalPrecisionPolicy をprecisionPolicy に設定します。

numericalPrecisionPolicy()も参照してください 。

void QSqlDatabase::setPassword(const QString &password)

接続のパスワードを `password` に設定します。この設定を有効にするには、接続が `opened`される前にパスワードを設定しておく必要があります。あるいは、接続に対して `close()` を実行し、パスワードを設定してから、再度 `open()` を呼び出すこともできます。

デフォルト値はありません。

関連項目： password()、setUserName()、setDatabaseName()、setHostName()、setPort()、setConnectOptions()、open()。

void QSqlDatabase::setPort(int port)

接続のポート番号をport に設定します。この設定を有効にするには、接続が openedされる前にポート番号を設定しておく必要があります。あるいは、接続に対してclose()を呼び出し、ポート番号を設定してから、再度open()を呼び出すこともできます。

デフォルト値はありません。

関連項目： port()、setUserName()、setPassword()、setHostName()、setDatabaseName()、setConnectOptions()、およびopen()。

void QSqlDatabase::setUserName(const QString &name)

接続のユーザー名を `name` に設定します。この設定を有効にするには、接続が `opened` される前にユーザー名を設定しておく必要があります。あるいは、接続に対して `close()` を実行し、ユーザー名を設定してから、再度 `open()` を呼び出すこともできます。

デフォルト値はありません。

関連項目: userName(),setDatabaseName(),setPassword(),setHostName(),setPort(),setConnectOptions(), およびopen()。

QStringList QSqlDatabase::tables(QSql::TableType type = QSql::Tables) const

パラメータ `type` で指定された、データベースのテーブル、システムテーブル、およびビューのリストを返します。

primaryIndex() およびrecord()も参照してください 。

[since 6.8] QThread *QSqlDatabase::thread() const

関連付けられたQThread インスタンスへのポインタを返します。

この関数はQt 6.8で導入されました。

bool QSqlDatabase::transaction()

ドライバがトランザクションをサポートしている場合、データベース上でトランザクションを開始します。操作が成功した場合は `true ` を返します。そうでない場合は `false` を返します。

QSqlDriver::hasFeature()、commit()、およびrollback()も参照してください 。

QString QSqlDatabase::userName() const

接続のユーザー名を返します。空の場合もあります。

setUserName()も参照してください 。

QSqlDatabase &QSqlDatabase::operator=(const QSqlDatabase &other)

このオブジェクトにother を割り当てます。