Python连接MySQL入门：从环境配置到pymysql实战

自从开始写 Python 学习记录这个系列，我就一直在想第一篇应该从哪讲起。后来发现，很多人卡住的第一关根本不是语法，而是“工具没装好、数据库连不上”。搜了一圈 python 安装教程、mysql 安装配置教程、navicat for mysql，再对照自己的报错信息，很容易陷入装了删、删了装的死循环。所以这一篇我打算把开发工具选择和链接 mysql 这条线串起来，从“选什么工具”到“代码怎么连”，按我自己踩坑的顺序重新梳理一遍，给同样在入门阶段的朋友一个可以直接照做的路径。

1. 先想明白：为什么要学 python 和 mysql 这对组合

1.1 这个组合到底能解决什么问题

先说一个很现实的问题：作为初学者，你到处搜“python 量化交易策略代码”“python 爬虫”“javaweb 项目完整案例 mysql”，最后会发现所有稍微有点实际意义的例子，背后几乎都会出现数据库。

Python 负责逻辑处理，MySQL 负责把数据存下来。爬虫抓到的内容需要入库，网站后端的用户数据需要入库，量化策略算出来的结果也需要入库。所以学 Python 的过程中迟早要面对“怎么把自己的程序和一个数据库连起来”这个问题。早点把 MySQL 连接打通，后面做任何练习都会顺手很多。

另外，这两个东西在网络上积累的教程量非常庞大：

• 遇到报错，搜索引擎一查基本都有前人踩过坑
• 学习路径清晰，从安装到连接再到操作，每一步都能找到大量参考
• 生态成熟，Python 操作 MySQL 的库有好几个，社区讨论的热度高

对于新手来说，选技术栈最重要的还真不是“谁更强”，而是“谁有更多现成的坑可以查”。Python 和 MySQL 恰好是这一类。

1.2 版本选择上的一些建议

我见过不少人在下载的时候纠结到底装 MySQL 5.7 还是 8.0。如果你是一台全新机器，直接装 MySQL 8.0 就行，别再回头去找 5.7。原因很简单：

• MySQL 8.0 从 2018 年发布到现在已经非常稳定，网上大部分新教程都在用它
• 5.7 虽然在很多公司存量环境里还有，但对新手学习来说，默认密码规则、初始化方式反而让老版本显得更别扭
• 8.0 的默认认证插件是 caching_sha2_password，早期确实让很多 pymysql 用户踩过坑，但现在的 pymysql 版本已经能兼容

Python 这边也一样，不用追最新大版本，稳定版本就够用。我当时选的 3.10，后来换过 3.11、3.12，日常写脚本连数据库都没问题。

1.3 这一篇的学习目标

本篇自己能跑通以下事情就算合格：

• 装好 Python，并能在终端里运行脚本
• 装好 MySQL 8.0，并能启动服务
• 用 Python 的 pymysql 库成功连上 MySQL
• 完成一次查询和一次写入，并顺便理解游标、事务这些基础概念

后面不管是学框架、做爬虫还是搞量化，数据库连接这一步都能直接复用。

2. 折腾半天的开发工具：VSCode、PyCharm 和 Jupyter 怎么挑

2.1 三种工具的定位差异

“hermes 配合什么开发工具使用”“swf 和 exe 开发工具”“鸿蒙开发工具连鸿蒙手机”——这些关键词一看就知道大家是真的在工具选择上迷茫过。我自己的想法是：Python 开发里不存在“最好的工具”，只有“最适合当前阶段的工具”。

先给一张很朴素的对照表，后面再展开说：

如果你只是想知道“我该装哪个”，我直接给答案：入门阶段用 VSCode，装好 Python 插件和 MySQL 插件就足够了。

2.2 为什么我推荐 VSCode 给新人

PyCharm 确实很强大，但很多新人第一次打开会蒙：项目解释器怎么配？虚拟环境是什么？窗口太多看不明白。相比起来 VSCode 的启动成本低很多，打开一个文件夹就能写代码，右边点一下运行就能出结果。而且：

1. 内置终端：直接在编辑器里敲命令，不用来回切换到 cmd，也能在这里跑 python 脚本、敲 mysql 命令
2. 插件体系完整：装一个 Python 扩展就能获得语法高亮、代码补全、格式化这些基础体验；需要操作 MySQL 时还能装 Database Client 类的插件，直接在侧边栏看表数据
3. 跨平台且免费：Windows、macOS、Linux 表现一致，换电脑没有任何迁移成本

这里插一句热搜里“python 连接 cmd”的困惑。很多新手问这个，其实说的是“怎么在 cmd 里运行 python”。这是环境变量 PATH 的功劳，python 安装时勾选“Add Python to PATH”，之后打开 cmd 输入 python 就能进入交互模式。VSCode 的集成终端和 cmd 原理相同，所以不必刻意去记命令行窗口的打开方式，知道“在终端里能敲 python xxx.py 运行脚本”就够了。

2.3 VSCode 环境配置的操作细节

我当时的安装和配置步骤大致是这样的，你可以直接抄：

1. 到 VSCode 官网下载安装包，一路 Next 装完
2. 打开 VSCode，左侧扩展商店搜“Python”，安装微软官方出的那个 Python 扩展
3. 如果需要看数据库，再装一个 MySQL 相关的扩展（比如 Database Client），其实不装也不影响程序连接
4. 按Ctrl + ~打开集成终端，输入python --version，如果能看到版本号，说明 Python 解释器和 VSCode 已经对接上了
5. 新建一个test.py文件，写print("hello mysql")，右键选择“在终端中运行 Python 文件”

到这里环境算真正通了，接下来才进入重点——搭好 Python 本体和 MySQL 服务。

3. 从零安装 Python：版本、环境变量和验证细节

3.1 下载和安装的关键选项

Python 官网下载地址很直接，进去以后选 Windows installer (64-bit) 就好。版本上我不建议装 3.13 这种刚出没多久的版本，因为个别第三方库可能存在兼容问题；一般选 3.10 到 3.12 之间的某个稳定版本。我后来给朋友推荐，都会说装 3.11 或 3.12，配套资料最全。

安装时有两个勾选容易被忽略：

• Add Python to PATH：必须勾选，不然后面没法在 cmd、VSCode 终端里直接用 python 命令
• Install launcher for all users：建议勾上，省得权限问题

有个小细节，我记得安装界面有一个“Customize installation”的入口，如果电脑上已经装了旧版 Python，可以直接在原目录覆盖升级，也可以装成平行版本。作为新手不用搞那么复杂，直接装默认路径即可。

3.2 验证安装并处理 PATH 问题

安装完别急着写代码，先在终端确认两件事：

python --version pip --version

如果发现输入python提示“不是内部或外部命令”，多半是安装时没有勾选 Add Python to PATH。解决方法有两个：

1. 重装一遍 Python，确保勾选 Add Python to PATH
2. 不重装，手动把 Python 安装目录和 Scripts 子目录添加到系统环境变量 Path 里

这个坑特别常见，尤其是从“python 安装教程”视频里照着操作，视频里可能一掠而过，到自己电脑上就各种卡壳。我个人的建议是直接重装勾选，比手动改环境变量省事。

3.3 顺手把 pip 源换成国内镜像

Python 安装完，紧接着要做的一件事是把 pip 源切换到国内镜像。原因没啥好避讳的，直接从官方源下载包经常超时，换了镜像以后下载速度会快很多。以清华源为例：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

设置完之后再执行pip install pymysql，基本几秒钟就装完了。这一步虽然不是必须的，但对体验影响很大。我见过太多新手在pip install这一步卡到怀疑人生，后来发现仅仅是网络问题。

3.4 几个容易忽略的验证小技巧

终端里除了看版本，还可以快速验证模块安装是否成功：

python -c "import pymysql; print(pymysql.__version__)"

这条命令会直接输出 pymysql 版本号，如果没有报错，说明模块已经正确安装到了当前解释器环境里。这里之所以强调“当前解释器环境”，是因为很多人电脑上同时装了多个 Python 版本，pip 安装的包可能装在另一个解释器里，导致 VSCode 里运行代码时找不到模块。遇到这种情况，直接在 VSCode 的终端里执行pip install xxx，因为终端默认使用的是同一个 Python，就不会有这种错位问题。

4. MySQL 的安装和初始化：8.0 版本最容易踩的几个点

4.1 下载、安装与服务启动

MySQL 官方下载地址是 MySQL Community Server，Windows 下有两种选择：ZIP 包手动配置，或者 MSI 安装包。新手走 MSI 最省心。

安装过程中有几个点以前让我很头疼，这里单独列一下：

• 选择安装类型：可以选择 Developer Default，也可以自定义选 MySQL Server。如果你不想装一堆用不上的组件，选 Server only 就行
• 设置 root 密码：安装向导会让你给 root 用户设置密码，这一步之后用 Navicat、用 Python 连接时都要用这个密码，建议记在一个文本文件里
• 认证插件：8.0 默认是 caching_sha2_password，强烈建议保持默认。曾经确实有版本兼容问题，但现在 pymysql 新版已经没问题了，不要为了“兼容”去改成 mysql_native_password
• 服务名称：默认是 MySQL80，后面在 cmd 里启动服务时会用到

装完以后打开 Windows 服务管理器，找到 MySQL80 服务和状态。如果没启动，可以手动启动，也可以在终端里执行：

net start mysql80

很多新手连不上数据库，最后发现根本不是代码问题，而是 MySQL 服务压根没跑起来。

4.2 root 密码和可视化工具的取舍

安装过程中设置的 root 密码就是你用管理员账号连接数据库时的凭证。我建议：

1. 安装完立刻试一次连接，确认密码没记错
2. 本地学习期间不必单独建新用户，直接用 root 即可；但生产环境千万别这样做
3. 可视化客户端方面，搜“navicat for mysql”的人很多，但如果你只想看数据，MySQL 官方自带的 MySQL Workbench 完全够用

有一点要提醒：现在很多人下载 Navicat 的时候容易搜错，下到各种推广的“破解版”或者“全家桶”。我的建议是新手阶段暂缓安装 Navicat，先用命令行或者 Workbench 熟悉概念。等建表、查询都熟练了，再决定是否需要更顺手的客户端。

4.3 建一个测试库，为 Python 连接做准备

既然目标是用 Python 连接 MySQL，那么得先有一个库一张表可以连。打开 MySQL 命令行，输入 root 密码进入后，执行下面这段 SQL：

CREATE DATABASE IF NOT EXISTS test_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE test_db; CREATE TABLE IF NOT EXISTS user_info ( id INT AUTO_INCREMENT PRIMARY KEY, username VARCHAR(50) NOT NULL, age INT DEFAULT 0, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; INSERT INTO user_info (username, age) VALUES ('san', 25), ('zhang', 30);

这段 SQL 做了三件事：建库、建表、插入两行测试数据。编码选 utf8mb4 是为了避免中文显示成问号，这个后面写 Python 代码时也要保持对应。

执行完以后用SELECT * FROM user_info;看一眼，能返回两行数据，说明 MySQL 这边准备工作已经全部完成。

4.4 端口占用这个老问题

MySQL 默认监听 3306 端口。有一类报错是提示端口被占，多半是机器上装了多个数据库，或者某次安装卸载没干净导致了残留服务。排查方法是在 cmd 里执行：

netstat -ano | findstr 3306

看输出的 PID，再去任务管理器确认是什么程序占用。如果确定是残留的 MySQL，停掉服务再清理干净即可。这个坑在“rpm 安装 mysql”“windows 安装 mysql 8”的场景里很常见，Windows 上尤其要养成“先看端口再看报错”的习惯。

5. 用 pymysql 打通 Python 和 MySQL：连接代码的完整写法

5.1 为什么选 pymysql

Python 连 MySQL 的库有好几个：PyMySQL、mysqlclient、MySQL Connector/Python。我之所以推荐 pymysql，主要是它对新手友好：

• 纯 Python 实现，安装即用，不需要额外的 C 编译器
• 在 Windows 上安装不会有编译链问题
• 支持 MySQL 8.0 的 caching_sha2_password，新版兼容性已经很成熟
• 语法简洁，接口清晰

mysqlclient 性能更好，但 Windows 上安装经常要处理 VC 编译环境，对新人来说纯属额外负担。前期练习没必要纠结性能差异。

5.2 一个最小的连接示例

假设前面已经执行了pip install pymysql，先写一个最简单的查询脚本：

import pymysql conn = pymysql.connect( host="127.0.0.1", port=3306, user="root", password="你的root密码", database="test_db", charset="utf8mb4", ) try: with conn.cursor() as cursor: cursor.execute("SELECT id, username, age FROM user_info") result = cursor.fetchall() for each in result: print(each) finally: conn.close()

运行后如果看到两行元组，说明连接已经成功。这里有几个细节值得展开：

• host 写 127.0.0.1：回环地址，表示连接本机，和 localhost 类似，但程序里更推荐写 127.0.0.1，可以避免一些奇怪的解析问题
• charset 必须和库表编码一致：库是 utf8mb4，Python 这边也写 utf8mb4，中文才不乱码
• conn.close() 放在 finally 里：确保连接一定被关闭。虽然脚本跑完进程回收也会释放，但从一开始就养成好习惯

5.3 执行插入操作：游标和事务

查询读数据只需要 execute 和 fetch 两个动作，但写入数据还涉及事务提交。这是初学者特别容易漏的一个环节。

import pymysql conn = pymysql.connect( host="127.0.0.1", port=3306, user="root", password="你的root密码", database="test_db", charset="utf8mb4", ) try: with conn.cursor() as cursor: sql = "INSERT INTO user_info (username, age) VALUES (%s, %s)" cursor.execute(sql, ("li", 28)) conn.commit() print("插入成功，受影响行数:", cursor.rowcount) except Exception as err: print("发生错误，回滚:", err) conn.rollback() finally: conn.close()

注意几个关键点：

• %s是占位符：不要自己用字符串拼接 SQL，那样容易出语法错误，更危险的是 SQL 注入。pymysql 的 execute 会自动处理参数转义
• 必须调用 commit()：MySQL 默认开启了事务，execute 只是把变更发送到数据库会话里，没有 commit 不会真正落地
• 异常时 rollback()：如果插入过程发生错误，回滚可以让数据保持一致，避免半截写入的脏数据

我见过很多人第一次写插入代码时，跑完没有报错，但SELECT一看数据没变，就是因为忘了commit()。

5.4 封装一个可复用的连接函数

写多了之后你会发现，每次连接都要重复写那一堆参数。一个很实用的做法是封装一个 get_conn 函数：

import pymysql def get_conn(): return pymysql.connect( host="127.0.0.1", port=3306, user="root", password="你的root密码", database="test_db", charset="utf8mb4", )

后续每个脚本都from db_utils import get_conn，然后拿到连接开始操作。这一步属于代码组织层面的常见实践，虽然不是这篇的重点，但建议从最开始就有这个意识，后面写爬虫存数据、写量化回测存指标时能省下大量重复劳动。

5.5 把配置单独拎出来的一个习惯

连接参数如果直接写在代码里，换台电脑、换个密码就要全局搜索修改，非常不方便。我会建议这么干：

# config.py DB_CONFIG = { "host": "127.0.0.1", "port": 3306, "user": "root", "password": "你的root密码", "database": "test_db", "charset": "utf8mb4", }

# db_utils.py import pymysql from config import DB_CONFIG def get_conn(): return pymysql.connect(**DB_CONFIG)

这样做的直接好处是：不同环境（本地、服务器）只需要改一个配置文件，代码主体不用动。这也是后面做真实项目时非常标准的组织方式。

6. 新人链接 MySQL 时的高频报错：错误码、原因和逐个排查

6.1 先从报错本身说起

我发现新手排查问题的最大障碍不是报错多，而是看到一长串英文就慌。其实 python 报错信息里最关键的部分往往在最后几行，前面一大段是调用栈，不用细看。链接 MySQL 的报错，核心就那么几类。

6.2 逐个排查的思路

Access denied是最常见的，一般就是密码问题。检查一下 MySQL 命令行能不能用你填的密码登录。如果命令行都进不去，那别提 Python 了。另外还有一种情况是用户填了 'root'@'localhost'，但连接时 host 填的是某个机器名，导致匹配不上的情况，本地连接统一回环地址即可。

Can't connect首先确认服务是否在运行。Windows 服务管理器里看到 MySQL80 状态是停止，就启动它。如果服务已经在跑但还是连不上，用netstat -ano | findstr 3306确认端口监听是不是在 127.0.0.1，有时候安装配置里绑定了特定 IP，也会导致连接失败。

caching_sha2_password cannot be loaded这类报错在 MySQL 8.0 刚出来那几年确实劝退了一大批人，本质是 pymysql 旧版本不支持新版默认认证协议。解决办法很简单：升级 pymysql 到最新版本。

pip install --upgrade pymysql

如果升级后还报这个错，再检查安装的 MySQL 服务端变量，确认默认认证插件是不是被手动改过。

SSL 连接错误这个我要多说几句。一些 MySQL 新版本默认开启 SSL，客户端却因为各种原因没有正确握手就会出现 SSL 错。pymysql 里可以通过如下参数显式处理：

conn = pymysql.connect( host="127.0.0.1", port=3306, user="root", password="你的root密码", database="test_db", charset="utf8mb4", ssl={"check_hostname": False, "verify_mode": 0}, )

注意：本地学习场景里关闭 SSL 验证不会带来多少安全风险，但如果是在公司生产环境，请务必遵循团队规范，不要随意关掉校验。

6.3 一个实战排查流程示例

假设运行下面这段代码时发现报错：

import pymysql conn = pymysql.connect( host="127.0.0.1", port=3306, user="root", password="123456", database="test_db", charset="utf8mb4", )

报错信息显示Can't connect to MySQL server on 127.0.0.1 (10061)，我的排查顺序是：

1. 先确认服务：按 Win+R 输入 services.msc，找到 MySQL80，看状态。发现是停止的
2. 启动服务：net start mysql80
3. 运行代码，此时又能报 Access denied——说明 10061 问题解决，现在到了密码环节
4. 用 MySQL 命令行直接验一遍，密码确实不对，换成安装时设置的密码
5. 连接成功

这个流程的核心逻辑是：每个报错只解决一个具体问题，从外到内一层层逼近真正的原因，而不是堆叠一顿乱查。

6.4 乱码问题的处理方式

查询结果里的中文显示成???，或者 Python 端输出乱码，绝大多数是编码不一致导致。记住一个组合：

• 建库建表时，库表字符集设置 utf8mb4
• pymysql 连接参数里 import 字段 charset="utf8mb4"
• 终端如果还是乱码，Windows 控制台可以在 Python 里强制指定输出编码

一个完整可用的连接参数写法：

conn = pymysql.connect( host="127.0.0.1", port=3306, user="root", password="你的root密码", database="test_db", charset="utf8mb4", cursorclass=pymysql.cursors.DictCursor, )

这里加了一个DictCursor，查询结果会变成字典而不是元组，字段名和值对应起来，对新手来说输出更直观。像这样的小改动，使用起来体验差异很大。

把 MySQL 连接这块跑通之后，你会发现后面学什么都顺了很多。比如写爬虫时把抓到的数据 insert 进表，逻辑就是这篇的插入代码加一个循环；做 Flask Web 项目时，用户登录校验就是查询代码加一个条件判断。我自己最开始最大的体会是，很多东西不是不会，而是被环境污染和工具选择耗掉了太多精力。所以这一篇记录里特意把开发工具、安装验证、连接报错这些杂事梳理成了固定流程，下一次你换电脑重装环境，照着走一遍就行，不用再从头搜一遍“mysql 安装教程 8.0”和“vscode python 环境配置”。