QSqlDatabase Class

Documentation sur les fonctions membres

QSqlDatabase::QSqlDatabase()

Crée un objet QSqlDatabase vide et non valide. Utilisez 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'adresse driver.

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

Crée une connexion QSqlDatabase qui utilise le pilote référencé par type. Si le site 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 aussi 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 les ressources allouées.

Voir également close().

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

Ajoute une base de données à la liste des connexions de base de données utilisant le pilote type et le nom de connexion connectionName. S'il existe déjà une connexion de base de données appelée connectionName, cette connexion 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 ultérieurs à database() sans l'argument du nom de la 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, il faut l'initialiser, par exemple en appelant tout ou partie de setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort(), setConnectOptions() et, enfin, open().

Remarque : cette fonction est à l'épreuve des threads.

Voir aussi database(), removeDatabase(), et Threads and the SQL Module.

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

Cette surcharge est utile lorsque vous souhaitez créer une connexion à une base de données avec une adresse driver que vous avez instanciée vous-même. Il peut s'agir de votre propre pilote de base de données, ou vous pouvez simplement avoir besoin d'instancier l'un des pilotes Qt vous-même. Dans ce cas, il est recommandé d'inclure le code du pilote dans votre application. Par exemple, vous pouvez créer une connexion PostgreSQL avec votre propre pilote QPSQL comme suit :

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, addDatabase() est appelée pour ajouter la connexion aux connexions connues afin qu'elle puisse être utilisée par les classes Qt SQL. Lorsqu'un pilote est instancié avec une poignée de connexion (ou un ensemble de poignées), Qt suppose 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 client de la base de données. Assurez-vous que la bibliothèque client 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 des pilotes fournis avec Qt, leurs fichiers de code source et les arguments de leur constructeur :

Voir aussi drivers().

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

Clone la connexion à la base de données other et la stocke sous 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 est une base de données invalide. 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 la stocke sous 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 est une base de données invalide. Renvoie la connexion à la base de données nouvellement créée.

Cette surcharge est utile pour cloner la base de données dans un autre thread à celui qui est 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 utilisés avec la base de données.

Cela affectera également les copies de cet objet QSqlDatabase.

Voir également removeDatabase().

bool QSqlDatabase::commit()

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

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

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

QString QSqlDatabase::connectOptions() const

Renvoie la chaîne d'options de connexion utilisée 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 à l'épreuve des threads.

Voir aussi contains(), database(), et 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 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é ajoutée au préalable avec addDatabase(). Si open est vrai (par défaut) et que la connexion à la base de données n'est pas déjà ouverte, elle l'est maintenant. Si aucun connectionName n'est spécifié, 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 à l'épreuve des threads.

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, qui 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 aussi addDatabase() et drivers().

QString QSqlDatabase::driverName() const

Renvoie le nom du pilote de la connexion.

Voir aussi 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 appelé name est disponible ; sinon, renvoie false.

Voir aussi 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 s'il y a eu une erreur lors de l'ouverture de la connexion à la base de données ; sinon, renvoie false. Les informations sur les erreurs peuvent être récupérées à l'aide de la fonction lastError().

bool QSqlDatabase::isValid() const

Renvoie true si le pilote de QSqlDatabase est valide.

Exemple :

QSqlDatabase db ;qDebug() << db.isValid();    // Returns false

db = QSqlDatabase::base de données("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 survenus lors d'une requête individuelle sont signalés par QSqlQuery::lastError().

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

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

Modifie l'affinité des threads pour QSqlDatabase et son pilote associé. Cette fonction renvoie true en cas de succès. Le traitement des événements se poursuivra dans l'instance targetThread.

Pendant cette opération, vous devez vous assurer qu'il n'y a pas de QSqlQuery lié à cette instance, sinon le QSqlDatabase ne sera pas déplacé vers le thread donné et la fonction renverra false.

Étant donné que le pilote associé est dérivé de QObject, toutes les contraintes liées 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 aussi QObject::moveToThread() et Threads et le module SQL.

QSql::NumericalPrecisionPolicy QSqlDatabase::numericalPrecisionPolicy() const

Renvoie la politique de précision numérique.

Voir également setNumericalPrecisionPolicy().

bool QSqlDatabase::open()

Ouvre la connexion à la base de données en utilisant les valeurs de connexion actuelles. Renvoie true en cas de succès ; sinon, renvoie false. Les informations sur les erreurs peuvent être récupérées à l'aide de lastError().

Voir aussi 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 user et password. Renvoie true en cas de succès, sinon false. Les informations relatives aux erreurs peuvent être récupérées à l'aide de la fonction lastError().

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

Voir aussi 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 setPassword(), et si le mot de passe a été donné dans l'appel open(), ou si aucun mot de passe n'a été utilisé.

Voir aussi 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. S'il n'existe pas d'index primaire, une adresse QSqlIndex vide est renvoyée.

Voir aussi tables() et record().

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

Renvoie une adresse QSqlRecord contenant les noms de tous les champs de la table (ou de la vue) appelée tablename. L'ordre dans lequel les champs apparaissent dans l'enregistrement n'est pas défini. Si une telle table (ou vue) n'existe pas, un enregistrement vide est renvoyé.

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

Cette fonction enregistre un nouveau pilote SQL appelé name, dans le cadre SQL. Ceci est utile si vous avez un pilote SQL personnalisé et que vous ne voulez 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 possession du pointeur creator, vous ne devez donc pas l'effacer vous-même.

Voir aussi 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 peut avoir été créée par 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 une base de données par défaut n'a pas été créée, une base de données invalide sera renvoyée.

Remarque : cette fonction est à l'épreuve des threads.

Voir aussi database(), connectionName(), et Threads et le module SQL.

bool QSqlDatabase::rollback()

Reprend une transaction sur la base de données, si le pilote supporte les transactions et qu'un transaction() a été lancé. Renvoie true si l'opération a réussi. Dans le cas contraire, il renvoie false.

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

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

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

Définit les paramètres spécifiques à la base de données options. Cette opération doit être effectuée avant l'ouverture de la connexion, sinon elle n'a aucun effet. Une autre possibilité est de fermer la connexion, d'appeler QSqlDatabase::setConnectOptions(), et open() la connexion à nouveau.

Le format de la chaîne options est une liste de noms d'options ou de paires option=valeur séparées par des points-virgules. Les options dépendent du client de base de données utilisé et sont décrites pour chaque plugin dans la page Pilotes de base 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 du client pour plus d'informations sur les différentes options.

Voir aussi connectOptions().

void QSqlDatabase::setDatabaseName(const QString &name)

Définit le nom de la base de données de la connexion à name. Pour que cela soit effectif, le nom de la base de données doit être défini avant que la connexion ne soit établie à opened. Vous pouvez également appeler close() pour établir la connexion, définir le nom de la base de données et appeler à nouveau open().

Pour le pilote QSQLITE, si le nom de la base de données spécifié n'existe pas, il créera le fichier pour vous à moins que l'option QSQLITE_OPEN_READONLY ne soit définie.

En outre, l'option name peut être définie à ":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 est le nom du service TNS.

Pour le pilote QODBC, name peut être soit un DSN, soit un nom de fichier DSN (dans ce cas, le fichier doit avoir une 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 un fichier .mdb directement, 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 aussi databaseName(), setUserName(), setPassword(), setHostName(), setPort(), setConnectOptions() et open().

void QSqlDatabase::setHostName(const QString &host)

Définit le nom d'hôte de la connexion à host. Pour que cela soit effectif, le nom d'hôte doit être défini avant que la connexion ne soit opened. Vous pouvez également appeler close() pour établir la connexion, définir le nom d'hôte et appeler à nouveau 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)

Remplace numericalPrecisionPolicy par precisionPolicy.

Voir aussi numericalPrecisionPolicy().

void QSqlDatabase::setPassword(const QString &password)

Définit le mot de passe de la connexion à password. Pour être effectif, le mot de passe doit être défini avant que la connexion ne soit opened. Sinon, vous pouvez close() la connexion, définir le mot de passe et rappeler open().

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

Voir aussi password(), setUserName(), setDatabaseName(), setHostName(), setPort(), setConnectOptions() et open().

void QSqlDatabase::setPort(int port)

Définit le numéro de port de la connexion à port. Pour que cela soit effectif, le numéro de port doit être défini avant que la connexion ne soit établie à opened. Sinon, vous pouvez close() la connexion, définir le numéro de port et appeler à nouveau 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 à name. Pour que cela soit effectif, le nom d'utilisateur doit être défini avant que la connexion ne soit opened. Sinon, vous pouvez close() la connexion, définir le nom d'utilisateur et appeler à nouveau open().

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

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

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

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

Voir aussi primaryIndex() et record().

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

Renvoie un pointeur sur l'instance QThread associée.

Cette fonction a été introduite dans Qt 6.8.

bool QSqlDatabase::transaction()

Commence une transaction sur la base de données si le pilote prend en charge les transactions. Il renvoie true si l'opération a réussi. Sinon, il 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 other à cet objet.