使用psycopg2的SQL模块构造INSERT语句时如何指定列名

核心实现逻辑 #

psycopg2的sql模块中，表名、列名这类数据库标识符必须通过sql.Identifier封装后，用format方法拼接到SQL结构中——这是模块的安全设计，既可以避免SQL注入，也能自动适配PostgreSQL的标识符转义规则。
之前的示例代码只对表名做了标识符替换，SQL模板里完全遗漏了列名的拼接位置，自然没法控制插入的目标列。

分场景代码示例 #

全列插入（对应原生SQL INSERT INTO my_table (col1, col2, col3) VALUES (1,2,3)） #

先定义列名列表和对应的值列表，再通过模块方法安全拼接SQL结构：

import psycopg2
from psycopg2 import sql

# 定义需要插入的目标列
target_cols = ['col1', 'col2', 'col3']
# 定义和列一一对应的待插入值
target_vals = [1, 2, 3]

# 安全拼接列名片段：自动生成带转义的列名结构，比如 ("col1", "col2", "col3")
col_fragment = sql.SQL('({})').format(
    sql.SQL(', ').join(map(sql.Identifier, target_cols))
)
# 安全拼接值占位片段：自动生成和列数匹配的参数占位，比如 %s, %s, %s
val_fragment = sql.SQL('({})').format(
    sql.SQL(', ').join(sql.Placeholder() * len(target_vals))
)

cur.execute(
    sql.SQL("INSERT INTO {} {} VALUES {}").format(
        sql.Identifier('my_table'),
        col_fragment,
        val_fragment
    ),
    target_vals
)

这里用sql.Placeholder()替代硬写的%s，好处是当列数动态变化时，不需要手动数占位符数量，只要列列表和值列表长度对齐即可，减少手写错误。

仅插入指定列（比如只给col3赋值） #

这套构造逻辑是通用的，只需要调整传入的列名列表和对应值列表即可，不需要修改核心拼接逻辑：

# 只指定要插入的col3列
target_cols = ['col3']
# 对应col3的待插入值
target_vals = [3]

# 后续SQL拼接、execute执行逻辑和上面的全列插入完全一致
col_fragment = sql.SQL('({})').format(
    sql.SQL(', ').join(map(sql.Identifier, target_cols))
)
val_fragment = sql.SQL('({})').format(
    sql.SQL(', ').join(sql.Placeholder() * len(target_vals))
)

cur.execute(
    sql.SQL("INSERT INTO {} {} VALUES {}").format(
        sql.Identifier('my_table'),
        col_fragment,
        val_fragment
    ),
    target_vals
)

最终这段代码生成的原生SQL为INSERT INTO my_table ("col3") VALUES (3)，未指定的列会自动按照表定义的默认值、空值约束规则处理，完全符合预期。

常见踩坑提醒 #

• 不要直接把列名硬拼到SQL模板字符串里。哪怕是写死的列名，这种写法也存在隐患：后续如果改成动态读取列名的逻辑，硬拼字符串会直接引入SQL注入风险；同时sql.Identifier会自动处理大小写敏感、关键字冲突的转义，比手写字符串的兼容性更好。
• 不要把值占位的%s用sql.Identifier封装。所有实际传入的业务值必须通过execute方法的第二个参数列表做绑定，直接拼到SQL字符串里既不安全，也容易出现类型转换错误。

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