如何用Polars/ConnectorX连接SQL Server避免超时并生成Polars DataFrame

问题重现 #

使用Polars或ConnectorX连接SQL Server时触发以下错误：

RuntimeError: Timed out in bb8

代码示例：

import pandas as pd
import polars as pl
import connectorx as cx

user='my_user'
password='my_password'
server='my_server'
database='my_database'

conn =f"mssql+pyodbc://{user}:{password}@{server}/{database}"

query = "SELECT * FROM [dbo].[my_table]"

# ConnectorX执行报错
df = cx.read_sql(conn,query)

# Polars执行同样报错
df = pl.read_sql(query,conn)

需求：直接获取Polars DataFrame，不通过pl.from_pandas()中转。

解决方案 #

1. 补全ODBC驱动与超时参数 #

SQL Server的ODBC连接需显式指定驱动版本，同时通过延长超时参数避免连接池等待超时：

# 替换为你的ODBC驱动版本（如ODBC Driver 17 for SQL Server）
driver = "ODBC Driver 17 for SQL Server"
# 转义空格并添加超时参数
conn = f"mssql+pyodbc://{user}:{password}@{server}/{database}?driver={driver.replace(' ', '+')}&login_timeout=30&timeout=60"

# Polars直接读取
df = pl.read_sql(query, conn)

2. 用SQLAlchemy引擎优化连接配置 #

通过SQLAlchemy引擎设置连接池参数，增强连接稳定性：

from sqlalchemy import create_engine

engine = create_engine(
    conn,
    pool_pre_ping=True,  # 检测无效连接并重建
    pool_recycle=300,    # 自动回收闲置连接
    pool_timeout=30      # 连接池等待超时时间
)

# Polars直接读取
df = pl.read_sql(query, engine)

3. ConnectorX专属配置（无需Pandas中转） #

ConnectorX支持直接返回Arrow格式，可无缝转换为Polars DataFrame，同时添加专属超时参数：

# ConnectorX专用连接字符串
conn_cx = f"mssql://{user}:{password}@{server}/{database}?driver={driver.replace(' ', '+')}&cx_timeout=60"
# 返回Arrow格式，直接转为Polars DataFrame
pl_df = pl.from_arrow(cx.read_sql(conn_cx, query, return_type="arrow"))

4. 排查SQL Server网络配置 #

• 确认SQL Server已开启TCP/IP远程连接
• 检查防火墙是否放行SQL Server默认端口（1433）
• 用SSMS等工具测试服务器连通性，验证账号、地址、数据库名正确性

5. 优化查询避免数据量过大超时 #

若因查询数据量过大触发超时，可先缩小范围测试：

• 限制行数：SELECT TOP 1000 * FROM [dbo].[my_table]
• 过滤数据：添加WHERE条件缩小查询范围
• 指定列：避免SELECT *，只查询需要的字段

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