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：
- SQL_MODE_READ_ONLY：只读连接，只能支持查询语句。
- 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跟踪功能
- SQL_OPT_TRACE_OFF：关闭
- SQL_OPT_RACE_ON：启用
- SQL_ATTR_CONNECTION_POOLING：是否启用连接池
- SQL_CP_OFF：不启用连接池，默认值。
- SQL_CP_ONE_PER_DRIVER：对于每个ODBC驱动启用一个连接池
- SQL_CP_ONE_PER_HENV：对于每个Env对象启用一个连接池
- SQL_CP_DRIVER_AWARE：如果驱动不支持驱动级连接池，则转为启用ENV级连接池。
- SQL_ATTR_ODBC_VERSION：当前ODBC接口的版本，如：
- SQL_OV_ODBC3_80：ODBC 3.8
- SQL_OV_ODBC3：ODBC 3.0
- 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()
如果驱动程序支持事务，则在数据库上开始事务。返回是否操作成功。