Python通过MySQL-connector-Python连接MySQL的配置方法

Jasper

发布时间：2026-10-24 | 3人浏览过

原创

在 Python 应用程序与 MySQL 数据库进行数据交互时，官方维护的 mysql-connector-python 驱动是一个兼容性高且不依赖本地 C 编译链的理想选择。本文将详细介绍如何通过该驱动完成从基础安装、连接参数组织、安全连接验证到异常处理与连接池的最佳配置路径，帮助开发者建立稳定、可维护的数据库通信通道。

一、驱动环境准备与依赖辨析

在使用 Python 连接 MySQL 之前，首要任务是在当前运行环境中正确安装官方驱动。Python 生态中存在若干名称相近的库，明确驱动的准确名称与定位有助于规避版本冲突与安全风险。

1. 依赖安装指令

通过 Python 官方包管理器 pip 即可快速安装驱动。建议在专用的虚拟环境（如 venv 或 conda）中执行：

# 标准纯 Python 驱动安装
pip install mysql-connector-python

# 验证安装是否成功
python -c "import mysql.connector; print(mysql.connector.__version__)"

依赖名称辨析：请务必安装 mysql-connector-python 而非已被废弃的 mysql-connector。官方驱动完全由 Oracle 官方团队维护，支持完整的 MySQL 8.0+ 新特性（包括默认的 caching_sha2_password 认证插件及原生 JSON 数据类型）。

Python通过MySQL-connector-Python连接MySQL的配置方法

图 1：Python 连接 MySQL 的核心执行阶段全景流程

二、核心连接参数配置规范

连接 MySQL 本质上是通过 TCP/IP 协议与远端服务器端口建立长连接会话。规范的配置应当集中化组织为字典结构，便于统一管理与解耦。

配置键名	类型	默认值	说明与最佳实践建议
`host`	str	`localhost`	MySQL 服务的 IP 地址或域名。本地推荐使用 `127.0.0.1` 避免解析延迟。
`port`	int	`3306`	MySQL 监听端口。注意在配置中必须为整型（int），而非字符串。
`user`	str	无	连接数据库所使用的账户名。生产环境严禁直接使用 root 超级管理员账号。
`password`	str	空	数据库用户密码。强烈建议通过系统环境变量读取，禁止明文硬编码在源码中。
`database`	str	无	连接建立后默认激活的数据库名称。若不指定，可在连接后通过游标切换。
`charset`	str	`utf8mb4`	通信字符集编码。必须配置为 `utf8mb4` 以完整支持 Emoji 及复杂多字节字符。
`connect_timeout`	int	`None`	建立 TCP 连接的超时阈值（单位：秒）。建议设置为 5 至 10 秒，防止网络阻塞卡死进程。
`auth_plugin`	str	自动协商	指定认证协议，如 `caching_sha2_password` 或 `mysql_native_password`。

图 2：Python 客户端与 MySQL 服务端通信层次及配置映射

三、标准连接代码实现与结果验证

编写高质量的数据库连接逻辑时，必须贯彻以下三项原则：配置与代码分离、完备的错误捕获（try-except）、确定的连接与游标回收（finally 或上下文管理器）。

1. 完整连接与查询示例代码

import mysql.connector
from mysql.connector import Error

# 1. 规范组织连接配置参数
DB_CONFIG = {
    'host': '127.0.0.1',       # 数据库服务器地址
    'port': 3306,              # 端口号（整型）
    'user': 'app_user',        # 业务专属账户
    'password': 'StrongPassword123!', # 账户密码
    'database': 'project_db',  # 目标数据库
    'charset': 'utf8mb4',      # 字符集
    'connect_timeout': 5,      # 超时限制（秒）
    'raise_on_warnings': True  # 将警告升级为异常便于排查
}

def test_mysql_connection():
    connection = None
    cursor = None
    try:
        print("正在尝试建立与 MySQL 数据库的连接...")
        # 2. 建立网络连接
        connection = mysql.connector.connect(**DB_CONFIG)
        
        if connection.is_connected():
            db_info = connection.get_server_info()
            print(f"成功连接至 MySQL 服务器！版本号: {db_info}")
            
            # 3. 创建游标并执行基准测试查询
            cursor = connection.cursor(dictionary=True)
            cursor.execute("SELECT DATABASE() AS current_db, CURRENT_USER() AS auth_user, NOW() AS sys_time;")
            record = cursor.fetchone()
            
            print("连接环境验证结果:")
            print(f" - 当前数据库: {record['current_db']}")
            print(f" - 认证用户:   {record['auth_user']}")
            print(f" - 服务器时间: {record['sys_time']}")

    except Error as e:
        # 4. 捕获专用异常并输出错误码与错误信息
        print(f"数据库连接失败！错误码: {e.errno}")
        print(f"详细错误详情: {e.msg}")
        
    finally:
        # 5. 确保资源被严谨释放
        if cursor is not None:
            cursor.close()
            print("游标对象已安全关闭。")
        if connection is not None and connection.is_connected():
            connection.close()
            print("MySQL 数据库网络连接已安全释放。")

if __name__ == '__main__':
    test_mysql_connection()

图 3：连接参数字典的结构分类与驱动实例化效应

四、进阶配置：高并发场景下的连接池（Connection Pool）

在 Web 服务（如 FastAPI、Flask、Django）或高频定时任务中，频繁地执行 TCP 三次握手与断开会消耗大量网络资源与系统 CPU。mysql-connector-python 原生提供了连接池支持，使得连接在关闭时不是断开网络，而是归还池中供下一个请求复用。

1. 连接池核心配置参数

pool_name: 连接池唯一命名标识，支持多库分池管理。
pool_size: 连接池维持的连接实例数量，默认值为 5，上限为 32。
pool_reset_session: 当连接归还回连接池时，是否重置用户变量与事务状态，默认为 True（推荐保持默认以防状态泄露）。

2. 连接池代码构建范例

from mysql.connector import pooling, Error

# 1. 建立全局共享的数据库连接池
try:
    connection_pool = pooling.MySQLConnectionPool(
        pool_name="web_app_pool",
        pool_size=10,                 # 维持 10 个预热连接
        pool_reset_session=True,       # 归还时清理会话状态
        host='127.0.0.1',
        port=3306,
        user='app_user',
        password='StrongPassword123!',
        database='project_db',
        charset='utf8mb4'
    )
    print("数据库连接池初始化成功，初始容量: 10")
except Error as e:
    print(f"连接池构建失败: {e}")

# 2. 从池中获取连接并执行查询
def query_with_pool(user_id: int):
    cnx = None
    cursor = None
    try:
        # 从池中借用活跃连接（非阻塞或复用已有 TCP 链路）
        cnx = connection_pool.get_connection()
        cursor = cnx.cursor(dictionary=True)
        
        # 参数化查询，防御 SQL 注入
        sql = "SELECT id, username, email FROM users WHERE id = %s"
        cursor.execute(sql, (user_id,))
        return cursor.fetchone()
    except Error as e:
        print(f"业务查询发生异常: {e}")
        return None
    finally:
        if cursor is not None:
            cursor.close()
        if cnx is not None:
            # 此处的 close() 会将连接放回 pool，而非销毁 TCP 链路
            cnx.close()

五、常见连接故障排查与诊断路径

在实际部署与连接测试时，开发者常遇到网络无法通达、密码鉴权不匹配或认证加密协议不兼容等情况。掌握错误码与对应的排查逻辑是快速恢复生产的关键能力。

图 4：MySQL 连接阶段典型异常分类与排障决策路径

六、工程实践总结

通过 mysql-connector-python 连接与配置 MySQL 是一项基础而关键的技术动作。在实际工程落地时，推荐遵循以下准则：

使用字典进行参数集中化管理：将数据库配置集中在 config.py 或通过 os.getenv() 从系统环境变量读取，实现多环境（本地开发、测试、生产）的平滑切换。
统一采用 utf8mb4 字符集：在配置参数中显式指定 charset='utf8mb4'，避免在写入 Emoji、生僻汉字时出现乱码或 Incorrect string value 错误。
常态化使用连接池：除简易一次性排错脚本外，服务端应用与异步任务一律采用 pooling.MySQLConnectionPool，极大提升吞吐能力并规避连接耗尽风险。
始终执行参数化查询：通过 cursor.execute(sql, params) 传递参数，严禁使用 Python 的 % 或 f-string 拼接 SQL 语句，彻底杜绝 SQL 注入隐患。