Python sqlite3 row_factory 如何返回命名字段

用 Python 的 sqlite3 查询数据时，默认每一行都是 tuple，只能写成 row[0]、row[1]。如果希望直接写 row["name"]，最简单的做法是在创建游标前设置 connection.row_factory = sqlite3.Row。它保留索引访问，同时增加按列名访问；如果业务层必须拿到普通字典，再使用自定义工厂。

默认 tuple 为什么不适合直接按字段读取

sqlite3 默认把每行返回为 tuple。它速度直观，但代码把字段含义藏在数字里：一旦调整 SELECT 顺序，row[1] 仍然能运行，却可能读到另一列。先用一个最小查询看清返回形态：

import sqlite3

# 使用内存数据库演示返回类型，不会改动磁盘文件
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE user_profile (id INTEGER, name TEXT)")
con.execute("INSERT INTO user_profile VALUES (?, ?)", (7, "林默"))

# 默认结果按 SELECT 顺序组成 tuple
row = con.execute("SELECT id, name FROM user_profile").fetchone()
print(row[0], row[1])
con.close()  # 示例结束后及时释放连接

如果 SELECT 改成 SELECT name, id，下标含义也随之交换。行工厂的价值，就是把“第几列”转换为“哪个字段”。

把连接级 row_factory 设成 sqlite3.Row

官方推荐优先设置 Connection.row_factory，这样从该连接之后创建的游标会继承配置。sqlite3.Row 支持索引访问、列名访问和 keys()，并且列名访问不区分大小写。

import sqlite3

con = sqlite3.connect(":memory:")
con.row_factory = sqlite3.Row  # 必须放在创建业务游标之前
con.execute("CREATE TABLE user_profile (id INTEGER, name TEXT)")
con.execute("INSERT INTO user_profile VALUES (?, ?)", (7, "林默"))

row = con.execute(
    "SELECT id AS user_id, name FROM user_profile"
).fetchone()

print(row[0])             # 仍可按位置访问
print(row["user_id"])     # 更适合按命名字段访问
print(row.keys())         # 用于确认当前查询实际返回的列名
con.close()               # 不再使用时关闭连接

这里的关键不是把每个游标都单独设置一遍，而是让连接成为统一入口。若一个游标已经创建，再修改连接的 row_factory，那个旧游标仍可能保持原来的返回方式；遇到这种情况应重新创建游标。

需要普通字典时再写自定义 row_factory

sqlite3.Row 适合读取，但它不是普通 dict。如果要直接交给 JSON 序列化、模板层或接口响应，可以根据 cursor.description 中的列名组装字典：

import sqlite3

def dict_factory(cursor, row):
    # description 的第一个元素是每列的名称
    fields = [column[0] for column in cursor.description]
    # 按查询返回顺序把列名和值配成普通字典
    return dict(zip(fields, row))

con = sqlite3.connect(":memory:")
con.row_factory = dict_factory  # 让新游标直接返回 dict
con.execute("CREATE TABLE item (id INTEGER, title TEXT)")
con.execute("INSERT INTO item VALUES (?, ?)", (3, "配置说明"))

item = con.execute(
    "SELECT id AS item_id, title AS display_title FROM item"
).fetchone()
print(item["item_id"], item["display_title"])
con.close()  # 连接由当前示例独占，结束后关闭

自定义工厂的边界也很明确：它只负责“每行如何表示”，不会替你修复 SQL 中的重复列名。连接了多张表时，建议用 SELECT a.id AS user_id, b.id AS order_id 这样的别名主动消除歧义。

列名和游标范围的三个常见坑

还要注意，row_factory 不会改变 SQL 的事务、类型转换或连接生命周期。它只是把“游标拿到的一行 tuple”转换为另一个 Python 对象；连接、游标和查询本身仍要按原来的资源管理方式处理。

相关问题

sqlite3.Row 能不能转成普通字典？

可以使用 dict(row)，也可以在连接初始化时直接采用自定义 dict_factory。前者适合少量转换，后者适合整个数据访问层统一返回。

row_factory 应该设置在连接还是游标上？

需要统一行为时设置在连接上，并且放在创建游标前；只想影响某一个已有游标时，再设置该游标的 row_factory。

为什么推荐给查询列写 AS 别名？

命名字段来自查询结果，不一定等于表字段名。别名能固定接口层字段，避免表连接、表达式或字段改名后让读取代码悄悄取错值。