1. 为什么 pymysql 查询只拿到数据表头却不见了用 Python 连 MySQL 写脚本时很多人第一次都会遇到这个场景SQL 明明执行成功了cursor.fetchall()也能打印出一堆数据行但想把字段名一起输出时发现结果里只有值没有列名。尤其是用 Cline、Cursor 这类 AI 工具辅助生成代码时模型经常只给你fetchall()的写法表头那一步被悄悄省略脚本跑起来看着没问题一旦要写 CSV、做数据校验或者对接前端表格字段缺失的问题立刻暴露。这个问题的本质不是 pymysql 有 bug而是查询结果的元信息藏在另一个属性里。cursor.execute()之后游标对象上会挂一个description它记录的是本次查询返回列的元数据包括列名、类型、是否可为空等。很多人只记得fetchall()忘了description于是表头就丢了。还有一种情况是 SQL 里用了SELECT *字段顺序和表结构一致但脚本里硬编码了列名一旦表结构变更代码和实际返回就对不上排查起来更费劲。这篇面向的是正在用 AI 工具写数据库脚本的开发者重点解决三件事怎么用cursor.description稳定拿到表头、怎么在 AI 工具的配置里统一管理模型 Key 避免到处粘贴、以及怎么用一条验证动作确认字段名和表结构一致。下面按可复制的步骤走代码都能直接跑。2. TaoToken 前置给 AI 工具一个统一 Key 入口在用 Cline、Cursor 这类工具辅助写 pymysql 脚本时一个很现实的麻烦是每个工具都要单独填模型地址和 Key换一个工具就重新配一遍团队里几个人用的配置还不一样排查问题时连到底用的哪个模型都说不清。TaoToken 在这里的作用是提供一个统一的接入入口把模型对话、编码计划、API Key 管理收敛到一处工具侧只需要指向同一个地址。它的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 这条不带 UTM 参数配置时直接填这个。对于写数据库脚本这种场景我一般会先把 Key 在控制台建好再让 AI 工具引用这样脚本里不出现明文 Key配置也能复用。需要提前准备的东西不多一个可用的 TaoToken 账号、在控制台创建的 API Key、以及你本地已经装好的 Python 环境和 MySQL 实例。Key 的创建入口在控制台的 API Keys 页面地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 建完之后复制出来后面配置里会用到。如果你更想先验证模型能不能正常对话可以走模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 先跑通一次再进编码环节。注意Key 属于敏感信息不要写进脚本源码提交到仓库建议放在环境变量或工具的配置文件里下面会给配置骨架。3. 可复制配置cursor.description 取表头 settings.json 骨架3.1 最小可运行脚本先装依赖pymysql 是纯 Python 实现安装没有编译负担pip install pymysql然后是完整脚本重点看cursor.description那一段import pymysql # 连接配置生产环境建议从环境变量读取 conn pymysql.connect( host127.0.0.1, port3306, userroot, passwordyour_password, dbtest, charsetutf8mb4, cursorclasspymysql.cursors.Cursor, ) try: with conn.cursor() as cursor: sql SELECT id, name, age FROM student cursor.execute(sql) # 关键description 在 execute 之后才有值 headers [col[0] for col in cursor.description] print(字段名列表:, headers) rows cursor.fetchall() print(数据行数:, len(rows)) for row in rows: print(row) finally: conn.close()cursor.description是一个元组序列每个元素描述一列col[0]就是列名col[1]是类型码col[2]到col[6]分别是显示大小、内部大小、精度、小数位数和是否可为空。日常取表头只用col[0]就够了要做类型映射时再取col[1]。3.2 把表头和数据拼成字典列表实际写脚本时光有表头列表还不够通常要拼成[{列名: 值}]的结构方便直接转 JSONdef query_as_dicts(conn, sql, argsNone): with conn.cursor() as cursor: cursor.execute(sql, args) headers [col[0] for col in cursor.description] rows cursor.fetchall() return [dict(zip(headers, row)) for row in rows] result query_as_dicts(conn, SELECT id, name, age FROM student WHERE age %s, (18,)) print(result)这里有个容易踩的点cursor.description必须在execute()之后、fetchall()之前或之后读都行但如果在execute()之前读它是None。AI 工具生成的代码有时把顺序写反跑起来就报TypeError: NoneType object is not iterable。3.3 settings.json 中 TaoToken 统一 Key 配置骨架如果你用 Cline 或 Cursor 这类支持自定义模型地址的工具可以在 settings.json 里统一配置避免每个项目重复填。下面是一个骨架字段名按你所用工具的实际规范调整{ aiProvider: { baseUrl: https://taotoken.net/api, apiKey: ${env:TAOTOKEN_API_KEY}, model: claude-sonnet-4-20250514, timeout: 60000 }, database: { host: 127.0.0.1, port: 3306, user: root, db: test, charset: utf8mb4 } }apiKey用${env:TAOTOKEN_API_KEY}引用环境变量本地在 shell 里export TAOTOKEN_API_KEY你的Key即可这样配置文件可以安全地进版本库。baseUrl填https://taotoken.net/api不要带 UTM 参数。模型名按你实际开通的填长期做编码和 Agent 任务的话Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 里有对应的套餐说明可以先看一眼再决定用哪个模型。提示不同工具对配置字段的命名不完全一样有的叫baseURL有的叫endpoint以工具文档为准核心是地址和 Key 两件事。4. 验证请求打印字段名列表并和表结构对齐配置写完不算完得有一条明确的验证动作。最直接的方式是跑一个脚本把cursor.description拿到的字段名和information_schema里的表结构做对比import pymysql conn pymysql.connect( host127.0.0.1, port3306, userroot, passwordyour_password, dbtest, charsetutf8mb4 ) table student with conn.cursor() as cursor: # 查询返回的字段名 cursor.execute(fSELECT * FROM {table} LIMIT 1) query_headers [col[0] for col in cursor.description] # 表结构里的字段名 cursor.execute( SELECT COLUMN_NAME FROM information_schema.COLUMNS WHERE TABLE_SCHEMA %s AND TABLE_NAME %s ORDER BY ORDINAL_POSITION, (test, table), ) schema_headers [row[0] for row in cursor.fetchall()] print(查询字段:, query_headers) print(表结构字段:, schema_headers) print(是否一致:, query_headers schema_headers) conn.close()跑出来如果两个列表完全相等说明SELECT *的返回顺序和表结构一致脚本里按位置取值的逻辑是安全的。如果不等通常是 SQL 里显式写了列顺序或者表结构刚改过而脚本没同步。这一步做完字段缺失的问题基本就定位清楚了。实测下来把这条验证脚本挂到 CI 里每次改表结构后自动跑一次能提前发现脚本和表结构脱节的情况比等到线上报错再查省事得多。5. 本篇常见错排查5.1 cursor.description 返回 None最常见的原因是读的时机不对。description只有在execute()执行了返回结果集的语句之后才有值INSERT、UPDATE、DELETE这类不返回结果集的语句执行完它仍然是None。另外如果execute()本身抛异常被吞掉了后面读description也会是None。排查时先确认 SQL 是SELECT再确认execute()没有报错。5.2 字段名对但顺序不对SELECT *的字段顺序由表结构决定但如果你在 SQL 里写了SELECT name, id FROM student返回顺序就按你写的来description也跟着变。脚本里如果用位置索引取值比如row[0]当 idSQL 一改顺序就错位。稳妥做法是用dict(zip(headers, row))转成字典按列名取值。5.3 中文列名或别名乱码如果表里有中文列名或者 SQL 里用了AS 别名description返回的是别名而不是原列名。连接时charset要设成utf8mb4否则中文列名可能显示成乱码。另外别名里带空格或特殊字符时记得用反引号包起来。5.4 AI 工具生成的代码漏了 description这是用 Cline、Cursor 时的高频问题。模型倾向于给最短的能跑通的代码fetchall()一写就完事表头那行经常被省。解决办法是在提示词里明确要求必须用 cursor.description 输出字段名列表或者在项目里放一个工具函数让模型复用而不是每次重写。配置里统一了 TaoToken 的 Key 之后模型调用稳定生成代码的一致性也会好一些。5.5 连接没关导致后续查询异常脚本里如果忘了conn.close()长时间运行会耗尽连接数后续查询可能直接失败表现成表头拿不到。用with conn.cursor()管理游标用try/finally或上下文管理器管理连接能避免大部分这类问题。6. 把 Key 和脚本配置收拢到一处写数据库脚本这件事代码本身不复杂麻烦的是配置散落各处模型 Key 在工具 A 里填一遍在工具 B 里再填一遍数据库密码又写在脚本里。把 TaoToken 作为统一的模型接入入口Key 在控制台建一次工具侧通过settings.json引用环境变量脚本侧只关心 SQL 和cursor.description的逻辑职责就清晰了。接入相关的文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置字段有疑问时可以对照。如果你主要用 Claude Code 这类命令行工具做编码Anthropic 兼容接入的说明在 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 按里面的地址填就行。最后留一个我常用的习惯每次新建数据库脚本项目先把上面那段验证脚本跑一遍确认query_headers schema_headers为真再开始写业务逻辑。这一步花不了一分钟但能省掉后面大量字段对不上的排查时间。