QSqlDatabase Class

Documentation des fonctions membres

QSqlDatabase::QSqlDatabase()

Crée un objet QSqlDatabase vide et non valide. Utilisez les méthodes addDatabase(), removeDatabase() et database() pour obtenir des objets QSqlDatabase valides.

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

Crée une connexion à la base de données à l'aide de l'driver fournie.

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

Crée une connexion QSqlDatabase utilisant le pilote spécifié par ` type`. Si ` type ` n'est pas reconnu, la connexion à la base de données ne fonctionnera pas.

Les types de pilotes actuellement disponibles sont les suivants :

D'autres pilotes tiers, y compris vos propres pilotes personnalisés, peuvent être chargés dynamiquement.

Voir également Pilotes de bases de données SQL, registerSqlDriver() et drivers().

QSqlDatabase::QSqlDatabase(const QSqlDatabase &other)

Crée une copie de other.

[noexcept] QSqlDatabase::~QSqlDatabase()

Détruit l'objet et libère toutes les ressources allouées.

Voir aussi close().

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

Ajoute une base de données à la liste des connexions à la base de données à l'aide du pilote type et du nom de connexion connectionName. Si une connexion à la base de données nommée connectionName existe déjà, celle-ci est supprimée.

La connexion à la base de données est désignée par connectionName. La connexion à la base de données nouvellement ajoutée est renvoyée.

Si type n'est pas disponible ou n'a pas pu être chargé, isValid() renvoie false.

Si connectionName n’est pas spécifié, la nouvelle connexion devient la connexion par défaut de l’application, et les appels suivants à database() sans l’argument du nom de connexion renverront la connexion par défaut. Si un connectionName est fourni ici, utilisez database(connectionName) pour récupérer la connexion.

Avant d’utiliser la connexion, celle-ci doit être initialisée. Par exemple, appelez tout ou partie des fonctions suivantes : setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() et setConnectOptions(), puis enfin open().

Remarque : cette fonction est sûre pour les threads.

Voir également database(), removeDatabase() et « Threads et le module SQL ».

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

Cette surcharge est utile lorsque vous souhaitez établir une connexion à une base de données à l'aide d'un objet ` driver ` que vous avez instancié vous-même. Il peut s'agir de votre propre pilote de base de données, ou vous pouvez simplement avoir besoin d'instancier vous-même l'un des pilotes Qt. Si vous procédez ainsi, il est recommandé d'intégrer le code du pilote dans votre application. Par exemple, vous pouvez créer une connexion PostgreSQL avec votre propre pilote QPSQL de la manière suivante :

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

Le code ci-dessus établit une connexion PostgreSQL et instancie un objet QPSQLDriver. Ensuite, la fonction addDatabase() est appelée pour ajouter la connexion à la liste des connexions connues, afin qu’elle puisse être utilisée par les classes Qt SQL. Lorsqu’un pilote est instancié avec un descripteur de connexion (ou un ensemble de descripteurs), Qt part du principe que vous avez déjà ouvert la connexion à la base de données.

N’oubliez pas que vous devez lier votre application à la bibliothèque cliente de la base de données. Assurez-vous que la bibliothèque cliente se trouve dans le chemin de recherche de votre éditeur de liens, et ajoutez des lignes comme celles-ci à votre fichier .pro:

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

La méthode décrite fonctionne pour tous les pilotes fournis. La seule différence réside dans les arguments du constructeur du pilote. Voici un tableau répertoriant les pilotes inclus avec Qt, leurs fichiers de code source et leurs arguments de constructeur :

Voir également drivers().

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

Clone la connexion à la base de données other et l'enregistre sous le nom connectionName. Tous les paramètres de la base de données d'origine, par exemple databaseName(), hostName(), etc., sont copiés. Ne fait rien si other correspond à une base de données non valide. Renvoie la connexion à la base de données nouvellement créée.

Remarque : cette fonction est réentrante.

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

Clone la connexion à la base de données other et l'enregistre sous le nom connectionName. Tous les paramètres de la base de données d'origine, par exemple databaseName(), hostName(), etc., sont copiés. Ne fait rien si other correspond à une base de données non valide. Renvoie la connexion à la base de données nouvellement créée.

Cette surcharge est utile lors du clonage de la base de données dans un autre thread que celui utilisé par la base de données représentée par other.

void QSqlDatabase::close()

Ferme la connexion à la base de données, libère toutes les ressources acquises et invalide tous les objets ` QSqlQuery ` existants utilisés avec la base de données.

Cela affectera également les copies de cet objet ` QSqlDatabase `.

Voir aussi removeDatabase().

bool QSqlDatabase::commit()

Valide une transaction dans la base de données si le pilote prend en charge les transactions et si une opération de validation ( transaction()) a été lancée. Renvoie « true » si l'opération a réussi. Sinon, elle renvoie « false ».

Appelez ` lastError()` pour obtenir des informations sur les erreurs.

Voir également QSqlQuery::isActive(), QSqlDriver::hasFeature() et rollback().

QString QSqlDatabase::connectOptions() const

Renvoie la chaîne de caractères contenant les options de connexion utilisées pour cette connexion. La chaîne peut être vide.

Voir aussi setConnectOptions().

QString QSqlDatabase::connectionName() const

Renvoie le nom de la connexion, qui peut être vide.

Voir aussi addDatabase().

[static] QStringList QSqlDatabase::connectionNames()

Renvoie une liste contenant les noms de toutes les connexions.

Remarque : cette fonction est sûre pour les threads.

Voir également contains(), database() et « Les threads et le module SQL ».

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

Renvoie ` true ` si la liste des connexions à la base de données contient ` connectionName` ; sinon, renvoie ` false`.

Remarque : cette fonction est sûre pour les threads.

Voir aussi connectionNames(), database() et « Les threads et le module SQL ».

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

Renvoie la connexion à la base de données appelée « connectionName ». La connexion à la base de données doit avoir été préalablement ajoutée à l’aide de la fonction addDatabase(). Si la valeur de « open » est « true » (valeur par défaut) et que la connexion à la base de données n’est pas encore ouverte, celle-ci est alors ouverte. Si aucune valeur n’est spécifiée pour « connectionName », la connexion par défaut est utilisée. Si « connectionName » n’existe pas dans la liste des bases de données, une connexion non valide est renvoyée.

Remarque : cette fonction est thread-safe.

Voir aussi isOpen() et « Threads et le module SQL ».

QString QSqlDatabase::databaseName() const

Renvoie le nom de la base de données de la connexion ; ce nom peut être vide.

Voir aussi setDatabaseName().

QSqlDriver *QSqlDatabase::driver() const

Renvoie le pilote de base de données utilisé pour accéder à la connexion à la base de données.

Voir également addDatabase() et drivers().

QString QSqlDatabase::driverName() const

Renvoie le nom du pilote de la connexion.

Voir également addDatabase() et driver().

[static] QStringList QSqlDatabase::drivers()

Renvoie une liste de tous les pilotes de base de données disponibles.

Voir aussi registerSqlDriver().

QString QSqlDatabase::hostName() const

Renvoie le nom d'hôte de la connexion ; il peut être vide.

Voir aussi setHostName().

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

Renvoie ` true ` si un pilote nommé ` name ` est disponible ; sinon, renvoie ` false`.

Voir également drivers().

bool QSqlDatabase::isOpen() const

Renvoie « true » si la connexion à la base de données est actuellement ouverte ; sinon, renvoie « false ».

bool QSqlDatabase::isOpenError() const

Renvoie « true » si une erreur s'est produite lors de l'ouverture de la connexion à la base de données ; sinon, renvoie « false ». Les informations relatives à l'erreur peuvent être récupérées à l'aide de la fonction « lastError() ».

bool QSqlDatabase::isValid() const

Renvoie « true » si l'QSqlDatabase dispose d'un pilote valide.

Exemple :

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

Renvoie des informations sur la dernière erreur survenue dans la base de données.

Les échecs liés à une requête spécifique sont signalés par la fonction QSqlQuery::lastError().

Voir également QSqlError et QSqlQuery::lastError().

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

Modifie l'affinité de thread pour QSqlDatabase et son pilote associé. Cette fonction renvoie true en cas de réussite. Le traitement des événements se poursuivra dans targetThread.

Au cours de cette opération, vous devez vous assurer qu’aucun QSqlQuery n’est lié à cette instance, sinon l’ QSqlDatabase ne sera pas déplacé vers le thread spécifié et la fonction renverra false.

Étant donné que le pilote associé est dérivé de ` QObject`, toutes les contraintes relatives au déplacement d’un ` QObject ` vers un autre thread s’appliquent également à cette fonction.

Cette fonction a été introduite dans Qt 6.8.

Voir également ` QObject::moveToThread()` et « Threads et le module SQL ».

QSql::NumericalPrecisionPolicy QSqlDatabase::numericalPrecisionPolicy() const

Renvoie la propriété `numericalPrecisionPolicy`.

Voir aussi setNumericalPrecisionPolicy().

bool QSqlDatabase::open()

Ouvre la connexion à la base de données en utilisant les paramètres de connexion actuels. Renvoie « true » en cas de succès ; sinon, renvoie « false ». Les informations relatives à l'erreur peuvent être récupérées à l'aide de la fonction « lastError() ».

Voir également lastError(), setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() et setConnectOptions().

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

Ouvre la connexion à la base de données en utilisant le nom d'user et l'password fournis. Renvoie true en cas de succès ; sinon, renvoie false. Les informations d'erreur peuvent être récupérées à l'aide de la fonction lastError().

Cette fonction ne stocke pas le mot de passe qui lui est fourni. Au lieu de cela, le mot de passe est transmis directement au pilote pour l'ouverture de la connexion, puis il est ignoré.

Voir également lastError().

QString QSqlDatabase::password() const

Renvoie le mot de passe de la connexion. Une chaîne vide sera renvoyée si le mot de passe n’a pas été défini avec la fonction setPassword(), si le mot de passe a été fourni lors de l’appel à la fonction open() ou si aucun mot de passe n’a été utilisé.

Voir également setPassword().

int QSqlDatabase::port() const

Renvoie le numéro de port de la connexion. La valeur est indéfinie si le numéro de port n'a pas été défini.

Voir aussi setPort().

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

Renvoie l'index primaire de la table tablename. Si aucun index primaire n'existe, une valeur vide QSqlIndex est renvoyée.

Voir également tables() et record().

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

Renvoie un objet ` QSqlRecord ` contenant les noms de tous les champs de la table (ou vue) nommée ` tablename`. L'ordre d'apparition des champs dans l'enregistrement n'est pas défini. Si aucune table (ou vue) de ce nom n'existe, un enregistrement vide est renvoyé.

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

Cette fonction enregistre un nouveau pilote SQL appelé « name » au sein du framework SQL. Cela s'avère utile si vous disposez d'un pilote SQL personnalisé et que vous ne souhaitez pas le compiler en tant que plugin.

Exemple :

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

QSqlDatabase prend en charge le pointeur creator; vous ne devez donc pas le supprimer vous-même.

Voir également drivers().

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

Supprime la connexion à la base de données connectionName de la liste des connexions à la base de données.

Exemple :

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

La bonne façon de procéder :

{
    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

Pour supprimer la connexion par défaut, qui a pu être créée à l’aide d’un appel à ` addDatabase()` sans spécifier de nom de connexion, vous pouvez récupérer le nom de la connexion par défaut en appelant ` connectionName()` sur la base de données renvoyée par ` database()`. Notez que si aucune base de données par défaut n’a été créée, une base de données invalide sera renvoyée.

Remarque : cette fonction est thread-safe.

Voir également database(), connectionName() et « Threads et le module SQL ».

bool QSqlDatabase::rollback()

Annule une transaction dans la base de données, à condition que le pilote prenne en charge les transactions et qu’une opération de type ` transaction()` ait été lancée. Renvoie ` true ` si l’opération a réussi. Sinon, elle renvoie ` false`.

Appelez ` lastError()` pour obtenir des informations sur les erreurs.

Voir également QSqlQuery::isActive(), QSqlDriver::hasFeature() et commit().

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

Définit les options de connexion spécifiques à la base de données ( options). Cette opération doit être effectuée avant l'ouverture de la connexion, sinon elle n'aura aucun effet. Une autre possibilité consiste à fermer la connexion, à appeler QSqlDatabase::setConnectOptions(), puis à ouvrir à nouveau la connexion à l'aide de open().

Le format de la chaîne d'options s est une liste, séparée par des points-virgules, de noms d'options ou de paires option=valeur. Les options dépendent du client de base de données utilisé et sont décrites pour chaque plugin sur la page Pilotes de bases de données SQL.

Exemples :

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

Reportez-vous à la documentation de la bibliothèque cliente pour plus d’informations sur les différentes options.

Voir également ` connectOptions()`.

void QSqlDatabase::setDatabaseName(const QString &name)

Définit le nom de la base de données de la connexion sur « name ». Pour que cette modification prenne effet, le nom de la base de données doit être défini avant que la connexion ne soit établie via ` opened`. Vous pouvez également créer la connexion via ` close()`, définir le nom de la base de données, puis appeler à nouveau ` open()`.

Pour le pilote QSQLITE, si le nom de base de données spécifié n’existe pas, le fichier sera créé automatiquement, sauf si l’option QSQLITE_OPEN_READONLY est activée.

De plus, la fonction ` name ` peut être définie sur ` ":memory:" `, ce qui créera une base de données temporaire qui ne sera disponible que pendant la durée de vie de l’application.

Pour le pilote QOCI (Oracle), le nom de la base de données correspond au nom de service TNS.

Pour le pilote QODBC, l’ name peut être soit un DSN, soit un nom de fichier DSN (auquel cas le fichier doit porter l’extension .dsn ), soit une chaîne de connexion.

Par exemple, les utilisateurs de Microsoft Access peuvent utiliser la chaîne de connexion suivante pour ouvrir directement un fichier d’ .mdb, au lieu de devoir créer une entrée DSN dans le gestionnaire ODBC :

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

Il n'y a pas de valeur par défaut.

Voir également databaseName(), setUserName(), setPassword(), setHostName(), setPort(), setConnectOptions() et open().

void QSqlDatabase::setHostName(const QString &host)

Définit le nom d'hôte de la connexion sur host. Pour que cette modification prenne effet, le nom d'hôte doit être défini avant l'opened de la connexion. Vous pouvez également utiliser la fonction close() pour obtenir la connexion, définir le nom d'hôte, puis appeler à nouveau la fonction open().

Il n’y a pas de valeur par défaut.

Voir également hostName(), setUserName(), setPassword(), setDatabaseName(), setPort(), setConnectOptions() et open().

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

Définit la propriété « numericalPrecisionPolicy » sur « precisionPolicy ».

Voir également numericalPrecisionPolicy().

void QSqlDatabase::setPassword(const QString &password)

Définit le mot de passe de la connexion sur password. Pour que cette modification prenne effet, le mot de passe doit être défini avant que la connexion ne soit établie via opened. Vous pouvez également fermer la connexion à l'aide de la fonction close(), définir le mot de passe, puis appeler à nouveau la fonction open().

Il n'y a pas de valeur par défaut.

Voir également : password(), setUserName(), setDatabaseName(), setHostName(), setPort(), setConnectOptions() et open().

void QSqlDatabase::setPort(int port)

Définit le numéro de port de la connexion sur port. Pour que cette modification prenne effet, le numéro de port doit être défini avant l'opened. Vous pouvez également utiliser la fonction close() sur la connexion, définir le numéro de port, puis appeler à nouveau la fonction open().

Il n’y a pas de valeur par défaut.

Voir également port(), setUserName(), setPassword(), setHostName(), setDatabaseName(), setConnectOptions() et open().

void QSqlDatabase::setUserName(const QString &name)

Définit le nom d'utilisateur de la connexion sur name. Pour que cette modification prenne effet, le nom d'utilisateur doit être défini avant l'établissement de la connexion opened. Vous pouvez également appeler la fonction close() sur la connexion, définir le nom d'utilisateur, puis appeler à nouveau la fonction open().

Il n’y a pas de valeur par défaut.

Voir également userName(), setDatabaseName(), setPassword(), setHostName(), setPort(), setConnectOptions() et open().

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

Renvoie une liste des tables, tables système et vues de la base de données, telles que spécifiées par le paramètre type.

Voir également primaryIndex() et record().

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

Renvoie un pointeur vers l'instance associée de ` QThread `.

Cette fonction a été introduite dans Qt 6.8.

bool QSqlDatabase::transaction()

Lance une transaction dans la base de données si le pilote prend en charge les transactions. Renvoie « true » si l'opération a réussi. Sinon, elle renvoie « false ».

Voir également QSqlDriver::hasFeature(), commit() et rollback().

QString QSqlDatabase::userName() const

Renvoie le nom d'utilisateur de la connexion ; il peut être vide.

Voir aussi setUserName().

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

Attribue la valeur « other » à cet objet.