How to Configure and Connect Django with MySQL Step by Step

We start from the premise that we already know how to work with models in Django, and the next step is the database; although, Django by default uses SQLite, which is an excellent database, sometimes we need to use a more complete database such as MySQL.

With all the layers that our framework has, one of the main ones is the data management layer, in other words, it is part of our database, which can be of various types such as MySQL, MariaDB, PostgreSQL, among others.

When I developed my first project with Django, the part that generated the most doubts for me was how to connect Django with MySQL. Although the framework comes with SQLite by default, as a project grows or is deployed in production, MySQL becomes a more robust and scalable option.

In this guide, I show you how to integrate Django with MySQL step by step, just as I do in my real projects. We will look at requirements, installation, configuration, and how to resolve the most common errors.

🚀 Why use MySQL with Django?

Although Django works perfectly with SQLite, MySQL offers key advantages:

• Scalability: ideal for production environments with multiple users.
• Compatibility: many hosting services support MySQL natively.
• Advanced management: you can use tools like MySQL Workbench or phpMyAdmin.

In my case, I decided to use MySQL because I needed to manage several databases and complex queries without depending on a single local file, as is the case with SQLite.

Connectors for each database engine

Django can connect to MySQL using two drivers:

• mysqlclient (official)
• PyMySQL (alternative, more flexible)

The main thing you have to consider when you want to connect to a database engine is that the connector simply varies, that is, depending on the database server you want to connect to, you simply have to change the connector, and in the official documentation that I leave you a little further down, you can see the different types of connectors you can use and with that, the different clients.

In this post, we will see how we can create a connection with MySQL in Django; for that we have a couple of ways, the official or the unofficial one; if we review the official documentation.

We will see that they indicate that starting from Django version 3 we can use a native Driver for MySQL and for MariaDB, you are free to try the official solution, but in case it gives you an error like the following:

*** cannot open include file 'mysql.h' ***

Testing the UNOFFICIAL version of the MySQL connector

We can try another solution which would be to install a package that will serve as a driver or connector to our MySQL, which is the following:

pip install PyMySQL

So we install it and now we have to tell our Django project to use this driver; for that:

firstProject\firstProject\__init__py
import pymysql
pymysql.version_info = (1, 3, 13, "final", 0)
pymysql.install_as_MySQLdb()

And now we simply have to create the database that we are going to use and then establish the rest of the connections:

firstProject\firstProject\settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'djangofirstproyect',
        'USER': 'root',
        'PASSWORD': ''
    }
}

And with this, we are ready to do more interesting operations using our MTV in Django, which we will do starting from the next post.  

• DATABASE_NAME We indicate the name of the database. If you are using SQLite, specify the full path including the file system to the file/database.
• DATABASE_USER We indicate which database user we are going to use to connect to the previous database.
• DATABASE_PASSWORD We indicate the password for the previous user.
• DATABASE_HOST This is one of the most important elements and it is the host, if we are in a development environment it will surely be localhost or local server, but if you are in a production environment it is very likely to change to another or an IP.

Depending on the database you are going to use, you will surely have to add some more or less parameters, for example in the case of SQLite, which is the default one, it is not necessary to indicate a username/password or a host, since it is simply a file.

The next thing we will see is how to create a model for our first application.

🧠 Initialize the connection and test the link

Once settings.py is configured, run the migrations in Django to verify the connection:

$ python manage.py migrate

If all goes well, Django will automatically create the system tables in your MySQL database.

I usually confirm the connection directly from MySQL Workbench: the auth_user, django_session tables, among others, should appear there.

You can also do a quick test from the shell:

$ python manage.py shell
>>> from django.db import connection
>>> connection.ensure_connection()
>>> print("Conexión establecida correctamente")

❗ Common errors when connecting Django with MySQL (and how I solved them)

During my first tests I ran into some typical errors:

Error    Cause    Solution
cannot open mysql.h    Missing MySQL client dependencies    Install PyMySQL or install libmysqlclient-dev on Linux
Access denied for user 'root'@'localhost'    Incorrect password or user without permissions    Check USER and PASSWORD in settings.py
django.db.utils.OperationalError    MySQL not started    Verify that the service is active (sudo service mysql start)

These small setbacks are common. In my case, everything worked smoothly with PyMySQL.

⚖️ PyMySQL vs mysqlclient: which one is better?

Aspect    PyMySQL    mysqlclient
Installation    Very simple, no compilation required    Requires system dependencies
Performance    Lightweight and sufficient for most projects    Slightly faster with large databases
Compatibility    Works well on Windows, macOS, and Linux    Sometimes throws errors on Windows
Recommendation    Ideal for development and medium-sized environments    Recommended in production if your environment allows it

I prefer PyMySQL for its ease and stability, especially when working on Windows or virtualized environments.

🏁 Conclusion and next steps

With this, you now have your Django project connected to MySQL and ready to build models, views, and migrations.
In my experience, this configuration remains stable even when deploying to production.
The natural next step is to create your models and start manipulating data from the Django ORM.

❓ Frequently Asked Questions

1. Can I use MariaDB instead of MySQL?
Yes, Django is natively compatible starting from version 3.

2. How do I test if my connection works?
Run python manage.py migrate or use python manage.py dbshell.

3. What do I do if PyMySQL doesn't work?
Verify your Python and Django version, reinstall with pip install --upgrade PyMySQL.