1. Python sqlite3 游标到底在做什么
如果你写过conn.execute("select ...")就直接拿结果，可能没意识到背后其实已经隐式创建了一个游标。sqlite3的游标（Cursor）是连接对象和 SQL 语句之间的执行通道，它负责把 SQL 发给数据库、维护结果集的位置、再把行按需吐给你。理解游标，本质上是理解「结果集是有状态的」这件事。
游标最容易被忽略的特性是：它像迭代器一样只能往前走，fetchone()取一行就少一行，fetchall()取完之后再取就是空列表。很多人第一次踩坑就是先fetchone()探一下有没有数据，然后再fetchall()，结果发现只剩后面几行。这不是 bug，是游标的位置被消耗了。
这篇面向的是本地脚本或小型服务场景：你用 Python 的sqlite3做增删改查，同时希望通过统一的 Key/API 通道调用模型来辅助生成 SQL、补全游标逻辑、排查报错。我会把settings.json配置骨架、游标验证脚本、连通性验证动作串成一条可复制的链路，让你一次跑通。
适合谁：写过一点 Python、知道import sqlite3但游标用得不够顺手的开发者；或者想把模型调用配置从代码里抽出来、统一走一个入口的工程化需求。下面所有代码都可以直接粘贴运行，配置项按你的实际环境替换即可。
2. 统一 Key 接入的前置准备
把模型调用配置写死在代码里，换环境就要改代码，这是小型项目最常见的维护痛点。更稳的做法是抽一个settings.json，把 base_url、api_key、模型名、超时这些放进去，代码只读配置。这样本地脚本、CI、小服务可以共用同一套骨架，只换配置文件。
统一接入的地址我用 TaoToken 这套：官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数，配置里写干净的 base_url 就行。Key 的获取在控制台的 API Keys 页面：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
这里要区分两个概念：sqlite3的游标是本地数据库操作，模型调用是另一条网络链路。两者不冲突，但配置要分开管理。我建议settings.json里用database和llm两个顶层键，数据库部分放文件路径和超时，模型部分放 base_url、api_key、model、timeout。这样你调试游标逻辑时不会因为模型配置写错而整个脚本起不来。
一个实际经验：不要把 api_key 提交进 git。settings.json可以提交一个settings.example.json，真实文件加进.gitignore，或者用环境变量覆盖。下面骨架里我会用api_key_env字段支持从环境变量读取，兼顾方便和安全。
3. settings.json 配置骨架与游标脚本
先给配置骨架。字段命名尽量直白，方便你和团队其他人一眼看懂。database.path是 sqlite 文件路径，:memory:表示内存库，适合测试。llm.base_url固定写 API 基址，llm.api_key_env指向环境变量名，代码运行时读取。
{ "database": { "path": "app.db", "timeout": 5.0, "detect_types": false }, "llm": { "base_url": "https://taotoken.net/api", "api_key_env": "TAOTOKEN_API_KEY", "model": "claude-sonnet-4-20250514", "timeout": 30, "max_tokens": 1024 }, "app": { "table": "catalog", "log_level": "INFO" } }读取配置和建立连接的代码。注意sqlite3.connect的timeout参数控制的是锁等待时间，不是查询超时，别混淆。row_factory设成sqlite3.Row之后，游标取出来的行可以按列名访问，比纯 tuple 好用很多，这是游标使用里性价比最高的一个设置。
import json import os import sqlite3 def load_settings(path="settings.json"): with open(path, "r", encoding="utf-8") as f: return json.load(f) def get_connection(cfg): db = cfg["database"] conn = sqlite3.connect(db["path"], timeout=db.get("timeout", 5.0)) conn.row_factory = sqlite3.Row return conn def get_api_key(cfg): env_name = cfg["llm"]["api_key_env"] key = os.environ.get(env_name) if not key: raise RuntimeError(f"环境变量 {env_name} 未设置") return key接下来是游标的核心操作。建表、插入、查询、更新、删除，每一步都用显式游标，方便你观察状态变化。executemany批量插入比循环execute快很多，数据量大时差别明显。
def init_table(conn, table): cur = conn.cursor() cur.execute(f""" create table if not exists {table} ( id integer primary key, pid integer, name varchar(32) unique ) """) conn.commit() cur.close() def insert_rows(conn, table, rows): cur = conn.cursor() cur.executemany( f"insert or ignore into {table} (id, pid, name) values (?, ?, ?)", rows ) conn.commit() print(f"插入影响行数: {cur.rowcount}") cur.close() def query_all(conn, table): cur = conn.cursor() cur.execute(f"select id, pid, name from {table} order by id") rows = cur.fetchall() cur.close() return rows游标的状态特性用一个对比脚本演示最清楚。下面这段先fetchone()再fetchall()，你会看到fetchall只剩后面的行，因为游标位置已经前移了。想重新从头取，必须重新execute。
def demo_cursor_state(conn, table): cur = conn.cursor() cur.execute(f"select id, name from {table} order by id") first = cur.fetchone() print("fetchone:", dict(first) if first else None) rest = cur.fetchall() print("fetchall 剩余:", [dict(r) for r in rest]) cur.close() cur2 = conn.cursor() cur2.execute(f"select id, name from {table} order by id") print("重新 execute 后 fetchall:", [dict(r) for r in cur2.fetchall()]) cur2.close()更新和删除同样走游标，重点是commit()的时机。sqlite3默认在 DML 语句前自动开事务，你不 commit，改动只在当前连接可见，别的连接读不到，程序异常退出还会回滚。小型服务里我习惯每次写操作后立即 commit，而不是攒到关闭时统一提交。
def update_row(conn, table, row_id, new_name): cur = conn.cursor() cur.execute(f"update {table} set name = ? where id = ?", (new_name, row_id)) conn.commit() print(f"更新影响行数: {cur.rowcount}") cur.close() def delete_row(conn, table, row_id): cur = conn.cursor() cur.execute(f"delete from {table} where id = ?", (row_id,)) conn.commit() print(f"删除影响行数: {cur.rowcount}") cur.close()把上面拼起来跑一遍，你就有了一个完整的游标操作闭环。参数化查询用?占位符，不要用字符串拼接，这是防注入的基本功，也是游标execute第二个参数存在的意义。
4. 连通性验证与成功结果
配置和脚本都有了，先验证模型通道能不能通。用requests发一个最小请求，确认 base_url 和 key 都正确。这一步和 sqlite 无关，但它是你后续用模型辅助生成 SQL 的前提。
import requests def verify_llm(cfg): key = get_api_key(cfg) url = cfg["llm"]["base_url"].rstrip("/") + "/v1/messages" headers = { "x-api-key": key, "anthropic-version": "2023-06-01", "content-type": "application/json", } payload = { "model": cfg["llm"]["model"], "max_tokens": 64, "messages": [ {"role": "user", "content": "只回复两个字：连通"} ], } resp = requests.post(url, headers=headers, json=payload, timeout=cfg["llm"]["timeout"]) print("状态码:", resp.status_code) print("响应:", resp.text[:300]) return resp.status_code == 200跑通后你会看到状态码 200，响应体里包含模型返回的文本。如果返回 401，检查环境变量是否设置、key 是否复制完整；返回 404 通常是 base_url 拼错，注意不要重复加/v1。
再验证 sqlite 游标链路。下面这段把配置加载、建表、插入、查询、状态演示、更新、删除串起来，直接运行看输出。
if __name__ == "__main__": cfg = load_settings() conn = get_connection(cfg) table = cfg["app"]["table"] init_table(conn, table) insert_rows(conn, table, [(0, 0, "name1"), (1, 0, "name2"), (2, 0, "name3")]) print("全量查询:", [dict(r) for r in query_all(conn, table)]) demo_cursor_state(conn, table) update_row(conn, table, 0, "name1_updated") delete_row(conn, table, 2) print("最终数据:", [dict(r) for r in query_all(conn, table)]) conn.close()预期输出大致是：插入影响行数 3，全量查询三行，fetchone返回第一行，fetchall只剩两行，重新 execute 后又是三行，更新影响行数 1，删除影响行数 1，最终数据两行。看到这个结果，说明游标的状态行为和你的预期一致了。
如果你想让模型帮你生成复杂 SQL，可以把表结构和需求描述发给模型，走同一个verify_llm里的通道。模型对话入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite ，适合快速试 prompt；长期写代码、跑 Agent 的场景更适合 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。
5. 本篇常见错排查
游标取完数据为空。最常见的原因是同一个游标先fetchone再fetchall，或者循环里重复fetchall。游标位置只前进不后退，取完就没了。解决方式是每次查询重新execute，或者用fetchmany(n)分批取。
忘记 commit 导致数据丢失。插入、更新、删除之后没commit，程序正常退出时sqlite3会回滚未提交事务。表现是脚本里查得到，重开连接就没了。养成写操作后立即 commit 的习惯，或者用with conn:上下文管理器自动提交。
rowcount对 select 返回 -1。rowcount只对 DML 语句有意义，select 之后它不可靠。想知道查询返回多少行，用len(cur.fetchall())，但注意这会消耗游标。
多线程共用连接报错。sqlite3连接默认不能跨线程使用，会抛ProgrammingError。小型服务里要么每个线程独立连接，要么用连接池，要么加锁串行化。别图省事全局共享一个 conn。
参数化查询写成字符串拼接。cur.execute(f"select * from t where id = {x}")这种写法既有注入风险，遇到字符串类型还会因为引号报错。统一用?占位符加元组参数。
模型调用返回 401 或 403。先确认环境变量名和settings.json里的api_key_env一致，再确认 key 没有多余空格。如果用的是控制台新建的 key，注意有些 key 只在创建时显示一次。接入文档里有完整的鉴权说明：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
base_url 拼接重复路径。https://taotoken.net/api后面接/v1/messages是完整路径，不要再手动加一层/api。建议在代码里用rstrip("/")统一处理尾部斜杠。
6. 把配置和游标固化成项目习惯
跑通之后，建议把settings.json的读取封装成一个模块，所有脚本都从它拿配置，而不是各自open文件。游标操作也封装成小函数，比如query_all、insert_rows，调用方不直接碰conn.cursor()。这样换数据库、换模型通道时，改动集中在一处。
Key 的管理走控制台：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，需要轮换或新增时在这里操作，代码侧只改环境变量。API 基址保持 https://taotoken.net/api 不变，配置骨架里的base_url就不用动。
最后留一个实用技巧：调试游标逻辑时，把conn.row_factory设成sqlite3.Row，打印时用dict(row)转一下，输出比裸 tuple 可读得多。等逻辑稳定了再考虑性能优化，比如批量操作用executemany、只读查询用fetchmany控制内存。游标本身不复杂，难的是记住它是有状态的，每次取数据前想一下「游标现在在哪」。
