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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keysAPI 基础地址统一用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 30Python 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(parentsTrue, exist_okTrue) 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 finsert 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 fselect 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 fselect 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels 。这一步和 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan 。接入细节和参数说明统一看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 。Key 管理和新建都在 API Keys 页完成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 。最后留个实用习惯每次改完config.toml先跑一遍python config.py确认能解析再跑python db_ops.py确认数据库链路两步都过再写业务逻辑。这样排障范围永远只有一层不会配置和代码混在一起查。