QSqlDatabase Class

Dokumentation der Mitgliedsfunktionen

QSqlDatabase::QSqlDatabase()

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

Dies ist eine überladene Funktion.

Erstellt eine Datenbankverbindung unter Verwendung der angegebenen driver.

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

Dies ist eine überladene Funktion.

Erzeugt eine QSqlDatabase-Verbindung, die den von type angegebenen Treiber verwendet. Wenn type nicht erkannt wird, hat die Datenbankverbindung keine Funktionalität.

Die derzeit verfügbaren Treiber-Typen sind:

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

Siehe auch SQL-Datenbank-Treiber, registerSqlDriver() und drivers().

QSqlDatabase::QSqlDatabase(const QSqlDatabase &other)

Erzeugt eine Kopie von other.

[noexcept] QSqlDatabase::~QSqlDatabase()

Zerstört das Objekt und gibt alle zugewiesenen Ressourcen frei.

Siehe auch close().

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

Fügt eine Datenbank zur Liste der Datenbankverbindungen mit dem Treiber type und dem Verbindungsnamen connectionName hinzu. Wenn bereits eine Datenbankverbindung mit dem Namen connectionName besteht, wird diese Verbindung entfernt.

Die Datenbankverbindung wird durch 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 eine connectionName angegeben wird, verwenden Sie database(connectionName), um die Verbindung abzurufen.

Bevor Sie die Verbindung verwenden, muss sie initialisiert werden. Rufen Sie z. B. einige oder alle der Funktionen setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() und setConnectOptions() und schließlich open() auf.

Hinweis: Diese Funktion ist thread-sicher.

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

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

Dies ist eine überladene Funktion.

Diese Überladung ist nützlich, wenn Sie eine Datenbankverbindung mit einer driver erstellen wollen, die Sie selbst instanziiert haben. Das kann Ihr eigener Datenbanktreiber sein, oder Sie müssen einfach einen der Qt-Treiber selbst instanziieren. Wenn Sie dies tun, sollten Sie den Treibercode in Ihre Anwendung einbinden. Zum Beispiel können Sie eine PostgreSQL-Verbindung mit Ihrem eigenen QPSQL-Treiber wie folgt erstellen:

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, so dass sie von den Qt SQL Klassen verwendet werden kann. Wenn ein Treiber mit einem Verbindungshandle (oder einer Reihe von Handles) instanziiert wird, nimmt Qt an, dass Sie die Datenbankverbindung bereits geöffnet haben.

Denken Sie daran, dass Sie Ihre Anwendung mit der Datenbank-Client-Bibliothek linken müssen. Stellen Sie sicher, dass sich die Client-Bibliothek im Suchpfad Ihres Linkers befindet, und fügen Sie Zeilen wie diese in Ihre .pro Datei ein:

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

Die beschriebene Methode funktioniert für alle mitgelieferten Treiber. Der einzige Unterschied liegt in den Argumenten des Treiberkonstruktors. Hier ist eine Tabelle mit den in Qt enthaltenen Treibern, ihren Quellcode-Dateien und ihren Konstruktor-Argumenten:

Siehe auch drivers().

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

Klont die Datenbankverbindung other und speichert sie als connectionName. Alle Einstellungen der ursprünglichen Datenbank, z. B. databaseName(), hostName() usw., werden übernommen. Führt nichts 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)

Dies ist eine überladene Funktion.

Klont die Datenbankverbindung other und speichert sie als connectionName. Alle Einstellungen der ursprünglichen Datenbank, z.B. databaseName(), hostName(), usw., werden übernommen. Führt nichts 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 auf die Datenbank geklont wird, die von der durch other dargestellten Datenbank verwendet wird.

void QSqlDatabase::close()

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

Dies betrifft auch Kopien dieses QSqlDatabase Objekts.

Siehe auch removeDatabase().

bool QSqlDatabase::commit()

Übergibt eine Transaktion an die Datenbank, wenn der Treiber Transaktionen unterstützt und eine transaction() gestartet wurde. Gibt true zurück, wenn der Vorgang erfolgreich war. Andernfalls gibt er false zurück.

Rufen Sie lastError() auf, um Informationen über Fehler zu erhalten.

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

QString QSqlDatabase::connectOptions() const

Gibt die Zeichenkette für die Verbindungsoptionen zurück, die für diese Verbindung verwendet wird. 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 mit den Namen aller Verbindungen zurück.

Hinweis: Diese Funktion ist thread-sicher.

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

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

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

Hinweis: Diese Funktion ist thread-sicher.

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

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

Gibt die Datenbankverbindung mit dem Namen connectionName zurück. Die Datenbankverbindung muss zuvor mit addDatabase() hinzugefügt worden sein. Wenn open wahr ist (die Vorgabe) und die Datenbankverbindung noch nicht geöffnet ist, wird sie jetzt geöffnet. Wenn keine 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 thread-sicher.

Siehe auch isOpen() und Threads und das SQL-Modul.

QString QSqlDatabase::databaseName() const

Gibt den Datenbanknamen 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 Treibernamen 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; er 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 ein Fehler beim Öffnen der Datenbankverbindung aufgetreten ist; andernfalls false. Fehlerinformationen können mit der Funktion lastError() abgefragt werden.

bool QSqlDatabase::isValid() const

Gibt true zurück, wenn QSqlDatabase einen gültigen Treiber hat.

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

Liefert Informationen über den letzten Fehler, der in der Datenbank aufgetreten ist.

Fehler, die in Verbindung 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 die Funktion erfolgreich ist. Die Ereignisverarbeitung wird in der targetThread fortgesetzt.

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

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

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch QObject::moveToThread() und 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)

Dies ist eine überladene Funktion.

Öffnet die Datenbankverbindung mit dem angegebenen user Namen und password. Gibt bei Erfolg true zurück, andernfalls false. Fehlerinformationen können mit der Funktion lastError() abgefragt werden.

Diese Funktion speichert das ihr übergebene Passwort nicht. Stattdessen wird das Kennwort direkt an den Treiber zum Öffnen der Verbindung übergeben und dann verworfen.

Siehe auch lastError().

QString QSqlDatabase::password() const

Gibt das Kennwort der Verbindung zurück. Es wird eine leere Zeichenkette zurückgegeben, wenn das Kennwort nicht mit setPassword() festgelegt wurde, wenn das Kennwort beim Aufruf von open() angegeben wurde oder wenn kein Kennwort 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 für die Tabelle tablename zurück. Wenn kein Primärindex existiert, wird ein leeres QSqlIndex zurückgegeben.

Siehe auch tables() und record().

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

Gibt eine QSqlRecord zurück, die mit den Namen aller Felder in der Tabelle (oder Ansicht) namens tablename gefüllt ist. Die Reihenfolge, in der die Felder im Datensatz erscheinen, ist undefiniert. 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 innerhalb des SQL-Frameworks. Dies ist nützlich, wenn Sie einen eigenen SQL-Treiber haben und diesen nicht als Plugin kompilieren wollen.

Beispiel:

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

QSqlDatabase übernimmt den Besitz des Zeigers creator, so dass Sie ihn nicht selbst löschen dürfen.

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

Der korrekte Weg, dies zu tun:

{
    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 mit einem Aufruf von addDatabase() ohne Angabe eines Verbindungsnamens erstellt wurde, können Sie den Standardverbindungsnamen abrufen, indem Sie connectionName() für die von database() zurückgegebene Datenbank aufrufen. Beachten Sie, dass eine ungültige Datenbank zurückgegeben wird, wenn keine Standarddatenbank erstellt wurde.

Hinweis: Diese Funktion ist thread-sicher.

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

bool QSqlDatabase::rollback()

Führt eine Transaktion in der Datenbank zurück, wenn der Treiber Transaktionen unterstützt und eine transaction() gestartet wurde. Gibt true zurück, wenn der Vorgang erfolgreich war. Andernfalls gibt es false zurück.

Rufen Sie lastError() auf, um Informationen über Fehler zu erhalten.

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

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

Setzt datenbankspezifische options. Dies muss geschehen, bevor die Verbindung geöffnet wird, sonst hat es keine Wirkung. Eine andere Möglichkeit ist, die Verbindung zu schließen, QSqlDatabase::setConnectOptions() aufzurufen und open() die Verbindung erneut zu öffnen.

Das Format des Strings options ist eine durch Semikolon getrennte Liste von Optionsnamen oder Option=Wert-Paaren. 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 finden Sie in der Dokumentation der Client-Bibliothek.

Siehe auch connectOptions().

void QSqlDatabase::setDatabaseName(const QString &name)

Setzt den Datenbanknamen der Verbindung auf name. Um Wirkung zu zeigen, muss der Datenbankname gesetzt werden , bevor die Verbindung opened aufgerufen wird. Alternativ dazu können Sie close() die Verbindung herstellen, den Datenbanknamen setzen und open() erneut aufrufen.

Wenn der angegebene Datenbankname nicht existiert, wird der QSQLITE-Treiber die Datei für Sie erstellen, es sei denn, die Option QSQLITE_OPEN_READONLY ist gesetzt.

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

Für den QOCI (Oracle)-Treiber ist der Datenbankname der TNS-Dienstname.

Für den QODBC-Treiber kann name entweder ein DSN, ein DSN-Dateiname (in diesem Fall muss die Datei die Erweiterung .dsn haben) oder ein Verbindungsstring sein.

Microsoft Access-Benutzer können beispielsweise die folgende Verbindungszeichenfolge verwenden, um eine .mdb -Datei direkt zu öffnen, ohne 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. Um Wirkung zu zeigen, muss der Hostname gesetzt werden , bevor die Verbindung opened aufgerufen wird. Alternativ dazu können Sie close() die Verbindung herstellen, den Hostnamen setzen und open() erneut 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)

Setzt das Kennwort der Verbindung auf password. Um wirksam zu sein, muss das Kennwort gesetzt werden , bevor die Verbindung opened aufgerufen wird. Alternativ können Sie close() die Verbindung herstellen, das Kennwort festlegen und open() erneut 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. Um wirksam zu sein, muss die Portnummer gesetzt werden , bevor die Verbindung opened aufgerufen wird. Alternativ können Sie close() die Verbindung herstellen, die Anschlussnummer festlegen und open() erneut aufrufen.

Es gibt keinen Standardwert.

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

void QSqlDatabase::setUserName(const QString &name)

Setzt den Benutzernamen der Verbindung auf name. Um wirksam zu sein, muss der Benutzername gesetzt werden , bevor die Verbindung opened aufgerufen wird. Alternativ dazu können Sie close() die Verbindung herstellen, den Benutzernamen setzen und open() erneut 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 Datenbanktabellen, Systemtabellen und Views 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()

Beginnt eine Transaktion in der Datenbank, wenn der Treiber Transaktionen unterstützt. Gibt true zurück, wenn der Vorgang erfolgreich war. Andernfalls gibt es false zurück.

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

QString QSqlDatabase::userName() const

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

Siehe auch setUserName().

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

Weist diesem Objekt other zu.