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()、Threads and the SQL Moduleも参照してください 。

[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 を返します。

例

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() およびThreads and the SQL Moduleも参照してください 。

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