MacOS下Qt连接SQL Server时QODBC驱动加载失败求助

问题描述 #

在MacBook上开发Qt项目，需与Docker部署的本地MS SQL Server数据库（地址localhost:1433）交互，连接时出现驱动未加载错误，尽管可用驱动列表中显示包含QODBC。

错误信息 #

qt.sql.qsqldatabase: QSqlDatabase: QODBC driver not loaded
qt.sql.qsqldatabase: QSqlDatabase: available drivers: QSQLITE QODBC QPSQL QMIMER
true

连接代码 #

void login::on_pushButton_clicked()
{
    db = QSqlDatabase::addDatabase("QODBC");
    //db.setDatabaseName("DRIVER={SQL Server};SERVER="+ui->lineEdit->text()+";DATABASE="+ui->lineEdit_2->text()+";");
    //db.setDatabaseName("DRIVER={ODBC Driver 18 for SQL Server};SERVER="
    //+ ui->lineEdit->text() + ";DATABASE=" + ui->lineEdit_2->text() + ";TrustServerCertificate=Yes;");

    db.setHostName("127.0.0.1");
    db.setPort(1433);
    db.setUserName("sa");
    db.setPassword("DB_Password");
    db.setDatabaseName("master");

    qDebug() << db.isDriverAvailable("QODBC");

    //db.setUserName(ui->label_3->text());
    //db.setPassword(ui->lineEdit_4->text());

    if (db.open()) {
        mes->setText("Success!");
    } else {
        mes->setText("Error");
    }

    mes->show();
}

已尝试操作 #

• 重新安装Qt及驱动，配置环境变量：

  export DYLD_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_LIBRARY_PATH"
  export ODBCINI=/usr/local/etc/odbc.ini 
  export ODBCINSTINI=/usr/local/etc/odbcinst.ini 
  source ~/.zshrc 
  

• 编译Qt的QODBC驱动插件：

  cd /path/to/Qt/Src/qtbase/src/plugins/sqldrivers/odbc 
  qmake "INCLUDEPATH+=/opt/homebrew/include" "LIBS+=-L/opt/homebrew/lib -lodbc" 
  make 
  cp libqsqlodbc.dylib /path/to/Qt/plugins/sqldrivers/
  

系统配置信息 #

执行odbcinst -j输出：

unixODBC 2.3.12
DRIVERS............: /opt/homebrew/etc/odbcinst.ini
SYSTEM DATA SOURCES: /opt/homebrew/etc/odbc.ini
FILE DATA SOURCES..: /opt/homebrew/etc/ODBCDataSources
USER DATA SOURCES..: /Users/artempervyh/.odbc.ini
SQLULEN Size.......: 8
SQLLEN Size........: 8
SQLSETPOSIROW Size.: 8

cat /opt/homebrew/etc/odbcinst.ini输出：

[ODBC Driver 18 for SQL Server]
Description=Microsoft ODBC Driver 18 for SQL Server
Driver=/opt/homebrew/lib/libmsodbcsql.18.dylib
UsageCount=2

解决方案 #

1. 确认驱动插件兼容性 #

检查编译生成的libqsqlodbc.dylib是否与当前Qt版本、系统架构（Intel/Apple Silicon）匹配：

file /path/to/Qt/plugins/sqldrivers/libqsqlodbc.dylib

确保输出包含当前系统架构（Apple Silicon为arm64，Intel为x86_64）。

2. 修正环境变量路径 #

环境变量中配置的ODBC文件路径与实际路径不符，需修正：

export ODBCINI=/opt/homebrew/etc/odbc.ini
export ODBCINSTINI=/opt/homebrew/etc/odbcinst.ini
export DYLD_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_LIBRARY_PATH"

修改后重启Qt Creator或终端，确保变量生效。

3. 调整数据库连接字符串 #

QODBC驱动依赖完整的ODBC连接字符串，替换原有分散的HostName/Port设置：

db.setDatabaseName("DRIVER={ODBC Driver 18 for SQL Server};SERVER=127.0.0.1,1433;DATABASE=master;UID=sa;PWD=DB_Password;TrustServerCertificate=Yes;");

注意：端口需用逗号与服务器地址分隔，添加TrustServerCertificate=Yes适配Docker SQL Server的自签名证书。

4. 验证ODBC基础连接 #

使用isql工具测试ODBC连接是否正常，排除Qt之外的问题：

isql -v "ODBC Driver 18 for SQL Server" sa DB_Password

若连接失败，优先排查ODBC驱动本身的配置问题。

5. 检查Qt插件加载路径 #

在代码中添加调试输出，确认Qt插件加载路径包含目标目录：

qDebug() << QCoreApplication::libraryPaths();

确保/path/to/Qt/plugins在列表中，且sqldrivers目录下的libqsqlodbc.dylib拥有正确读写权限。

内容的提问来源于stack exchange，提问作者lzrtefactl