SQLAlchemy 2.0.4中使用URL类构建MySQL连接URL报错问题

这是SQLAlchemy 2.x版本对URL类构造逻辑的明确调整，和1.x版本的行为存在差异：

1. URL类参数规则的变更
   在SQLAlchemy 2.0及以后版本中，URL.create()方法将query设为必填的 positional-only 参数。而在1.x版本里，这个参数是可选的，默认值为空字典。

2. 字符串URL能正常工作的原因
   当你使用字符串形式的连接URL时，SQLAlchemy内部会自动执行解析逻辑，把字符串转换为URL对象。如果字符串里没有携带查询参数（比如?charset=utf8mb4这类后缀），解析器会自动传入一个空的immutabledict作为query参数，因此不会触发必填参数的报错。

3. 代码示例对比

   • 正常工作的字符串连接方式：

     from sqlalchemy import create_engine
     engine = create_engine("mysql+pymysql://user:password@remote-host:3306/mydb")
     

   • 触发报错的URL类调用（缺少query参数）：

     from sqlalchemy.engine.url import URL
     # 此处会抛出TypeError，因为缺少必填的query参数
     url = URL.create(
         drivername="mysql+pymysql",
         username="user",
         password="password",
         host="remote-host",
         port=3306,
         database="mydb"
     )
     

   • 正确的URL类调用（传入空query参数）：

     url = URL.create(
         drivername="mysql+pymysql",
         username="user",
         password="password",
         host="remote-host",
         port=3306,
         database="mydb",
         query={}  # 即使没有查询参数，也必须显式传入空字典
     )
     engine = create_engine(url)
     

4. 设计层面的原因
   SQLAlchemy团队做这个变更，是为了强制开发者明确处理查询参数的逻辑，避免隐式默认值带来的潜在混淆。比如有些场景下需要传递ssl、charset等连接配置，显式传入query参数能让代码意图更清晰，同时统一了URL对象的构建规则。

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