Qt连接服务器数据库的核心答案：通过QSqlDatabase类配置好数据库驱动、服务器地址、端口、账号密码，然后调用open()方法，一次open()成功就是连接的开始。 但真正的功夫在连接之前：驱动是否齐全、网络是否通、权限是否到位，这三样缺一个,你的代码再对也只能看着报错发呆。
Qt连接数据库前要准备好这四样东西
写代码之前，先当一回“侦探”，Qt本身只是客户端工具，服务器那边不配合，你连个寂寞，按下面顺序检查,能省下两个小时排查时间。
- 数据库类型和版本，MySQL、PostgreSQL、SQL Server的驱动名和端口完全不一样，别拿MySQL的QMYSQL去连SQL Server,那不是努力的问题。
- Qt自带的驱动插件，安装完Qt后，查看安装目录下
plugins/sqldrivers文件夹，确认有没有对应数据库的动态库，比如qsqlmysql.dll或libqsqlmysql.so，没有的话，后面会直接报“Driver not loaded”。 - 服务器网络可达，从你自己的电脑上尝试用命令行工具（比如
mysql -h 服务器IP -P 端口）测试能否连通，连不上,先查防火墙和安全组规则。 - 数据库账号有远程权限，默认情况下面MySQL的root账号只允许本机登录，你需要在服务器上创建一个允许（任意主机）访问的专用账号,或者修改现有账号的host。
行业共识认为，相当一部分“Qt连接数据库失败”的案例，根源都是服务器端配置问题，而不是Qt代码问题，别急着抄代码,先确认这四样。
Qt连接MySQL数据库步骤
这里以最常见的MySQL为例，一步步来，假设你已经在云服务器上部署了MySQL 8.0，客户端是Windows上的Qt 6.x。
第一步：在.pro工程文件中加入SQL模块
打开你的.pro文件,添加一行：
QT += sql
没有这一步，代码里写#include <QSqlDatabase>会直接报找不到头文件。
第二步：加载驱动并设置连接参数
几乎每个Qt程序里都会看到类似下面这段代码,但细节各有不同：
#include <QSqlDatabase>
#include <QSqlError>
#include <QDebug>
QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL");
db.setHostName("123.45.67.89"); // 服务器IP或域名
db.setPort(3306);
// MySQL默认端口
db.setDatabaseName("your_db"); // 要连接的数据库名
db.setUserName("qt_user"); // 专用账号
db.setPassword("your_password"); // 密码
if (db.open()) {
qDebug() << "连接成功";
} else {
qDebug() << "连接失败：" << db.lastError().text();
}
注意，addDatabase的第一个参数是驱动名，MySQL对应QMYSQL，PostgreSQL对应QPSQL，SQLite对应QSQLITE。
第三步：检查驱动是否可用
如果你不确定自己的Qt版本支持哪些驱动,一行代码打出来看：
qDebug() << QSqlDatabase::drivers();
输出列表里如果没有QMYSQL，说明驱动插件缺失，此时你有两个选择：重装勾选Qt SQL驱动组件,或者去官方文档找到对应模块手动编译。
第四步：处理连接错误
db.open()只是返回布尔值，真正有用的信息在db.lastError().text()里，务必先打印它,再据错误内容去排查。
Qt连接数据库失败原因，九成出在这几个地方
代码看起来没问题，但就是连不上，这时你需要的不是改代码,而是对照下面这几个高频坑。
驱动编译版本和MySQL不匹配
Qt的QMySQL驱动实际上通过动态加载libmysql.dll或libmysql.so来工作，如果MySQL是8.0，你用的驱动却还是5.x时代编译的，连接时大概率报“Client does not support authentication protocol requested by server”，解决办法是下载对应版本的MySQL客户端库,放到Qt目录或程序运行目录。
服务器没有开启远程访问
MySQL默认bind-address=127.0.0.1，只监听本机，你需要编辑/etc/mysql/mysql.conf.d/mysqld.cnf，把它改为bind-address=0.0.0.0，然后重启MySQL服务。这一步几乎是远程连接的标配，却经常被忽略。
防火墙和安全组没放行端口
云服务器一般有两层防火墙：系统自带的iptables/firewalld，以及云控制台的安全组规则，哪怕你本机防火墙全关，安全组没放行3306,外部依然无法访问。
数据库用户授权host不对
在MySQL里执行：
SELECT user, host FROM mysql.user;
如果用户qt_user的host是localhost，那你从别的机器连必然被拒绝,授权时这样写：
GRANT ALL PRIVILEGES ON your_db. TO 'qt_user'@'%' IDENTIFIED BY 'your_password'; FLUSH PRIVILEGES;
字符集和编码导致连接后数据乱码
连接成功后查询中文变问号，别慌,在连接字符串里加编码参数即可：
QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL");
// ...省略其他设置
db.setConnectOptions("MYSQL_OPT_RECONNECT=1;UNIX_SOCKET_CONNECT_TIMEOUT=5;CHARSET=utf8mb4");
对于MySQL，建议服务端、客户端、表结构三处统一使用utf8mb4。
进阶：Qt数据库连接池实现
如果你只是写个小工具，每次操作前open()、操作后close()没问题，但如果你在写服务器端Qt应用，或者需要频繁访问数据库的桌面程序，连接池几乎是必须的，因为一次数据库连接从建立到释放，开销相当可观,在高频请求下会明显卡顿。
连接池的核心思想
维护一组永不真正关闭的QSqlDatabase实例，用的时候从池子里拿，用完归还,而不是销毁。
最简单的实现方式
用QQueue存空闲连接，配合QMutex保证线程安全：
QQueue<QSqlDatabase> connectionPool;
QMutex poolMutex;
QSqlDatabase getConnection() {
QMutexLocker locker(&poolMutex);
if (!connectionPool.isEmpty()) {
return connectionPool.dequeue();
}
// 创建新连接
QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL", "conn_" + QString::number(qrand()));
// ...设置参数并open
return db;
}
void releaseConnection(QSqlDatabase db) {
QMutexLocker locker(&poolMutex);
connectionPool.enqueue(db);
}
这里有一个关键点：addDatabase时第二个参数是自定义连接名，避免覆盖默认连接，如果每次都用addDatabase("QMYSQL")而不指定名字,会直接破坏已有连接。
连接池需要注意的线程归属问题
QSqlDatabase不能跨线程使用。 也就是说，你在线程A里创建的连接，不能拿到线程B里去执行查询，所以连接池在分配连接时，最好记录创建它的线程ID，或者按照线程号创建独立连接，多数成熟的做法是：每个线程持有一份私有连接，线程内部复用,线程结束时销毁。
服务器端如何配合Qt连接
说一句大实话：Qt连接远程数据库，一半的代码在Qt端，另一半的配置在服务器端,这里给你一份服务器调整清单。
- 修改MySQL监听地址：编辑
/etc/mysql/mysql.conf.d/mysqld.cnf，将bind-address改为0.0.0。 - 创建专用账号：不要用root直接给Qt程序，单独建一个权限最小的账号,只给应用所需的数据库权限。
- 开放安全组端口：登录云服务商控制台，找到对应云主机的安全组，添加入站规则，允许TCP 3306端口来源为你的客户端IP或网段。
- 确认SELinux状态：如果服务器是CentOS/RHEL，可能还需要放行SELinux对3306端口的限制，临时测试可以先
setenforce 0,但生产环境不建议。 - 重启数据库服务：执行
systemctl restart mysql或service mysql restart。
Qt和服务器建立数据库连接常见问题
问题1：Qt编译时显示“Driver not loaded”怎么办？
先运行程序，用QSqlDatabase::drivers()打印可用驱动列表，如果列表里没有QMYSQL，说明你的Qt安装时没有勾选MySQL驱动插件，在Linux上可以安装libqt5sql5-mysql（或对应Qt6版本）包；Windows上则需要从Qt安装工具里添加Qt SQL组件，将MySQL的客户端动态库文件（如libmysql.dll）放到程序可执行文件所在目录,也能解决部分加载问题。
问题2：连接过程中总是超时，但同一台电脑用命令行又能连上？
这种情况很像端口被防火墙拦截，但命令行能连上说明端口是通的，更多原因在于你写的连接参数有误，比如setHostName填成了localhost而实际服务器IP是外网地址，或者setPort没有调用，默认端口变成0，还有一种可能是Qt程序所在机器的DNS解析慢,试试直接填IP字符串。
问题3：为什么我的数据库连接在多线程里经常崩溃？
因为QSqlDatabase不是线程安全的，一个连接实例同时只能被一个线程使用，正确做法是每个线程分别创建自己的连接，或者使用QThreadStorage保存线程私有连接，连接池的跨线程分配要格外小心，最好与线程ID绑定，避免连接被多个线程交替使用，频繁地创建和销毁连接不仅慢,还可能因为底层库的清理机制导致崩溃。
首发原创文章，作者：王坚，如若转载，请注明出处：https://idctop.com/article/593665.html
