selfdb 是一个将 Python 程序运行时状态自动暴露为 SQL 可查询数据库的开发工具，让你用 SQL 直接查询内存中的对象、函数调用和变量。

痛点：调试和观测 Python 程序为何如此痛苦

在开发 Python 应用时，我们经常面临这样的困境：

• 调试复杂状态：当程序运行到某个分支时，你想知道当前所有模块的全局变量、某个对象的属性、甚至最近几次函数调用的参数——但只能靠 print 或 pdb 手动断点，效率低下。
• 事后分析：程序崩溃后，你想复盘“当时发生了什么”，但日志不够详细，回放困难。
• 性能分析：你想知道某个函数被调用了多少次、平均耗时多少，通常需要引入 cProfile 或手动埋点。
• 动态数据探索：你希望像操作数据库一样，用 SELECT 和 JOIN 去探索程序内部的数据关系，但 Python 对象图是任意复杂的，没有统一查询接口。

传统方案要么是侵入式埋点（污染业务代码），要么是外部调试器（无法访问运行时上下文），要么是日志分析（丢失对象结构）。selfdb 提出一个全新的思路：把整个 Python 进程变成一台数据库服务器，你可以在程序运行的同时，用 SQL 查询它的内部状态。

selfdb 是什么

selfdb 是一个纯 Python 库，它通过 sys.settrace 钩子自动捕获程序执行过程中的所有帧（frame）、局部变量、全局变量、函数调用和返回值，并将它们组织成一张张关系表。然后，它启动一个内置的 SQLite 虚拟数据库（通过 sqlite3 的虚拟表机制），让外部客户端（如 sqlite3 命令行、Python sqlite3 模块、甚至其他语言的 SQLite 驱动）直接连接并查询这些表。

简单说：你的程序运行到一半，你可以用 SQL 去查询它现在的内存状态。

快速上手

安装

bash
pip install selfdb

最小示例：查询全局变量

python
import selfdb
import threading
import time

启动 selfdb，监听在本地 12345 端口（默认）

selfdb.start(port=12345)

程序正常运行

counter = 0
def worker():
global counter
for i in range(100):
counter += 1
time.sleep(0.01)

threads = [threading.Thread(target=worker) for _ in range(5)]
for t in threads:
t.start()

保持程序运行，等待外部查询

selfdb.wait() # 阻塞，直到 Ctrl+C

在另一个终端，用任意 SQLite 客户端连接：

bash
sqlite3 selfdb.db

或者通过 Python 连接：

python
import sqlite3
conn = sqlite3.connect('selfdb.db')

查看有哪些表

print(conn.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall())

查询全局变量 counter 的当前值

rows = conn.execute("SELECT * FROM globals WHERE name='counter'").fetchall()
print(rows)

你会发现 globals 表中有当前所有全局变量的名称、类型和值。更神奇的是，你可以实时查询——每次 SELECT 都会获取最新状态。

查询函数调用历史

selfdb 会自动记录每次函数调用的参数和返回值，存到 calls 表：

sql
SELECT function_name, args, return_value, duration_ms
FROM calls
ORDER BY timestamp DESC
LIMIT 10;

你可以看到最近 10 次函数调用的完整记录，包括参数值、返回值和耗时。这对于调试性能瓶颈和异常流程非常有用。

查询局部变量和帧信息

selfdb 还记录了每个活动线程的调用栈（stack frames）。你可以查询 frames 表：

sql
SELECT thread_id, filename, lineno, function, locals_json
FROM frames
WHERE thread_id = 5;

locals_json 是该帧的所有局部变量序列化后的 JSON 字符串。这样，你可以看到某个线程当前执行到哪一行，局部变量是什么。

核心亮点：深入技术细节

1. 基于 sys.settrace 的零侵入捕获

selfdb 利用 Python 的追踪钩子（sys.settrace）在每次函数调用、行执行、返回时触发回调。它不修改你的源代码，也不要求你显式地记录任何数据。你只需要 import selfdb; selfdb.start()，剩下的自动完成。

需要注意的是，sys.settrace 本身会带来一定的性能开销（通常 20%-50%），所以 selfdb 更适合开发调试和测试环境，不适合生产环境长期开启。但它的设计允许你通过环境变量或命令行参数动态开启/关闭，例如：

bash
SELFDB_ENABLED=1 python my_app.py

2. 虚拟表：SQLite 与 Python 对象的桥梁

selfdb 没有把数据复制到 SQLite 文件，而是通过 SQLite 的虚拟表机制（sqlite3 模块中的 create_module）动态生成查询结果。每次你执行 SELECT，它都会实时从 Python 的内存中提取数据并返回。这意味着：

• 数据永远是最新的：你看到的就是程序此刻的状态。
• 无持久化开销：不需要写文件，不占用磁盘。
• 支持复杂 SQL：你可以对查询结果进行 WHERE、JOIN、GROUP BY 等操作，因为虚拟表的行为和普通表一样。

3. 支持多线程和异步

selfdb 能正确区分不同线程的帧和局部变量。对于 asyncio 协程，它也能捕获事件循环中的任务状态（通过钩住 asyncio.Task 的创建和切换）。

4. 安全性和访问控制

默认只监听 127.0.0.1，避免远程访问风险。你可以通过 selfdb.start(host='0.0.0.0') 开启远程，但需要自己加认证（建议通过 SSH 隧道）。

5. 可扩展的表结构

除了内置的 globals、locals、frames、calls 表，selfdb 还提供 objects 表，让你按类名查询所有实例：

sql
SELECT class_name, id, repr, attributes_json
FROM objects
WHERE class_name = 'MyClass';

这会遍历 gc.get_objects() 找到所有 MyClass 的实例，并序列化它们的属性。

适用场景

1. 复杂算法调试：比如图算法、动态规划，你想在每一步检查中间状态，用 SQL 比用 print 更灵活。
2. Web 服务开发：在 Flask/Django 开发中，你可以开启 selfdb，然后通过 SQL 查询当前请求的上下文、数据库连接池状态、缓存命中率等。
3. 数据分析脚本：你在 Jupyter 中运行长任务，想中途查看某个变量的分布，直接用 SQL 查询。
4. 教学演示：向学生展示 Python 程序内部执行过程，用 SQL 查询帧和变量，直观且有趣。
5. 自动化测试：在测试框架中，你可以用 selfdb 断言某个函数被调用了多少次、参数是否正确，而不用 mock。

与其他工具对比

工具	定位	与 selfdb 的区别
pdb/ipdb	交互式调试器	需要手动打断点，只能查看当前帧，不能跨线程/跨时间查询。selfdb 提供全局、实时的 SQL 接口。
py-spy	采样性能分析器	只给出 CPU 火焰图，无法查询变量值。selfdb 能给出具体数据。
tracemalloc	内存跟踪	只关注内存分配，不提供业务对象状态。
logging	日志记录	需要手动埋点，且日志是文本流，无法结构化查询。selfdb 自动捕获所有调用和变量。
django-debug-toolbar	Web 调试面板	只适用于 Django，且只显示 SQL 查询和请求信息，不能查询任意 Python 对象。
ipython 的 %debug	事后调试	只能在异常后进入，不能实时查询。

selfdb 的核心差异化在于：它把调试从“断点思维”转变为“数据库思维”。你不再需要关心“停在哪一行”，而是可以随时问“现在全局有哪些对象？它们之间的关系是什么？”

局限性与注意事项

• 性能开销：开启追踪后，程序运行速度会明显下降，不适合生产环境。
• 序列化限制：某些对象（如生成器、socket、线程锁）无法被序列化为 JSON，selfdb 会用其 repr 字符串代替。
• 安全性：暴露了程序内部所有数据，切勿在不可信网络下开启远程连接。
• Python 版本：目前支持 CPython 3.7+，不兼容 PyPy 或 Jython（因为 sys.settrace 行为差异）。

总结

selfdb 是一个极具创意的开发工具，它模糊了“程序运行”和“数据库查询”的边界。虽然它可能不会成为生产环境中的常驻工具，但在开发、调试、测试和教学场景中，它提供了一种全新的、高效的交互方式。如果你厌倦了 print 和断点调试，不妨试试用 SQL 来“审视”你的程序。

项目链接：https://github.com/fzakaria/selfdb