Como conectar o Django (Python) ao Banco de Dados PostgreSQL

✅ Artigo atualizado em Setembro 2026 Passo a passo executado com Django 6.1.1, psycopg 3.3 e PostgreSQL 18 (imagem Docker postgres). O driver recomendado agora é o psycopg 3 (suportado desde o Django 4.2), o comando Docker passou a criar o banco usado no settings.py e incluímos as versões mínimas do PostgreSQL exigidas pelo Django 6.1 e pela LTS 5.2.

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 Postgres, um sistema de gerenciamento de banco de dados relacional extremamente poderoso.

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…

• Mas primeiro… O que é o PostgreSQL?
• Executando o Postgres localmente com Docker
• Configurando o Django para se conectar ao Postgres
• Definindo os Modelos da nossa aplicação
• Executando as Migrações no Banco de Dados

Mas primeiro… O que é o PostgreSQL?

PostgreSQL é um popular Sistema de Gerenciamento de Banco de Dados (SGBD) de código aberto, conhecido por sua confiabilidade, escalabilidade e recursos avançados.

Ele suporta o modelo de banco de dados relacional, que é a base de muitas aplicações modernas.

O Postgres é amplamente utilizado em projetos de todos os tamanhos, desde pequenas startups até grandes empresas.

Executando o Postgres localmente com Docker

Antes de conectar o Django ao Postgres, precisamos ter uma instância local do Postgres em execução.

Uma maneira fácil de fazer isso é usando o Docker.

O Docker permite que você execute aplicativos em contêineres isolados, facilitando a configuração e o gerenciamento de bancos de dados e outras dependências.

Para executar o Postgres localmente com Docker, você precisará ter o Docker instalado em sua máquina.

Uma vez instalado, você pode usar o seguinte comando para iniciar uma instância do Postgres:

1

docker run -d -p 5432:5432 --name postgres-db -e POSTGRES_PASSWORD=minha_senha -e POSTGRES_USER=meu_usuario -e POSTGRES_DB=nome_do_banco postgres

Altere minha_senha para uma senha de sua preferência, meu_usuario para um nome de usuário de sua preferência e nome_do_banco para o nome do banco da sua aplicação.

Isso iniciará um contêiner do Postgres na porta 5432, definirá o usuário e a senha especificados e criará o banco nome_do_banco. Sem o POSTGRES_DB, a imagem cria um banco com o mesmo nome do usuário (meu_usuario), e a conexão com nome_do_banco configurada abaixo falharia com “database does not exist”.

A imagem postgres sem tag baixa a versão mais recente do PostgreSQL (a 18, em Setembro 2026). O Django 6.1 exige PostgreSQL 15 ou mais recente, e a LTS 5.2 exige PostgreSQL 14 ou mais recente. Se quiser uma versão fixa, use uma tag, por exemplo postgres:17.

Configurando o Django para se conectar ao Postgres

Agora que temos uma instância do Postgres em execução, podemos configurar nosso projeto Django para se conectar a ela.

Abra o arquivo settings.py do seu projeto Django e localize o dicionário de configurações DATABASES.

Substitua o valor default pela seguinte configuração:

1
2
3
4
5
6
7
8
9
10

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'nome_do_banco',
        'USER': 'meu_usuario',
        'PASSWORD': 'minha_senha',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

Certifique-se de substituir nome_do_banco, meu_usuario e minha_senha pelos valores corretos para o seu banco de dados.

Estou construindo o Ebookr.ai, uma plataforma onde você cria ebooks profissionais com IA sobre qualquer assunto - do zero ao PDF pronto, com capas e infográficos gerados automaticamente. Dá uma olhada!

Além disso, é necessário instalar uma outra dependência para que o Django saiba conversar com o Banco de Dados: o driver do PostgreSQL.

Hoje a recomendação da documentação do Django é o psycopg 3 (pacote psycopg), suportado desde o Django 4.2. O Django 6.1 exige o psycopg 3.1.12 ou mais recente.

Com seu ambiente virtual ativado (saiba mais sobre ambientes virtuais e Virtualenv clicando aqui), instale-o com:

1

pip install "psycopg[binary]"

O extra [binary] traz o psycopg já compilado, junto com a biblioteca cliente do PostgreSQL (libpq), então você não precisa de compilador nem de bibliotecas do sistema. É a forma de instalação que a própria documentação do psycopg recomenda para a maioria dos usuários. Se o seu sistema não tiver pacote binário disponível, a alternativa é a instalação local (pip install "psycopg[c]"), que compila a extensão e exige as ferramentas de build e a libpq instaladas.

Não é preciso mudar nada no settings.py: o ENGINE continua sendo 'django.db.backends.postgresql', que funciona tanto com o psycopg 3 quanto com o antigo psycopg2.

💡 E o psycopg2? Ele ainda é aceito (o Django 6.1 exige a versão 2.9.9 ou mais recente), mas a documentação do Django avisa que esse suporte deve ser descontinuado no futuro. Se você mantém um projeto antigo com psycopg2-binary, saiba que a documentação do psycopg2 desaconselha o pacote binário em produção, recomendando o pacote compilado a partir do código-fonte (pip install psycopg2, que exige compilador, pg_config e os headers da libpq). Para projetos novos, prefira o psycopg 3.

Definir esses models é só o começo: na Jornada Python você aprende Django com PostgreSQL de verdade, do model até as APIs REST:

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!

Definindo os Modelos da nossa aplicação

Agora que o Django está configurado para se conectar ao Postgres, podemos criar os modelos de dados que serão usados ​​em nossa aplicação.

Vamos criar um exemplo simples de uma aplicação de Blog.

Abra o arquivo models.py da sua aplicação (criado pelo python manage.py startapp; lembre-se de adicionar o app em INSTALLED_APPS no settings.py) e adicione o seguinte código:

1
2
3
4
5
6

from django.db import models

class Post(models.Model):
    title = models.CharField(max_length=250)
    content = models.TextField()
    pub_date = models.DateTimeField(auto_now_add=True)

Neste exemplo, criamos um modelo chamado Post com três campos: title, content e pub_date.

O campo pub_date é configurado para ser preenchido automaticamente com a data e hora atuais sempre que um novo Post for criado.

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

Executando as Migrações no Banco de Dados

Antes de podermos usar nosso modelo Post, precisamos aplicar as migrações ao banco de dados.

As migrações são um recurso do Django que permite controlar e gerenciar as alterações no esquema do banco de dados ao longo do tempo.

Para executar as migrações, use o seguinte comando:

1
2

python manage.py makemigrations
python manage.py migrate

Isso criará as tabelas necessárias no banco de dados e deixará tudo pronto para começarmos a usar os modelos em nossa aplicação.

Conclusão

Conectar o Django a um Banco de Dados Postgres é uma tarefa essencial ao desenvolver aplicações web com o framework.

Neste artigo, exploramos como executar o Postgres localmente com Docker e como configurar o Django para se conectar a ele.

Também foi mostrado como criar e usar modelos de dados com o Django.

Agora, você está pronto para construir aplicações robustas e escaláveis utilizando o Django e o poderoso banco de dados Postgres.

Quer levar esse conteúdo para onde for com nosso ebook GRÁTIS de Desenvolvimento Web com Python e Django?

Então aproveita essa chance

Ebook GRÁTIS

DESENVOLVIMENTO WEB COM PYTHON E DJANGO

Conteúdo:

• Veja como modelar sua aplicação
• Utilize a robusta API de Acesso a Dados do Django
• Aprenda sobre Class Based Views
• Construa Middlewares próprios
• Desenvolva filtros e tags customizados para criar lindos templates

Baixe já!

Se quiser ir além da conexão com o banco e construir um projeto Django completo, do model às APIs REST, o curso de Django da Jornada Python pode te ajudar.

Nos vemos na próxima!

Por Vinícius Ramos em 16/09/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:

• 
• 
•