Python sqlite3用 detect_types 转换日期字段的实现方法

Python 的 sqlite3 不会仅凭“看起来像日期”的字符串自动返回日期对象。要让查询结果变成 datetime.date 或 datetime.datetime，需要先注册转换器，再在连接时设置 detect_types。固定表结构适合 PARSE_DECLTYPES；同一列在不同查询中需要不同解释，或查询包含聚合表达式时，使用 PARSE_COLNAMES 更稳妥。

官方文档地址：https://docs.python.org/3/library/sqlite3.html

先把日期转换链拆成四个环节

SQLite 原生类型只有 NULL、INTEGER、REAL、TEXT 和 BLOB。日期常被保存为 ISO 8601 文本，例如 2026-09-19 或 2026-09-19T10:30:00。读取时，sqlite3 需要通过类型名找到转换器：连接参数决定“在哪里找类型名”，register_converter() 决定“找到后如何构造 Python 对象”。

下面的转换器故意使用清晰的注册名。它返回的是 date 或 datetime，而不是继续返回字符串；函数内部先解码字节，再交给标准库解析。

import datetime as dt
import sqlite3

def convert_date(raw):
    # 转换器接收 bytes，按 ISO 日期构造 date 对象。
    return dt.date.fromisoformat(raw.decode("utf-8"))

def convert_datetime(raw):
    # 仅适用于不含时区偏移的 ISO 日期时间文本。
    return dt.datetime.fromisoformat(raw.decode("utf-8"))

sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)

固定表结构用 PARSE_DECLTYPES

如果日期列在建表时已经明确声明为 date 或 datetime，连接可以这样配置。PARSE_DECLTYPES 会读取每个列声明的第一个类型词，所以 datetime(6) 会按 datetime 查找转换器。

con = sqlite3.connect(
    "schedule.db",
    detect_types=sqlite3.PARSE_DECLTYPES,
)

con.execute("""
    CREATE TABLE IF NOT EXISTS task_run(
        id INTEGER PRIMARY KEY,
        run_date date NOT NULL,
        started_at datetime NOT NULL
    )
""")

row = con.execute(
    "SELECT run_date, started_at FROM task_run ORDER BY id DESC LIMIT 1"
).fetchone()
if row is not None:
    # 读取后的两个字段分别应是 date 和 datetime 对象。
    run_date, started_at = row
con.close()  # 连接不会因查询结束自动关闭。

这种方式的优点是查询语句简洁，缺点是它依赖表的声明。视图、表达式和 MAX(started_at) 这类生成字段未必携带可用的声明类型，因此不能把所有查询都交给它。

聚合列和临时结果用 PARSE_COLNAMES

PARSE_COLNAMES 把类型名写进查询列别名，例如 "latest [datetime]"。它适合聚合、视图或没有日期声明的表，也能把转换范围限制在本次查询。

con = sqlite3.connect(
    "schedule.db",
    detect_types=sqlite3.PARSE_COLNAMES,
)

row = con.execute(
    'SELECT MAX(started_at) AS "latest [datetime]" FROM task_run'
).fetchone()
if row is not None and row[0] is not None:
    # 方括号中的名称匹配 register_converter 的注册名。
    latest = row[0]
con.close()  # 完成读取后显式释放连接。

别名中的可见名称和方括号类型是两部分：程序看到的列名仍可写成 latest，转换器查找的是 datetime。如果两种标记同时开启，列名标记优先于声明类型。

参数选择、时区和排查清单

遇到“结果还是字符串”时，按四项排查：连接是否传入了 detect_types；注册名大小写和拼写是否一致；数据库里的文本是否符合转换器预期；查询是否是生成字段。转换器始终收到 bytes，不要直接调用只接受字符串的方法。

还要留意版本边界：Python 官方文档已将默认日期/时间适配器和转换器标记为 3.12 起弃用，因此新项目应显式注册自己的规则。默认 timestamp 转换器会忽略 UTC 偏移并返回无时区对象；如果业务需要保留偏移，应禁用这套默认转换或注册能处理偏移的转换器。

常见问题

为什么设置了 detect_types 仍然得到字符串？

最常见原因是没有注册同名转换器，或列声明、别名标记与注册名不一致。先打印返回值类型，再检查连接参数和查询别名。

PARSE_DECLTYPES 能处理 MAX 日期吗？

不要默认依赖它。官方文档提示生成字段可能按字符串返回；对聚合结果使用 PARSE_COLNAMES 并在别名中写入类型名更明确。

date 和 datetime 可以共用一个转换器吗？

不建议。两种文本的精度和目标对象不同，分别注册转换器更容易发现格式错误，也能避免把日期时间误截断。