Django 连 MySQL 通常不是只改一处 DATABASES 就完事,实际卡住的点大多集中在三处:Python 驱动装不上或装错、MySQL 侧的库和账号权限没给对、连接参数与字符集没对齐。因此建议按“先确认环境 → 再改配置 → 跑一次迁移验证 → 回头检查边界”的顺序做,而不是照抄一段 settings 就结束。
Django 配置 MySQL 的可行路径是:先确认 Django 版本、MySQL 或 MariaDB 版本、部署形态和字符集需求,再安装驱动(mysqlclient 或 PyMySQL)、用 utf8mb4 建库建账号、在 settings 中写 engine/name/user/host/port 与 charset,最后用 migrate、dbshell 和一次中文写入确认连通与字符集是否正确。若驱动编译失败、账号只允许本地登录或库排序规则与已有表不一致,配置看起来对也连不上;此时可先保留原 sqlite 配置作为回退,不要直接删掉。
先确认当前场景和目标
这套配置成立的前提是:你要把某个 Django 项目的默认数据库从 sqlite 换成 MySQL,或者给已有项目新增一个 MySQL 连接。动手前先确认下面几项,任何一项不清楚都可能导致后面反复试错。
- Django 版本与 MySQL 版本:较新的 Django 对 MySQL 最低版本有要求,老版本 Django 与 MySQL 8 的认证插件也可能不兼容。具体支持范围要对照你所装 Django 版本的发布说明确认,不要凭印象。
- 是 MySQL 还是 MariaDB:两者驱动相同但行为有差异,尤其是默认排序规则和部分 SQL 语法,MariaDB 需要单独确认兼容性。
- 部署形态:本机、容器、还是云托管数据库。云数据库通常要求先加白名单或安全组,并且账号带主机后缀(如
'appuser'@'10.%'),只建'appuser'@'localhost'在容器里一定连不通。 - 字符集需求:只要涉及中文、emoji 或用户昵称,库和表都建议用
utf8mb4,不要在 utf8 与 utf8mb4 之间混用。 - 是否已有数据:已有 sqlite 数据要迁移,属于另一个任务,先保证空库能连上再谈导数据。
按这个顺序处理
第一步装驱动。常规选择是 mysqlclient,它需要本机有 MySQL 客户端开发库;Debian/Ubuntu 上通常要先装 default-libmysqlclient-dev 和 pkg-config,macOS 上一般依赖 mysql-client。如果编译条件不具备,可以退到纯 Python 的 PyMySQL,但要在项目入口(如 __init__.py 或 settings.py 顶部)声明替身:
pip install mysqlclient
# 备选方案
pip install PyMySQL
# 在 settings.py 顶部或包的 __init__.py 中
import pymysql
pymysql.install_as_MySQLdb()第二步在 MySQL 侧建库和账号。下面的语句可以直接改库名、账号和网段后执行,字符集统一用 utf8mb4:

CREATE DATABASE appdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'appuser'@'10.%' IDENTIFIED BY '替换成强密码';
GRANT ALL PRIVILEGES ON appdb.* TO 'appuser'@'10.%';
FLUSH PRIVILEGES;第三步写 settings。建议把连接信息走环境变量,避免密码进仓库;OPTIONS 里指定 charset,并按需设严格模式,替换项是库名、账号、主机和端口:
import os
DATABASES = {
"default": {
"ENGINE": "django.db.backends.mysql",
"NAME": os.environ.get("DB_NAME", "appdb"),
"USER": os.environ.get("DB_USER", "appuser"),
"PASSWORD": os.environ.get("DB_PASSWORD", ""),
"HOST": os.environ.get("DB_HOST", "127.0.0.1"),
"PORT": os.environ.get("DB_PORT", "3306"),
"OPTIONS": {
"charset": "utf8mb4",
"init_command": "SET sql_mode='STRICT_TRANS_TABLES'",
},
"CONN_MAX_AGE": 60,
}
}HOST 填 127.0.0.1 而不是 localhost 能避开一部分 socket 路径问题;如果 MySQL 装在非默认 socket 位置,才需要显式配 OPTIONS 中的 unix_socket。
改完后怎么验证
先用 Django 自带的检查命令确认配置能被解析,较新的 Django 版本支持指定数据库别名:

python manage.py check --database default再执行迁移,这一步既验证连接,也验证账号有建表权限:
python manage.py migrate然后进 dbshell 看实际生效的字符集和 SQL 模式,而不是只看配置里写了什么:

python manage.py dbshell
SELECT @@character_set_database, @@collation_database, @@sql_mode;预期信号是:迁移输出全部为 OK 或已应用,没有 Access denied、Unknown database、Can't connect to MySQL server;dbshell 返回的字符集是 utf8mb4。最后做一次真实写入校验,比如通过 shell 创建一条含中文和 emoji 的记录再读出来:
python manage.py shell
from django.db import connection
with connection.cursor() as c:
c.execute("SELECT 1")
print(c.fetchone())能返回 (1,) 说明连接链路通;写入含 emoji 的字符串不报 Incorrect string value,说明字符集这一环也过了。报错信息里的错误码比日志堆栈更好用,先按错误码定位是网络、权限还是字符集问题。
容易忽略的边界
- 驱动编译失败不是配置问题。缺少 MySQL 开发库时
pip install mysqlclient会直接失败,此时先补系统依赖,或临时切 PyMySQL,不要把编译错误当成 settings 写错。 - 账号主机范围写窄了。只在
localhost建账号,在容器或远程连接场景下必然拒绝访问,需要按来源网段授权。 - 排序规则混用。新建库用了 utf8mb4_unicode_ci,而 MySQL 8 默认可能是 utf8mb4_0900_ai_ci,与旧表 JOIN 时会出现排序规则冲突,建库前对齐已有表更省事。
- 严格模式与旧数据。开启
STRICT_TRANS_TABLES后,超长字段会直接报错而不是静默截断;如果是从宽松环境迁过来的老表,需要先确认字段长度。 CONN_MAX_AGE与数据库 wait_timeout。连接复用时间超过服务端空闲超时会出现“MySQL server has gone away”,长连接要结合服务端超时值设置。- 时区。启用
USE_TZ后,MySQL 侧的时区表若未导入,部分时间函数会报错,需要按官方说明加载时区数据。
如果上述任一步在本机环境无法通过,建议先把新配置放到一个独立别名(如 new_db)里试连,保留原来的 sqlite 配置不动,等确认可用了再切换 default,避免改坏后连项目都跑不起来。