python3 操作 SQLite 实战：TaoToken 统一 Key 下用 config.toml 骨架创建表、添加数据与查询数据

1. 为什么我建议你用 config.toml 管 SQLite 项目配置

python3 操作 SQLite 这件事本身不复杂，sqlite3是标准库，import进来就能建库建表。但真正写项目时，麻烦的往往不是 SQL 语句，而是配置散落各处：数据库文件路径写死在代码里、模型调用的 Key 硬编码在脚本顶部、换台机器就得改一遍。我试过把路径、表名、API 通道参数全塞进一个config.toml，代码只负责读配置和执行逻辑，迁移和排障都清爽很多。

这篇就聚焦一条完整链路：用 python3 的sqlite3模块完成创建表、添加数据、查询数据，同时把数据库路径和 TaoToken 统一 Key 的调用配置抽到config.toml骨架里。适合刚接触 SQLite 的 Python 初学者，也适合想把本地小工具配置规范化的开发者。读完之后你能拿到可直接复制的配置片段、建表与增查代码，以及运行验证步骤，跑通本地 SQLite 数据操作。

SQLite 能保存的数据类型其实很朴素：空值、整数、浮点数、字符串和 blob。blob 就是二进制大对象，图片、音乐、zip 文件都能塞进去。而游标（cursor）是在数据库里移动并执行查询的对象，你可以把它理解成「拿着 SQL 语句去数据库里跑腿的人」。下面所有操作都围绕conn（连接）和cursor（游标）这两个角色展开。

2. TaoToken 前置：统一 Key 与 config.toml 骨架

在动手写 SQL 之前，先把配置层搭好。TaoToken 在这里扮演的是统一 API 通道的角色：你只需要一个 Key，就能在同一个入口下调用不同模型，省去为每个模型单独维护一套地址和密钥的麻烦。对于本地 SQLite 小工具来说，这意味着当你想给数据加个「自动生成摘要」或「自然语言查询」的能力时，不用改数据库代码，只改配置即可。

先到官网了解整体能力，再进控制台创建 Key：

• 官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• 控制台创建 Key：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console
• API Keys 管理页：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys

API 基础地址统一用https://taotoken.net/api，注意这个地址不带任何查询参数，配置里直接写死即可。Key 拿到后不要提交到 Git，放进config.toml的本地副本或环境变量里。

下面是我常用的config.toml骨架，分成[database]和[taotoken]两段。数据库段管路径和表名，TaoToken 段管统一 Key 和模型参数：

# config.toml [database] # SQLite 数据库文件路径，相对当前工作目录 path = "./data/students.db" # 表名集中管理，避免代码里到处写字符串 table = "students" [taotoken] # 统一 API 通道地址，固定不带查询参数 base_url = "https://taotoken.net/api" # 从控制台复制，切勿提交到公开仓库 api_key = "sk-你的Key" # 默认模型，按需替换 model = "claude-sonnet-4-20250514" # 请求超时（秒） timeout = 30

Python 3.11 起标准库自带tomllib，可以直接读 TOML，不需要额外装包。如果你用的是更早版本，pip install tomli后把import tomllib换成import tomli as tomllib即可。读取配置的封装我习惯单独放一个config.py：

# config.py import tomllib from pathlib import Path def load_config(path: str = "config.toml") -> dict: with open(path, "rb") as f: return tomllib.load(f) if __name__ == "__main__": cfg = load_config() print("db path:", cfg["database"]["path"]) print("base url:", cfg["taotoken"]["base_url"])

运行python config.py，能打印出路径和地址就说明配置读取正常。这一步先跑通，后面所有脚本都复用这个load_config。

3. 可复制配置：建表、添加数据、查询数据

配置就绪后，进入正题。我把建表、插入、查询拆成三个函数，放在同一个db_ops.py里，方便你逐段复制测试。先看建表部分，注意路径从配置读取，目录不存在时自动创建：

# db_ops.py import sqlite3 from pathlib import Path from config import load_config cfg = load_config() DB_PATH = Path(cfg["database"]["path"]) TABLE = cfg["database"]["table"] def get_conn() -> sqlite3.Connection: DB_PATH.parent.mkdir(parents=True, exist_ok=True) return sqlite3.connect(DB_PATH) def create_table() -> None: conn = get_conn() cursor = conn.cursor() sql = f""" create table if not exists {TABLE} ( id integer primary key autoincrement, name text not null, username text not null, score real default 0.0 ) """ cursor.execute(sql) conn.commit() cursor.close() conn.close() print(f"表 {TABLE} 已就绪")

这里用if not exists避免重复建表报错，id用integer primary key autoincrement让 SQLite 自动维护主键。score用real存浮点数，对应 SQLite 的浮点类型。建表语句里我特意没写死表名，而是用 f-string 注入配置里的TABLE，这样换表名只改config.toml。

添加数据用参数化插入，别用字符串拼接，否则遇到带引号的名字就翻车。executemany适合批量插入：

def add_students(rows: list[tuple]) -> None: conn = get_conn() cursor = conn.cursor() sql = f"insert into {TABLE} (name, username, score) values (?, ?, ?)" cursor.executemany(sql, rows) conn.commit() cursor.close() conn.close() print(f"已插入 {len(rows)} 条记录")

查询数据分两种：拿全部用fetchall，拿单条用fetchone。查询结果默认是元组，加个row_factory就能按列名取值，调试时更直观：

def query_all() -> list: conn = get_conn() conn.row_factory = sqlite3.Row cursor = conn.cursor() sql = f"select id, name, username, score from {TABLE} order by id" cursor.execute(sql) rows = cursor.fetchall() cursor.close() conn.close() return [dict(r) for r in rows] def query_by_name(name: str) -> list: conn = get_conn() conn.row_factory = sqlite3.Row cursor = conn.cursor() sql = f"select id, name, username, score from {TABLE} where name = ?" cursor.execute(sql, (name,)) rows = cursor.fetchall() cursor.close() conn.close() return [dict(r) for r in rows]

把三个函数串起来跑一遍，就是完整的建表、插入、查询链路：

if __name__ == "__main__": create_table() add_students([ ("张三", "zhangsan", 88.5), ("李四", "lisi", 92.0), ("王五", "wangwu", 76.5), ]) print("全部记录：") for row in query_all(): print(row) print("按名字查询：") print(query_by_name("李四"))

4. 验证请求：运行结果与成功标志

在终端执行python db_ops.py，正常输出应该类似下面这样。第一次运行会创建./data/students.db文件，第二次运行因为if not exists不会重复建表，但插入会再追加三条，所以如果你反复跑，记录数会累加，这是预期行为：

表 students 已就绪 已插入 3 条记录 全部记录： {'id': 1, 'name': '张三', 'username': 'zhangsan', 'score': 88.5} {'id': 2, 'name': '李四', 'username': 'lisi', 'score': 92.0} {'id': 3, 'name': '王五', 'username': 'wangwu', 'score': 76.5} 按名字查询： [{'id': 2, 'name': '李四', 'username': 'lisi', 'score': 92.0}]

看到id从 1 开始自增、score保留浮点、按名字能精确命中，就说明建表、添加数据、查询数据三段都通了。如果你想确认数据库文件真的落盘了，用ls -lh data/看下大小，或者用命令行sqlite3 data/students.db ".tables"列出表名。

注意：sqlite3.connect默认不会自动提交，插入后必须调用conn.commit()，否则关连接时数据可能丢失。查询不需要 commit。

如果你还想验证 TaoToken 统一 Key 通道是否可用，可以单独写个小脚本，用配置里的base_url和api_key发一次模型对话请求。模型对话入口在这里：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=models 。这一步和 SQLite 解耦，只是确认配置段没写错。

5. 本篇常见错排查

报错一：ModuleNotFoundError: No module named 'tomllib'说明你的 Python 低于 3.11。两个选择：升级到 3.11+，或者pip install tomli，然后把import tomllib改成import tomli as tomllib。功能完全一致。

报错二：sqlite3.OperationalError: no such table: students通常是建表和执行查询用了不同的数据库文件。检查config.toml里的path是否被改过，或者查询脚本的工作目录和建表时不一致。相对路径是相对「当前工作目录」而非脚本所在目录，建议统一在项目根目录运行，或者把path写成绝对路径。

报错三：插入中文后查询显示乱码SQLite 默认用 UTF-8 存储文本，Python 3 的字符串也是 Unicode，正常不会乱码。如果出现乱码，多半是终端编码问题，而不是数据库问题。在 Windows 终端执行chcp 65001切到 UTF-8 再跑一次即可。

报错四：sqlite3.ProgrammingError: You did not supply a value for binding参数化插入时占位符数量和参数个数不匹配。检查values (?, ?, ?)是不是三个问号，而executemany传入的每个元组也必须是三个元素。用executemany时参数是「元组的列表」，别传成单个元组。

报错五：Key 泄露风险config.toml里写了真实 Key 后，务必把config.toml加进.gitignore，仓库里只保留config.example.toml。这是最容易被忽略、后果又最严重的一条。

提示：排障时优先看报错最后一行，SQLite 的报错信息通常很直白，no such table、no such column、UNIQUE constraint failed基本能直接定位问题。

6. 把配置和代码分开，后面加能力更省事

走到这里，你已经用 python3 的sqlite3模块跑通了创建表、添加数据、查询数据的完整链路，并且把数据库路径、表名、TaoToken 统一 Key 都收进了config.toml。这个骨架的价值在于：以后想给数据加个「自动打标签」或「自然语言查询」的能力，只需要在[taotoken]段换模型、在业务代码里加一次 API 调用，数据库层完全不用动。

如果你打算长期在本地做编码类小工具或 Agent 实验，可以了解下 Coding Plan，它更适合高频调用场景：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan 。接入细节和参数说明统一看文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc 。Key 管理和新建都在 API Keys 页完成：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys 。

最后留个实用习惯：每次改完config.toml，先跑一遍python config.py确认能解析，再跑python db_ops.py确认数据库链路，两步都过再写业务逻辑。这样排障范围永远只有一层，不会配置和代码混在一起查。