Qt SQL：QSqlDatabase

一、描述

QSqlDatabase 类处理与数据库的连接。此类提供了一个通过连接访问数据库的接口。

QSqlDatabase 的实例代表一个连接，该连接通过受支持的数据库驱动程序提供对数据库的访问，这些驱动程序派生自 QSqlDriver。

通过调用静态函数 addDatabase() 创建连接。可以与一个数据库建立多个连接。

不要将 QSqlDatabase 的副本作为类的成员保留，因为这将阻止实例在关闭时被正确清理。

如果创建了多个数据库连接，则需要在调用 addDatabase() 时为每个连接指定一个唯一的连接名称。使用带有连接名称的 database() 来获取该连接。使用带有连接名称的 removeDatabase() 来删除连接。

二、部分成员函数

1、【protected】QSqlDatabase(const QString &type)

创建一个使用按类型引用的驱动程序的 QSqlDatabase 连接。如果无法识别类型，则数据库连接将不起作用。

• QDB2：IBM DB2
• QIBASE：Borland InterBase
• QMYSQL：MySQL
• QOCI：Oracle
• QODBC：ODBC
• QPSQL：PostgreSQL
• QSQLITE：SQLite

2、~QSqlDatabase()

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

当最后一个连接被销毁时，析构函数会隐式调用 close()来释放数据库连接。

3、【static】QSqlDatabase addDatabase(const QString &type, const QString &connectionName = QLatin1String(defaultConnection))

使用驱动程序 type 和连接名称 connectionName 将数据库添加到数据库连接列表中。如果连接列表已经存在名为 connectionName 的数据库连接，则删除该连接。

返回新添加的数据库连接。

如果类型不可用或无法加载，isValid() 返回 false。

如果未指定连接名称，则新连接将成为应用程序的默认连接，后续调用不带连接名称参数的database() 将返回默认连接。

在使用连接之前，必须对其进行初始化。初始化后调用 open()。

4、【static】QSqlDatabase cloneDatabase(const QSqlDatabase &other, const QString &connectionName)

克隆其他数据库连接并将其存储为 connectionName。来自原始数据库的所有设置都被复制过来。 返回新创建的数据库连接。

克隆后新连接尚未打开。在使用新连接之前，必须调用 open()。

      【static】QSqlDatabase cloneDatabase(const QString &other, const QString &connectionName)

这个重载版本加了锁所以跨线程克隆时应该用这个。

5、void close()

关闭数据库连接，释放所有资源，并使与数据库一起使用的所有 QSqlQuery 对象无效。

这也会影响此 QSqlDatabase 对象的副本。

6、bool commit()

如果驱动程序支持事务并且 transaction() 已启动，则将事务提交到数据库。返回是否操作成功。

对于某些数据库，如果存在使用数据库进行 SELECT 的活动查询，则提交将失败并返回 false。

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

7、QString connectionName()

返回连接名称。

8、【static】QStringList connectionNames()

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

9、【static】bool contains(const QString &connectionName = QLatin1String(defaultConnection))

数据库连接列表是否包含 connectionName。

10、【static】QSqlDatabase database(const QString &connectionName = QLatin1String(defaultConnection), bool open = true)

返回名为 connectionName 的数据库连接。数据库连接必须是已使用 addDatabase() 添加的连接。

如果 open 为 true并且数据库连接尚未打开，则打开它。

如果未指定 connectionName，则使用默认连接。

如果数据库列表中不存在 connectionName，则返回无效连接。

11、QString databaseName()

返回连接的数据库名称。

12、QSqlDriver * driver()

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

13、QString driverName()

返回连接的驱动程序名称。

14、【static】QStringList drivers()

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

15、QSqlQuery exec(const QString &query = QString())

在数据库上执行一条 SQL 语句并返回一个 QSqlQuery 对象。

16、【static】bool isDriverAvailable(const QString &name)

名为 name 的驱动程序是否可用。

17、bool isOpen()

数据库连接是否是打开的。

18、bool isOpenError()

是否打开数据库连接出错。可以使用 lastError() 函数检索错误信息。

19、bool isValid()

是否具有有效的驱动程序。

20、QSqlError lastError()

返回有关数据库上发生的最后一个错误的信息。

与单个查询一起发生的错误则由 QSqlQuery::lastError() 报告。

21、void setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)

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

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

enum QSql::NumericalPrecisionPolicy：数据库中的数值可以具有比其对应的 C++ 类型更高的精度。此枚举列出了在应用程序中表示此类值的策略。

• QSql::LowPrecisionInt32：强制 32 位整数值。在浮点数的情况下，小数部分被静默丢弃。
• QSql::LowPrecisionInt64：强制 64 位整数值。在浮点数的情况下，小数部分被静默丢弃。
• QSql::LowPrecisionDouble：强制双精度值。默认策略。
• QSql::HighPrecision：字符串将使用高精度。

22、bool open()

使用当前连接值打开数据库连接。返回是否成功。可以使用 lastError() 检索错误信息。

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

使用给定的用户名和密码打开数据库连接。

此函数不存储给定的密码，密码直接传递给驱动程序以打开连接，然后将其丢弃。

23、void setPassword(const QString &password)

设置连接的密码。必须在打开连接之前设置密码。

24、void setPort(int port)

设置连接的端口号。必须在打开连接之前设置端口号。

25、QSqlIndex primaryIndex(const QString &tablename)

返回表 tablename 的主索引。如果不存在主索引，则返回一个空的 QSqlIndex。

26、QSqlRecord record(const QString &tablename)

返回一个记录，其中填充了名为 tablename 的表（或视图）中所有字段的名称。字段在记录中出现的顺序是未定义的。

27、【static】void removeDatabase(const QString &connectionName)

从数据库连接列表中删除数据库连接 connectionName。

调用此函数时，数据库连接上不应有打开的查询，否则会发生资源泄漏。

QSqlDatabase db = QSqlDatabase::database("sales");
QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db);
QSqlDatabase::removeDatabase("sales"); // 将输出警告
// "db" 现在是一个悬空的无效数据库连接，
// “query”包含无效的结果集

{
    QSqlDatabase db = QSqlDatabase::database("sales");
    QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db);
}
// "db" 和 "query" 都被销毁，因为它们超出了范围
QSqlDatabase::removeDatabase("sales"); // 正确的用法

要删除默认连接可以通过在 database() 返回的数据库上调用 connectionName() 来检索默认连接名称。

28、bool rollback()

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

对于某些数据库，如果存在使用数据库进行 SELECT 的活动查询，则回滚将失败并返回 false。

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

29、void setConnectOptions(const QString &options = QString())

设置特定于数据库的选项。这必须在打开连接之前完成，否则没有效果。

选项字符串的格式：选项名称或选项=值对的分号分隔列表。

选项取决于使用的数据库客户端（随便看看，资料有的找不全）：

ODBC：

• SQL_ATTR_ACCESS_MODE：

1. SQL_MODE_READ_ONLY：只读连接，只能支持查询语句。
2. SQL_MODE_READ_WRITE：默认值，可读可写。

• SQL_ATTR_LOGIN_TIMEOUT：连接超时时间
• SQL_ATTR_CONNECTION_TIMEOUT：数据源响应超时时间
• SQL_ATTR_CURRENT_CATALOG
• SQL_ATTR_METADATA_ID
• SQL_ATTR_PACKET_SIZE：网络报文字节数
• SQL_ATTR_TRACEFILE：TRACE文件路径
• SQL_ATTR_TRACE：是否启用ODBC跟踪功能

1. SQL_OPT_TRACE_OFF：关闭
2. SQL_OPT_RACE_ON：启用

• SQL_ATTR_CONNECTION_POOLING：是否启用连接池

1. SQL_CP_OFF：不启用连接池，默认值。
2. SQL_CP_ONE_PER_DRIVER：对于每个ODBC驱动启用一个连接池
3. SQL_CP_ONE_PER_HENV：对于每个Env对象启用一个连接池
4. SQL_CP_DRIVER_AWARE：如果驱动不支持驱动级连接池，则转为启用ENV级连接池。

• SQL_ATTR_ODBC_VERSION：当前ODBC接口的版本，如：

1. SQL_OV_ODBC3_80：ODBC 3.8
2. SQL_OV_ODBC3：ODBC 3.0
3. SQL_OV_ODBC2：ODBC 2.0

MySQL：

• CLIENT_COMPRESS：使用压缩协议
• CLIENT_FOUND_ROWS：返回匹配的行数
• CLIENT_IGNORE_SPACE：允许在函数名后留空格位
• CLIENT_ODBC
• CLIENT_NO_SCHEMA：不允许使用 database.table.column 语法
• CLIENT_INTERACTIVE：在关闭连接前所允许的交互超时非活动时间
• UNIX_SOCKET
• MYSQL_OPT_RECONNECT：启用/禁用（当发现连接断开时的）自动重连
• MYSQL_OPT_CONNECT_TIMEOUT：连接超时时间
• MYSQL_OPT_READ_TIMEOUT：读取超时时间
• MYSQL_OPT_WRITE_TIMEOUT：写入超时时间
• SSL_KEY：客户端私钥文件的路径名
• SSL_CERT：客户端公钥证书文件的路径名
• SSL_CA：证书颁发机构 (CA) 证书文件的路径名。如果使用此选项，则必须指定服务器使用的相同证书。
• SSL_CAPATH：包含受信任 SSL CA 证书文件的目录的路径名
• SSL_CIPHER：SSL 加密的允许密码列表

SQLite：

• QSQLITE_BUSY_TIMEOUT：操作的超时时间
• QSQLITE_OPEN_READONLY：以只读方式打开数据库
• QSQLITE_OPEN_URI：打开的URI
• QSQLITE_ENABLE_SHARED_CACHE：是否启用共享高速缓存。连接到一个 database 的多个链接，对同一个数据的操作会在 shared cache 层面进行操作。这可以减少对数据库的IO次数和内存操作次数，提高效率。
• QSQLITE_ENABLE_REGEXP：是否支持语句里面使用正则表达式
• QSQLITE_NO_USE_EXTENDED_RESULT_CODES：是否启用扩展错误码。

例如：

db.setConnectOptions("SSL_KEY=client-key.pem;SSL_CERT=client-cert.pem;SSL_CA=ca-cert.pem;CLIENT_IGNORE_SPACE=1"); // 使用与服务器的 SSL 连接
if (!db.open()) 
{
    db.setConnectOptions(); // 清除连接选项字符串
    // ...
}

// ODBC connection
db.setConnectOptions("SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLY;SQL_ATTR_TRACE=SQL_OPT_TRACE_ON");
if (!db.open()) 
{
    db.setConnectOptions(); 
    // ...
}

 30、void setDatabaseName(const QString &name)

设置连接的数据库名称。必须在打开连接之前设置数据库名称。

数据库名称不是连接名称。连接名称必须在连接对象创建时传递给 addDatabase()。

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

名称可以设置为“:memory:”，这将创建一个临时数据库，该数据库仅在应用程序的生命周期内可用。

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

对于 QODBC 驱动程序，名称可以是 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!
}

31、void setHostName(const QString &host)

设置连接的主机名。必须在打开连接之前设置主机名。

32、void setUserName(const QString &name)

设置连接的用户名。必须在打开连接之前设置用户名。

33、QStringList tables(QSql::TableType type = QSql::Tables)

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

enum QSql::TableType：此枚举类型描述 SQL 表的类型。

• QSql::Tables：用户可见的所有表。
• QSql::SystemTables：数据库使用的内部表。
• QSql::Views：用户可见的所有视图。
• QSql::AllTables：以上所有。

34、bool transaction()

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