windows下，Qt通过自带驱动连接PostgreSQL等数据库避坑指南

问题描述

Qt提供了qt sql模块，对SQL操作进行了一层包装，可以让qt程序员使用熟悉的qt风格编写SQL相关的程序，代价是需要调用目标数据库的驱动。
qt默认只提供了三个数据库的驱动——sqlite3，odbc，postgreSql，存放在Qt安装目录\Qt版本\plugins\sqldrivers内，其它的驱动需要自行从源码编译。而且十分不幸的是，这里真正开箱即用的数据库有且只有sqlite3，其它数据库不管是否官方自带驱动，都是无法直接使用的。
以下是qt源码提供驱动的数据库名单——

驱动文件夹	对应数据库 / 环境	Qt中的简称	默认安装
db2	IBM DB2	“QDB2”	否
mysql	MySQL	“QMYSQL3”, “QMYSQL”, “QMARIADB”	否
oci	Oracle	“QOCI8”, “QOCI”	否
odbc	ODBC	“QODBC3”, “QODBC”	是
psql	PostgreSQL	“QPSQL7”, “QPSQL”	是
sqlite	SQLite3	“QSQLITE”	是
sqlite2	SQLite2	“QSQLITE2”	否，qt5.14后废弃，qt6移除
tds	FreeTDS	“QTDS7”, “QTDS”	否

其中通过odbc和tds可以实现更多不在官方支持的数据库的连接，笔者曾经做过一个项目，在linux下通过tds和odbc的组合拳实现了远程连接SQL server，当然过程非常曲折，不想再回首。
所以如果你要实现一个不在官方支持列表内的数据库连接，例如流行的Redis或者mongoDB，可以选择ODBC试试，当然或多或少会损失一些功能或者性能，且不保证成功，或许经过几天的尝试后，还是不得不放弃qt sql，而采用直接调用目标数据库提供的c++接口。

本文能解决什么问题

好，说了这么多，是时候直奔主题了，通过本文的阅读，希望读者能够掌握Qt连接以上驱动列表内的数据库的方法，而不会出现诸如“QSqlDatabase: QPSQL driver not loaded”之类的错误。

Qt连接数据库的一般性操作步骤（以PostgreSQL 为例）

1.安装目标数据库环境

先去postgresql官网找到需求的版本下载，安装，注意这里要选择和使用的qt版本相匹配版本，比如你是用的qt版本是msvc2019_64版，那么需要下载64位数据库。下载之后设置postgreSQL服务器的用户名和连接密码。最好通过第三方工具（Navicat或者Dbeaver等）连接postgreSQL服务器，测试服务器是否建立成功。

2.编写代码连接数据库

新建一个工程，在pro文件中 添加 QT += sql
然后在工程中添加能执行到的代码段

    QSqlDatabase db = QSqlDatabase::addDatabase("QPSQL");
    db.setHostName("127.0.0.1");
    db.setPort(5432);
    // 需要改成自己的用户名和密码
    db.setUserName("postgres");
    db.setPassword("123456");
    if (db.open()) {
        QMessageBox::information(this, "infor", "success");
    } else {
        QMessageBox::information(this, "infor", "open failed");
    }

编译运行，不出意外会报错

QSqlDatabase: QPSQL driver not loaded
QSqlDatabase: available drivers: QSQLITE QODBC QODBC3 QPSQL QPSQL7

3.拷贝库文件至正确位置

打开postgresql安装目录中的bin文件夹，将其中的6个文件拷贝到程序可执行文件同级目录中，6个文件是

libcrypto-3-x64.dll
libiconv-2.dll
libintl-9.dll
libpq.dll
libssl-3-x64.dll
libwinpthread-1.dll

注意这里只针对PostgreSQL15版本，如果是其他版本，文件名或许会不同。
很多文章提到这里只需要拷贝前5个文件，经笔者测试，如果是mingw编译器，前5个文件就可以了，如果是msvc编译器，必须要加入libwinpthread-1.dll，否则加载驱动不会成功！
如果还是不行，建议将PostgreSQL安装目录中bin文件夹下所有的dll文件全部拷贝至程序可执行文件同级目录中，确保驱动能够正确加载后，再一个个试验，把冗余的dll文件删除。
这里也有一些文章建议把这几个dll文件拷贝到windows系统目录中，或者qt安装目录\plugins\sqldrivers内的，我的建议是不要这样做，会污染系统环境，而且有些方法也不奏效。
另外为了让用户程序位置具有确定性，可以在pro文件中添加一行

DESTDIR = $$PWD/bin

这样以上文件可直接拷贝到bin文件夹

4.编译对应数据库驱动

如果是postgresql，那么到第3步应当已经完成了，如果很不幸第3步照做还是不行，或者你连接的是MySQL等没有提供默认驱动的数据库，那么还需要从官方提供的源码自己编译驱动。
这一步也很简单，官网下载qt源码，找到Src\qtbase\src\plugins\sqldrivers目录，里面有所有支持的驱动列表，我们这里打开psql文件夹，Qt Creator打开psql.pro文件，注释掉#QMAKE_USE += psql字段，并添加外部库pq.dll支持，并在qsqldriverbase.pri中注释掉

include($$shadowed($$PWD)/qtsqldrivers-config.pri)

改为include(./configure.pri)，编译通过，生成qsqlpsql.dll等文件，拷贝至Qt\5.15.2\msvc2019_64\plugins\sqldrivers内，搞定~
详见这篇文章: link

总结

调试qt sql驱动的本质是调试c++库的依赖关系，因此有一些一般的原则是应当遵守的：
1.库版本要匹配，这里操作系统，库位数，编译器版本都尽量做到一致，会减少出错概率。
2.如果使用qt自带的驱动，那么对应的数据库版本应当选择qt版本发布时间接近的，如果懒得查发布时间表，那么最好使用新版本的qt和新版本的数据库
3.数据库驱动文件存放在Qt安装目录\Qt版本\plugins\sqldrivers内，且除了sqlite之外，其它数据库的驱动还需要各数据库提供的若干支持库才能运行（MySQL只需要libmysql.dll一个文件，postgresql则需要前面所述的6个文件），而这些库文件建议最好放到用户可执行文件的同级目录下，这样奏效且不影响系统环境。
4.如果不知道数据库的驱动文件需要哪些支持库，则可以把对应数据库的bin文件夹下所有dll文件全部拷贝到执行文件的同级目录下，保证数据库先能够连接，再做精简。

结束收工~~