使用Pandas read_sql带参数操作PostgreSQL时遇TypeError错误排查

问题场景 #

你尝试用Pandas的read_sql执行带参数的SQL查询，编写了如下代码：

import pandas as pd
from sqlalchemy import create_engine

engine = create_engine('postgresql:///mydb')
conn = engine.connect()
sql = '''
SELECT id, name, age FROM person WHERE name=%{name}s
'''

df = pd.read_sql(sql, conn, params={'name': 'John Doe'})
print(df)

运行时抛出TypeError: dict is not a sequence错误，但你认为这段代码符合Pandas文档要求。

你已经找到了解决方案：用SQLAlchemy的text()包裹SQL语句，使用:name风格的占位符：

import pandas as pd
from sqlalchemy import create_engine, text

engine = create_engine('postgresql:///mydb')
conn = engine.connect()
sql = '''
SELECT id, name, age FROM person WHERE name=:name
'''

df = pd.read_sql(text(sql), conn, params={'name': 'John Doe'})
print(df)

但想知道第一种方法的错误原因。

错误原因分析 #

第一种方法出错有两个核心问题：

1. 占位符语法错误：你使用了%{name}s作为命名占位符，但PostgreSQL的DBAPI驱动（psycopg2）要求的命名参数格式是%(name)s（圆括号而非大括号）。错误的占位符格式导致驱动无法识别这是命名参数，转而将其当作位置参数处理，此时要求params是序列（列表/元组），但你传入了字典，因此抛出dict is not a sequence错误。
2. 参数处理逻辑差异：当直接给read_sql传入字符串形式的SQL时，Pandas会将参数直接传递给底层DBAPI驱动处理，而不是用SQLAlchemy的参数解析逻辑。DBAPI驱动的参数规则和SQLAlchemytext()对象的规则不统一：
   • DBAPI（如psycopg2）的命名参数用%(name)s，位置参数用%s
   • SQLAlchemytext()对象的命名参数统一用:name，跨数据库兼容

修正第一种方法的方案 #

如果你不想用text()，只需修正占位符格式为DBAPI要求的%(name)s即可：

import pandas as pd
from sqlalchemy import create_engine

engine = create_engine('postgresql:///mydb')
conn = engine.connect()
sql = '''
SELECT id, name, age FROM person WHERE name=%(name)s
'''

df = pd.read_sql(sql, conn, params={'name': 'John Doe'})
print(df)

总结 #

推荐使用text()+:name的方式，因为它能实现跨数据库的参数语法统一，避免依赖特定DBAPI的规则。而第一种方法的核心错误是占位符语法写错，导致驱动无法正确解析字典类型的参数。

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