Django连接MySQL配置及迁移教程

本文详细讲解了Django项目从默认SQLite切换至MySQL数据库的完整配置与迁移流程，涵盖DATABASES配置要点（如正确设置ENGINE为'django.db.backends.mysql'、预创建utf8mb4编码的数据库、严格填写账号密码及HOST/PORT）、mysqlclient安装常见问题与跨平台解决方案（含macOS、Linux、Windows差异处理），以及PyMySQL作为临时替代方案的适用场景与限制；同时强调了执行migrate前必须核查的三大关键项：数据库用户权限、迁移文件生成状态、字符集一致性，帮助开发者避开“Access denied”“mysql_config not found”“no such table”等高频陷阱，确保生产环境稳定高效运行。

怎么改 Django 的 DATABASES 字典才能连上 MySQL

直接改 DATABASES 里的引擎和连接参数，不是加个 mysqlclient 就能自动切换的。Django 默认用 SQLite，换 MySQL 必须显式指定驱动、地址、账号密码，且字段名不能错。

常见错误现象：运行 python manage.py migrate 报 django.core.exceptions.ImproperlyConfigured: 'mysql' isn't an available database backend —— 这说明没装驱动，或引擎写成了 mysql（正确是 mysqlclient）。

• 引擎必须设为 'ENGINE': 'django.db.backends.mysql'，不是 mysql 或 pymysql
• NAME 是数据库名（不是文件路径），得提前在 MySQL 里用 CREATE DATABASE mysite CHARACTER SET utf8mb4; 建好
• USER 和 PASSWORD 不能留空字符串，MySQL 8+ 默认禁用空密码登录
• 推荐加上 'OPTIONS': {'charset': 'utf8mb4'}，避免 emoji 或生僻字存不进去

为什么 pip install mysqlclient 总失败

因为 mysqlclient 是 C 扩展包，编译依赖系统级头文件和库，Windows/macOS/Linux 表现不同，但核心问题就一个：找不到 MySQL 的 mysql_config。

使用场景：你本地没装 MySQL Server（比如只装了 MySQL Workbench 或只靠 Docker），pip install mysqlclient 就会报 mysql_config not found。

• macOS 上用 Homebrew 装过 MySQL：先确认 which mysql_config 有输出，再运行 pip install mysqlclient
• macOS M1/M2：可能需要额外指定架构，例如 ARCHFLAGS="-arch arm64" pip install mysqlclient
• Linux（如 Ubuntu）：装 sudo apt-get install python3-dev default-libmysqlclient-dev build-essential 再 pip
• Windows：别硬刚，直接用 pip install PyMySQL + 在 __init__.py 里加两行（见下条）

PyMySQL 能不能替代 mysqlclient

能，但只是开发/测试阶段的权宜之计。PyMySQL 纯 Python 实现，没 C 扩展，安装零依赖，但性能差、并发低、部分高级特性（如 prepared statements）支持不完整。

使用场景：CI 流水线跑测试、新手本地快速验证逻辑、Windows 上实在搞不定 mysqlclient 编译时。

• 在项目根目录的 __init__.py（不是 settings.py）里加：

  import pymysql
  pymysql.install_as_MySQLdb()

• 仍要保持 DATABASES['ENGINE'] 为 'django.db.backends.mysql'，Django 不知道你在底下换了实现
• 上线前务必切回 mysqlclient，否则高并发下连接池行为异常、CPU 占用明显偏高

执行 migrate 之前最容易漏的三件事

不是改完 DATABASES 就能直接 migrate。Django 会读配置、建连接、查 schema，中间任何一环断掉都卡在“no such table”或“access denied”。

常见错误现象：报 OperationalError: (1045, "Access denied for user 'xxx'@'localhost'")，或者 CommandError: Can't find the initial migration files。

• 确认 MySQL 用户有权限操作目标库：GRANT ALL PRIVILEGES ON mysite.* TO 'myuser'@'localhost'; FLUSH PRIVILEGES;
• 检查 manage.py makemigrations 是否真生成了迁移文件（在 myapp/migrations/ 下看有没有 0001_initial.py）
• 如果之前用 SQLite 跑过 migrate，db.sqlite3 文件还在，Django 可能误判已应用过迁移 —— 直接删掉它，再从头 makemigrations + migrate

最麻烦的是字符集不一致：MySQL 库用 latin1，Django 迁移建表却按 utf8mb4 发请求，结果字段长度超限或建表失败。建库时那句 CHARACTER SET utf8mb4 别跳过。

以上就是《Django连接MySQL配置及迁移教程》的详细内容，更多关于的资料请关注golang学习网公众号！