1. 为什么 SQLite 总被质疑先把场景说清楚SQLite 是一个嵌入式关系型数据库整个数据库就是一个文件没有独立服务进程不需要账号密码和端口。它能做完整的 SQL 增删改查、事务、索引、触发器适合单机应用、桌面软件、移动 App、边缘设备、本地 AI 工具链的数据落盘。适合谁适合写入并发不高、部署环境简单、希望零运维的开发者。不适合谁不适合几十个进程同时高频写同一张表的场景。质疑声基本都来自后者。很多人拿 SQLite 和 MySQL、PostgreSQL 对比说它并发差写入会锁库。这个说法有一半是对的SQLite 默认的 rollback journal 模式下写操作会加排他锁同一时刻只允许一个写者其他写请求要么等待要么直接返回 SQLITE_BUSY。但这不是缺陷而是设计取舍——它把复杂度从服务端挪到了使用方换来了零配置和单文件的可移植性。真正的问题往往不在 SQLite 本身而在配置。默认参数是为兼容性准备的不是为并发准备的。只要打开 WAL 模式、设置合理的 busy_timeout、控制事务粒度单机场景下每秒几千次写入是完全可行的。这篇就围绕这个思路用 TaoToken 统一 Key/API 通道在本地 AI 工具链里搭一套 SQLite 配置骨架把读写验证和并发压测跑一遍让你自己判断它够不够用。2. TaoToken 前置统一 Key 与 API 通道在本地 AI 工具链里模型调用、代码补全、Agent 任务经常要接好几个服务Key 分散在各处换一个工具就要重新配一遍。TaoToken 做的事情是把这些调用收敛到一个入口一个 Key、一套 API 地址兼容主流模型协议工具侧只改 base_url 和 api_key 两个字段就能接上。对这篇的场景来说它的价值在于我可以用同一个 Key 驱动本地脚本让模型帮我生成 SQLite 压测代码、分析错误日志、解释 EXPLAIN 输出而不用在多个平台之间来回切换。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 注意这个地址不带查询参数。你需要提前准备的东西不多一个可用的 API KeyPython 3.9 以上环境sqlite3 命令行工具Python 自带 sqlite3 模块命令行工具可选。Key 在控制台创建地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建后复制保存后面配置文件里要用。如果你只是想先验证模型能不能通可以直接用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条消息试试。注意API Key 只放在本地配置文件或环境变量里不要提交到 Git 仓库也不要在截图里露出完整字符串。3. 可复制配置config.toml 与 settings.json 骨架先给一套最小可用的配置。假设你的项目目录结构是这样的项目根目录下有config.toml放模型通道配置.taotoken/settings.json放工具侧设置data/app.db放 SQLite 数据库文件。config.toml内容如下重点是 base_url 指向 TaoToken 的 API 根地址model 填你要用的模型名# config.toml [llm] provider taotoken base_url https://taotoken.net/api api_key sk-你的Key model claude-sonnet-4-20250514 timeout 60 max_retries 2 [sqlite] db_path data/app.db journal_mode WAL busy_timeout_ms 5000 synchronous NORMAL cache_size_kb -64000settings.json是给本地工具链读的字段和 toml 对应方便脚本统一加载{ llm: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-20250514 }, sqlite: { dbPath: data/app.db, pragma: { journal_mode: WAL, busy_timeout: 5000, synchronous: NORMAL, cache_size: -64000 } } }几个参数解释一下。journal_modeWAL是关键它把写操作先追加到-wal文件读操作不再被写锁阻塞读写可以并行。busy_timeout5000表示遇到锁时最多等 5 秒再报错而不是立刻返回 SQLITE_BUSY。synchronousNORMAL在 WAL 模式下是安全且性能较好的档位兼顾了持久性和速度。cache_size-64000表示分配约 64MB 页缓存负值单位是 KB。初始化数据库和 PRAGMA 的 Python 脚本可以这样写import sqlite3 from pathlib import Path db_path Path(data/app.db) db_path.parent.mkdir(parentsTrue, exist_okTrue) conn sqlite3.connect(str(db_path), timeout5.0) conn.execute(PRAGMA journal_modeWAL;) conn.execute(PRAGMA busy_timeout5000;) conn.execute(PRAGMA synchronousNORMAL;) conn.execute(PRAGMA cache_size-64000;) conn.execute( CREATE TABLE IF NOT EXISTS events ( id INTEGER PRIMARY KEY AUTOINCREMENT, source TEXT NOT NULL, payload TEXT NOT NULL, created_at INTEGER NOT NULL ); ) conn.execute(CREATE INDEX IF NOT EXISTS idx_events_created ON events(created_at);) conn.commit() conn.close() print(init done:, db_path.resolve())跑完这一步data/目录下会出现app.db、app.db-wal、app.db-shm三个文件看到后两个就说明 WAL 生效了。4. 验证请求与成功结果读写 并发压测先做基础读写验证。下面这段脚本插入一条记录再读回来确认通道和数据库都正常import sqlite3, time, json conn sqlite3.connect(data/app.db, timeout5.0) conn.execute(PRAGMA busy_timeout5000;) cur conn.cursor() cur.execute( INSERT INTO events(source, payload, created_at) VALUES (?, ?, ?), (manual-test, json.dumps({msg: hello sqlite}), int(time.time())) ) conn.commit() cur.execute(SELECT id, source, payload FROM events ORDER BY id DESC LIMIT 1) print(cur.fetchone()) conn.close()预期输出类似(1, manual-test, {msg: hello sqlite})。如果这一步就报sqlite3.OperationalError: database is locked说明有别的进程占着写锁先检查是不是有没关掉的连接。接下来是并发写入压测这是判断 SQLite 能不能扛住你场景的核心动作。用多进程模拟真实写入压力import sqlite3, time, os, multiprocessing as mp DB data/app.db def writer(worker_id, n): conn sqlite3.connect(DB, timeout10.0) conn.execute(PRAGMA busy_timeout10000;) conn.execute(PRAGMA journal_modeWAL;) cur conn.cursor() ok, fail 0, 0 for i in range(n): try: cur.execute( INSERT INTO events(source, payload, created_at) VALUES (?, ?, ?), (fw{worker_id}, frow-{i}, int(time.time() * 1000)) ) conn.commit() ok 1 except sqlite3.OperationalError as e: fail 1 print(f[w{worker_id}] {e}) conn.close() return ok, fail if __name__ __main__: workers, per 8, 500 start time.time() with mp.Pool(workers) as pool: results pool.starmap(writer, [(i, per) for i in range(workers)]) cost time.time() - start total_ok sum(r[0] for r in results) total_fail sum(r[1] for r in results) print(fworkers{workers} rows{workers*per} ok{total_ok} fail{total_fail} cost{cost:.2f}s) print(ftps{total_ok/cost:.0f})实测下来8 进程各写 500 行、每行单独 commit 的情况下WAL busy_timeout 组合基本能做到零失败吞吐在几百到两千 TPS 之间具体取决于磁盘。如果把每行 commit 改成每 100 行 commit 一次TPS 会明显上升因为事务提交才是真正的磁盘同步点。想进一步确认写入是否真的落盘可以查一下 WAL 文件大小和页数PRAGMA wal_checkpoint(TRUNCATE); PRAGMA page_count; PRAGMA freelist_count;wal_checkpoint(TRUNCATE)会把 WAL 内容合并回主库并清空 WAL 文件适合在低峰期做一次。page_count是当前数据库总页数freelist_count是空闲页数两者结合能看出碎片情况。5. 本篇常见错排查错误一database is locked。最常见。原因通常是没开 WAL或者 busy_timeout 设得太短或者有连接忘了 close。排查顺序先确认PRAGMA journal_mode;返回wal再确认PRAGMA busy_timeout;返回非零值最后检查代码里每个 connect 是否都有对应的 close 或用了 with 语句。错误二attempt to write a readonly database。多半是文件权限问题或者数据库文件所在目录不可写。WAL 模式需要在同目录创建-wal和-shm文件如果目录只读就会失败。检查ls -l data/的权限。错误三多进程下偶发disk I/O error。常见于网络文件系统NFS、SMB上放 SQLite 文件。SQLite 的锁机制依赖本地文件系统的原子操作网络盘上不可靠。解决办法是把数据库放本地磁盘或者改用客户端-服务端数据库。错误四WAL 文件无限增长。如果长期只有写没有 checkpointWAL 会一直变大。可以设置PRAGMA wal_autocheckpoint1000;表示每 1000 页自动 checkpoint 一次。也可以在业务低峰主动执行PRAGMA wal_checkpoint(PASSIVE);。错误五模型调用返回 401 或超时。先确认config.toml里的base_url是https://taotoken.net/api没有多余斜杠或路径再确认 Key 没有多余空格。如果持续超时把timeout调到 120 试试。需要重新生成 Key 的话去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 操作。接入细节可以对照文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。排查时如果想让模型帮你读日志可以把错误堆栈贴到模型对话里让它给出可能原因和验证命令比自己翻文档快。6. 判断 SQLite 是否适合你以及后续怎么接回到最初的问题SQLite 被质疑本质是场景错配。如果你的写入是单进程或少量进程、每秒几十到几千次、数据量在 GB 级别以内WAL busy_timeout 合理事务粒度完全够用而且省掉了整个数据库服务的运维成本。如果你的场景是几十个服务实例同时高频写同一张表、需要跨机共享、需要细粒度权限控制那就该上客户端-服务端数据库这不是 SQLite 的问题。把这篇的配置落到你的项目里动作就三步复制config.toml和settings.json跑一遍初始化脚本确认 WAL 生效再跑并发压测看失败率和 TPS。压测结果就是你的判断依据不用听别人说行不行。如果你打算把模型调用长期接进本地编码流程比如让 Agent 自动生成 SQL、分析慢查询、写迁移脚本可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它面向的就是这种持续编码和 Agent 场景。Claude Code 相关的接入说明在 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。先把 SQLite 这套骨架跑通再决定要不要把模型通道也固化下来。 为什么这么多人质疑SQLite数据库？从配置到验证的TaoToken实战拆解
1. 为什么 SQLite 总被质疑先把场景说清楚SQLite 是一个嵌入式关系型数据库整个数据库就是一个文件没有独立服务进程不需要账号密码和端口。它能做完整的 SQL 增删改查、事务、索引、触发器适合单机应用、桌面软件、移动 App、边缘设备、本地 AI 工具链的数据落盘。适合谁适合写入并发不高、部署环境简单、希望零运维的开发者。不适合谁不适合几十个进程同时高频写同一张表的场景。质疑声基本都来自后者。很多人拿 SQLite 和 MySQL、PostgreSQL 对比说它并发差写入会锁库。这个说法有一半是对的SQLite 默认的 rollback journal 模式下写操作会加排他锁同一时刻只允许一个写者其他写请求要么等待要么直接返回 SQLITE_BUSY。但这不是缺陷而是设计取舍——它把复杂度从服务端挪到了使用方换来了零配置和单文件的可移植性。真正的问题往往不在 SQLite 本身而在配置。默认参数是为兼容性准备的不是为并发准备的。只要打开 WAL 模式、设置合理的 busy_timeout、控制事务粒度单机场景下每秒几千次写入是完全可行的。这篇就围绕这个思路用 TaoToken 统一 Key/API 通道在本地 AI 工具链里搭一套 SQLite 配置骨架把读写验证和并发压测跑一遍让你自己判断它够不够用。2. TaoToken 前置统一 Key 与 API 通道在本地 AI 工具链里模型调用、代码补全、Agent 任务经常要接好几个服务Key 分散在各处换一个工具就要重新配一遍。TaoToken 做的事情是把这些调用收敛到一个入口一个 Key、一套 API 地址兼容主流模型协议工具侧只改 base_url 和 api_key 两个字段就能接上。对这篇的场景来说它的价值在于我可以用同一个 Key 驱动本地脚本让模型帮我生成 SQLite 压测代码、分析错误日志、解释 EXPLAIN 输出而不用在多个平台之间来回切换。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 注意这个地址不带查询参数。你需要提前准备的东西不多一个可用的 API KeyPython 3.9 以上环境sqlite3 命令行工具Python 自带 sqlite3 模块命令行工具可选。Key 在控制台创建地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建后复制保存后面配置文件里要用。如果你只是想先验证模型能不能通可以直接用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条消息试试。注意API Key 只放在本地配置文件或环境变量里不要提交到 Git 仓库也不要在截图里露出完整字符串。3. 可复制配置config.toml 与 settings.json 骨架先给一套最小可用的配置。假设你的项目目录结构是这样的项目根目录下有config.toml放模型通道配置.taotoken/settings.json放工具侧设置data/app.db放 SQLite 数据库文件。config.toml内容如下重点是 base_url 指向 TaoToken 的 API 根地址model 填你要用的模型名# config.toml [llm] provider taotoken base_url https://taotoken.net/api api_key sk-你的Key model claude-sonnet-4-20250514 timeout 60 max_retries 2 [sqlite] db_path data/app.db journal_mode WAL busy_timeout_ms 5000 synchronous NORMAL cache_size_kb -64000settings.json是给本地工具链读的字段和 toml 对应方便脚本统一加载{ llm: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-20250514 }, sqlite: { dbPath: data/app.db, pragma: { journal_mode: WAL, busy_timeout: 5000, synchronous: NORMAL, cache_size: -64000 } } }几个参数解释一下。journal_modeWAL是关键它把写操作先追加到-wal文件读操作不再被写锁阻塞读写可以并行。busy_timeout5000表示遇到锁时最多等 5 秒再报错而不是立刻返回 SQLITE_BUSY。synchronousNORMAL在 WAL 模式下是安全且性能较好的档位兼顾了持久性和速度。cache_size-64000表示分配约 64MB 页缓存负值单位是 KB。初始化数据库和 PRAGMA 的 Python 脚本可以这样写import sqlite3 from pathlib import Path db_path Path(data/app.db) db_path.parent.mkdir(parentsTrue, exist_okTrue) conn sqlite3.connect(str(db_path), timeout5.0) conn.execute(PRAGMA journal_modeWAL;) conn.execute(PRAGMA busy_timeout5000;) conn.execute(PRAGMA synchronousNORMAL;) conn.execute(PRAGMA cache_size-64000;) conn.execute( CREATE TABLE IF NOT EXISTS events ( id INTEGER PRIMARY KEY AUTOINCREMENT, source TEXT NOT NULL, payload TEXT NOT NULL, created_at INTEGER NOT NULL ); ) conn.execute(CREATE INDEX IF NOT EXISTS idx_events_created ON events(created_at);) conn.commit() conn.close() print(init done:, db_path.resolve())跑完这一步data/目录下会出现app.db、app.db-wal、app.db-shm三个文件看到后两个就说明 WAL 生效了。4. 验证请求与成功结果读写 并发压测先做基础读写验证。下面这段脚本插入一条记录再读回来确认通道和数据库都正常import sqlite3, time, json conn sqlite3.connect(data/app.db, timeout5.0) conn.execute(PRAGMA busy_timeout5000;) cur conn.cursor() cur.execute( INSERT INTO events(source, payload, created_at) VALUES (?, ?, ?), (manual-test, json.dumps({msg: hello sqlite}), int(time.time())) ) conn.commit() cur.execute(SELECT id, source, payload FROM events ORDER BY id DESC LIMIT 1) print(cur.fetchone()) conn.close()预期输出类似(1, manual-test, {msg: hello sqlite})。如果这一步就报sqlite3.OperationalError: database is locked说明有别的进程占着写锁先检查是不是有没关掉的连接。接下来是并发写入压测这是判断 SQLite 能不能扛住你场景的核心动作。用多进程模拟真实写入压力import sqlite3, time, os, multiprocessing as mp DB data/app.db def writer(worker_id, n): conn sqlite3.connect(DB, timeout10.0) conn.execute(PRAGMA busy_timeout10000;) conn.execute(PRAGMA journal_modeWAL;) cur conn.cursor() ok, fail 0, 0 for i in range(n): try: cur.execute( INSERT INTO events(source, payload, created_at) VALUES (?, ?, ?), (fw{worker_id}, frow-{i}, int(time.time() * 1000)) ) conn.commit() ok 1 except sqlite3.OperationalError as e: fail 1 print(f[w{worker_id}] {e}) conn.close() return ok, fail if __name__ __main__: workers, per 8, 500 start time.time() with mp.Pool(workers) as pool: results pool.starmap(writer, [(i, per) for i in range(workers)]) cost time.time() - start total_ok sum(r[0] for r in results) total_fail sum(r[1] for r in results) print(fworkers{workers} rows{workers*per} ok{total_ok} fail{total_fail} cost{cost:.2f}s) print(ftps{total_ok/cost:.0f})实测下来8 进程各写 500 行、每行单独 commit 的情况下WAL busy_timeout 组合基本能做到零失败吞吐在几百到两千 TPS 之间具体取决于磁盘。如果把每行 commit 改成每 100 行 commit 一次TPS 会明显上升因为事务提交才是真正的磁盘同步点。想进一步确认写入是否真的落盘可以查一下 WAL 文件大小和页数PRAGMA wal_checkpoint(TRUNCATE); PRAGMA page_count; PRAGMA freelist_count;wal_checkpoint(TRUNCATE)会把 WAL 内容合并回主库并清空 WAL 文件适合在低峰期做一次。page_count是当前数据库总页数freelist_count是空闲页数两者结合能看出碎片情况。5. 本篇常见错排查错误一database is locked。最常见。原因通常是没开 WAL或者 busy_timeout 设得太短或者有连接忘了 close。排查顺序先确认PRAGMA journal_mode;返回wal再确认PRAGMA busy_timeout;返回非零值最后检查代码里每个 connect 是否都有对应的 close 或用了 with 语句。错误二attempt to write a readonly database。多半是文件权限问题或者数据库文件所在目录不可写。WAL 模式需要在同目录创建-wal和-shm文件如果目录只读就会失败。检查ls -l data/的权限。错误三多进程下偶发disk I/O error。常见于网络文件系统NFS、SMB上放 SQLite 文件。SQLite 的锁机制依赖本地文件系统的原子操作网络盘上不可靠。解决办法是把数据库放本地磁盘或者改用客户端-服务端数据库。错误四WAL 文件无限增长。如果长期只有写没有 checkpointWAL 会一直变大。可以设置PRAGMA wal_autocheckpoint1000;表示每 1000 页自动 checkpoint 一次。也可以在业务低峰主动执行PRAGMA wal_checkpoint(PASSIVE);。错误五模型调用返回 401 或超时。先确认config.toml里的base_url是https://taotoken.net/api没有多余斜杠或路径再确认 Key 没有多余空格。如果持续超时把timeout调到 120 试试。需要重新生成 Key 的话去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 操作。接入细节可以对照文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。排查时如果想让模型帮你读日志可以把错误堆栈贴到模型对话里让它给出可能原因和验证命令比自己翻文档快。6. 判断 SQLite 是否适合你以及后续怎么接回到最初的问题SQLite 被质疑本质是场景错配。如果你的写入是单进程或少量进程、每秒几十到几千次、数据量在 GB 级别以内WAL busy_timeout 合理事务粒度完全够用而且省掉了整个数据库服务的运维成本。如果你的场景是几十个服务实例同时高频写同一张表、需要跨机共享、需要细粒度权限控制那就该上客户端-服务端数据库这不是 SQLite 的问题。把这篇的配置落到你的项目里动作就三步复制config.toml和settings.json跑一遍初始化脚本确认 WAL 生效再跑并发压测看失败率和 TPS。压测结果就是你的判断依据不用听别人说行不行。如果你打算把模型调用长期接进本地编码流程比如让 Agent 自动生成 SQL、分析慢查询、写迁移脚本可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它面向的就是这种持续编码和 Agent 场景。Claude Code 相关的接入说明在 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。先把 SQLite 这套骨架跑通再决定要不要把模型通道也固化下来。