1. Linux 下 Python 连 MySQL 的真实痛点
在 Linux 上写 Python 操作 MySQL，本身并不复杂：装个pymysql，connect()一下，cursor()一开，SQL 一执行，数据就回来了。真正让人头疼的是工程化落地这一步。你本地可能同时跑着好几个 AI 工具：一个用来补全代码，一个用来做代码审查，还有一个 Agent 在后台跑任务。每个工具都要配 Key、配 Base URL、配模型名，散落在.bashrc、.env、IDE 插件设置、项目config.toml里，改一次要翻五个地方。
更麻烦的是，数据库连接信息也在到处复制。host、port、user、password写死在脚本里，换台机器就得重新改一遍，密码还容易跟着代码提交到仓库。这篇就聚焦 Linux 环境下 Python 连接 MySQL 的工程化落地：用一份可复制的config.toml配置骨架，把数据库连接参数和 AI 工具的 Key 统一收口，再通过 TaoToken 的统一 Key 接入，让多工具共用一套凭证。适合需要统一管理多 AI 工具 Key、又想让 Python 脚本干净可维护的开发者。下面从配置骨架开始，一步步跑通最小验证脚本，最后给一份报错排查清单。
2. TaoToken 前置：统一 Key 与配置骨架设计
TaoToken 在这里扮演的角色是统一凭证入口。你不需要给每个 AI 工具单独申请一套 Key，而是用同一个 Key 去访问不同的模型能力。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api （这个不加 UTM）。注意，TaoToken 是正规的 API 聚合服务，不是所谓的中转，所有请求都走标准 HTTP 接口。
配置骨架的核心思路是：把「连接什么」和「用什么凭证」分开。数据库连接参数放[mysql]段，AI 工具凭证放[taotoken]段，Python 脚本只读配置，不硬编码任何敏感信息。这样你在 Linux 上换环境、换机器，只需要替换config.toml一个文件。
先看目录结构，建议这样组织：
project/ ├── config.toml ├── db.py ├── verify.py └── requirements.txtconfig.toml的骨架如下，可以直接复制：
# config.toml —— 统一配置骨架 [mysql] host = "127.0.0.1" port = 3306 database = "jing_dong" user = "root" password = "your_mysql_password" charset = "utf8mb4" [taotoken] api_key = "sk-你的TaoTokenKey" base_url = "https://taotoken.net/api" model = "claude-3-5-sonnet" [app] debug = true timeout = 10这里有几个设计点值得说明。charset用utf8mb4而不是utf8，因为 MySQL 的utf8实际只支持三字节，存 emoji 或部分生僻字会报错，utf8mb4才是真正的四字节 UTF-8。base_url指向 TaoToken 的 API 入口，后面 Python 侧调用模型时直接读这个值。api_key单独放一段，方便你后续换成环境变量注入。
注意：
config.toml不要提交到 Git。在.gitignore里加上config.toml，或者用config.example.toml做模板，真实文件本地保留。
如果你还没有 Key，可以去 API Keys 页面创建：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。创建后把 Key 填进config.toml的api_key字段。想先确认模型通道是否正常，可以用模型对话页面发一条测试消息：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。
3. 可复制配置：Python 读取 config.toml 并连接 MySQL
Python 3.11 之后标准库自带tomllib，可以直接解析 TOML，不需要额外装toml包。先确认你的 Python 版本：
python3 --version如果低于 3.11，用pip install tomli并import tomli as tomllib。下面写一个db.py，负责读配置和建立连接：
# db.py import tomllib from pathlib import Path import pymysql CONFIG_PATH = Path(__file__).parent / "config.toml" def load_config(): with open(CONFIG_PATH, "rb") as f: return tomllib.load(f) def get_connection(): cfg = load_config()["mysql"] return pymysql.connect( host=cfg["host"], port=cfg["port"], database=cfg["database"], user=cfg["user"], password=cfg["password"], charset=cfg["charset"], cursorclass=pymysql.cursors.DictCursor, )注意tomllib.load需要二进制模式打开文件，所以是"rb"而不是"r"，这是新手最容易踩的坑之一。cursorclass设成DictCursor后，查询结果返回字典而不是元组，字段名直接可读，调试时省事很多。
安装依赖：
pip install pymysql如果你在 Linux 上遇到pymysql装不上，通常是 pip 版本太旧，先python3 -m pip install --upgrade pip。MySQL 服务端本身不需要额外 Python 驱动，pymysql是纯 Python 实现，不依赖 C 库，这也是它在 Linux 上比mysqlclient更好装的原因。
接下来写最小验证脚本verify.py，把「连数据库」和「读 TaoToken 配置」两件事都验证一遍：
# verify.py from db import get_connection, load_config def main(): # 1. 验证 MySQL 连接 conn = get_connection() try: with conn.cursor() as cur: cur.execute("SELECT VERSION() AS v") row = cur.fetchone() print("MySQL 版本:", row["v"]) cur.execute("SHOW DATABASES") dbs = [list(r.values())[0] for r in cur.fetchall()] print("数据库列表:", dbs) finally: conn.close() # 2. 验证 TaoToken 配置读取 cfg = load_config()["taotoken"] print("TaoToken base_url:", cfg["base_url"]) print("TaoToken model:", cfg["model"]) print("Key 前缀:", cfg["api_key"][:6] + "****") if __name__ == "__main__": main()运行：
python3 verify.py预期输出类似：
MySQL 版本: 8.0.36 数据库列表: ['information_schema', 'jing_dong', 'mysql', 'performance_schema', 'sys'] TaoToken base_url: https://taotoken.net/api TaoToken model: claude-3-5-sonnet Key 前缀: sk-abc****看到 MySQL 版本号和数据库列表，说明数据库通道通了；看到 TaoToken 的base_url和 Key 前缀，说明配置读取正常。这两步都过，配置骨架就算跑通了。
4. 验证请求：参数化查询与事务提交
配置通了之后，重点看 Python 操作 MySQL 的几个关键动作。先建一张测试表：
# create_table.py from db import get_connection conn = get_connection() try: with conn.cursor() as cur: cur.execute(""" CREATE TABLE IF NOT EXISTS goods_cates ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(64) NOT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 """) conn.commit() print("建表完成") finally: conn.close()插入数据时，一定要用参数化，不要用字符串拼接。下面是对比：
# 错误示范：字符串拼接，有 SQL 注入风险 name = '硬盘' sql = f'INSERT INTO goods_cates(name) VALUES("{name}")' # 正确示范：参数化，%s 占位 sql = 'INSERT INTO goods_cates(name) VALUES(%s)' cur.execute(sql, [name])参数化查询的%s是pymysql的占位符，不是 Python 的字符串格式化。多个参数就传列表：cur.execute(sql, [v1, v2])。这样 MySQL 驱动会把参数和 SQL 分开传输，从根本上杜绝注入。
插入、更新、删除之后必须commit()，否则数据不会真正落库。Python 的数据库操作默认开启事务，pymysql也一样。查询则不需要 commit，直接fetchone()或fetchall()：
# query_demo.py from db import get_connection conn = get_connection() try: with conn.cursor() as cur: cur.execute("INSERT INTO goods_cates(name) VALUES(%s)", ["机械硬盘"]) cur.execute("INSERT INTO goods_cates(name) VALUES(%s)", ["固态硬盘"]) conn.commit() print("受影响行数:", cur.rowcount) cur.execute("SELECT id, name FROM goods_cates WHERE id >= %s", [1]) rows = cur.fetchall() for r in rows: print(r["id"], r["name"]) finally: conn.close()rowcount是只读属性，表示最近一次execute()影响的行数，做批量操作时很有用。fetchone()取一行返回字典，fetchall()取全部返回字典列表。数据量大时不要一次fetchall()，用游标迭代或分页查询，避免内存爆掉。
如果你想把 TaoToken 的模型能力也接进来，比如让脚本自动生成 SQL 注释，可以读[taotoken]段的配置去调 API。长期做编码和 Agent 任务的话，Coding Plan 页面有更完整的接入说明：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言的调用示例。
5. 本篇常见错排查清单
跑不通的时候，按下面顺序排查，基本能覆盖九成问题。
报错ModuleNotFoundError: No module named 'pymysql'说明依赖没装到当前 Python 环境。Linux 上常有系统 Python 和虚拟环境两套，确认你pip install和python3用的是同一个。用python3 -m pip install pymysql更稳。
报错Access denied for user 'root'@'localhost'密码错了，或者用户没有从localhost连接的权限。检查config.toml里的user和password。MySQL 8 默认认证插件是caching_sha2_password，老版本pymysql可能不兼容，升级pip install --upgrade pymysql即可。
报错Can't connect to MySQL server on '127.0.0.1'MySQL 服务没启动，或者端口不对。Linux 上用systemctl status mysql看服务状态，ss -tlnp | grep 3306看端口监听。如果 MySQL 装在容器里，host要改成容器映射的地址。
报错Unknown database 'jing_dong'数据库不存在。先CREATE DATABASE jing_dong DEFAULT CHARSET utf8mb4;，或者把config.toml里的database改成已存在的库。
中文乱码或 emoji 报错Incorrect string valuecharset没设成utf8mb4，或者建表时没指定字符集。连接参数和建表语句都要用utf8mb4，两处缺一不可。
tomllib.load报TypeError文件没用二进制模式打开。确认是open(path, "rb")，不是"r"。
数据插入后查不到忘了commit()。查询前先确认上一次写操作有没有提交，或者把连接设成autocommit=True（不推荐，事务控制会变粗）。
TaoToken 请求返回 401Key 填错或过期。去 API Keys 页面重新生成：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。确认base_url是https://taotoken.net/api，不要多加斜杠或路径。
配置读取到旧值config.toml改了但脚本没重启，或者读的是缓存。Python 每次load_config()都重新读文件，如果还不对，检查是不是有多个config.toml，Path(__file__).parent定位的是脚本所在目录。
6. 把配置收口，让脚本可迁移
这套骨架跑通后，你在 Linux 上换机器只需要带走config.toml一个文件，代码原样复制就能跑。数据库参数和 AI 工具 Key 都收口在配置里，脚本本身不碰敏感信息，提交到仓库也放心。我试过把这套结构用在几个小工具上，从本地开发机迁到测试服务器，改一下host和password就完事，不用翻代码找硬编码。
后续要扩展的话，[taotoken]段可以加temperature、max_tokens这些参数，Python 侧读出来直接传给 API。数据库侧可以加连接池配置，比如pymysql配合DBUtils做PooledDB，高并发场景下比每次新建连接省资源。控制台入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，可以看调用量和 Key 状态。Claude Code 相关的接入说明在 https://taotoken.net/claude-code?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite ，如果你用 Anthropic 系模型做编码，那边有更细的配置示例。
最后留一个实用习惯：在verify.py里加一行print(load_config()["mysql"]["host"])，每次改完配置先跑验证脚本，确认读到的是新值再跑业务逻辑。这个动作花三秒，能省掉大量「改了没生效」的排查时间。
