Flask-SQLAlchemy连接远程MSSQL失败：用户登录错误（macOS）

我之前在High Sierra上折腾过一模一样的场景，给你一步步排查和解决的方案：

1. 先验证FreeTDS本身是否能连通服务器 #

FreeTDS是底层的连接组件，先确保它能正常工作：

• 找到FreeTDS的配置文件（brew安装的话路径是/usr/local/etc/freetds.conf），添加服务器配置：

  [my_mssql_server]
      host = 你的服务器IP或域名
      port = 1433
      tds version = 7.3
  

• 执行测试命令：

  tsql -S my_mssql_server -U 你的用户名 -P 你的密码
  

  如果能进入SQL命令行，说明FreeTDS没问题；如果报错，先解决FreeTDS的连通问题（比如服务器防火墙、网络、tds版本不兼容）。

2. 测试pyodbc单独连接 #

跳过Flask-SQLAlchemy，直接用pyodbc测试连接，排除ORM层的问题：

import pyodbc
# 注意这里的DRIVER要加大括号，参数名是大写
conn_str = (
    'DRIVER={FreeTDS};'
    'SERVER=你的服务器IP或域名;'
    'PORT=1433;'
    'DATABASE=你的数据库名;'
    'UID=你的用户名;'
    'PWD=你的密码;'
    'TDS_Version=7.3'
)
conn = pyodbc.connect(conn_str)
cursor = conn.cursor()
cursor.execute("SELECT 1")
print(cursor.fetchone())

如果这段代码能正常输出(1,)，说明pyodbc配置正确，问题出在SQLAlchemy的URI上。

3. 修正Flask-SQLAlchemy的URI配置 #

你原来的URI可能存在两个问题：

• 参数格式问题：pyodbc的URI中，driver需要用大括号包裹，且部分参数的写法要符合SQLAlchemy的规范
• 特殊字符编码：如果用户名/密码包含@、&等特殊字符，必须URL编码

修正后的URI写法有两种：

写法一：直接构造编码后的URI #

from urllib.parse import quote_plus

username = quote_plus("你的用户名")
password = quote_plus("你的密码")
server = "你的服务器IP或域名"
db_name = "你的数据库名"

app.config['SQLALCHEMY_DATABASE_URI'] = (
    f'mssql+pyodbc://{username}:{password}@{server}:1433/{db_name}?'
    'driver={FreeTDS}&tds_version=7.3'
)

注意把port放在server后面（server:1433），而不是作为查询参数，部分SQLAlchemy版本对后者的解析有问题。

写法二：使用ODBC连接字符串格式 #

如果上面的写法还是报错，可以试试用?odbc_connect=参数直接传入完整的pyodbc连接字符串：

from urllib.parse import quote_plus

conn_str = (
    'DRIVER={FreeTDS};'
    'SERVER=你的服务器IP或域名;'
    'PORT=1433;'
    'DATABASE=你的数据库名;'
    'UID=你的用户名;'
    'PWD=你的密码;'
    'TDS_Version=7.3'
)
encoded_conn_str = quote_plus(conn_str)
app.config['SQLALCHEMY_DATABASE_URI'] = f'mssql+pyodbc:///?odbc_connect={encoded_conn_str}'

这种写法更直接，避免SQLAlchemy对URI参数的解析问题。

4. 检查依赖版本兼容性 #

• 确保你安装的是适配Python3的版本：

  pip3 install --upgrade flask flask-sqlalchemy pyodbc
  

• FreeTDS建议用brew安装最新兼容7.3版本的：

  brew install freetds
  

如果按照上面的步骤还是报错，把完整的错误信息贴出来（比如pyodbc后面的具体错误内容），能更精准定位问题。

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