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 = QLatin1StringView(defaultConnection))

ドライバ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 = QLatin1StringView(defaultConnection))

これはオーバーロードされた関数です。

このオーバーロードは、自分でインスタンス化したdriver でデータベース接続を作成したい場合に便利です。独自のデータベースドライバかもしれませんし、Qtドライバのインスタンスを作成する必要があるかもしれません。この場合、アプリケーションにドライバのコードを含めることをお勧めします。例えば、このように独自の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 = QLatin1StringView(defaultConnection))

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

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

connectionNames()、database()、およびスレッドと SQL モジュールも参照してください 。

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

connectionName というデータベース接続を返します。このデータベース接続は、事前にaddDatabase() で追加しておく必要があります。open が真 (既定値) で、データベース接続がまだ開かれていない場合は、今開かれます。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 を返す。

例

QSqlDatabasedb；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)

この関数は、name という新しいSQLドライバを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 文字列の形式は、オプション名または option=value ペアのセミコロン区切りリストです。オプションは使用するデータベースクライアントに依存し、各プラグインについてはSQL Database Driversのページで説明しています。

例

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 を割り当てる。