MariaDB 3306 握手失败时，别急着重装数据库或把端口改来改去。先把完整报错原文贴给走 TaoToken 的 Codex，让它在本地 SQL 客户端返回的报错上对照 pymysql、asyncmy、SQLAlchemy 连接串和 3306 端口逐项排查。TaoToken 官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 用来创建 Key，API 通道是 https://taotoken.net/api。TaoToken 只供 Codex 的 Key 和通道，不替 pymysql 建立数据库会话。
这篇按排障视角写。你前面在 Vibe Coding 的安装环境里一路装 HBuilder X、微信开发者工具、trae、Python，再到 MariaDB，默认端口保持 3306，也按要求装了 asyncmy、pymysql 等 Python 驱动。结果 SQLAlchemy 一连接就握手失败。这个问题不一定在 MariaDB 本身，很多时候出在驱动和连接串不匹配、端口指向了另一个实例、用户授权 host 不对、认证插件不兼容，或者 utf8mb4 参数没有按连接层核对。本文不讨论复杂架构，只做一件事：借助走 TaoToken 的 Codex，把报错原文、驱动、端口、参数一条条对齐。
一、原问题与场景：MariaDB 3306 握手失败，SQLAlchemy 先别乱改
典型场景是这样的：Windows 本地已经安装 MariaDB，服务能启动，命令行也能用mysql -V看到版本。Python 环境里装了 SQLAlchemy、pymysql、asyncmy。你以为接下来create_engine就能连上，但运行时报错，例如连接握手阶段失败、连接丢失、SSL 握手异常、认证插件不匹配，或者干脆提示驱动加载不到。报错可能长这样：
sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError) (2013, 'Lost connection to MySQL server during query')也可能是：
(2003, "Can't connect to MySQL server on '127.0.0.1'")还可能是 asyncmy 或 SSL 相关错误。此时不要先改代码，也不要直接怀疑 MariaDB 安装失败。正确顺序是先把报错原文完整复制出来，包括 traceback、SQLAlchemy 版本、Python 版本、连接串中隐藏密码后的形式，然后贴给走 TaoToken 的 Codex。
为什么强调“走 TaoToken 的 Codex”？因为 Codex 在这里的角色是排障助手：它根据你给出的本地 SQL 客户端报错、驱动版本、连接串和端口信息，帮你列出下一步验证命令。它不是数据库驱动，不会替你创建 pymysql 会话，也不会绕过 MariaDB 的认证。TaoToken 提供的是 Codex 可用的 Key 和 API 通道。把它和 MariaDB 的账号密码区分开，后面排查才不会混。
你原文安装环境时保持默认 3306，并要求安装 asyncmy、pymysql。这个前提很重要：同步连接用 pymysql，异步连接通常用 asyncmy。SQLAlchemy 连接串前缀必须匹配，否则驱动层在握手前就可能报错。再加上 utf8mb4 参数，如果连接层没有写 charset，或者服务端字符集与客户端不一致，也可能出现看似“握手失败”的连锁问题。
所以第一段的目标不是立刻修好，而是把现场固定下来：MariaDB 服务状态、3306 监听情况、命令行能否登录、pymysql 能否单独连接、asyncmy 能否单独连接、SQLAlchemy 用哪个连接串。把这几项结果交给 Codex，比反复重装有效。
二、TaoToken 前置：创建 Key，把 https://taotoken.net/api 填进 Codex
先处理 Codex 的通道。打开 TaoToken 官网，进入控制台创建 API Key。链接是：
https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
创建后你会拿到类似YOUR_API_KEY的 Key。不要把它写进文章、截图或公开仓库。这个 Key 是给 Codex 请求模型用的，不是 MariaDB 的密码。MariaDB 仍然使用你自己的数据库用户名、密码、库名和 3306 端口。
Codex 自定义 Base URL 填：
https://taotoken.net/api
注意这个 API 地址不加 UTM 参数。官网入口可以带 UTM，但配置进 Codex 的 base_url 保持干净。也就是说，base_url 不要写成官网首页，不要带?utm_source=...，也不要自己拼成奇怪的路径。若你的 Codex 版本使用配置文件，就写进config.toml。若使用环境变量，就把 Key 放进环境变量，例如TAOTOKEN_API_KEY。
这一步的核心是让 Codex 能正常对话。验证方式很简单：配置完成后启动 Codex，问一个和数据库排障无关的普通问题，看是否能返回内容。如果 Codex 报 401、403、404、model not found，那属于 TaoToken 接入问题，不要和 MariaDB 握手失败混在一起查。如果 Codex 能正常对话，再让它分析 pymysql 和 asyncmy 的报错。
还要提醒一次：TaoToken 只供 Codex 的 Key 和通道。它能帮你分析“为什么 pymysql 握手失败”，但不能替你执行pymysql.connect()，也不能替你修改 MariaDB 用户权限。数据库会话仍然由你本地的驱动建立。
三、可复制配置：Codex config.toml、环境变量与排障提示词
下面按 Codex 的config.toml来写。Windows 下常见路径是：
C:\Users\你的用户名\.codex\config.tomlLinux 或 macOS 常见路径是：
~/.codex/config.toml先设置环境变量。Windows PowerShell 临时生效：
$env:TAOTOKEN_API_KEY="YOUR_API_KEY"Windows 持久化可以用：
setx TAOTOKEN_API_KEY "YOUR_API_KEY"设置后需要新开终端。Linux 或 macOS：
export TAOTOKEN_API_KEY="YOUR_API_KEY"然后编辑config.toml：
model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat"其中model换成 TaoToken 控制台里可用的模型 ID，不要照抄一个不可用的名字。base_url保持https://taotoken.net/api。env_key对应你设置的环境变量。若你的 Codex 版本对wire_api有要求，按接入文档确认用chat还是responses；如果这里填错，常见表现是 404 或协议错误，不是 MariaDB 握手错误。
配置完成后，用 Codex 做数据库排障时，提示词不要只写“连不上”。建议这样贴：
你是 Python 数据库连接排障助手。我的环境是 Windows，MariaDB 默认端口 3306，Python 已装 SQLAlchemy、pymysql、asyncmy。现在用 SQLAlchemy 连接时报握手失败。完整 traceback 如下： <粘贴完整报错> 连接串隐藏密码后如下： mysql+pymysql://user:***@127.0.0.1:3306/db?charset=utf8mb4 mysql+asyncmy://user:***@127.0.0.1:3306/db?charset=utf8mb4 请按顺序让我验证： 1. 驱动是否安装、版本是否匹配； 2. 连接串前缀和驱动是否匹配； 3. 3306 是否被 MariaDB 监听，是否被其他 MySQL 实例占用； 4. 用户 host 授权和认证插件； 5. utf8mb4、SSL 参数； 6. 防火墙、多实例、IPv6 与 localhost 差异。 每一步给出 Windows 可执行命令和判断标准，先不要让我重装数据库。这个提示词的作用是把 Codex 的输出限制在排障路径上。否则它可能直接给你一大段新代码，反而掩盖真正问题。你要的是对照驱动和端口，而不是让模型替你猜 MariaDB 密码。
四、验证请求与成功结果：从 mysql 命令行到 SQLAlchemy 连通
先验 MariaDB 本身。命令行执行：
mysql -V确认你调用的是 MariaDB 客户端，而不是另一个 MySQL 实例的客户端。然后检查 3306 监听：
netstat -ano | findstr 3306Linux 可以用：
ss -lntp | grep 3306再尝试命令行登录：
mysql -h 127.0.0.1 -P 3306 -u 你的用户 -p如果这里都连不上，先不要碰 SQLAlchemy。如果这里能连上，再验驱动。同步 pymysql 单独测试：
import pymysql conn = pymysql.connect( host="127.0.0.1", port=3306, user="你的用户", password="你的密码", database="你的库", charset="utf8mb4", ) print(conn.ping()) conn.close()不抛异常就说明 pymysql 这一层和 MariaDB 的握手基本正常。异步 asyncmy 单独测试：
import asyncio import asyncmy async def main(): conn = await asyncmy.connect( host="127.0.0.1", port=3306, user="你的用户", password="你的密码", db="你的库", charset="utf8mb4", ) print(await conn.ping()) conn.close() asyncio.run(main())如果 asyncmy 失败而 pymysql 成功，重点查 async 驱动安装、Python 版本、连接串前缀和认证插件。然后测试 SQLAlchemy 同步连接：
from sqlalchemy import create_engine, text engine = create_engine( "mysql+pymysql://你的用户:你的密码@127.0.0.1:3306/你的库?charset=utf8mb4" ) with engine.connect() as conn: print(conn.execute(text("select version()")).scalar())异步 SQLAlchemy 则用：
from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine( "mysql+asyncmy://你的用户:你的密码@127.0.0.1:3306/你的库?charset=utf8mb4" )成功结果不是“Codex 说成功了”，而是本地命令真实返回 MariaDB 版本、ping()不抛异常、SQLAlchemy 不再出现握手失败。Codex 正常对话只是前提：它能根据你贴的 traceback 指出下一项检查，例如让你先看pip list、3306 监听、用户 host、认证插件。最终连库仍然由 pymysql 或 asyncmy 完成。
五、本篇常见错排查：pymysql、asyncmy、3306、utf8mb4 一项项对
第一，连接串前缀与驱动不匹配。mysql+pymysql对应 pymysql，mysql+asyncmy对应 asyncmy。同步引擎用异步驱动，或异步引擎用同步驱动，都会在握手阶段或驱动加载阶段报错。
第二，只装了 pymysql，却在 SQLAlchemy 里写mysql+asyncmy。表现可能是No module named asyncmy，也可能被外层包装成连接失败。用pip list看 sqlalchemy、pymysql、asyncmy 是否都在，版本是否正常。
第三，3306 被占用或多实例。你安装 MariaDB 时默认 3306，但机器上可能还有 MySQL、XAMPP、Docker 映射的 3306。命令行mysql -V显示 MariaDB，不代表你连到的就是 MariaDB。用netstat -ano | findstr 3306看 PID，再对应服务。
第四，localhost和127.0.0.1差异。有的环境里localhost可能走 IPv6 或命名管道，127.0.0.1走 IPv4。连接串里写一个，命令行里试另一个。MariaDB 的bind-address若只监听某地址，也会影响结果。
第五，用户 host 授权。user@localhost和user@127.0.0.1可能不是同一个授权项。查看mysql.user里的 user 和 host，确认当前连接来源有权限。
第六，认证插件。MariaDB 用户可能使用某种认证插件，而当前 pymysql 或 asyncmy 版本不支持。先看报错里有没有 authentication plugin、ed25519、caching_sha2_password 等关键词，再决定是否调整用户认证方式。
第七，utf8mb4 参数。安装时选了 utf8mb4，不代表连接层自动使用。连接串里应带charset=utf8mb4，并检查服务端character_set_server、collation_server。字符集问题通常表现为乱码，但在某些驱动组合下也可能让初始化阶段异常。
第八，SSL/TLS 握手。如果报错里有 SSL、certificate、TLS，先确认 MariaDB 是否配置了对应证书，再检查驱动是否默认要求 SSL。不要盲目关闭，但可以按文档在测试环境临时调整。
第九，密码特殊字符。密码里有@、#、/、:时，连接串需要 URL 编码。否则解析出的 host 或 port 可能完全错误，看起来像 3306 握手失败。
第十，Codex 配置错误。base_url如果填成官网首页，或者 Key 没放进环境变量，Codex 会报 401、404。这和 MariaDB 握手失败是两类问题。先让 Codex 能正常对话，再让它分析数据库报错。
第十一，防火墙或安全软件拦截 3306。命令行本机可连，Python 进程却被拦截，这种情况要看防火墙规则和监听地址。
第十二，安装环境里的多个工具互相干扰。HBuilder X、微信开发者工具、trae 本身不直接改 MariaDB，但如果你在 trae 或其他终端里使用了不同 Python 解释器，pip install装的 pymysql、asyncmy 可能不在当前解释器里。用python -m pip list确认当前解释器的包。
六、语义一致 CTA：排障接入先拿 Key，再按文档配置
这篇的核心是排障和接入：让 Codex 通过 TaoToken 拿到可用的 Key 与通道，再对照 pymysql、asyncmy、3306、utf8mb4 逐项排查 MariaDB 握手失败。建议先打开 API Keys 创建或管理 Key：
https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=maria3306_codex&utm_campaign=rewrite
然后对照接入文档，把 Codex 的config.toml、环境变量和base_url配置正确：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=maria3306_codex&utm_campaign=rewrite
如果你后续要长期用 Codex 做安装环境、数据库连接和工程排障，可以再看 Coding Plan：
https://taotoken.net/console/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=maria3306_codex&utm_campaign=rewrite
配置时记住两件事：Codex 的 Key 来自 TaoToken，MariaDB 的会话来自 pymysql 或 asyncmy。TaoToken 不替驱动连库，但可以让 Codex 在你贴出报错原文后，按驱动、端口、认证和 utf8mb4 参数给出更清晰的排查顺序。先把 Key 配好，再把报错贴全，MariaDB 3306 握手失败就不再是盲猜。
