Jupyter Notebook中SQL引擎正常，SQL魔法连接SQL Server失败

问题详情 #

• 已在64位ODBC数据源管理器中创建名为jupyterCMS的系统DSN（使用SQL Server驱动），连接测试成功。
• SQLAlchemy连接引擎可正常工作，代码如下：

  from getpass import getpass
  from urllib.parse import quote_plus
  import pandas as pd
  from sqlalchemy import create_engine
  
  username = 'username'
  quoted_password = quote_plus(getpass('Input Password: '))
  server_name = 'servername'
  database_name = 'dbname'
  
  connection_string = f"mssql+pyodbc://{username}:{quoted_password}@jupyterCMS"
  engine = create_engine(connection_string)
  connection = engine.connect()
  

• 已验证连接引擎正常：通过inspect获取到数据库中的正确表名，验证代码：

  from sqlalchemy import inspect
  
  inspector = inspect(engine)
  for table in inspector.get_table_names():
      print(table, end=', ')
  

• 使用IPython SQL魔法连接失败，代码：

  %load_ext sql
  %sql mssql+pyodbc://[username]:[password]@jupyterCMS #实际使用完整用户名和密码
  

• 报错信息：

  MetaData.init() got an unexpected keyword argument 'bind'
  Connection info needed in SQLAlchemy format, example:
  postgresql://username:password@hostname/dbname
  or an existing connection: dict_keys([])

• 预期输出：

  'Connected: username@None'

已尝试去掉用户名和密码的括号、更换不同驱动创建DSN，均无效，且密码无特殊字符。

解决方案 #

1. 核心原因：版本不兼容 #

报错MetaData.__init__() got an unexpected keyword argument 'bind'是因为SQLAlchemy 2.0+版本移除了MetaData类的bind参数，而旧版本的ipython-sql（低于0.4.1）仍在调用该参数，导致冲突。

2. 升级ipython-sql到兼容版本 #

执行以下命令升级：

pip install --upgrade ipython-sql

升级后重新加载SQL魔法并尝试连接即可。

3. 复用已有的SQLAlchemy引擎（替代方案） #

如果升级后仍有问题，可以直接复用已经验证有效的SQLAlchemy引擎，绕开连接字符串解析的问题：

%load_ext sql
%sql engine

这里的engine就是你之前创建并验证过的连接引擎对象。

4. 检查连接字符串格式 #

确保连接字符串中用户名和密码没有多余符号，正确格式应为：

%sql mssql+pyodbc://your_real_username:your_real_password@jupyterCMS

不要给用户名和密码加方括号。

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