4、连接MySQL数据库：安装配置MySQL驱动（QMYSQL）、创建数据库连接、处理连接错误、设置连接参数（主机、端口、用户、密码、字符集）

在Qt应用中访问MySQL数据库，核心环节是正确加载QMYSQL驱动插件、配置连接参数并建立可靠的数据库会话。与SQLite这种嵌入式数据库不同，MySQL采用客户端-服务器架构，Qt程序作为客户端通过网络协议与MySQL服务端通信。这一章我们将深入讲解从驱动安装、连接创建到错误处理与参数调优的完整链路，帮助你在实际项目中快速、稳定地接入MySQL。

4.1 核心原理：Qt 数据库驱动架构与 QMYSQL 插件机制

Qt 的数据库模块采用插件化架构设计。QSqlDatabase 类本身不直接与具体数据库通信，而是通过加载对应的驱动插件（如 QMYSQL、QPSQL、QODBC）来桥接 Qt 应用与数据库客户端库。对于 MySQL，QMYSQL 驱动插件在 Windows 平台对应 qsqlmysql.dll，在 Linux/macOS 平台对应 libqsqlmysql.so 或 libqsqlmysql.dylib。该插件内部封装了 MySQL 官方 C API（libmysqlclient 或 MariaDB Connector/C），通过标准 TCP/IP 协议与 MySQL 服务端交互。

理解这一架构对排障至关重要。很多初学者遇到 "Driver not loaded" 错误时，往往误以为是代码问题，实际上绝大多数情况是驱动插件缺失、路径不正确或依赖库（libmysqlclient）未找到。Qt 在运行时通过 QCoreApplication::libraryPaths() 搜索插件目录，默认在 Qt 安装目录的 plugins/sqldrivers 下。如果应用部署到其他机器，必须将驱动插件和 MySQL 客户端库一并拷贝到可执行文件同级目录的 sqldrivers 文件夹中。

4.2 操作流程：从驱动配置到建立连接的完整步骤

建立 MySQL 连接需要遵循固定的操作序列，每一步都有对应的验证点。下面给出标准流程，并附上关键代码片段。

步骤一：确认驱动可用性

// 检查驱动是否可用
QStringList availableDrivers = QSqlDatabase::drivers();
if (!availableDrivers.contains("QMYSQL")) {
    qCritical() << "QMYSQL driver not available!";
    return;
}

步骤二：创建并配置连接对象

// 创建连接（连接名可自定义，默认使用默认连接）
QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL", "main_connection");

// 设置连接参数
db.setHostName("192.168.1.100");      // 主机地址
db.setPort(3306);                     // 端口号
db.setUserName("app_user");           // 用户名
db.setPassword("SecurePass!2024");    // 密码
db.setDatabaseName("erp_system");     // 数据库名

// 设置连接选项（可选）
db.setConnectOptions("MYSQL_OPT_RECONNECT=1;MYSQL_OPT_CONNECT_TIMEOUT=5");

步骤三：打开连接并验证状态

if (!db.open()) {
    // 连接失败，获取详细错误信息
    QSqlError err = db.lastError();
    qCritical() << "Connection failed:" << err.text();
    qCritical() << "Database error code:" << err.nativeErrorCode();
} else {
    qInfo() << "MySQL connected successfully!";
    // 验证连接是否真正可用
    QSqlQuery query(db);
    query.exec("SELECT VERSION()");
    if (query.next()) {
        qInfo() << "MySQL version:" << query.value(0).toString();
    }
}

步骤四：使用完毕后关闭连接

// 关闭连接并移除连接对象
db.close();
QSqlDatabase::removeDatabase("main_connection");

配置项	方法	典型值	说明
主机	setHostName()	127.0.0.1 / 域名	本地连接可用 localhost，远程需 IP 或域名
端口	setPort()	3306	MySQL 默认端口，可自定义
用户名	setUserName()	root / 业务账号	建议使用最小权限账号
密码	setPassword()	强密码	生产环境建议加密存储
数据库名	setDatabaseName()	业务库名	可选，可在 SQL 中指定
字符集	setConnectOptions()	utf8mb4	通过 MYSQL_SET_CHARSET_NAME 设置

4.3 案例拆解：生产环境 MySQL 连接配置与排障实战

某制造业企业的 MES 系统需要从 Qt 客户端连接部署在 Linux 服务器上的 MySQL 8.0 数据库。初始现象是：开发环境（Windows + Qt 5.15）连接正常，但部署到产线工控机（Windows 10 精简版）后，程序启动时报 "QSqlDatabase: QMYSQL driver not loaded" 错误。

分析判断过程：首先在工控机上运行 QSqlDatabase::drivers() 输出，发现列表中没有 QMYSQL。进一步检查 Qt 安装目录下的 plugins/sqldrivers 文件夹，发现 qsqlmysql.dll 存在，但程序运行时并未加载。使用 Dependency Walker 工具检查 qsqlmysql.dll 的依赖，发现缺少 libmysql.dll（MySQL 客户端库）。

实际操作步骤：

1. 从 MySQL 安装目录的 lib 文件夹中拷贝 libmysql.dll 到 Qt 的 bin 目录（与 Qt5Cored.dll 同级）。
2. 将 plugins/sqldrivers 整个文件夹拷贝到可执行文件同级目录下，确保相对路径正确。
3. 在 main.cpp 中显式添加插件路径：QCoreApplication::addLibraryPath("./plugins");
4. 重新运行程序，连接成功。

结果对比：修复前程序无法启动数据库功能，修复后连接耗时约 80ms，查询响应正常。同时发现工控机系统缺少 VC++ 运行库，一并安装后彻底解决。

风险与代价：如果直接静态编译 Qt 的 MySQL 驱动，虽然可以避免 DLL 依赖问题，但会增加部署包体积约 15MB，且升级 MySQL 客户端库时需要重新编译。动态部署方案更灵活，但必须确保目标机器具备所有运行库。

4.4 连接参数深度解析：字符集与连接选项

字符集设置是中文应用最容易踩坑的地方。MySQL 默认字符集在 8.0 版本为 utf8mb4，但旧库可能使用 latin1 或 gbk。如果 Qt 客户端与 MySQL 服务端字符集不一致，会出现中文乱码。推荐在连接选项中显式指定字符集：

// 方式一：通过连接选项设置
db.setConnectOptions("MYSQL_SET_CHARSET_NAME=utf8mb4");

// 方式二：连接后执行 SET NAMES
QSqlQuery query(db);
query.exec("SET NAMES 'utf8mb4' COLLATE 'utf8mb4_unicode_ci'");

连接选项还可以设置其他重要参数：

• MYSQL_OPT_RECONNECT=1：自动重连，适合长时间运行的应用
• MYSQL_OPT_CONNECT_TIMEOUT=5：连接超时（秒），避免网络异常时卡死
• MYSQL_OPT_READ_TIMEOUT=10：读超时
• MYSQL_OPT_WRITE_TIMEOUT=10：写超时
• MYSQL_INIT_COMMAND=SET NAMES utf8mb4：连接建立后自动执行初始化命令

4.5 常见误区与总结复盘

误区	后果	正确做法
忽略驱动插件部署	目标机器报 "Driver not loaded"	部署时携带 sqldrivers 目录及依赖库
使用 root 账号连接业务库	安全风险高，权限过大	创建最小权限专用账号
不设置连接超时	网络异常时界面卡死	设置 MYSQL_OPT_CONNECT_TIMEOUT
字符集不统一	中文乱码	统一使用 utf8mb4
连接未关闭就 removeDatabase	程序崩溃或资源泄漏	先 close() 再 removeDatabase()
每次查询都新建连接	性能极差	使用连接池或复用连接

总结复盘：连接 MySQL 的核心要点可以归纳为"三查三设"——查驱动、查依赖、查权限；设参数、设字符集、设超时。在实际项目中，建议将数据库连接封装为单例类，统一管理连接生命周期，并记录连接日志（时间、IP、用户、耗时），便于后续排查问题。对于千万级数据分页展示场景，连接稳定性比连接速度更重要，务必开启自动重连并设置合理的超时时间。