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 为 true（默认为 false），字段中的所有尾部空白都会被剪掉。
• 如果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

返回数值精度策略。

另请参阅 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 为 true，字符串将包含占位符而不是值。

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

这种方法可用于操作表，而不必担心与数据库相关的 SQL 方言。对于非预处理语句，值将被正确转义。

在 WHERE 语句中，rec 的每个非空字段都指定了与字段值相等的过滤条件，如果是预置的，则指定了占位符。但是，无论是否准备好，空字段都会指定条件 IS NULL，而不会引入占位符。在执行过程中，应用程序不得尝试为空字段绑定数据。如果需要占位符，必须将字段设置为某个非空值。此外，由于非空字段指定了相等条件，而 SQL 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()。