QSqlDatabase Class

Dokumentation zu den Mitgliedsfunktionen

QSqlDatabase::QSqlDatabase()

Erstellt ein leeres, ungültiges QSqlDatabase-Objekt. Verwenden Sie „ addDatabase()“, „ removeDatabase()“ und „ database()“, um gültige QSqlDatabase-Objekte zu erhalten.

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

Stellt eine Datenbankverbindung unter Verwendung des angegebenen „ driver “ her.

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

Erstellt eine QSqlDatabase-Verbindung, die den unter type angegebenen Treiber verwendet. Wird die Datei „ type “ nicht erkannt, ist die Datenbankverbindung nicht funktionsfähig.

Die derzeit verfügbaren Treibertypen sind:

Zusätzliche Treiber von Drittanbietern, einschließlich Ihrer eigenen benutzerdefinierten Treiber, können dynamisch geladen werden.

Siehe auch „SQL-Datenbanktreiber“, „ registerSqlDriver()“ und „ drivers()“.

QSqlDatabase::QSqlDatabase(const QSqlDatabase &other)

Erstellt eine Kopie von „ other “.

[noexcept] QSqlDatabase::~QSqlDatabase()

Löscht das Objekt und gibt alle zugewiesenen Ressourcen frei.

Siehe auch ` close()`.

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

Fügt der Liste der Datenbankverbindungen eine Datenbank hinzu, wobei der Treiber „ type “ und der Verbindungsname „ connectionName “ verwendet werden. Falls bereits eine Datenbankverbindung mit dem Namen „ connectionName “ vorhanden ist, wird diese Verbindung entfernt.

Die Datenbankverbindung wird über connectionName referenziert. Die neu hinzugefügte Datenbankverbindung wird zurückgegeben.

Wenn type nicht verfügbar ist oder nicht geladen werden konnte, gibt isValid() false zurück.

Wenn connectionName nicht angegeben wird, wird die neue Verbindung zur Standardverbindung für die Anwendung, und nachfolgende Aufrufe von database() ohne das Argument für den Verbindungsnamen geben die Standardverbindung zurück. Wenn hier ein connectionName angegeben wird, verwenden Sie database(connectionName), um die Verbindung abzurufen.

Bevor die Verbindung verwendet werden kann, muss sie initialisiert werden. Rufen Sie dazu beispielsweise einige oder alle der folgenden Funktionen auf: ` setDatabaseName()`, ` setUserName()`, ` setPassword()`, ` setHostName()`, ` setPort()` und ` setConnectOptions()` sowie schließlich ` open()`.

Hinweis: Diese Funktion ist threadsicher.

Siehe auch database(), removeDatabase() sowie „Threads und das SQL-Modul“.

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

Diese Überladung ist nützlich, wenn Sie eine Datenbankverbindung mit einem „ driver “ herstellen möchten, den Sie selbst instanziiert haben. Dabei kann es sich um Ihren eigenen Datenbanktreiber handeln, oder Sie müssen lediglich einen der Qt-Treiber selbst instanziieren. In diesem Fall wird empfohlen, den Treibercode in Ihre Anwendung einzubinden. So können Sie beispielsweise wie folgt eine PostgreSQL-Verbindung mit Ihrem eigenen QPSQL-Treiber herstellen:

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

Der obige Code richtet eine PostgreSQL-Verbindung ein und instanziiert ein `QPSQLDriver`-Objekt. Anschließend wird `addDatabase()` aufgerufen, um die Verbindung zu den bekannten Verbindungen hinzuzufügen, damit sie von den ` Qt SQL `-Klassen verwendet werden kann. Wenn ein Treiber mit einem Verbindungs-Handle (oder einer Reihe von Handles) instanziiert wird, geht Qt davon aus, dass Sie die Datenbankverbindung bereits geöffnet haben.

Beachten Sie, dass Sie Ihre Anwendung gegen die Datenbank-Client-Bibliothek verlinken müssen. Stellen Sie sicher, dass sich die Client-Bibliothek im Suchpfad Ihres Linkers befindet, und fügen Sie Zeilen wie die folgenden in Ihre Datei „ .pro “ ein:

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

Die beschriebene Vorgehensweise funktioniert für alle mitgelieferten Treiber. Der einzige Unterschied besteht in den Konstruktorargumenten des jeweiligen Treibers. Hier ist eine Tabelle der in Qt enthaltenen Treiber, ihrer Quellcode-Dateien und ihrer Konstruktorargumente:

Siehe auch ` drivers()`.

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

Kloniert die Datenbankverbindung „ other “ und speichert sie unter „ connectionName “. Alle Einstellungen der ursprünglichen Datenbank, z. B. „ databaseName()“, „ hostName()“ usw., werden übernommen. Führt keine Aktion aus, wenn „ other “ eine ungültige Datenbank ist. Gibt die neu erstellte Datenbankverbindung zurück.

Hinweis: Diese Funktion ist reentrant.

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

Kloniert die Datenbankverbindung „ other “ und speichert sie unter „ connectionName “. Alle Einstellungen der ursprünglichen Datenbank, z. B. „ databaseName()“, „ hostName()“ usw., werden übernommen. Führt keine Aktion aus, wenn „ other “ eine ungültige Datenbank ist. Gibt die neu erstellte Datenbankverbindung zurück.

Diese Überladung ist nützlich, wenn die Datenbank in einem anderen Thread geklont wird als dem, der von der durch ` other` dargestellten Datenbank verwendet wird.

void QSqlDatabase::close()

Schließt die Datenbankverbindung, gibt alle belegten Ressourcen frei und macht alle vorhandenen „ QSqlQuery “-Objekte ungültig, die mit der Datenbank verwendet werden.

Dies wirkt sich auch auf Kopien dieses ` QSqlDatabase `-Objekts aus.

Siehe auch ` removeDatabase()`.

bool QSqlDatabase::commit()

Führt eine Transaktion in der Datenbank durch, sofern der Treiber Transaktionen unterstützt und ein ` transaction()` gestartet wurde. Gibt ` true ` zurück, wenn der Vorgang erfolgreich war. Andernfalls wird ` false` zurückgegeben.

Rufen Sie ` lastError()` auf, um Informationen zu Fehlern abzurufen.

Siehe auch QSqlQuery::isActive(), QSqlDriver::hasFeature() und rollback().

QString QSqlDatabase::connectOptions() const

Gibt die für diese Verbindung verwendete Zeichenkette mit den Verbindungsoptionen zurück. Die Zeichenkette kann leer sein.

Siehe auch ` setConnectOptions()`.

QString QSqlDatabase::connectionName() const

Gibt den Verbindungsnamen zurück, der leer sein kann.

Siehe auch addDatabase().

[static] QStringList QSqlDatabase::connectionNames()

Gibt eine Liste zurück, die die Namen aller Verbindungen enthält.

Hinweis: Diese Funktion ist threadsicher.

Siehe auch contains(), database() sowie „Threads und das SQL-Modul“.

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

Gibt „ true “ zurück, wenn die Liste der Datenbankverbindungen „ connectionName “ enthält; andernfalls wird „ false “ zurückgegeben.

Hinweis: Diese Funktion ist threadsicher.

Siehe auch connectionNames(), database() sowie „Threads und das SQL-Modul“.

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

Gibt die Datenbankverbindung mit dem Namen „ connectionName “ zurück. Die Datenbankverbindung muss zuvor mit „ addDatabase()“ hinzugefügt worden sein. Wenn „ open “ auf „true“ gesetzt ist (Standard) und die Datenbankverbindung noch nicht geöffnet ist, wird sie nun geöffnet. Wenn kein „ connectionName “ angegeben ist, wird die Standardverbindung verwendet. Wenn „ connectionName “ nicht in der Liste der Datenbanken vorhanden ist, wird eine ungültige Verbindung zurückgegeben.

Hinweis: Diese Funktion ist threadsicher.

Siehe auch ` isOpen()` sowie „Threads und das SQL-Modul“.

QString QSqlDatabase::databaseName() const

Gibt den Namen der Datenbank der Verbindung zurück, der leer sein kann.

Siehe auch ` setDatabaseName()`.

QSqlDriver *QSqlDatabase::driver() const

Gibt den Datenbanktreiber zurück, der für den Zugriff auf die Datenbankverbindung verwendet wird.

Siehe auch addDatabase() und drivers().

QString QSqlDatabase::driverName() const

Gibt den Namen des Treibers der Verbindung zurück.

Siehe auch addDatabase() und driver().

[static] QStringList QSqlDatabase::drivers()

Gibt eine Liste aller verfügbaren Datenbanktreiber zurück.

Siehe auch „ registerSqlDriver()“.

QString QSqlDatabase::hostName() const

Gibt den Hostnamen der Verbindung zurück; dieser kann leer sein.

Siehe auch ` setHostName()`.

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

Gibt „ true “ zurück, wenn ein Treiber namens „ name “ verfügbar ist; andernfalls wird „ false “ zurückgegeben.

Siehe auch „ drivers()“.

bool QSqlDatabase::isOpen() const

Gibt „ true “ zurück, wenn die Datenbankverbindung derzeit geöffnet ist; andernfalls wird „ false “ zurückgegeben.

bool QSqlDatabase::isOpenError() const

Gibt „ true “ zurück, wenn beim Öffnen der Datenbankverbindung ein Fehler aufgetreten ist; andernfalls wird „ false “ zurückgegeben. Fehlerinformationen können mit der Funktion „ lastError()“ abgerufen werden.

bool QSqlDatabase::isValid() const

Gibt „ true “ zurück, wenn das „ QSqlDatabase “ über einen gültigen Treiber verfügt.

Beispiel:

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

Gibt Informationen zum letzten Fehler zurück, der in der Datenbank aufgetreten ist.

Fehler, die im Zusammenhang mit einer einzelnen Abfrage auftreten, werden von ` QSqlQuery::lastError()` gemeldet.

Siehe auch ` QSqlError ` und ` QSqlQuery::lastError()`.

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

Ändert die Thread-Affinität für „ QSqlDatabase “ und den zugehörigen Treiber. Diese Funktion gibt „ true “ zurück, wenn der Vorgang erfolgreich war. Die Ereignisverarbeitung wird im „ targetThread “ fortgesetzt.

Während dieses Vorgangs müssen Sie sicherstellen, dass kein ` QSqlQuery ` an diese Instanz gebunden ist; andernfalls wird der ` QSqlDatabase ` nicht in den angegebenen Thread verschoben und die Funktion gibt ` false` zurück.

Da der zugehörige Treiber von ` QObject` abgeleitet ist, gelten alle Einschränkungen für die Verlagerung eines ` QObject ` in einen anderen Thread auch für diese Funktion.

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch ` QObject::moveToThread()` sowie „Threads und das SQL-Modul“.

QSql::NumericalPrecisionPolicy QSqlDatabase::numericalPrecisionPolicy() const

Gibt die „numericalPrecisionPolicy“ zurück.

Siehe auch „ setNumericalPrecisionPolicy()“.

bool QSqlDatabase::open()

Öffnet die Datenbankverbindung unter Verwendung der aktuellen Verbindungswerte. Gibt bei Erfolg „ true “ zurück; andernfalls „ false “. Fehlerinformationen können mit „ lastError()“ abgerufen werden.

Siehe auch lastError(), setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() und setConnectOptions().

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

Öffnet die Datenbankverbindung unter Verwendung des angegebenen Namens „ user “ und der Adresse „ password “. Gibt bei Erfolg „ true “ zurück; andernfalls wird „ false “ zurückgegeben. Fehlerinformationen können mit der Funktion „ lastError()“ abgerufen werden.

Diese Funktion speichert das übergebene Passwort nicht. Stattdessen wird das Passwort direkt an den Treiber zum Öffnen der Verbindung weitergeleitet und anschließend verworfen.

Siehe auch ` lastError()`.

QString QSqlDatabase::password() const

Gibt das Passwort der Verbindung zurück. Es wird eine leere Zeichenkette zurückgegeben, wenn das Passwort nicht mit ` setPassword()` festgelegt wurde und wenn das Passwort beim Aufruf von ` open()` angegeben wurde oder wenn kein Passwort verwendet wurde.

Siehe auch ` setPassword()`.

int QSqlDatabase::port() const

Gibt die Portnummer der Verbindung zurück. Der Wert ist undefiniert, wenn die Portnummer nicht festgelegt wurde.

Siehe auch ` setPort()`.

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

Gibt den Primärindex der Tabelle „ tablename “ zurück. Wenn kein Primärindex vorhanden ist, wird ein leeres „ QSqlIndex “ zurückgegeben.

Siehe auch ` tables()` und ` record()`.

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

Gibt einen ` QSqlRecord ` zurück, der mit den Namen aller Felder der Tabelle (oder Ansicht) namens ` tablename` gefüllt ist. Die Reihenfolge, in der die Felder im Datensatz erscheinen, ist nicht definiert. Wenn keine solche Tabelle (oder Ansicht) existiert, wird ein leerer Datensatz zurückgegeben.

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

Diese Funktion registriert einen neuen SQL-Treiber namens „ name “ im SQL-Framework. Dies ist nützlich, wenn Sie über einen benutzerdefinierten SQL-Treiber verfügen und diesen nicht als Plugin kompilieren möchten.

Beispiel:

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

QSqlDatabase übernimmt die Verantwortung für den Zeiger „ creator “, daher dürfen Sie ihn nicht selbst löschen.

Siehe auch drivers().

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

Entfernt die Datenbankverbindung „ connectionName “ aus der Liste der Datenbankverbindungen.

Beispiel:

// 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

Die richtige Vorgehensweise:

{
    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

Um die Standardverbindung zu entfernen, die möglicherweise durch einen Aufruf von ` addDatabase()` ohne Angabe eines Verbindungsnamens erstellt wurde, können Sie den Namen der Standardverbindung abrufen, indem Sie ` connectionName()` auf die von ` database()` zurückgegebene Datenbank anwenden. Beachten Sie, dass eine ungültige Datenbank zurückgegeben wird, wenn keine Standarddatenbank erstellt wurde.

Hinweis: Diese Funktion ist threadsicher.

Siehe auch database(), connectionName() sowie „Threads und das SQL-Modul“.

bool QSqlDatabase::rollback()

Führt ein Rollback einer Transaktion in der Datenbank durch, sofern der Treiber Transaktionen unterstützt und ein ` transaction()` gestartet wurde. Gibt ` true ` zurück, wenn der Vorgang erfolgreich war. Andernfalls wird ` false` zurückgegeben.

Rufen Sie ` lastError()` auf, um Informationen zu Fehlern abzurufen.

Siehe auch QSqlQuery::isActive(), QSqlDriver::hasFeature() und commit().

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

Legt die datenbankspezifischen Verbindungsoptionen fest ( options). Dies muss vor dem Öffnen der Verbindung erfolgen, da es andernfalls keine Wirkung hat. Eine weitere Möglichkeit besteht darin, die Verbindung zu schließen, QSqlDatabase::setConnectOptions() aufzurufen und die Verbindung anschließend erneut mit open() zu öffnen.

Das Format der Zeichenkette ` options ` ist eine durch Semikolons getrennte Liste von Optionsnamen oder Paaren aus Option und Wert. Die Optionen hängen vom verwendeten Datenbank-Client ab und werden für jedes Plugin auf der Seite „SQL-Datenbanktreiber“ beschrieben.

Beispiele:

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
    // ...
}
}

Weitere Informationen zu den verschiedenen Optionen findest du in der Dokumentation der Client-Bibliothek.

Siehe auch ` connectOptions()`.

void QSqlDatabase::setDatabaseName(const QString &name)

Legt den Datenbanknamen der Verbindung auf „ name “ fest. Damit dies wirksam wird, muss der Datenbankname festgelegt werden, bevor die Verbindung mit „ opened “ hergestellt wird. Alternativ können Sie die Verbindung mit „ close()“ erstellen, den Datenbanknamen festlegen und anschließend erneut „ open()“ aufrufen.

Beim QSQLITE-Treiber wird die Datei automatisch erstellt, wenn der angegebene Datenbankname nicht existiert, es sei denn, die Option `QSQLITE_OPEN_READONLY` ist gesetzt.

Zudem kann ` name ` auf ` ":memory:" ` gesetzt werden, wodurch eine temporäre Datenbank erstellt wird, die nur für die Laufzeit der Anwendung verfügbar ist.

Beim QOCI-Treiber (Oracle) entspricht der Datenbankname dem TNS-Dienstnamen.

Beim QODBC-Treiber kann „ name “ entweder ein DSN, ein DSN-Dateiname (in diesem Fall muss die Datei die Erweiterung „ .dsn “ haben) oder eine Verbindungszeichenfolge sein.

Beispielsweise können Microsoft-Access-Benutzer die folgende Verbindungszeichenfolge verwenden, um eine „ .mdb “-Datei direkt zu öffnen, anstatt einen DSN-Eintrag im ODBC-Manager erstellen zu müssen:

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

Es gibt keinen Standardwert.

Siehe auch databaseName(), setUserName(), setPassword(), setHostName(), setPort(), setConnectOptions() und open().

void QSqlDatabase::setHostName(const QString &host)

Setzt den Hostnamen der Verbindung auf host. Damit dies wirksam wird, muss der Hostname vor dem Aufbau der Verbindung festgelegt werden: opened. Alternativ können Sie die Verbindung mit close() aufrufen, den Hostnamen festlegen und anschließend erneut open() aufrufen.

Es gibt keinen Standardwert.

Siehe auch „ hostName()“, „ setUserName()“, „ setPassword()“, „ setDatabaseName()“, „ setPort()“, „ setConnectOptions()“ und „ open()“.

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

Setzt „ numericalPrecisionPolicy “ auf „ precisionPolicy “.

Siehe auch numericalPrecisionPolicy().

void QSqlDatabase::setPassword(const QString &password)

Legt das Passwort der Verbindung auf „ password “ fest. Damit dies wirksam wird, muss das Passwort vor dem Herstellen der Verbindung mit „ opened “ festgelegt werden. Alternativ können Sie die Verbindung mit „ close()“ schließen, das Passwort festlegen und anschließend erneut „ open()“ aufrufen.

Es gibt keinen Standardwert.

Siehe auch „ password()“, „ setUserName()“, „ setDatabaseName()“, „ setHostName()“, „ setPort()“, „ setConnectOptions()“ und „ open()“.

void QSqlDatabase::setPort(int port)

Setzt die Portnummer der Verbindung auf port. Damit die Änderung wirksam wird, muss die Portnummer festgelegt werden, bevor die Verbindung hergestellt wird ( opened). Alternativ können Sie die Verbindung mit ` close()` schließen, die Portnummer festlegen und anschließend erneut ` open()` aufrufen.

Es gibt keinen Standardwert.

Siehe auch port(), setUserName(), setPassword(), setHostName(), setDatabaseName(), setConnectOptions() und open().

void QSqlDatabase::setUserName(const QString &name)

Legt den Benutzernamen der Verbindung auf „ name “ fest. Damit dies wirksam wird, muss der Benutzername vor dem Herstellen der Verbindung mit „ opened “ festgelegt werden. Alternativ können Sie die Verbindung mit „ close()“ öffnen, den Benutzernamen festlegen und anschließend erneut „ open()“ aufrufen.

Es gibt keinen Standardwert.

Siehe auch userName(), setDatabaseName(), setPassword(), setHostName(), setPort(), setConnectOptions() und open().

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

Gibt eine Liste der Tabellen, Systemtabellen und Ansichten der Datenbank zurück, wie durch den Parameter „ type “ angegeben.

Siehe auch ` primaryIndex()` und ` record()`.

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

Gibt einen Zeiger auf die zugehörige „ QThread “-Instanz zurück.

Diese Funktion wurde in Qt 6.8 eingeführt.

bool QSqlDatabase::transaction()

Leitet eine Transaktion in der Datenbank ein, sofern der Treiber Transaktionen unterstützt. Gibt „ true “ zurück, wenn der Vorgang erfolgreich war. Andernfalls wird „ false “ zurückgegeben.

Siehe auch „ QSqlDriver::hasFeature()“, „ commit()“ und „ rollback()“.

QString QSqlDatabase::userName() const

Gibt den Benutzernamen der Verbindung zurück; dieser kann leer sein.

Siehe auch ` setUserName()`.

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

Weist diesem Objekt „ other “ zu.