PySpark连接SQL Server LocalDB实例失败求助

问题背景 #

已通过PYODBC成功连接SQL Server 2019 LocalDB实例（服务器名称：ProjectLocalDB），PYODBC代码如下：

import pyodbc

server = "(LocalDB)\\ProjectLocalDB"
database = "my_db"
trusted_connection = "yes"

conn = pyodbc.connect(
    f"Driver={{ODBC Driver 17 for SQL Server}};"
    f"Server={server};"
    f"Database={database};"
    f"Trusted_Connection={trusted_connection};"
)

cursor = conn.cursor()
cursor.execute("SELECT @@version")
row = cursor.fetchone()
while row:
    print(row[0])
    row = cursor.fetchone()

conn.close()

但相同实例使用PySpark JDBC连接时报错，PySpark代码如下：

from pyspark.sql import SparkSession

server_name = "(LocalDB)\\ProjectLocalDB"
dbname = "my_db"
table_name = "dbo.polls_choice"

jdbc_driver_path = "E:\Program Files\SSMS\sqljdbc_12.6\enu\jars\mssql-jdbc-12.6.1.jre8.jar"

jdbc_url = f"jdbc:sqlserver://{server_name};databaseName={dbname};integratedSecurity=true;loginTimeout=60;"

employees_df = spark.read \
    .format("jdbc") \
    .option("url", jdbc_url) \
    .option("dbtable", table_name) \
    .option("driver", "com.microsoft.sqlserver.jdbc.SQLServerDriver") \
    .load()

错误信息 #

Py4JJavaError: An error occurred while calling o72.load.
com.microsoft.sqlserver.jdbc.SQLServerException: The TCP/IP connection to the host ProjectLocalDB, port 1433 has failed.
Error: "ProjectLocalDB. Verify the connection properties. Make sure that an instance of SQL Server is running on the host and accepting TCP/IP connections at the port. Make sure that TCP connections to the port are not blocked by a firewall.

已尝试操作 #

• 启用SQL Server TCP/IP协议
• 关闭防火墙（已配置允许SQL Server运行）

解决建议 #

1. 明确LocalDB连接机制差异 #

LocalDB默认通过命名管道而非TCP/IP提供服务，ODBC驱动会自动解析LocalDB实例名并映射到对应管道，但JDBC驱动不支持直接解析(LocalDB)\\实例名格式，需显式指定命名管道路径。

2. 获取LocalDB实例的命名管道路径 #

打开命令提示符，执行命令获取实例信息：

sqllocaldb info ProjectLocalDB

在输出中找到Named pipe字段，示例值为：np:\\.\pipe\LOCALDB#ABC123\tsql\query（ABC123为随机生成的实例标识）。

3. 修改JDBC URL使用命名管道 #

将命名管道路径转义后填入JDBC URL，注意路径中的\需替换为\\：

# 替换为实际获取的命名管道路径
named_pipe = "np:\\\\.\\pipe\\LOCALDB#ABC123\\tsql\\query"
jdbc_url = f"jdbc:sqlserver://{named_pipe};databaseName={dbname};integratedSecurity=true;loginTimeout=60;"

4. 确保Spark正确加载JDBC驱动 #

除代码中指定driver参数外，需确保Spark进程能访问JDBC驱动包：

• 方式一：启动Spark时通过--jars参数加载驱动：

  spark-submit --jars "E:\Program Files\SSMS\sqljdbc_12.6\enu\jars\mssql-jdbc-12.6.1.jre8.jar" your_spark_script.py
  

• 方式二：在SparkSession初始化时配置驱动路径：

  spark = SparkSession.builder \
      .appName("LocalDBConnection") \
      .config("spark.driver.extraClassPath", "E:\Program Files\SSMS\sqljdbc_12.6\enu\jars\mssql-jdbc-12.6.1.jre8.jar") \
      .getOrCreate()
  

5. 验证LocalDB实例运行状态 #

执行命令确保目标实例处于运行状态：

sqllocaldb start ProjectLocalDB

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