SQLite的VALUES子句主要用于构造行值集合，常见于INSERT语句和CTE临时表场景中，很多开发者在使用过程中会因为对语法细节不熟悉，或者参数传递方式错误，遇到各类异常问题。
VALUES基础语法规范
标准的VALUES语法用于定义一行或多行数据，每一行数据需要用括号包裹，多个行之间用逗号分隔，基础语法结构如下：
-- 单行插入
INSERT INTO user (name, age) VALUES ('张三', 20);
-- 多行插入
INSERT INTO user (name, age) VALUES ('李四', 22), ('王五', 25);
在使用VALUES时，需要注意每个括号对应一行数据，行内的值的数量需要和表字段数量匹配，否则会直接触发语法错误。
常见VALUES语法错误场景
1. 括号使用不规范
很多开发者会在VALUES后直接写值而不加括号，或者多行插入时只对最后一行加括号，这类写法不符合SQLite的语法要求，会直接返回错误。
-- 错误写法：缺少括号
INSERT INTO user (name, age) VALUES '赵六', 28;
-- 错误写法：多行插入时括号不完整
INSERT INTO user (name, age) VALUES ('孙七', 30), '周八', 32;
上述两种写法都会触发near "赵六": syntax error或者near "周八": syntax error的报错，正确写法需要给每一行数据都添加独立的括号。
2. 行值数量和字段数量不匹配
当INSERT语句指定的字段数量和VALUES中每行的值数量不一致时，SQLite会返回table user has 2 columns but 1 values were supplied的报错，这类错误在批量插入时更容易出现。
-- 错误写法：字段有2个，值只有1个
INSERT INTO user (name, age) VALUES ('吴九');
参数传递常见陷阱
1. 占位符格式错误
SQLite支持?和@name两种参数占位符，很多开发者会混用其他数据库的占位符格式，比如使用:name或者$name，这类写法在SQLite中无法被正确识别，会导致参数绑定失败。
import sqlite3
conn = sqlite3.connect('test.db')
cursor = conn.cursor()
# 正确占位符写法
cursor.execute("INSERT INTO user (name, age) VALUES (?, ?)", ('郑十', 35))
# 错误占位符写法，会触发参数绑定错误
cursor.execute("INSERT INTO user (name, age) VALUES (:name, :age)", {'name': '冯十一', 'age': 36})
2. 批量插入时参数格式错误
使用executemany方法批量插入数据时，参数需要是包含多个元组的列表，每个元组对应一行数据，很多开发者会错误地传递单个元组或者字典列表，导致参数数量不匹配。
import sqlite3
conn = sqlite3.connect('test.db')
cursor = conn.cursor()
# 正确批量插入参数
data = [('陈十二', 38), ('褚十三', 40)]
cursor.executemany("INSERT INTO user (name, age) VALUES (?, ?)", data)
# 错误参数：传递单个元组，会触发参数数量错误
wrong_data = ('卫十四', 42)
cursor.executemany("INSERT INTO user (name, age) VALUES (?, ?)", wrong_data)
3. 特殊字符转义问题
当插入的数据包含单引号时，如果没有正确转义，会破坏SQL语句结构，导致语法错误。正确的做法是通过参数绑定的方式传递数据，而不是手动拼接SQL字符串。
import sqlite3
conn = sqlite3.connect('test.db')
cursor = conn.cursor()
# 错误写法：手动拼接SQL，单引号会导致语法错误
name = "O'Neil"
cursor.execute(f"INSERT INTO user (name, age) VALUES ('{name}', 45)")
# 正确写法：使用参数绑定，自动处理转义
cursor.execute("INSERT INTO user (name, age) VALUES (?, ?)", (name, 45))
问题排查方法
当遇到VALUES相关的错误时，可以按照以下步骤排查：
- 首先检查VALUES后每一行是否都用括号包裹，多行插入时逗号分隔是否正确
- 核对每行值的数量和INSERT指定的字段数量是否一致
- 检查参数占位符是否符合SQLite的规范，批量插入时参数格式是否正确
- 避免手动拼接SQL字符串，优先使用参数绑定的方式传递数据
通过以上方法可以快速定位大部分VALUES语法和参数传递相关的问题，减少开发过程中的调试成本。