1. pymysql 连接 MySQL 报错频发先理清 Python 项目里的配置分层刚接触 Python 操作 MySQL 时很多人会把连接参数直接写死在脚本里跑通一次就以为万事大吉。等到项目里同时出现数据库连接、AI 工具调用、环境切换时才发现参数散落各处改一个地方要翻五个文件。pymysql 本身是纯 Python 实现的 MySQL 客户端安装简单、API 直观适合快速验证和中小型项目。它的基本使用流程是引入模块、建立连接、创建游标、执行 SQL、获取结果、关闭连接。这套流程本身不复杂真正让人头疼的是连接失败时的排查——报错信息往往只给一个错误码不告诉你到底是网络、认证还是字符集的问题。我试过在一个新环境里部署脚本pymysql 报Access denied for user rootlocalhost查了半天发现是密码里有个特殊字符被 shell 转义了。这类问题不是 pymysql 的锅而是配置管理没做好。所以这篇内容的核心思路是先把 pymysql 的基本使用跑通再引入一个统一的配置文件骨架config.toml把数据库连接和 AI 工具接入的 Key 管理放在同一层避免后面接大模型时又要重新折腾一遍配置。适合谁看如果你正在学 Python 数据库操作或者项目里已经用 pymysql 但配置散乱又或者你打算在项目里接入 AI 能力但不想把 Key 硬编码在代码里这篇的步骤可以直接跟做。下面从环境准备开始一步步给出可复制的配置和验证命令。2. TaoToken 统一 Key 接入前的前置准备与 config.toml 定位在讲 pymysql 连接之前先说明为什么要在项目里预留config.toml。Python 项目常见的配置方式有三种硬编码在脚本里、用.env文件、用 TOML/YAML 配置文件。硬编码最省事但最危险.env适合简单键值对TOML 则适合分层结构比如[database]、[ai]、[logging]各占一段可读性好Python 3.11 之后标准库自带tomllib解析不需要额外装包。TaoToken 在这里的角色是统一 Key 和 API 通道。你可以把它理解为一个中间层项目里所有需要调用 AI 能力的地方都通过同一个 Base URL 和同一个 Key 走不用为每个模型单独记一套地址和密钥。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置里填这个就行。前置准备清单Python 3.8 以上、MySQL 5.7 或 8.0 已启动、pymysql 已安装pip install pymysql、一个可用的数据库和账号。如果你还没有 TaoToken 的 Key可以去控制台创建一个地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。Key 创建后在 API Keys 页面管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。config.toml放在项目根目录和main.py同级。它的作用是数据库连接参数集中管理AI 接入参数预留占位环境切换时只改这一个文件。下面给出完整骨架。3. 可复制的 config.toml 骨架与 pymysql 连接参数模板先给config.toml的完整内容你可以直接复制到项目根目录把值改成自己的# config.toml # 项目统一配置数据库与 AI 工具接入共用 [database] host 127.0.0.1 port 3306 user root password root1234 charset utf8mb4 database db_04 connect_timeout 10 [ai] # TaoToken 统一 Key 接入配置 base_url https://taotoken.net/api api_key sk-你的Key填这里 default_model claude-sonnet-4-20250514 timeout 60 [logging] level INFO file app.log注意几个细节。charset写utf8mb4而不是utf8因为 MySQL 的utf8是阉割版存 emoji 会报错utf8mb4才是完整的四字节 UTF-8。connect_timeout设 10 秒避免网络不通时脚本卡死。[ai]段里的base_url填 TaoToken 的 API 地址api_key填你创建的那串 Keydefault_model先占位后面接 Claude Code 或 Cline 时再按需改。读取配置的 Python 代码import tomllib with open(config.toml, rb) as f: config tomllib.load(f) db_conf config[database] ai_conf config[ai]如果你用的是 Python 3.10 或更低版本tomllib不可用装tomli代替pip install tomli然后import tomli as tomllib。pymysql 连接模板把配置传进去import pymysql conn pymysql.connect( hostdb_conf[host], portdb_conf[port], userdb_conf[user], passworddb_conf[password], charsetdb_conf[charset], databasedb_conf[database], connect_timeoutdb_conf[connect_timeout], cursorclasspymysql.cursors.DictCursor, )这里把cursorclass直接设在连接上后面conn.cursor()就不用再传了返回的每行是字典取值用row[字段名]比下标清晰。如果你用 Cline MCP 或 Claude Code 做辅助开发它们读取项目配置时也会认这个config.tomlBase URL、Key、Model ID 三件套在[ai]段里已经齐了。4. 验证请求与成功结果从连接测试到游标操作配置写好后先做最小验证只连接不查数据。import pymysql import tomllib with open(config.toml, rb) as f: config tomllib.load(f) db config[database] try: conn pymysql.connect( hostdb[host], portdb[port], userdb[user], passworddb[password], charsetdb[charset], databasedb[database], connect_timeoutdb[connect_timeout], cursorclasspymysql.cursors.DictCursor, ) print(连接成功MySQL 版本, conn.get_server_info()) except pymysql.err.OperationalError as e: print(连接失败错误码, e.args[0], 信息, e.args[1]) finally: if conn in dir() and conn.open: conn.close()跑通后输出类似连接成功MySQL 版本 8.0.35。这一步过了再执行查询with conn.cursor() as cursor: sql select * from dep; affected cursor.execute(sql) print(影响行数, affected) print(第一条, cursor.fetchone()) print(下一条, cursor.fetchone()) cursor.scroll(0, absolute) print(全部, cursor.fetchall())execute返回的是受影响行数不是结果集。fetchone取一条光标下移fetchmany(n)取 n 条fetchall取剩余全部。scroll(offset, mode)里relative是相对当前位置absolute是相对起始位置。实测下来DictCursor配合fetchall最顺手直接拿到字典列表转 JSON 也方便。如果你要验证 TaoToken 的 AI 通道是否通可以用模型对话页面发一条测试消息https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。或者在代码里用requests调base_url加/v1/messages带上api_key看返回是否正常。这一步不是必须但能提前确认 Key 有效避免后面接 Coding Plan 时才发现 Key 填错。5. 本篇常见报错排查401、local proxy failed、reading choices连接失败时先看错误码。下面按真实报错分类。报错一(1045, Access denied for user rootlocalhost (using password: YES))这是认证失败。检查config.toml里的user和password是否和 MySQL 里的一致。常见坑密码里有#或在 TOML 里要用引号包起来已经包了就没问题但如果密码是从环境变量读的注意 shell 转义。另外 MySQL 8.0 默认认证插件是caching_sha2_password老版本 pymysql 可能不兼容升级 pymysql 到最新版即可。报错二(2003, Cant connect to MySQL server on 127.0.0.1)网络层不通。先确认 MySQL 服务在跑systemctl status mysql或netstat -an | grep 3306。如果 MySQL 在 Docker 里host不能写127.0.0.1要写容器名或宿主机 IP。connect_timeout设太小也会误报先调到 30 试。报错三(2019, Cant initialize character set utf8mb4)字符集不支持。检查 MySQL 服务端是否编译了utf8mb4一般 5.7 以上都支持。如果用的是charsetutf-8改成utf8mb4注意是utf8mb4不是utf-8。报错四AI 通道返回401 Unauthorized这是 TaoToken Key 的问题。检查config.toml里api_key是否填了完整 Key有没有多余空格。如果用的是环境变量覆盖确认变量名没写错。401 也可能是 Key 过期或被删去 API Keys 页面重新生成一个。报错五local proxy failed或connection refused这类报错通常出现在 AI 工具接入时Base URL 填错或本地网络策略拦截。确认base_url填的是https://taotoken.net/api不要多加/v1或结尾斜杠。如果公司网络有出口限制换网络环境试。报错六reading choices相关错误这是解析 AI 返回结构时字段对不上。不同模型的返回格式略有差异choices字段在 OpenAI 兼容接口里有但 Anthropic 原生接口是content。如果你用 Claude Code 或 Cline确认 Model ID 填对比如claude-sonnet-4-20250514不要填成gpt-4。Codex 的auth.json里如果 Base URL 和 Key 不匹配也会报类似错误三件套要一起检查。排查顺序建议先确认 MySQL 服务活着再确认账号密码对再确认字符集最后才怀疑代码。AI 通道的排查顺序先确认 Key 有效再确认 Base URL 正确再确认 Model ID 匹配。6. 语义一致 CTA把配置骨架用起来config.toml骨架和 pymysql 连接模板已经给全了接下来就是把它跑起来。如果你在排障过程中需要确认 Key 状态或重新生成去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的调用示例。如果你打算长期在项目里用 AI 辅助编码比如接 Claude Code 或 Cline MCPCoding Plan 页面有套餐说明https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Claude Code 的接入配置可以参考https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后提醒一个实用技巧config.toml不要提交到 Git在.gitignore里加上config.toml然后提供一个config.example.toml作为模板。这样 Key 不会泄露新环境部署时复制模板改值就行。pymysql 的连接用完记得conn.close()或者用with上下文管理避免连接泄漏。
mysql专栏 06.pymysql 01.基本使用：TaoToken 统一 Key 接入前的 config.toml 骨架与报错排查
1. pymysql 连接 MySQL 报错频发先理清 Python 项目里的配置分层刚接触 Python 操作 MySQL 时很多人会把连接参数直接写死在脚本里跑通一次就以为万事大吉。等到项目里同时出现数据库连接、AI 工具调用、环境切换时才发现参数散落各处改一个地方要翻五个文件。pymysql 本身是纯 Python 实现的 MySQL 客户端安装简单、API 直观适合快速验证和中小型项目。它的基本使用流程是引入模块、建立连接、创建游标、执行 SQL、获取结果、关闭连接。这套流程本身不复杂真正让人头疼的是连接失败时的排查——报错信息往往只给一个错误码不告诉你到底是网络、认证还是字符集的问题。我试过在一个新环境里部署脚本pymysql 报Access denied for user rootlocalhost查了半天发现是密码里有个特殊字符被 shell 转义了。这类问题不是 pymysql 的锅而是配置管理没做好。所以这篇内容的核心思路是先把 pymysql 的基本使用跑通再引入一个统一的配置文件骨架config.toml把数据库连接和 AI 工具接入的 Key 管理放在同一层避免后面接大模型时又要重新折腾一遍配置。适合谁看如果你正在学 Python 数据库操作或者项目里已经用 pymysql 但配置散乱又或者你打算在项目里接入 AI 能力但不想把 Key 硬编码在代码里这篇的步骤可以直接跟做。下面从环境准备开始一步步给出可复制的配置和验证命令。2. TaoToken 统一 Key 接入前的前置准备与 config.toml 定位在讲 pymysql 连接之前先说明为什么要在项目里预留config.toml。Python 项目常见的配置方式有三种硬编码在脚本里、用.env文件、用 TOML/YAML 配置文件。硬编码最省事但最危险.env适合简单键值对TOML 则适合分层结构比如[database]、[ai]、[logging]各占一段可读性好Python 3.11 之后标准库自带tomllib解析不需要额外装包。TaoToken 在这里的角色是统一 Key 和 API 通道。你可以把它理解为一个中间层项目里所有需要调用 AI 能力的地方都通过同一个 Base URL 和同一个 Key 走不用为每个模型单独记一套地址和密钥。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置里填这个就行。前置准备清单Python 3.8 以上、MySQL 5.7 或 8.0 已启动、pymysql 已安装pip install pymysql、一个可用的数据库和账号。如果你还没有 TaoToken 的 Key可以去控制台创建一个地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。Key 创建后在 API Keys 页面管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。config.toml放在项目根目录和main.py同级。它的作用是数据库连接参数集中管理AI 接入参数预留占位环境切换时只改这一个文件。下面给出完整骨架。3. 可复制的 config.toml 骨架与 pymysql 连接参数模板先给config.toml的完整内容你可以直接复制到项目根目录把值改成自己的# config.toml # 项目统一配置数据库与 AI 工具接入共用 [database] host 127.0.0.1 port 3306 user root password root1234 charset utf8mb4 database db_04 connect_timeout 10 [ai] # TaoToken 统一 Key 接入配置 base_url https://taotoken.net/api api_key sk-你的Key填这里 default_model claude-sonnet-4-20250514 timeout 60 [logging] level INFO file app.log注意几个细节。charset写utf8mb4而不是utf8因为 MySQL 的utf8是阉割版存 emoji 会报错utf8mb4才是完整的四字节 UTF-8。connect_timeout设 10 秒避免网络不通时脚本卡死。[ai]段里的base_url填 TaoToken 的 API 地址api_key填你创建的那串 Keydefault_model先占位后面接 Claude Code 或 Cline 时再按需改。读取配置的 Python 代码import tomllib with open(config.toml, rb) as f: config tomllib.load(f) db_conf config[database] ai_conf config[ai]如果你用的是 Python 3.10 或更低版本tomllib不可用装tomli代替pip install tomli然后import tomli as tomllib。pymysql 连接模板把配置传进去import pymysql conn pymysql.connect( hostdb_conf[host], portdb_conf[port], userdb_conf[user], passworddb_conf[password], charsetdb_conf[charset], databasedb_conf[database], connect_timeoutdb_conf[connect_timeout], cursorclasspymysql.cursors.DictCursor, )这里把cursorclass直接设在连接上后面conn.cursor()就不用再传了返回的每行是字典取值用row[字段名]比下标清晰。如果你用 Cline MCP 或 Claude Code 做辅助开发它们读取项目配置时也会认这个config.tomlBase URL、Key、Model ID 三件套在[ai]段里已经齐了。4. 验证请求与成功结果从连接测试到游标操作配置写好后先做最小验证只连接不查数据。import pymysql import tomllib with open(config.toml, rb) as f: config tomllib.load(f) db config[database] try: conn pymysql.connect( hostdb[host], portdb[port], userdb[user], passworddb[password], charsetdb[charset], databasedb[database], connect_timeoutdb[connect_timeout], cursorclasspymysql.cursors.DictCursor, ) print(连接成功MySQL 版本, conn.get_server_info()) except pymysql.err.OperationalError as e: print(连接失败错误码, e.args[0], 信息, e.args[1]) finally: if conn in dir() and conn.open: conn.close()跑通后输出类似连接成功MySQL 版本 8.0.35。这一步过了再执行查询with conn.cursor() as cursor: sql select * from dep; affected cursor.execute(sql) print(影响行数, affected) print(第一条, cursor.fetchone()) print(下一条, cursor.fetchone()) cursor.scroll(0, absolute) print(全部, cursor.fetchall())execute返回的是受影响行数不是结果集。fetchone取一条光标下移fetchmany(n)取 n 条fetchall取剩余全部。scroll(offset, mode)里relative是相对当前位置absolute是相对起始位置。实测下来DictCursor配合fetchall最顺手直接拿到字典列表转 JSON 也方便。如果你要验证 TaoToken 的 AI 通道是否通可以用模型对话页面发一条测试消息https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。或者在代码里用requests调base_url加/v1/messages带上api_key看返回是否正常。这一步不是必须但能提前确认 Key 有效避免后面接 Coding Plan 时才发现 Key 填错。5. 本篇常见报错排查401、local proxy failed、reading choices连接失败时先看错误码。下面按真实报错分类。报错一(1045, Access denied for user rootlocalhost (using password: YES))这是认证失败。检查config.toml里的user和password是否和 MySQL 里的一致。常见坑密码里有#或在 TOML 里要用引号包起来已经包了就没问题但如果密码是从环境变量读的注意 shell 转义。另外 MySQL 8.0 默认认证插件是caching_sha2_password老版本 pymysql 可能不兼容升级 pymysql 到最新版即可。报错二(2003, Cant connect to MySQL server on 127.0.0.1)网络层不通。先确认 MySQL 服务在跑systemctl status mysql或netstat -an | grep 3306。如果 MySQL 在 Docker 里host不能写127.0.0.1要写容器名或宿主机 IP。connect_timeout设太小也会误报先调到 30 试。报错三(2019, Cant initialize character set utf8mb4)字符集不支持。检查 MySQL 服务端是否编译了utf8mb4一般 5.7 以上都支持。如果用的是charsetutf-8改成utf8mb4注意是utf8mb4不是utf-8。报错四AI 通道返回401 Unauthorized这是 TaoToken Key 的问题。检查config.toml里api_key是否填了完整 Key有没有多余空格。如果用的是环境变量覆盖确认变量名没写错。401 也可能是 Key 过期或被删去 API Keys 页面重新生成一个。报错五local proxy failed或connection refused这类报错通常出现在 AI 工具接入时Base URL 填错或本地网络策略拦截。确认base_url填的是https://taotoken.net/api不要多加/v1或结尾斜杠。如果公司网络有出口限制换网络环境试。报错六reading choices相关错误这是解析 AI 返回结构时字段对不上。不同模型的返回格式略有差异choices字段在 OpenAI 兼容接口里有但 Anthropic 原生接口是content。如果你用 Claude Code 或 Cline确认 Model ID 填对比如claude-sonnet-4-20250514不要填成gpt-4。Codex 的auth.json里如果 Base URL 和 Key 不匹配也会报类似错误三件套要一起检查。排查顺序建议先确认 MySQL 服务活着再确认账号密码对再确认字符集最后才怀疑代码。AI 通道的排查顺序先确认 Key 有效再确认 Base URL 正确再确认 Model ID 匹配。6. 语义一致 CTA把配置骨架用起来config.toml骨架和 pymysql 连接模板已经给全了接下来就是把它跑起来。如果你在排障过程中需要确认 Key 状态或重新生成去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的调用示例。如果你打算长期在项目里用 AI 辅助编码比如接 Claude Code 或 Cline MCPCoding Plan 页面有套餐说明https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Claude Code 的接入配置可以参考https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后提醒一个实用技巧config.toml不要提交到 Git在.gitignore里加上config.toml然后提供一个config.example.toml作为模板。这样 Key 不会泄露新环境部署时复制模板改值就行。pymysql 的连接用完记得conn.close()或者用with上下文管理避免连接泄漏。