QSqlDatabase Class

成员函数文档

QSqlDatabase::QSqlDatabase()

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

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

这是一个重载函数。

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

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

这是一个重载函数。

创建一个 QSqlDatabase 连接，该连接使用type 引用的驱动程序。如果type 未被识别，数据库连接将不起作用。

当前可用的驱动程序类型如下

可动态加载其他第三方驱动程序，包括您自己的自定义驱动程序。

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

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 ，则使用 database(connectionName) 获取连接。

例如，调用setDatabaseName(),setUserName(),setPassword(),setHostName(),setPort(), 和setConnectOptions() 中的部分或全部，最后调用open() 。

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

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

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

这是一个重载函数。

当您想使用自己实例化的driver 创建数据库连接时，这个重载函数就非常有用。它可能是你自己的数据库驱动程序，也可能只是你自己需要实例化的 Qt 驱动程序之一。如果这样做，建议在应用程序中包含驱动程序代码。例如，您可以使用自己的 QPSQL 驱动程序创建 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 附带的驱动程序、源代码文件及其构造函数参数表：

另请参阅 drivers()。

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

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

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

[static] 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() 和rollback()。

QString QSqlDatabase::connectOptions() const

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

另请参阅 setConnectOptions()。

QString QSqlDatabase::connectionName() const

返回连接名称，可能为空。

另请参阅 addDatabase() 。

[static] QStringList QSqlDatabase::connectionNames()

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

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

另请参阅 contains(),database() 和线程与 SQL 模块。

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

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

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

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

[static] 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()。

[static] QStringList QSqlDatabase::drivers()

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

另请参见 registerSqlDriver()。

QString QSqlDatabase::hostName() const

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

另请参阅 setHostName()。

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

如果存在名为name 的驱动程序，则返回true ；否则返回false 。

另请参阅 drivers() 。

bool QSqlDatabase::isOpen() const

如果当前数据库连接已打开，则返回true ；否则返回false 。

bool QSqlDatabase::isOpenError() const

如果打开数据库连接出错，则返回true ；否则返回false 。可使用lastError() 函数获取错误信息。

bool QSqlDatabase::isValid() const

如果QSqlDatabase 有有效的驱动程序，则返回true 。

示例

QSqlDatabasedb；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()。

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

更改QSqlDatabase 及其相关驱动程序的线程亲和性。函数成功执行后，将返回true 。事件处理将继续在targetThread 中进行。

在此操作过程中，必须确保没有QSqlQuery 绑定到此实例，否则QSqlDatabase 将不会被移动到给定的线程，函数将返回false 。

由于相关驱动程序源于QObject ，因此将QObject 移动到另一个线程的所有约束也适用于该函数。

此函数在 Qt 6.8 中引入。

另请参阅 QObject::moveToThread() 和Threads 以及SQL 模块。

QSql::NumericalPrecisionPolicy QSqlDatabase::numericalPrecisionPolicy() const

返回数值精度策略。

另请参阅 setNumericalPrecisionPolicy().

bool QSqlDatabase::open()

使用当前连接值打开数据库连接。成功时返回true ，否则返回false 。错误信息可通过lastError() 获取。

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

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

这是一个重载函数。

使用给定的user 名称和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 的表（或视图）中所有字段的名称。字段在记录中出现的顺序未定义。如果不存在此类表（或视图），则返回空记录。

[static] 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

另请参见 drivers().

[static] 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() 时创建的，且未指定连接名称），可以在database() 返回的数据库上调用connectionName() 来获取默认连接名称。请注意，如果尚未创建默认数据库，则将返回无效数据库。

注意：该函数是线程安全的。

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

bool QSqlDatabase::rollback()

如果驱动程序支持事务，且transaction() 已启动，则回滚数据库中的事务。如果操作成功，则返回true 。否则返回false 。

调用lastError() 获取错误信息。

另请参阅 QSqlQuery::isActive()、QSqlDriver::hasFeature() 和commit()。

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

设置特定于数据库的options 。这必须在打开连接之前完成，否则不会有任何效果。另一种方法是关闭连接，调用 QSqlDatabase::setConnectOptions()，然后再次open() 连接。

options 字符串的格式是一个分号分隔的选项名称或选项=值对列表。这些选项取决于所使用的数据库客户端，并在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 。数据库名称必须在连接opened之前设置才能生效。或者，也可以close() 连接，设置数据库名称，然后再次调用open() 。

对于 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 。主机名必须在连接opened之前设置才能生效。或者，也可以close() 连接，设置主机名，然后再次调用open() 。

没有默认值。

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

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

将numericalPrecisionPolicy 设置为precisionPolicy 。

另请参阅 numericalPrecisionPolicy() 。

void QSqlDatabase::setPassword(const QString &password)

将连接密码设置为password 。密码必须在连接opened之前设置才能生效。或者，您可以close() 连接，设置密码，然后再次调用open() 。

没有默认值。

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

void QSqlDatabase::setPort(int port)

将连接的端口号设置为port 。端口号必须在连接opened之前设置才能生效。或者，您可以close() 连接，设置端口号，然后再次调用open() 。

没有默认值。

另请参阅 port()、setUserName()、setPassword()、setHostName()、setDatabaseName()、setConnectOptions() 和open()。

void QSqlDatabase::setUserName(const QString &name)

将连接的用户名设置为name 。用户名必须在连接opened之前设置才能生效。或者，也可以close() 连接，设置用户名，然后再次调用open() 。

没有默认值。

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

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

返回参数type 指定的数据库表、系统表和视图的列表。

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

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

返回指向相关QThread 实例的指针。

此函数在 Qt 6.8 中引入。

bool QSqlDatabase::transaction()

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

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

QString QSqlDatabase::userName() const

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

另请参阅 setUserName()。

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

为该对象指定other 。