我给自己写了一个本地 SQLite 数据浏览器：查表、看结构、导出都不离开电脑

目录

1. 缘起：查看一个本地数据库不应该先写脚本
2. 需求拆解：数据浏览器首先要防止误修改
3. 技术选型：sqlite3 标准库足够起步
4. 核心实现一：只读连接与结构扫描
5. 核心实现二：查询执行、分页与导出
6. UI 定制：让表结构和数据同时可见
7. 三个 SQLite 浏览中容易踩的坑
8. 结尾：数据工具的价值是缩短验证路径

1. 缘起：查看一个本地数据库不应该先写脚本

SQLite 很适合小型应用：一个文件就能保存完整数据，不需要启动数据库服务。但当我想临时查看内容时，常常还是要打开 Python、写几行连接代码、打印表名，再根据结果继续写查询。

这种方式的问题很实际：

• 只想看一眼表结构，却要先准备脚本；
• 查询结果输出到终端后不方便横向比较；
• 表字段很多时，打印内容很快失去可读性；
• 一不小心执行了更新语句，测试数据就被改掉；
• 导出几百行数据时，还要额外处理 CSV 转义。

我不需要一个完整数据库管理平台，而是想要一个打开 .db 文件就能浏览的本地工具：默认只读、结构清楚、查询结果可分页，必要时再明确开启写入。

2. 需求拆解：数据浏览器首先要防止误修改

我把功能边界写成以下清单：

第一版不负责数据库迁移、结构设计和多人协作，也不支持同时编辑多个数据库文件。它只是一个浏览和验证工具，先把“安全地看数据”做好。

心得：数据库工具最重要的按钮不是“执行”，而是让用户知道当前连接是否只读。

3. 技术选型：sqlite3 标准库足够起步

Python 自带 sqlite3 模块，足以完成连接、查询和元数据读取：

打开数据库时使用只读 URI：

import sqlite3

def open_readonly(path):
    uri = f"file:{path.resolve()}?mode=ro"
    return sqlite3.connect(uri, uri=True)

只读连接不是 UI 上的一句提示，而是底层连接模式。即使用户误写了一条 UPDATE，数据库也会拒绝执行。写入能力如果以后加入，也应该使用另一个明确的连接入口。

4. 核心实现一：只读连接与结构扫描

数据库打开后，先扫描对象列表，再按用户点击加载字段信息：

def list_objects(connection):
    sql = """
        SELECT type, name, sql
        FROM sqlite_master
        WHERE type IN ('table', 'view', 'index')
        ORDER BY type, name
    """
    return connection.execute(sql).fetchall()

def table_columns(connection, table_name):
    safe_name = table_name.replace('"', '""')
    return connection.execute(
        f'PRAGMA table_info("{safe_name}")'
    ).fetchall()

对象列表显示类型、名称和是否包含 SQL 定义。系统表 sqlite_sequence 默认折叠，避免普通用户被内部对象干扰。

点击表名后，工具加载字段名、类型、是否允许 NULL、默认值和主键标记。索引单独列出，并显示索引覆盖的字段顺序。用户可以从字段列表双击字段名，自动插入到 SQL 编辑器当前位置。

扫描操作不读取整张表，只读取元数据，因此即使数据库很大，打开结构也应该保持快速。数据库文件被其他程序占用时，工具只读连接仍然可以在 SQLite 允许的情况下读取快照；失败则显示具体锁定原因。

5. 核心实现二：查询执行、分页与导出

查询区默认自动追加行数限制，但不会篡改用户输入。更准确的做法是将用户 SQL 放进只读连接执行，然后限制界面读取的行数。

def run_query(connection, sql, limit=500):
    cursor = connection.execute(sql)
    columns = [item[0] for item in cursor.description or []]
    rows = cursor.fetchmany(limit)
    return columns, rows, cursor.fetchone() is not None

界面显示“已加载 500 行，可能还有更多”，而不是把截断结果伪装成完整结果。用户明确点击“加载更多”时，再继续从同一个游标读取下一批。

查询执行放在后台线程，取消按钮通过连接的进度回调中断长时间计算：

def progress_handler():
    return 1 if cancel_event.is_set() else 0

connection.set_progress_handler(progress_handler, 1000)

导出 CSV 时使用 csv.DictWriter，正确处理逗号、引号、换行和 NULL。导出的文件包含列名，文件名默认带表名或查询时间，但不会把完整 SQL 直接拼进文件名。

如果查询返回二进制 BLOB，表格中显示大小和十六进制前缀，导出时按二进制写入，而不是强行解码成乱码文本。

6. UI 定制：让表结构和数据同时可见

窗口采用三栏布局：左侧是数据库对象树，中间是 SQL 编辑器，右侧是结果表格和结构信息。

常用操作保持在顶部：打开文件、刷新结构、执行、取消、导出和只读状态。只读状态使用醒目的锁图标，避免用户忘记当前连接的权限。

结果表格支持列宽调整、排序和复制选中单元格。排序只针对已经加载到内存的结果，不会偷偷修改 SQL；如果用户需要数据库排序，界面提供“插入 ORDER BY”提示。

SQL 编辑器保存最近几条查询模板，但默认只保存 SQL 文本，不保存数据库文件中的数据。包含敏感值的查询可以手动标记为“不入历史”。

状态栏显示数据库路径、文件大小、最后修改时间、查询耗时和加载行数。数据文件在外部被更新后，工具提示“结构可能已变化”，用户可以手动刷新，而不是自动重置当前查询。

7. 三个 SQLite 浏览中容易踩的坑

坑一：表名和字段名不能都用参数绑定。 SQL 值可以用 ? 参数绑定，但表名需要通过标识符引用并进行严格转义。工具不把用户输入的表名直接拼进 SQL，而是只允许从已扫描的对象列表中选择。

坑二：COUNT(*) 可能比加载数据还慢。 为了显示总行数而每次都执行完整计数，会让大表查询失去响应。界面优先显示当前已加载行数，只有用户明确请求时才计算总数，并提示这可能需要扫描整张表。

坑三：数据库文件可能处于 WAL 状态。 SQLite 的写前日志会让旁观者误以为主数据库文件没有变化。只读工具需要尊重 SQLite 的连接机制，不自己复制文件拼接内容；如果无法获得一致快照，就明确提示重试。

另外，视图不一定拥有可直接编辑的表结构，虚拟表也可能支持特殊查询语法。浏览器默认把所有对象当作只读结果展示，不依据名称猜测它们是否可更新。

8. 结尾：数据工具的价值是缩短验证路径

做完这个 SQLite 浏览器后，我查看测试数据不再需要临时写脚本：打开文件，点选表，看看字段，执行一条查询，必要时导出结果，整个过程都在一个窗口内完成。

一个可靠的本地数据库浏览器应该做到：

1. 打开时默认只读；
2. 让表结构和数据同样容易查看；
3. 大查询限制结果和内存使用；
4. 明确区分截断结果与完整结果；
5. 导出时正确处理 NULL、引号和二进制内容。

如果你也想做类似工具，可以先实现只读连接、对象树和前 100 行预览。等查询取消、分页和导出稳定后，再考虑写入功能。数据库工具越接近真实数据，越应该优先保护数据而不是追求按钮数量。

能让一次临时验证少写一段脚本，就是这个小工具最实际的价值。