QSqlDatabase 类

成员函数文档

QSqlDatabase::QSqlDatabase()

创建一个空的、无效的QSqlDatabase对象。使用addDatabase()、removeDatabase()和database()函数来获取有效的QSqlDatabase对象。

[显式受保护] QSqlDatabase::QSqlDatabase(const QString &type)

这是一个重载函数。

创建一个使用由type指定的驱动程序的QSqlDatabase连接。如果无法识别type，数据库连接将没有任何功能。

当前可用的驱动程序类型有

可以加载额外的第三方驱动程序，包括您自己的自定义驱动程序。

也请参阅 SQL数据库驱动程序、registerSqlDriver()和drivers()。

[显式受保护] QSqlDatabase::QSqlDatabase(QSqlDriver *driver)

这是一个重载函数。

使用给定的driver创建数据库连接。

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，则使用数据库(connectionName) 以检索连接。

在使用连接之前，必须对其进行初始化。例如，调用其中一些或全部 setDatabaseName()、setUserName()、setPassword()、setHostName()、setPort() 和 setConnectOptions()，最后，调用 open().

注意：此函数是 线程安全。

另请参阅：database()、removeDatabase() 和 线程和 SQL 模块。

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

此重载在您想使用您自己实例化的 driver 创建数据库连接时很有用。这可能是指您的自定义数据库驱动程序，或者您可能只需自己实例化一个 Qt 驱动程序。如果是这样，我们建议您将驱动程序代码包含在您的应用程序中。例如，您可以使用以下方式创建一个 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中包含的驱动程序、它们的源代码文件及其构造函数参数的表格。

另请参阅：驱动程序。

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

复制数据库连接other并存储为connectionName。所有原始数据库的设置，例如databaseName()、hostName()等，都将复制过来。如果other是无效数据库，则不执行任何操作。返回新创建的数据库连接。

注意：此函数是可重入的。

[静态] 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() 和 回滚。

QString QSqlDatabase::connectOptions() const

返回为此连接使用的连接选项字符串。字符串可能为空。

另请参阅 setConnectOptions。

QString QSqlDatabase::connectionName() const

返回连接名，可能为空。

另请参阅 addDatabase。

[静态] QStringList QSqlDatabase::connectionNames()

返回包含所有连接名称的列表。

注意：此函数是 线程安全。

另请参阅 contains，database 和 线程和SQL模块。

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

如果数据库连接列表包含connectionName，则返回true；否则返回false。

注意：此函数是 线程安全。

另请参阅 connectionNames，database 和 线程和SQL模块。

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

返回名为 connectionName 的数据库连接。数据库连接必须已通过 addDatabase() 添加。如果 open 为 true（默认值）且数据库连接尚未打开，则现在打开。如果没有指定 connectionName，则使用默认连接。如果connectionName 不存在于数据库列表中，则返回无效的连接。

注意：此函数是 线程安全。

另请参阅 isOpen() 和 线程和SQL模块。

QString QSqlDatabase::databaseName() const

返回连接的数据库名称，可能为空。

另请参阅 setDatabaseName。

QSqlDriver *QSqlDatabase::driver() const

返回用于访问数据库连接的数据库驱动。

另请参阅 addDatabase 和 drivers。

QString QSqlDatabase::driverName() const

返回连接的驱动名称。

另请参阅 addDatabase() 和 driver().

[静态] QStringList QSqlDatabase::drivers()

返回所有可用数据库驱动程序列表。

另请参阅 registerSqlDriver().

QString QSqlDatabase::hostName() const

返回连接的计算机名；可能为空。

另请参阅 setHostName().

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

如果有一个名为name的驱动程序可用，则返回true；否则返回false。

另请参阅：驱动程序。

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。

QSql::NumericalPrecisionPolicy QSqlDatabase::numericalPrecisionPolicy() const

返回当前数据库连接的默认精度策略。

另请参阅 QSql::NumericalPrecisionPolicy、setNumericalPrecisionPolicy、QSqlQuery::numericalPrecisionPolicy 和 QSqlQuery::setNumericalPrecisionPolicy。

bool QSqlDatabase::open()

使用当前连接值打开数据库连接。成功时返回true；否则返回false。可以通过lastError检索错误信息。

另请参阅 lastError、setDatabaseName、setUserName、setPassword、setHostName、setPort 和 setConnectOptions。

bool QSqlDatabase::open(const QString &user, const QString &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

返回一个QSqlRecord，其中包含调用tablename的表（或视图）中所有字段的名字。字段在记录中出现的顺序是未定义的。如果不存在此类表（或视图），则返回一个空记录。

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

此函数在SQL框架内注册一个名为name的新SQL驱动程序。如果你有一个自定义SQL驱动程序且不想将其作为插件编译，这将很有用。

示例

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

QSqlDatabase将获取creator指针的所有权，因此你不得自行删除它。

另请参阅：驱动程序。

[静态] 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()函数创建，可以通过调用数据库返回对象的connectionName()函数获取默认连接名。注意，如果没有创建默认数据库，将会返回一个无效的数据库。

注意：此函数是 线程安全。

另请参阅database()，connectionName()，以及线程和SQL模块。

bool QSqlDatabase::rollback()

如果数据库驱动支持事务且已经启动了一个transaction()，则回滚数据库上的事务。如果操作成功返回true，否则返回false。

调用lastError () 来获取有关错误的信息。

另请参阅QSqlQuery::isActive，QSqlDriver::hasFeature，以及commit。

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

设置特定于数据库的选项。必须在打开连接之前完成此操作，否则将不起作用。另一种可能是关闭连接，调用QSqlDatabase::setConnectOptions()，然后再打开连接。

选项字符串的格式是用分号分隔的选项名称或option=value对的列表。这些选项依赖于使用的数据库客户端，并在SQL数据库驱动程序页面中为每个插件进行了说明。

示例

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。为了生效，数据库名称必须在打开连接之前设置。另一种可能性是关闭连接，设置数据库名称，然后再次打开连接。

对于QSQLITE驱动程序，如果指定的数据库名称不存在，则除非设置了QSQLITE_OPEN_READONLY选项，否则将为您创建文件。

此外，name还可以设置为":memory:"，这将创建一个仅在应用程序生存期内的临时数据库。

对于QOCI（Oracle）驱动程序，数据库名称是TNS服务名称。

对于QODBC驱动程序，name可以是DSN，DSN文件名（在这种情况下，文件必须具有.dsn扩展名），或连接字符串。

例如，Microsoft Access用户可以使用以下连接字符串直接打开具有.mdb扩展名的文件，而不是在ODBC管理器中创建DSN条目

// ...
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。要生效，必须在连接之前设置主机名。或者，您可以先 关闭() 连接，设置主机名，然后再调用 open()。

没有默认值。

另请参阅 hostName()、setUserName()、setPassword()、setDatabaseName()、setPort()、setConnectOptions() 以及 open()。

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

将在此数据库连接上创建的查询使用的默认数值精度策略设置为 precisionPolicy。

注意：不支持以低精度获取数值的驱动程序将忽略精度策略。您可以使用 QSqlDriver::hasFeature() 来查找是否支持此功能。

注意：将默认精度策略设置为 precisionPolicy 不会影响当前任何活动查询。

另请参阅 QSql::NumericalPrecisionPolicy、numericalPrecisionPolicy()、QSqlQuery::setNumericalPrecisionPolicy() 以及 QSqlQuery::numericalPrecisionPolicy()。

void QSqlDatabase::setPassword(const QString &password)

将连接的密码设置为 password。要生效，必须在连接之前设置密码。或者，您可以先 关闭() 连接，设置密码，然后再调用 open()。

没有默认值。

另请参阅 password()、setUserName()、setDatabaseName()、setHostName()、setPort()、setConnectOptions() 以及 open()。

void QSqlDatabase::setPort(int port)

将连接的端口号设置为 port。要生效，必须在连接之前设置端口号。或者，您可以先 关闭() 连接，设置端口号，然后再调用 open()。

没有默认值。

另请参阅 端口()，setUserName()，setPassword()，setHostName()，setDatabaseName()，setConnectOptions()，和 open()。

void QSqlDatabase::setUserName(const QString &name)

将连接的用户名设置为name。要生效，用户名必须在连接打开之前设置。或者，您可以关闭()连接，设置用户名，然后再次调用open()。

没有默认值。

另请参阅 userName()，setDatabaseName()，setPassword()，setHostName()，setPort()，setConnectOptions()，和 open()。

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

返回数据库中的表、系统表和视图列表，具体取决于参数type。

另请参阅 primaryIndex() 和 record()。

bool QSqlDatabase::transaction()

如果驱动程序支持事务，则在数据库上开始一个事务。如果操作成功，返回true。否则返回false。

另请参阅 QSqlDriver::hasFeature()，commit()，和 rollback()。

QString QSqlDatabase::userName() const

返回连接的用户名；它可能为空。

另请参阅 setUserName。

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

将other赋给此对象。