Python sqlite3 怎样注册自定义类型适配器

Python sqlite3 注册自定义类型，核心是把读写拆成两个方向：写入时用 sqlite3.register_adapter() 把对象转换成 SQLite 能保存的原生值；读取时用 sqlite3.register_converter() 把数据库返回的 bytes 还原成 Python 对象，并在连接上打开 detect_types。只注册 adapter 只能解决“存进去”，不能自动解决“取出来还是原类型”。

官方文档：https://docs.python.org/3.14/library/sqlite3.html

先分清 sqlite3 的写入适配与读取转换

SQLite 原生类型只有 NULL、INTEGER、REAL、TEXT 和 BLOB。像坐标、货币、业务值对象这类 Python 实例不能直接绑定到参数，必须先确定一种稳定的存储表示。例如把 Point(12.5, -3.0) 写成 12.5;-3.0 文本。

这条链路可以画成：Point → adapt_point → TEXT，反向读取则是 bytes → convert_point → Point。第一张图是关系说明图，不是运行截图；它对应后文的字段格式与转换职责。

用 register_adapter 把自定义对象写入 SQLite

应用侧希望直接把 Point 作为参数传给 execute() 时，注册一个只接收该对象、返回文本的函数即可。SQL 仍然使用 ? 占位符，不要把对象拼接进 SQL 字符串。

import sqlite3

class Point:
    def __init__(self, x, y):
        self.x = float(x)
        self.y = float(y)

    def __repr__(self):
        return f"Point({self.x}, {self.y})"

def adapt_point(point):
    # 只返回 SQLite 原生支持的 TEXT，并固定字段顺序。
    return f"{point.x};{point.y}"

sqlite3.register_adapter(Point, adapt_point)

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE marker (name TEXT, position POINT)")
con.execute(
    "INSERT INTO marker(name, position) VALUES (?, ?)",
    ("origin", Point(12.5, -3.0)),
)
con.commit()  # 写入事务完成后再继续读取。
raw = con.execute("SELECT position FROM marker").fetchone()[0]
print(raw)  # 12.5;-3.0
con.close()  # 示例结束时显式关闭连接。

这里的 POINT 只是列声明中的类型名，adapter 本身并不依赖它。真正决定写入结果的是 adapt_point() 的返回值。若返回字典、对象或无法被 SQLite 绑定的类型，执行插入时会抛出绑定错误。

用 register_converter 和 detect_types 恢复自定义对象

读取方向需要两步：先注册类型名对应的 converter，再创建连接时开启类型检测。声明类型方式最适合表结构稳定的场景；如果同一列有时要按原始文本、有时要按对象读取，可以改用列名标注。

def convert_point(raw):
    # converter 总是按 bytes 接收，先解码再校验字段数量。
    text = raw.decode("utf-8")
    x_text, y_text = text.split(";", 1)
    return Point(float(x_text), float(y_text))

sqlite3.register_converter("POINT", convert_point)

con = sqlite3.connect(
    ":memory:",
    detect_types=sqlite3.PARSE_DECLTYPES,
)
con.execute("CREATE TABLE marker (position POINT)")
con.execute("INSERT INTO marker(position) VALUES (?)", (Point(12.5, -3.0),))
con.commit()
point = con.execute("SELECT position FROM marker").fetchone()[0]
print(point, type(point).__name__)  # Point(12.5, -3.0) Point
con.close()  # 关闭连接，避免留下未释放资源。

register_converter("POINT", ...) 的类型名匹配不区分大小写。PARSE_DECLTYPES 会读取建表语句中的第一段声明类型，因此 position POINT NOT NULL 仍然会命中 POINT。若使用查询列名标注，则连接改成 sqlite3.PARSE_COLNAMES，SQL 写成 SELECT position AS "position [POINT]" FROM marker。

上线前检查类型名、版本和查询边界

生产代码还应在 converter 内处理空值、分隔符和非法数字，并给存储格式留出版本空间。若字段格式会变化，可以存 JSON 文本或 BLOB，但仍建议把序列化协议写进模块文档，避免只凭类型名猜测数据含义。

相关问题

只注册 register_adapter 能在查询时得到自定义对象吗？

不能。adapter 只参与 Python 对象到 SQLite 值的写入；要恢复对象，需要 converter 和连接上的类型检测。

converter 为什么要先处理 bytes？

sqlite3 的 converter 回调约定接收 bytes，与数据库底层存储类型无关。先按约定解码，再校验格式，能避免把文本和字节混用。

PARSE_DECLTYPES 和 PARSE_COLNAMES 怎么选？

表结构固定时用前者更直接；同一查询需要临时指定返回类型时用后者。两者组合时，列名标注优先于声明类型。