Como conectar o Django (Python) ao MySQL

✅ Artigo atualizado em Setembro 2026 Versões mínimas atualizadas: o Django 6.1 (versão estável atual) exige MySQL 8.4+ ou MariaDB 10.11+; a LTS 5.2 exige MySQL 8.0.11+ ou MariaDB 10.5+. O comando Docker agora cria o banco e o usuário usados no settings.py, o HOST passou a ser 127.0.0.1 e incluímos as dependências de sistema do mysqlclient. Conexão e migrate executados com Django 6.1.1 e MySQL 8.4 (via PyMySQL; a instalação do mysqlclient foi conferida só na documentação).

Salve salve Pythonista!

O Django é um framework de desenvolvimento web em Python que permite a criação de aplicações robustas e escaláveis.

Uma das principais tarefas ao construir uma aplicação Django é conectar o framework a um banco de dados para armazenar as informações da sua aplicação.

Neste artigo, vamos explorar como conectar o Django a um Banco de Dados MySQL, um sistema de gerenciamento de banco de dados relacional extremamente popular.

Este artigo faz parte do Guia Completo de Django. Lá você encontra o caminho inteiro, da instalação ao deploy: Models, Views, Templates, Forms, Admin, bancos de dados, boas práticas e DRF.

Vá Direto ao Assunto…

• Executando o MySQL localmente com Docker
• Configurando o Django para se conectar ao MySQL

Executando o MySQL localmente com Docker

Antes de conectar o Django ao MySQL, é necessário ter o banco de dados em execução localmente.

Uma forma fácil e conveniente de fazer isso é utilizando o Docker.

O Docker permite criar e executar aplicativos dentro de containers, de forma isolada e sem a necessidade de instalação do software diretamente no sistema operacional.

Para iniciar um container do MySQL através do Docker, você pode executar o seguinte comando no terminal:

1
2
3
4
5
6
7
8

docker run \
    -p 3306:3306 \
    --name mysql-container \
    -e MYSQL_ROOT_PASSWORD=senha_do_root \
    -e MYSQL_DATABASE=seu_banco_de_dados \
    -e MYSQL_USER=seu_usuario \
    -e MYSQL_PASSWORD=sua_senha \
    -d mysql:8.4

Esse comando irá baixar a imagem do MySQL 8.4 (versão LTS do MySQL, aceita tanto pelo Django 6.1 quanto pela LTS 5.2 do Django), criar um container com o nome “mysql-container”, definir a senha do usuário root e já criar o banco seu_banco_de_dados e o usuário seu_usuario (com a senha sua_senha) com acesso a ele. Sem MYSQL_DATABASE, MYSQL_USER e MYSQL_PASSWORD, o container só teria o usuário root e nenhum banco da aplicação, e a configuração do Django abaixo não conseguiria conectar.

Além disso, ele mapeará a porta 3306 do container para a mesma porta do host local.

Está curtindo esse conteúdo?

Que tal receber 30 dias de conteúdo direto na sua Caixa de Entrada?

Sua assinatura não pôde ser validada.

Você fez sua assinatura com sucesso.

Assine as PyDicas e receba 30 dias do melhor conteúdo Python na sua Caixa de Entrada: direto e sem enrolação!

Seu nome

Seu e-mail

ASSINAR PYDICAS

Configurar a conexão é só o primeiro passo: para dominar Django de ponta a ponta, de models a views, com prática guiada, conheça a Jornada Python:

Domine Python: A Linguagem da Inteligência Artificial, do Desenvolvimento Web e das Carreiras do Futuro.

A mais completa formação para você se tornar um especialista em Python, pronto para construir desde aplicações web robustas com Django até projetos de Inteligência Artificial e Ciência de Dados .

Quero conhecer!

Nota 4,9 de 5 na Hotmart O curso de Python mais bem avaliado da Hotmart!

Configurando o Django para se conectar ao MySQL

Após ter o MySQL em execução localmente, é necessário realizar as configurações apropriadas no Django para que ele possa se conectar ao banco de dados.

Vamos considerar que você já tenha um projeto Django criado.

Para que o Django possa se comunicar com o MySQL, é necessário instalar a biblioteca mysqlclient, o driver recomendado pela documentação do Django (o Django 6.1 exige a versão 2.2.1 ou mais recente).

No Linux e no macOS, o mysqlclient é compilado durante a instalação, então antes você precisa das bibliotecas de desenvolvimento do MySQL. Segundo a documentação do mysqlclient, no Debian/Ubuntu:

1

sudo apt-get install python3-dev default-libmysqlclient-dev build-essential pkg-config

(no macOS com Homebrew: brew install mysql pkg-config; no Windows há pacotes pré-compilados e esse passo não é necessário.)

Depois, com seu ambiente virtual ativado, execute o seguinte comando no terminal:

1

pip install mysqlclient

💡 E o PyMySQL? O pymysql é um driver em Python puro, mais fácil de instalar, mas não é oficialmente suportado pela documentação do Django. Se quiser usá-lo mesmo assim (por exemplo, quando não dá para compilar o mysqlclient), instale com pip install pymysql e adicione no topo do settings.py as linhas import pymysql e pymysql.install_as_MySQLdb(), que fazem o PyMySQL se apresentar ao Django como se fosse o mysqlclient. Sem isso, o Django falha com Error loading MySQLdb module. Did you install mysqlclient?.

Em seguida, no arquivo settings.py do seu projeto Django, encontre a seção DATABASES e substitua as configurações padrão pelo seguinte código:

1
2
3
4
5
6
7
8
9
10

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'seu_banco_de_dados',
        'USER': 'seu_usuario',
        'PASSWORD': 'sua_senha',
        'HOST': '127.0.0.1',
        'PORT': '3306'
    }
}

Certifique-se de substituir ‘seu_banco_de_dados’, ‘seu_usuario’ e ‘sua_senha’ pelos valores correspondentes ao seu ambiente local.

Caso você tenha configurado o MySQL em uma porta diferente, lembre-se de alterar o valor de PORT de acordo.

Repare que usamos '127.0.0.1' e não 'localhost' no HOST. Com o mysqlclient, o valor localhost faz a biblioteca cliente do MySQL tentar se conectar por um arquivo de socket local (Unix socket) em vez de TCP, e isso falha quando o MySQL está rodando dentro de um container Docker. Com 127.0.0.1, a conexão é feita via TCP na porta mapeada.

Após realizar as alterações nas configurações do Django, é necessário criar as tabelas do banco de dados. O comando abaixo aplica as migrações dos apps instalados (num projeto novo, as 18 migrações dos apps nativos do Django, como auth e admin); quando você criar seus próprios models, rode antes o python manage.py makemigrations.

Execute o seguinte comando no terminal para aplicar essas alterações:

1

python manage.py migrate

Estou desenvolvendo o Ebookr.ai, uma plataforma que transforma suas ideias em ebooks profissionais usando IA - com geração de capa, infográficos e exportação em PDF. Te convido a conhecer!

Conclusão

Neste artigo, exploramos como conectar o Django a um banco de dados MySQL.

Primeiramente, vimos como executar o MySQL localmente utilizando o Docker.

Em seguida, realizamos as configurações necessárias no Django para estabelecer a conexão com o banco de dados.

Por fim, aplicamos as migrações com o migrate, criando as tabelas no MySQL.

Ao seguir essas instruções, você será capaz de utilizar o Django em conjunto com o MySQL para desenvolver poderosas aplicações web de forma simples e eficiente.

Agora você está pronto para começar a construir seus próprios projetos Django utilizando o MySQL como seu banco de dados de escolha.

Se quiser ir além e construir um projeto Django completo com banco de dados real, conheça a Jornada Python, nosso curso de Python completo.

Nos vemos no próximo artigo!

Por Vinícius Ramos em 22/10/2023

Engenheiro de Computação pela UnB com especialização em Inteligência Artificial. Sr. Software Engineer com 10+ anos de experiência desenvolvendo sistemas críticos em Python e Django. Atuei no Banco do Brasil liderando equipes para monitoramento de mainframe, trabalhei como desenvolvedor sênior em projetos forenses para a Polícia Federal, e atualmente sou engenheiro de software na Labcorp (Estados Unidos), desenvolvendo soluções escaláveis para testes genéticos. Fundador da Python Academy, compartilhando conhecimento técnico com a comunidade brasileira desde 2018.

Bora se conectar no LinkedIn! vinicius-aramos

Minhas redes:

• 
• 
•