Django 连接 MySQL 数据库该怎么配置

文章导读
Django 连 MySQL 通常不是只改一处 DATABASES 就完事,实际卡住的点大多集中在三处:Python 驱动装不上或装错、MySQL 侧的库和账号权限没给对、连接参数与字符集没对齐。因此建议按“先确认环境 → 再改配置 → 跑一次迁移验证 → 回头检查边界”的顺序做,而不是照抄一段 settings 就结束。
📋 目录
  1. A 先确认当前场景和目标
  2. B 按这个顺序处理
  3. C 改完后怎么验证
  4. D 容易忽略的边界
A A

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:

Django 连接 MySQL 数据库该怎么配置
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 版本支持指定数据库别名:

Django 连接 MySQL 数据库该怎么配置
python manage.py check --database default

再执行迁移,这一步既验证连接,也验证账号有建表权限:

python manage.py migrate

然后进 dbshell 看实际生效的字符集和 SQL 模式,而不是只看配置里写了什么:

Django 连接 MySQL 数据库该怎么配置
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,避免改坏后连项目都跑不起来。