Python日志SQL查询报错：IndexError: 替换索引超出位置参数元组范围

先解决你遇到的IndexError #

你触发的IndexError大概率是因为手动替换SQL占位符时逻辑错误——比如把SQL里的?当成了Python字符串格式化的占位符（比如%s或{}），但替换方式不对。举个典型的错误示例：

# 错误的日志拼接方式
sql = "UPDATE table SET col1=?, col2=? WHERE id=?"
params = ("val1", "val2", 1)
# 直接用%替换?会报错，因为?不是%的占位符
log_sql = sql % params  # 抛出IndexError或TypeError

或者误用format方法时没解包元组：

log_sql = sql.format(params)  # 把整个元组当成一个参数，导致占位符数量不匹配

快速修复错误 #

如果要手动拼接日志SQL，先把?替换成Python格式化占位符，再解包参数：

sql = "UPDATE table SET col1=?, col2=? WHERE id=?"
params = ("val1", "val2", 1)
# 先把?换成%s，再用%解包参数
log_sql = sql.replace("?", "%s") % params

但这种方式有隐患（比如SQL里本身有%符号时会出错），更稳妥的是用数据库驱动的内置方法。

更优的SQL日志记录方案 #

方案1：用数据库驱动的内置拼接方法（推荐） #

几乎所有Python数据库驱动都提供了将参数化SQL转换为可执行字符串的方法，能自动处理占位符替换、类型转义和特殊字符转义，完全避免手动拼接的错误：

示例（SQLite3）：

import sqlite3
import logging

logging.basicConfig(level=logging.INFO)

def sql_query(conn, sql, params=()):
    # 使用mogrify生成带参数的完整SQL
    log_sql = conn.cursor().mogrify(sql, params).decode("utf-8")
    logging.info(f"Executing SQL: {log_sql}")
    
    # 执行SQL
    cursor = conn.cursor()
    cursor.execute(sql, params)
    conn.commit()
    return cursor

# 调用示例
conn = sqlite3.connect("test.db")
sql_query(conn, "UPDATE users SET name=?, age=? WHERE id=?", ("Alice", 30, 1))

示例（MySQL/mysql-connector）：

import mysql.connector
import logging

logging.basicConfig(level=logging.INFO)

def sql_query(conn, sql, params=()):
    cursor = conn.cursor()
    # mogrify方法同样适用
    log_sql = cursor.mogrify(sql, params).decode("utf-8")
    logging.info(f"Executing SQL: {log_sql}")
    
    cursor.execute(sql, params)
    conn.commit()
    return cursor

示例（PostgreSQL/psycopg2）：

import psycopg2
import logging

logging.basicConfig(level=logging.INFO)

def sql_query(conn, sql, params=()):
    cursor = conn.cursor()
    # psycopg2的mogrify直接返回字节串
    log_sql = cursor.mogrify(sql, params).decode("utf-8")
    logging.info(f"Executing SQL: {log_sql}")
    
    cursor.execute(sql, params)
    conn.commit()
    return cursor

方案2：手动安全替换占位符（无依赖场景） #

如果不想依赖驱动的方法，可以自己实现一个安全的替换函数，处理不同类型参数的转义：

import logging

logging.basicConfig(level=logging.INFO)

def format_sql_for_log(sql, params):
    def escape_param(p):
        # 处理不同类型参数的转义
        if isinstance(p, str):
            # 转义单引号和反斜杠
            return f"'{p.replace('\\', '\\\\').replace('''', '''''')}'"
        elif isinstance(p, (int, float)):
            return str(p)
        elif p is None:
            return "NULL"
        else:
            # 其他类型用repr
            return repr(p)
    
    # 拆分SQL并拼接参数
    sql_parts = sql.split("?")
    if len(sql_parts) != len(params) + 1:
        raise ValueError("占位符数量与参数数量不匹配")
    
    return "".join([part + escape_param(p) for part, p in zip(sql_parts[:-1], params)]) + sql_parts[-1]

# 使用示例
sql = "UPDATE users SET name=?, age=? WHERE id=?"
params = ("Alice O'Neil", 30, 1)
log_sql = format_sql_for_log(sql, params)
logging.info(f"Executing SQL: {log_sql}")

方案3：分开记录SQL模板和参数（轻量方式） #

如果不需要完整的拼接SQL，也可以直接记录SQL模板和参数，这样更简洁且避免拼接错误：

logging.info(f"Executing SQL: {sql}, params: {params}")

这种方式适合调试时快速查看，也不会有占位符替换的问题。

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