SQLite管理工具（免费版）

本工具为独立开发者、运维与AI Agent提供SQLite本地数据库的管理能力。免费版聚焦核心场景：并发模型、外键约束、类型系统、性能Pragma、空间回收、安全备份，足以覆盖SQLite日常使用的绝大多数需求。

概述

SQLite是全球部署最广的嵌入式数据库，以单文件、零运维、跨平台的特性深度集成在各类应用中。但SQLite的并发模型、外键默认关闭、类型亲和性、Schema变更限制等特性，与 PostgreSQL、MySQL等传统数据库有显著差异，若不正确配置极易踩坑。

本工具将这些SQLite特有的知识点与实战配置整合为一套管理指南，帮助用户在AI Agent工作流、桌面应用、CLI工具中正确使用SQLite，避免"database is locked"、外键失效、类型混乱、文件膨胀等常见问题。

核心能力

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Agent、SQLite、管理工具免费版、覆盖并发、备份等核心场景、面向独立开发者与、本地数据库管理工、具免费版、特有的并发模型、外键默认关闭、Schema、变更限制、维护等关键知识点、事务批处理等实战、帮助用户正确使用、避免常见陷阱等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：AI Agent会话存储（Agent视角）

将Agent的会话上下文持久化到SQLite，利用WAL模式支持多读单写，避免并发访问时的锁冲突。

场景二：桌面应用本地数据库（开发者视角）

为桌面应用配置SQLite的Pragma参数与外键约束，保障数据完整性与查询性能。

场景三：日志归档与检索（运维视角）

将应用日志结构化写入SQLite，配合索引实现快速检索，定期VACUUM回收删除数据产生的空间碎片。

场景四：原型与测试数据库（测试视角）

利用内存模式或临时文件数据库快速搭建测试环境，进程结束即清理，无需维护独立数据库服务。

不适用场景

以下场景SQLite管理(免费版)不适合处理：

• 数据库架构设计决策
• NoSQL选型
• 数据仓库ETL设计

触发条件

需要数据库操作、SQL查询、数据存储管理时使用。不适用于非本工具能力范围的需求。

快速开始

第一步：创建并配置数据库

sqlite3 mydb.sqlite
# ...
# 启用WAL并发模式
PRAGMA journal_mode=WAL;
# ...
# 设置写等待超时（毫秒）
PRAGMA busy_timeout=5000;
# ...
# 已知限制
PRAGMA foreign_keys=ON;

第二步：创建规范表结构

CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT NOT NULL UNIQUE,
    name TEXT NOT NULL,
    created_at TEXT DEFAULT (datetime('now'))
);
# ...
CREATE TABLE orders (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    total REAL NOT NULL CHECK(total >= 0),
    status TEXT NOT NULL DEFAULT 'pending'
        CHECK(status IN ('pending','paid','shipped','cancelled')),
    created_at TEXT DEFAULT (datetime('now'))
);
# ...
CREATE INDEX idx_orders_user_id ON orders(user_id);

第三步：批处理事务写入

-- 慢：每条单独提交
INSERT INTO logs (msg) VALUES ('a');
INSERT INTO logs (msg) VALUES ('b');
# ...
-- 快：事务包裹批量写入，性能提升10-100倍
BEGIN;
INSERT INTO logs (msg) VALUES ('a');
INSERT INTO logs (msg) VALUES ('b');
INSERT INTO logs (msg) VALUES ('c');
COMMIT;

完整上手时间约60秒。

响应解析: 完成完成后,查看输出响应确认任务状态。成功时输出包含解析摘要和响应数据;失败时根据错误信息排查问题,查阅错误解析章节获取恢复步骤。

示例

性能Pragma调优

PRAGMA journal_mode=WAL;          -- WAL并发模式，读不阻塞写
PRAGMA synchronous=NORMAL;        -- 与WAL搭配，平衡安全与速度
PRAGMA cache_size=-64000;         -- 64MB缓存（负数=KB）
PRAGMA temp_store=MEMORY;         -- 临时表存内存，加速排序
PRAGMA page_size=4096;            -- 页大小优化
PRAGMA mmap_size=268435456;       -- 256MB内存映射，加速读

外键约束校验

-- 检查外键是否启用（返回0或1）
PRAGMA foreign_keys;
# ...
-- 查看外键定义
PRAGMA foreign_key_list(orders);
# ...
-- 校验全库外键完整性
PRAGMA foreign_key_check;

安全备份

# 方法1：使用.backup命令（安全，支持在线备份）
sqlite3 mydb.sqlite ".backup backup.sqlite"
# ...
# 方法2：VACUUM INTO创建独立副本（3.27+）
sqlite3 mydb.sqlite "VACUUM INTO 'backup.sqlite';"
# ...
# 注意：WAL模式下需同时复制 -wal 和 -shm 文件

最佳实践

1. 每个连接都设置foreign_keys=ON

外键约束不会持久化到数据库文件，每个新连接默认关闭。若依赖外键约束保障完整性，必须在每次连接后执行PRAGMA foreign_keys=ON。

2. 写操作用BEGIN IMMEDIATE提前获取锁

-- 避免"读后写"死锁：先获取写锁
BEGIN IMMEDIATE;
SELECT balance FROM accounts WHERE id = 1;
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
COMMIT;

3. 批量插入务必用事务

默认每条语句都是独立事务，批量插入时开销巨大。用BEGIN...COMMIT包裹可提升10-100倍性能。

4. 删除大量数据后执行VACUUM

SQLite删除数据后文件不会自动缩小，需VACUUM回收空间。注意VACUUM需要约2倍磁盘空间，建议低峰期执行。

5. 不要用SQLite支撑高并发写入

SQLite同一时刻只允许一个写操作。若写并发是瓶颈，应迁移到 PostgreSQL 等客户端-服务端架构数据库。

已知限制

• 本skill的能力范围受限于核心能力章节中定义的功能,不支持超出范围的操作
• 复杂业务场景建议结合人工经验判断
• 执行效率受模型能力与网络环境影响
• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

常见问题

Q1：出现"database is locked"如何解决？

A：(1) 启用WAL模式（PRAGMA journal_mode=WAL）；(2) 设置busy_timeout（PRAGMA busy_timeout=5000）；(3) 写操作用BEGIN IMMEDIATE提前获取锁；(4) 若仍频繁锁表，说明写并发过高，需迁移到 PostgreSQL。

Q2：外键约束为什么不生效？

A：SQLite默认每连接关闭外键约束。需在每次连接后执行PRAGMA foreign_keys=ON。用PRAGMA foreign_keys检查返回值（0=关闭，1=开启）。

Q3：INTEGER列存了字符串"hello"为什么不报错？

A：SQLite使用类型亲和性而非严格类型。INTEGER亲和性的列会尝试转换输入，转换失败则按原类型存储。若需严格类型，使用STRICT表（SQLite 3.37+）：CREATE TABLE t (...) STRICT;。

Q4：ROWID在VACUUM后会变化吗？

A：会。VACUUM可能重排ROWID。若需要稳定标识，应使用显式的INTEGER PRIMARY KEY（即别名ROWID），其值不会被VACUUM改变。

Q5：内存模式数据共享吗？

A：不共享。:memory:模式每个连接是独立的数据库。若需多连接共享内存数据库，使用file::memory:?cache=sharedURI。

Q6：LIKE查询为什么不走索引？

A：前缀模糊匹配LIKE 'term%'可走索引，但LIKE '%term'和LIKE '%term%'无法走索引。若需全文检索，考虑SQLite FTS5扩展。

免费版限制

本免费体验版限制以下高级功能：

• 不支持自动定时备份（仅支持手动备份）
• 不支持连接池监控与告警
• 不支持Schema自动迁移工具
• 不支持DuckDB分析引擎集成
• 不支持增量备份与时间点恢复

解锁全部功能请使用专业版：sqlite-manager-pro

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• Python: 3.8+（用于sqlite3模块示例）

依赖详情

API Key 配置

• 本免费版基于本地SQLite，无需任何API Key
• 不涉及云端服务调用，数据完全保留在本地

可用性分类

• 分类: MD+EXEC（纯Markdown指令，部分功能需要exec命令行执行能力）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作

错误处理

输出格式

{
  "success": true,
  "data": {
    "result": "SQLite管理(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "sqlite manager"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}