1. 从一次真实的 sqlite3 踩坑说起：为什么数据库连接、游标、事务要一起学
刚接触 sqlite3 的时候，很多人会经历一个很典型的阶段：照着教程敲完sqlite3.connect('test.db')，插了几条数据，select一下能看到结果，就以为学会了。结果第二天再打开数据库，数据没了；或者程序中途报错，表里多出一堆半截数据；再或者用for i in cursor.execute(sql)遍历完一次，第二次遍历居然是空的。这些问题单独看都像玄学，其实全都指向同一件事——你只学会了「连接」，没搞懂「游标」和「事务」。
sqlite3 是 Python 标准库自带的轻量级数据库，不需要额外安装服务端，一个.db文件就是一个完整数据库。它特别适合本地工具、脚本、原型验证、桌面小应用这类场景。但正因为「太简单」，很多人跳过了连接对象、游标对象、事务边界这三块基础，后面写复杂逻辑时就会反复踩坑。
这篇文章面向的就是刚上手 sqlite3 的开发者。我会把「数据库连接 → 游标操作 → 事务提交与回滚」这条完整链路拆开讲清楚，给出可以直接复制的建表脚本、插入脚本、查询脚本，以及事务回滚的验证动作。同时，因为现在很多人在本地实验时会顺手接一个统一的模型/API 通道来辅助生成 SQL、解释报错，我也会把 TaoToken 的统一 Key 接入方式放在前面讲清楚，让你在同一个环境里既能跑数据库实验，也能用统一通道做辅助。整篇的目标只有一个：让你完成一次可复现的数据库读写实验，而不是复制完代码就忘。
先明确三个核心概念，后面所有代码都围绕它们展开：
连接对象（connection）负责和数据库文件建立会话，它管的是「事务」这一层，提供cursor()、commit()、rollback()、close()这些方法。游标对象（cursor）负责真正执行 SQL，它管的是「语句」这一层，提供execute()、fetchone()、fetchmany()、fetchall()、rowcount、close()。事务则是连接对象维护的一个边界：在你调用commit()之前，所有写操作都还在「未提交」状态，一旦中途出错调用rollback()，这些改动会被整体撤销。
理解了这个分层，你就能明白为什么「插了数据但重启后没了」——因为你没commit()；为什么「报错后表里多了脏数据」——因为你没在异常里rollback()；为什么「游标遍历一次就空了」——因为游标是一个迭代器，取完就到底了，需要重新execute()。
2. TaoToken 统一 Key 前置准备：让本地实验环境一次配好
在正式写数据库代码之前，先把辅助环境配好。这里说的辅助环境，指的是你在做 sqlite3 实验时，可能会想让模型帮你生成建表语句、解释OperationalError、或者把一段 SQL 改写成参数化写法。TaoToken 提供的是统一的 Key 和 API 通道，你只需要配一次 Base URL 和 Key，就能在多个工具里复用，不用每个工具单独申请。
先拿到 Key。打开控制台地址https://taotoken.net/console，登录后进入 API Keys 页面https://taotoken.net/api-keys，创建一个新的 Key 并复制保存。这个 Key 就是你后面所有工具共用的凭证。注意 Key 只在创建时完整显示一次，建议直接存进环境变量，不要硬编码进脚本。
Base URL 统一用https://taotoken.net/api，这个地址不带任何查询参数，是标准的 API 入口。模型 ID 按你实际使用的模型填写，比如做代码辅助时选一个擅长代码的模型即可。三件套就是：Base URL + Key + Model ID，缺一不可。
如果你用的是 Claude Code 这类命令行编码工具，可以在它的配置里填入上面的 Base URL 和 Key；如果你用的是 Cline、Cursor 这类编辑器插件，同样在模型设置里选「自定义 OpenAI 兼容」然后填 Base URL。配置完成后，你可以先在模型对话页面https://taotoken.net/models里发一条测试消息，确认通道是通的，再去写数据库代码。
这里要强调一点：TaoToken 是辅助你生成和排查 SQL 的通道，不是数据库本身。sqlite3 的连接、游标、事务全部由 Python 标准库完成，两者职责不要混淆。把环境配好之后，我们进入真正的数据库实验。
配置时建议用环境变量管理 Key，避免泄露：
export TAOTOKEN_API_KEY="你的Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"Windows 下可以用set或系统环境变量面板设置。设置完成后，在 Python 里用os.environ.get("TAOTOKEN_API_KEY")读取即可。这样你的脚本可以安全地提交到 Git，而不会把 Key 带出去。
3. 可复制的 sqlite3 连接配置与建表脚本：连接、游标、事务一次到位
这一节是全文的核心，给出可以直接复制运行的完整脚本。我会把连接配置、建表、插入、查询、事务提交与回滚全部串起来，并且每一段都加上注释说明它在做什么。
先看连接和建表部分。sqlite3.connect('test.db')会在当前目录创建或打开test.db文件。如果文件不存在就新建，存在就打开。连接成功后返回 connection 对象，接着用conn.cursor()创建游标，所有 SQL 都通过游标执行。
import sqlite3 # 连接数据库，文件不存在则自动创建 conn = sqlite3.connect('test.db') print("Opened database successfully") # 创建游标对象，后续所有 SQL 通过它执行 cursor = conn.cursor() # 如果表已存在先删除，保证实验可复现 cursor.execute('DROP TABLE IF EXISTS student') # 创建 student 表，id 为主键且非空，name 为文本 cursor.execute(''' CREATE TABLE student ( id INTEGER PRIMARY KEY NOT NULL, name TEXT NOT NULL, age INTEGER ) ''') print("Table created successfully") # 提交建表操作 conn.commit()注意这里用了DROP TABLE IF EXISTS，这是保证实验可复现的关键。很多教程直接DROP TABLE student，第一次跑没问题，第二次跑就报no such table。加上IF EXISTS之后，无论表存不存在都不会中断脚本。
接下来是插入数据。这里演示参数化写法，用?占位符，把真实值放在元组里传入。参数化不仅能防止 SQL 注入，还能正确处理字符串里的引号，避免拼接字符串带来的转义问题。
# 插入单条数据，使用参数化占位符 cursor.execute( 'INSERT OR REPLACE INTO student (id, name, age) VALUES (?, ?, ?)', (1, 'Alice', 20) ) # 插入多条数据，用 executemany 批量执行 students = [ (2, 'Bob', 22), (3, 'Carol', 21), (4, 'David', 23), ] cursor.executemany( 'INSERT OR REPLACE INTO student (id, name, age) VALUES (?, ?, ?)', students ) # 提交事务，数据才真正写入文件 conn.commit() print("Data inserted successfully")INSERT OR REPLACE是 sqlite3 的一个实用语法：如果主键冲突，就替换原有行。这在做可复现实验时很方便，重复运行脚本不会因为主键重复而报错。
查询部分要特别注意游标的迭代特性。cursor.execute(sql)之后，游标本身就是一个可迭代对象，可以直接for row in cursor遍历。但遍历完之后游标就到底了，再遍历就是空的。如果需要多次读取，要么重新execute()，要么用fetchall()一次性取出存成列表。
# 查询方式一：直接遍历游标 cursor.execute('SELECT * FROM student') for row in cursor: print(row) # 查询方式二：fetchall 取出全部结果 cursor.execute('SELECT * FROM student') rows = cursor.fetchall() for row in rows: print('id:', row[0], 'name:', row[1], 'age:', row[2]) # 查询方式三：带参数查询单条 cursor.execute('SELECT * FROM student WHERE id = ?', (1,)) one = cursor.fetchone() print('fetchone result:', one)fetchone()取下一行，fetchmany(size)取接下来 size 行，fetchall()取剩余全部。rowcount属性可以拿到最近一次execute影响的行数，做插入或更新后可以用它确认影响范围。
最后是关闭顺序。先关游标，再关连接。虽然 Python 的垃圾回收最终也会释放，但显式关闭能确保事务状态干净，避免文件句柄泄漏。
cursor.close() conn.close() print("Connection closed")把上面几段拼起来就是一个完整可运行的脚本。运行后你会看到建表、插入、查询、关闭的完整输出。这就是一次可复现的数据库读写实验。
4. 验证请求与成功结果：事务提交与回滚的实测动作
光会插入查询还不够，事务的提交和回滚才是 sqlite3 真正容易出错的地方。这一节我用两个对照实验来验证：一个演示正常提交，一个演示异常回滚。
先看提交实验。事务的本质是「一组操作要么全成功，要么全失败」。在 sqlite3 里，默认情况下每条写操作其实都在一个隐式事务里，但当你连续执行多条写操作时，最好显式控制事务边界。
import sqlite3 conn = sqlite3.connect('test.db') cursor = conn.cursor() try: cursor.execute('INSERT INTO student (id, name, age) VALUES (?, ?, ?)', (5, 'Eve', 24)) cursor.execute('INSERT INTO student (id, name, age) VALUES (?, ?, ?)', (6, 'Frank', 25)) conn.commit() print("Transaction committed successfully") except sqlite3.Error as e: conn.rollback() print("Transaction rolled back:", e) finally: cursor.close() conn.close()运行后如果两条插入都成功，commit()会把它们一起写入文件。此时你重新打开数据库查询，能看到 id 为 5 和 6 的记录。
再看回滚实验。故意制造一个错误，比如插入重复主键，观察回滚是否生效。
import sqlite3 conn = sqlite3.connect('test.db') cursor = conn.cursor() try: cursor.execute('INSERT INTO student (id, name, age) VALUES (?, ?, ?)', (7, 'Grace', 26)) # 下面这条会因主键冲突报错 cursor.execute('INSERT INTO student (id, name, age) VALUES (?, ?, ?)', (7, 'Heidi', 27)) conn.commit() except sqlite3.IntegrityError as e: conn.rollback() print("IntegrityError caught, rolled back:", e) finally: cursor.close() conn.close()运行后你会看到IntegrityError被捕获，rollback()执行。此时再查询数据库，id 为 7 的记录不存在，因为第一条插入也被一起回滚了。这就是事务的原子性：要么两条都进，要么一条都不进。
如果你把rollback()去掉，只捕获异常不处理，那么第一条插入会留在未提交状态，连接关闭时 sqlite3 的行为取决于版本，可能自动提交也可能丢弃，结果不可控。所以「捕获异常必须回滚」是铁律。
验证结果时，可以用一个独立的查询脚本确认数据状态：
import sqlite3 conn = sqlite3.connect('test.db') cursor = conn.cursor() cursor.execute('SELECT * FROM student ORDER BY id') for row in cursor.fetchall(): print(row) cursor.close() conn.close()正常提交后能看到 5、6 号记录；回滚实验后看不到 7 号记录。两个实验对照，事务的提交与回滚就验证清楚了。
5. 本篇常见报错排查：从 401 到 reading choices 逐个击破
做 sqlite3 实验时，报错分两类：一类是数据库本身的，一类是辅助通道的。我把最常见的几个列出来，对照排查。
sqlite3.OperationalError: no such table: student。这个报错说明你查询的表不存在。原因通常是建表脚本没跑，或者跑在了另一个目录的test.db上。sqlite3 的路径是相对当前工作目录的，如果你在 A 目录建表、在 B 目录查询，打开的是两个不同的文件。解决办法是统一用绝对路径，或者确认os.getcwd()。
sqlite3.IntegrityError: UNIQUE constraint failed: student.id。主键冲突。如果你用的是INSERT而不是INSERT OR REPLACE，重复 id 就会报这个。要么改用INSERT OR REPLACE，要么在插入前先查询是否存在。
sqlite3.ProgrammingError: Cannot operate on a closed cursor。游标已经关闭还在用。检查cursor.close()之后是否还有execute调用。关闭顺序应该是先游标后连接，且关闭后不再使用。
sqlite3.ProgrammingError: You can only execute one statement at a time。一次execute里塞了多条 SQL。sqlite3 的execute一次只能执行一条语句，多条要用executescript()，或者拆成多次execute。
local proxy failed或401 Unauthorized。这类报错通常出现在你配置 TaoToken 通道时。401 说明 Key 无效或没带上，检查Authorization: Bearer <Key>头是否正确，Key 是否复制完整。local proxy failed一般是本地代理配置和 Base URL 冲突，确认 Base URL 用的是https://taotoken.net/api，不要额外加路径或参数。
reading choices相关报错。这类通常出现在模型返回结构解析阶段，说明返回体不是预期的 JSON 结构。检查请求的Content-Type和模型 ID 是否正确，确认你调用的模型支持当前接口格式。如果用的是 Claude Code 或 Cline 这类工具，检查它们的配置文件里 Base URL、Key、Model ID 三件套是否齐全。
OAuth相关报错。如果你用的是需要 OAuth 的工具，确认授权流程是否走完，token 是否过期。OAuth 和 API Key 是两套机制，不要混用。
排查顺序建议：先确认数据库文件路径和表是否存在，再确认游标和连接的生命周期，最后确认辅助通道的 Base URL、Key、Model ID。把这三层分开看，大部分报错都能定位。
6. 把统一 Key 用进日常编码：从这次实验到长期工作流
这次实验跑通之后，你手里其实有了两样东西：一套可复现的 sqlite3 连接、游标、事务模板，以及一个配好的统一 Key 通道。接下来可以把它们组合进日常编码流程。
比如你写一个新的建表脚本时，可以让模型帮你根据字段描述生成CREATE TABLE语句，然后自己复制进脚本运行验证。遇到OperationalError时，把报错和上下文贴给模型，让它帮你判断是路径问题还是 SQL 语法问题。写复杂查询时，让模型把子查询改写成 JOIN，再自己跑一遍确认结果一致。
如果你长期做编码和 Agent 类任务，可以考虑用 Coding Plan 这类方案，把统一 Key 用在更多工具里，减少重复配置。模型对话入口在https://taotoken.net/models，接入文档在https://taotoken.net/doc，API Keys 管理在https://taotoken.net/api-keys。需要长期编码支持的话，Coding Plan 页面在https://taotoken.net/coding-plan。
回到 sqlite3 本身，给你几个实用建议。第一，所有写操作都放在try/except里，异常时rollback()。第二，游标用完就关，连接用完就关，不要依赖垃圾回收。第三，参数化查询永远用?占位符，不要拼接字符串。第四，做实验时用DROP TABLE IF EXISTS保证可复现。第五，路径统一用绝对路径，避免工作目录切换导致的「表不见了」。
这套模板你可以直接拿去改字段、改表名，用在本地工具、脚本、原型里。数据库连接、游标、事务这三块吃透之后，再去看 ORM 或者更复杂的数据库，底层逻辑都是相通的。
