使用Python(pyodbc)执行SQL Merge时参数不匹配错误求助

核心原因 #

pyodbc使用?作为位置参数占位符，每个?都会被计数为一个独立的参数，哪怕你在SQL语句中重复引用同一个逻辑值。而SSMS中可以通过变量复用同一个值，不会重复计数，这是导致参数数量不匹配的关键差异。

具体解决步骤 #

1. 核对SQL中的参数标记数量 #

先确认终端打印的Merge语句里?的总数，比如报错提示的10个，意味着你需要传递10个参数值——哪怕其中某些值是重复的。
举个典型的Merge语句示例（对应10个?的场景）：

MERGE INTO TargetTable t
USING (VALUES (?, ?, ?, ?, ?)) s(Col1, Col2, Col3, Col4, Col5)
ON t.Col1 = s.Col1
WHEN MATCHED THEN
    UPDATE SET t.Col2 = ?, t.Col3 = ?, t.Col4 = ?, t.Col5 = ?
WHEN NOT MATCHED THEN
    INSERT (Col1) VALUES (?);

这里?总数为5（源表值）+4（更新字段）+1（插入字段）=10，此时必须传递10个参数值，而非5个。

2. 修正参数传递逻辑 #

把每个?对应的参数值依次补充到参数列表中，哪怕是重复的值。比如原始参数组是data = [val1, val2, val3, val4, val5]，对应上述10个?的场景，参数列表需要扩展为：

params = data + [val2, val3, val4, val5] + [val1]
cursor.execute(merge_sql, params)

3. 可选：使用命名参数（需驱动支持） #

如果不想重复传值，可以尝试使用pyodbc的命名参数（SQL Server ODBC驱动通常支持），用:param_name作为占位符，然后传递字典作为参数：

MERGE INTO TargetTable t
USING (VALUES (:col1, :col2, :col3, :col4, :col5)) s(Col1, Col2, Col3, Col4, Col5)
ON t.Col1 = s.Col1
WHEN MATCHED THEN
    UPDATE SET t.Col2 = :col2, t.Col3 = :col3, t.Col4 = :col4, t.Col5 = :col5
WHEN NOT MATCHED THEN
    INSERT (Col1) VALUES (:col1);

执行时传递字典参数：

params = {
    "col1": val1,
    "col2": val2,
    "col3": val3,
    "col4": val4,
    "col5": val5
}
cursor.execute(merge_sql, params)

4. 验证参数数量 #

执行前可以打印参数列表长度和SQL中?的数量，确认两者一致：

print(f"SQL参数标记数: {merge_sql.count('?')}")
print(f"提供的参数数量: {len(params)}")

额外排查点 #

• 检查SQL语句是否有拼写错误：比如多写/遗漏?，导致计数偏差
• 若使用SQLAlchemy执行原生SQL：需用text()包裹语句，且参数绑定要遵循相同规则，避免参数传递不完整

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