QSqlDriver Class

成员函数文档

[explicit] QSqlDriver::QSqlDriver(QObject *parent = nullptr)

使用给定的parent 创建一个新的驱动程序。

[virtual noexcept] QSqlDriver::~QSqlDriver()

销毁该对象并释放所有已分配的资源。

[virtual] bool QSqlDriver::beginTransaction()

调用此函数以开始一个事务。如果成功，则返回 true；否则返回 false。默认实现不执行任何操作，并返回false 。

另请参阅 commitTransaction() 和rollbackTransaction()。

[pure virtual] void QSqlDriver::close()

派生类必须重写此纯虚函数，以便关闭数据库连接。成功时返回 true，失败时返回 false。

另请参见 open() 和setOpen()。

[virtual] bool QSqlDriver::commitTransaction()

调用此函数用于提交事务。若成功，则返回 true；否则返回 false。默认实现不执行任何操作，并返回false 。

另请参见 beginTransaction() 和rollbackTransaction()。

[since 6.9] QString QSqlDriver::connectionName() const

返回通过QSqlDatabase::addDatabase()创建该驱动程序时所用的数据库连接名称

该函数在 Qt 6.9 中引入。

[pure virtual] QSqlResult *QSqlDriver::createResult() const

在数据库上创建一个空的SQL结果集。派生类必须重写此函数，并向调用方返回一个适用于其数据库的QSqlResult 对象。

[virtual] QString QSqlDriver::escapeIdentifier(const QString &identifier, QSqlDriver::IdentifierType type) const

返回根据数据库规则进行转义的identifier 。identifier 可以是表名，也可以是字段名，具体取决于type 。

默认实现不执行任何操作。

另请参阅 isIdentifierEscaped()。

[virtual] QString QSqlDriver::formatValue(const QSqlField &field, bool trimStrings = false) const

返回该数据库的field 值的字符串表示形式。例如，在构建INSERT和UPDATE语句时会用到它。

默认实现会根据以下规则将值格式化为字符串并返回：

• 如果 `field ` 是字符数据，则返回的值将用单引号括起，这适用于许多 SQL 数据库。任何嵌入的单引号字符都会被转义（替换为两个单引号字符）。如果 `trimStrings ` 为真（默认值为假），则会从字段中删除所有尾随空格。
• 如果 `field ` 是日期/时间数据，则该值将按 ISO 格式进行格式化，并用单引号括起来。如果日期/时间数据无效，则返回“NULL”。
• 如果field 是bytearray 数据，且驱动程序能够编辑二进制字段，则该值将格式化为十六进制字符串。
• 对于任何其他字段类型，将对其值调用 toString() 方法，并返回该方法的结果。

另请参阅 QVariant::toString()。

[virtual] QVariant QSqlDriver::handle() const

返回一个由QVariant 封装的低级数据库句柄；如果不存在句柄，则返回一个无效的变体。

此处返回的句柄取决于数据库，在访问它之前，应查询该变体的类型名称。

以下示例检索 sqlite 连接的句柄：

QSqlDatabase db = QSqlDatabase::database();
QVariant v = db.driver()->handle();
if (v.isValid() && (qstrcmp(v.typeName(), "sqlite3*") == 0)) {
    // v.data() returns a pointer to the handle
    sqlite3 *handle = *static_cast<sqlite3 **>(v.data());
    if (handle) {
        // ...
    }
}

以下代码片段返回 PostgreSQL 或 MySQL 的连接句柄：

if (qstrcmp(v.typeName(), "PGconn*") == 0) {
    PGconn *handle = *static_cast<PGconn **>(v.data());
    if (handle) {
        // ...
    }
}

if (qstrcmp(v.typeName(), "MYSQL*") == 0) {
    MYSQL *handle = *static_cast<MYSQL **>(v.data());
    if (handle) {
        // ...
    }
}

另请参阅 QSqlResult::handle()。

[pure virtual] bool QSqlDriver::hasFeature(QSqlDriver::DriverFeature feature) const

如果驱动程序支持feature 功能，则返回true ；否则返回false 。

请注意，某些数据库需要先调用open() 才能确定这一点。

另请参阅 DriverFeature 。

[virtual] bool QSqlDriver::isIdentifierEscaped(const QString &identifier, QSqlDriver::IdentifierType type) const

返回identifier 是否已根据数据库规则进行转义。identifier 可以是表名或字段名，具体取决于type 。

若要在 `QSqlDriver ` 的子类中提供自定义实现，请重写此函数，

另请参阅 stripDelimiters() 和escapeIdentifier()。

[virtual] bool QSqlDriver::isOpen() const

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

bool QSqlDriver::isOpenError() const

如果打开数据库连接时发生错误，则返回true ；否则返回false 。

QSqlError QSqlDriver::lastError() const

返回一个QSqlError 对象，其中包含有关数据库中最近发生的错误的信息。

另请参阅 setLastError()。

[virtual, since 6.0] int QSqlDriver::maximumIdentifierLength(QSqlDriver::IdentifierType type) const

根据数据库设置，返回标识符type 的最大长度。如果数据库中未设置最大长度，则默认返回INT_MAX。

该函数于 Qt 6.0 中引入。

[signal] void QSqlDriver::notification(const QString &name, QSqlDriver::NotificationSource source, const QVariant &payload)

当数据库发布驱动程序已订阅的事件通知时，会发出此信号。name 标识该事件通知，source 指示信号源，payload 包含通知中可选的附加数据。

另请参阅 subscribeToNotification()。

QSql::NumericalPrecisionPolicy QSqlDriver::numericalPrecisionPolicy() const

返回 numericalPrecisionPolicy。

另请参阅 ` setNumericalPrecisionPolicy()`。

[pure virtual] bool QSqlDriver::open(const QString &db, const QString &user = QString(), const QString &password = QString(), const QString &host = QString(), int port = -1, const QString &options = QString())

派生类必须重写此纯虚函数，以在数据库db 上建立数据库连接，使用用户名user 、密码password 、主机host 、端口port 以及连接选项options 。

该函数在成功时必须返回 true，失败时必须返回 false。

另请参阅 setOpen()。

[virtual] QSqlIndex QSqlDriver::primaryIndex(const QString &tableName) const

返回表tableName 的主键索引。如果该表没有主键索引，则返回一个空的QSqlIndex 。默认实现返回一个空索引。

[virtual] QSqlRecord QSqlDriver::record(const QString &tableName) const

返回一个QSqlRecord ，其中填充了表tableName 中的字段名称。如果不存在该表，则返回一个空记录。默认实现返回一个空记录。

[virtual] bool QSqlDriver::rollbackTransaction()

调用此函数用于回滚事务。若成功，则返回 true；否则返回 false。默认实现不执行任何操作，并返回false 。

另请参阅 beginTransaction() 和commitTransaction()。

[virtual protected] void QSqlDriver::setLastError(const QSqlError &error)

此函数用于设置数据库中发生的最后一个错误error 的值。

另请参阅 lastError()。

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

将numericalPrecisionPolicy 设置为precisionPolicy 。

另请参阅 numericalPrecisionPolicy()。

[virtual protected] void QSqlDriver::setOpen(bool open)

该函数将数据库的打开状态设置为open 。派生类可以使用此函数来报告open()的状态。

另请参阅 open() 和setOpenError()。

[virtual protected] void QSqlDriver::setOpenError(bool error)

该函数将数据库的打开状态设置为error 。派生类可以使用此函数来报告open()的返回状态。请注意，如果error 为true，则数据库的打开状态将被设置为关闭（即isOpen()返回false ）。

另请参阅 isOpenError()、open() 和setOpen()。

[virtual] QString QSqlDriver::sqlStatement(QSqlDriver::StatementType type, const QString &tableName, const QSqlRecord &rec, bool preparedStatement) const

返回针对表 `tableName ` 的类型为 `type ` 的 SQL 语句，其中包含来自 `rec` 的值。如果 `preparedStatement ` 为真，则字符串中将包含占位符而非具体值。

rec 中每个字段生成的标志决定了该字段是否包含在生成的语句中。

此方法可用于操作表，而无需担心与数据库相关的 SQL 方言。对于非预编译语句，值将进行适当的转义。

在 WHERE 子句中，rec 的每个非空字段都指定了一个与字段值相等的筛选条件；如果是预编译语句，则指定为占位符。但是，无论是否为预编译语句，空字段都指定条件为 IS NULL，且绝不会引入占位符。应用程序在执行期间不得尝试为空字段绑定数据。 若需要占位符，则该字段必须设置为某个非空值。此外，由于非空字段指定的是相等条件，而 SQL 中的 NULL 不等于任何值（甚至不等于其自身），因此将 NULL 绑定到占位符通常没有意义。

[virtual] QString QSqlDriver::stripDelimiters(const QString &identifier, QSqlDriver::IdentifierType type) const

返回已移除首尾分隔符的identifier ，identifier 可以是表名或字段名，具体取决于type 。如果identifier 没有首尾分隔符，则直接返回identifier ，不作任何修改。

若要在QSqlDriver 子类中提供自定义实现，请重写此函数，

另请参阅 isIdentifierEscaped()。

[virtual] bool QSqlDriver::subscribeToNotification(const QString &name)

调用此函数可订阅来自数据库的事件通知。name 用于标识该事件通知。

若调用成功，则返回 true；否则返回 false。

调用此函数时，数据库必须处于打开状态。当通过调用close() 关闭数据库时，所有已订阅的事件通知都会自动取消订阅。请注意，在已打开的数据库上调用open() 可能会隐式地导致close() 被调用，从而导致驱动程序取消订阅所有事件通知。

当数据库发布由 `name ` 标识的事件通知时，将发出 `notification()` 信号。

若要在您自己的QSqlDriver 子类中提供事件通知支持，请重写此函数，

另请参阅 unsubscribeFromNotification()、subscribedToNotifications() 以及QSqlDriver::hasFeature()。

[virtual] QStringList QSqlDriver::subscribedToNotifications() const

返回当前已订阅的事件通知名称的列表。

若要在您自己的 `QSqlDriver ` 子类中提供事件通知支持，请重写此函数，

另请参阅 subscribeToNotification() 和unsubscribeFromNotification()。

[virtual] QStringList QSqlDriver::tables(QSql::TableType tableType) const

返回数据库中表名的列表。默认实现返回一个空列表。

tableType 参数用于指定应返回哪些类型的表。出于二进制兼容性的考虑，该字符串包含枚举QSql::TableTypes的值（以文本形式表示）。为保持向后兼容性，应将空字符串视为QSql::Tables 。

[virtual] bool QSqlDriver::unsubscribeFromNotification(const QString &name)

调用此函数可取消订阅数据库的事件通知。name 用于标识该事件通知。

若调用成功，则返回 true；否则返回 false。

调用此函数时，数据库必须处于打开状态。调用close() 函数时，所有已订阅的事件通知都会自动取消订阅。

调用此函数后，当数据库发布由 `name ` 标识的事件通知时，将不再发出 `notification()` 信号。

若要在您自己的 `QSqlDriver ` 子类中提供事件通知支持，请重写此函数，

另请参阅 subscribeToNotification() 和subscribedToNotifications()。