PostgreSQL no Docker: Um guia passo a passo para iniciantes

Configurando o PostgreSQL no Docker

A única coisa de que você precisará para executar o banco de dados Postgres no Docker é o próprio mecanismo do Docker.

Nesta seção, orientarei você no processo de cobrir os pré-requisitos e executar um banco de dados PostgreSQL totalmente funcional em um contêiner do Docker.

Pré-requisitos

Antes de começar a usar o PostgreSQL no Docker, você precisará de Docker instalado em seu sistema.

A instalação varia de acordo com o sistema operacional. Os usuários do Windows e do macOS podem simplesmente instalar o DockerDesktop, que é uma interface gráfica fácil de usar para gerenciar contêineres. Faça o download em no site oficial do Docker.

Os usuários do Linux podem instalar o Docker Engine diretamente usando o gerenciador de pacotes de sua distribuição. Por exemplo, no Ubuntu:

sudo apt update
sudo apt install docker.io
sudo systemctl enable --now docker

Além de ter o Docker instalado, é recomendável que você esteja familiarizado com os comandos básicos do terminal e com os conceitos básicos do Docker, como imagens, contêineres e volumes. Estes guias práticos da DataCamp têm tudo o que você precisa:

• Docker para iniciantes: Um guia prático para contêineres
• Instalar o Docker no Ubuntu: Da configuração ao primeiro contêiner

Extração da imagem do Docker do PostgreSQL

Antes de executar o PostgreSQL, você precisa fazer o download da imagem oficial do PostgreSQL Docker no Docker Hub. Essa imagem serve como um modelo para a criação de contêineres.

Para obter a imagem mais recente do PostgreSQL, abra o terminal ou o prompt de comando e execute:

docker pull postgres

Esse comando faz o download da versão estável mais recente do PostgreSQL. Se precisar de uma versão específica, você pode especificá-la com uma tag:

docker pull postgres:17

Imagem 1 - Extraindo a última versão estável da imagem do banco de dados PostgreSQL

Algumas tags de imagem do PostgreSQL comumente usadas incluem:

• postgres:latest - A versão estável mais recente do PostgreSQL
• postgres:17 - PostgreSQL versão 14.x (o patch mais recente da versão 17)
• postgres:17.4 - Uma versão específica (17.4, neste caso).
• postgres:bookworm - PostgreSQL construído na distribuição Linux Debian Bookworm.

Você pode ver todas as tags disponíveis na página oficial do PostgreSQL Docker Hub.

Executando o PostgreSQL em um contêiner do Docker

Depois de ter a imagem do PostgreSQL, você pode criar e iniciar um contêiner com um único comando:

docker run --name postgres-db -e POSTGRES_PASSWORD=mypassword postgres

Imagem 2 - Iniciando um contêiner do PostgreSQL

Esse comando cria um novo contêiner chamado postgres-db e define uma variável de ambiente para a senha do PostgreSQL.

No entanto, esse comando básico tem limitações. Recomendo que você use opções adicionais:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mypassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -p 5432:5432 \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Imagem 3 - Iniciando um contêiner do PostgreSQL com variáveis de ambiente no modo desanexado

Vou detalhar essas opções adicionais:

• Variáveis de ambiente:
  • POSTGRES_PASSWORD: Define a senha para o superusuário do PostgreSQL (obrigatório).
  • POSTGRES_USER: Cria um novo superusuário com esse nome (o padrão é "postgres" se não for especificado).
  • POSTGRES_DB: Cria um novo banco de dados com esse nome (o padrão é o nome de usuário, se não for especificado).
• O mapeamento de portas (-p 5432:5432 ) mapeia a porta PostgreSQL do contêiner (5432) para a mesma porta no seu computador host, permitindo que você se conecte ao PostgreSQL usando localhost:5432.
• A montagem de volume (-v postgres-data:/var/lib/postgresql/data ) cria um volume do Docker chamado postgres-data que mantém os arquivos de banco de dados fora do contêiner. Isso garante que seus dados não sejam perdidos quando o contêiner parar ou for removido.
• O sinalizador -d garante que o contêiner seja executado no modo desconectado. Em linguagem simples, isso significa que o contêiner é executado em segundo plano.

Você pode verificar se o contêiner está em execução com:

docker ps

Imagem 4 - Listagem de todos os contêineres em execução

Na próxima seção, mostrarei a você como configurar ainda mais o contêiner do PostgreSQL para casos de uso específicos.

Configurando o PostgreSQL no Docker

A configuração básica que abordei na seção anterior servirá para você começar, mas, para algo mais avançado, você provavelmente desejará personalizar o contêiner do PostgreSQL.

É disso que trata esta seção.

Configuração do armazenamento persistente com volumes

Um dos aspectos mais importantes da execução de um banco de dados no Docker é garantir que seus dados persistam além do ciclo de vida do contêiner. Por padrão, todos os dados em um contêiner são perdidos quando o contêiner é removido. Para um banco de dados, isso raramente é o que você deseja.

Os volumes do Docker oferecem uma solução para esse problema, armazenando dados fora do sistema de arquivos do contêiner.

Para configurá-lo, comece criando um volume nomeado:

docker volume create postgres-data

Opcionalmente, você pode inspecionar os detalhes do volume executando o seguinte comando:

docker volume inspect postgres-data

Imagem 5 - Detalhes do volume da listagem

Agora, ao iniciar o contêiner do PostgreSQL, monte o volume no diretório de dados do PostgreSQL:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

O parâmetro -v postgres-data:/var/lib/postgresql/data conecta o volume nomeado ao diretório de dados do contêiner.

Para resumir, o uso de volumes para o PostgreSQL tem as seguintes vantagens:

• Seus dados persistem mesmo que você remova o contêiner.
• Você pode parar, iniciar ou atualizar seu contêiner sem perder dados.
• Você pode criar backups de seus dados fazendo o backup do volume.
• Melhor desempenho em comparação com as montagens de ligação (especialmente no macOS e no Windows).

Expondo portas para você se conectar ao PostgreSQL

Para se conectar ao banco de dados PostgreSQL a partir de aplicativos executados no computador host, você precisa expor a porta do PostgreSQL (5432) ao seu sistema local.

A abordagem mais simples é mapear a porta 5432 do contêiner para a mesma porta no seu host:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d postgres

O parâmetro -p 5432:5432 mapeia a porta 5432 do contêiner para a porta 5432 no seu computador host.

Se você já tiver o PostgreSQL ou outro serviço usando a porta 5432 em seu host, poderá mapear para uma porta diferente:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5433:5432 \
  -d postgres

Agora, a porta 5432 do contêiner está mapeada para a porta 5433 no seu host. Ao se conectar, você precisará especificar a porta 5433 em vez da porta padrão 5432.

Por padrão, a porta é exposta em todas as interfaces de rede (0.0.0.0). Opcionalmente, você pode restringi-lo a localhost para aumentar a segurança:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 127.0.0.1:5432:5432 \
  -d postgres

Isso permite conexões apenas do seu computador local, não de outros computadores na rede.

Configuração das definições do PostgreSQL

Você pode alterar muitas configurações padrão do PostgreSQL ao iniciar o seu contêiner. Uma abordagem comum, mas não a única, é usar variáveis de ambiente.

Aqui estão algumas variáveis que você pode usar para configurar o banco de dados:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -e POSTGRES_INITDB_ARGS="--data-checksums" \
  -e POSTGRES_HOST_AUTH_METHOD=scram-sha-256 \
  -d postgres

E aqui está o que cada um deles faz:

• POSTGRES_PASSWORD: Define a senha do superusuário (obrigatório).
• POSTGRES_USER: Define o nome do superusuário (o padrão é "postgres").
• POSTGRES_DB: Define o nome padrão do banco de dados (o padrão é o nome do usuário).
• POSTGRES_INITDB_ARGS: Passa argumentos para o comando initdb do PostgreSQL.
• POSTGRES_HOST_AUTH_METHOD: Define o método de autenticação.

Além das variáveis de ambiente, você também pode personalizar a configuração do PostgreSQL para fazer alterações mais avançadas na configuração do banco de dados.

Algumas configurações do PostgreSQL personalizadas com frequência são:

• max_connections: Controla quantas conexões o PostgreSQL aceita (o padrão é 100).
• shared_buffers: Define a memória usada para armazenamento em cache (o padrão geralmente é muito baixo para produção).
• work_mem: Memória usada para operações de consulta.
• maintenance_work_mem: Memória usada para operações de manutenção.

Para uma implementação prática, comece criando um arquivo, vamos chamá-lo de my-postgres-conf:

max_connections = 200
shared_buffers = 1GB
work_mem = 16MB
maintenance_work_mem = 256MB

Agora, monte esse arquivo ao executar o contêiner:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v ./my-postgres.conf:/etc/postgresql/postgresql.conf \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres \
  -c 'config_file=/etc/postgresql/postgresql.conf'

Resumindo, ao configurar corretamente a persistência, o acesso à rede e as definições do PostgreSQL, você pode criar um ambiente PostgreSQL baseado no Docker que seja executado exatamente como você deseja. A imagem base do postgres:latest é apenas isso - a base - e você pode fazer muitos ajustes.

Na próxima seção, mostrarei a você como se conectar ao banco de dados PostgreSQL em execução no Docker.

Conectando-se ao PostgreSQL em execução no Docker

Agora que você tem o contêiner do PostgreSQL em funcionamento, a próxima etapa é conectar-se a ele. Afinal de contas, por que outra razão você executaria um banco de dados?

Nesta seção, mostrarei a você duas maneiras de se conectar ao seu banco de dados PostgreSQL em contêiner: usando a ferramenta psql de linha de comando e usando uma interface gráfica.

Para referência, estou executando meu contêiner de banco de dados com este comando:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -v postgres-data:/var/lib/postgresql/data \
  -p 5432:5432 \
  -d postgres

Conexão usando a ferramenta de linha de comando psql

A ferramenta de linha de comando psql é o cliente oficial do PostgreSQL que permite que você interaja com o banco de dados usando comandos SQL. 

Para se conectar ao banco de dados PostgreSQL em execução no contêiner a partir do computador host, execute o seguinte comando, mas lembre-se de atualizar os valores do usuário e do banco de dados:

docker exec -it postgres-db psql -U myuser -d mydatabase

Figura 6 - Conexão com o banco de dados Postgres usando psql

E é isso!

Se você não tiver certeza do que o comando faz, aqui está um resumo simples:

• docker exec -it postgres-db: Execute um comando interativo dentro do contêiner chamado "postgres-db".
• psql -U myuser -d mydatabase: Inicie o psql, conectando-se como "myuser" ao banco de dados "mydatabase".

Se você estiver tendo problemas para se conectar, verifique esses problemas comuns:

• Confirme se o contêiner está em execução com docker ps.
• Verifique o mapeamento de portas com docker port postgres-db.

Conexão usando uma ferramenta GUI

Muitos desenvolvedores preferem usar uma ferramenta gráfica em vez de uma CLI, inclusive eu. O pgAdmin é uma opção popular e gratuita para o PostgreSQL, mas o processo de conexão é semelhante para outras ferramentas, como DBeaver, DataGrip ou TablePlus.

A instalação do pgAdmin é simples, portanto, não falarei sobre ela aqui.

Supondo que você o tenha instalado e iniciado, clique com o botão direito do mouse em "Servers" (Servidores) no painel do navegador e selecione "Register > Server" (Registrar > Servidor). Agora, na guia General (Geral), dê um nome à sua conexão:

Figura 7 - Guia geral do pgAdmin

Em seguida, vá para a guia "Connection" (Conexão) e insira esses detalhes:

• Nome/endereço do host: localhost
• Porta: 5432 (ou qualquer porta que você tenha mapeado)
• Banco de dados de manutenção: mydatabase
• Nome de usuário: myuser
• Senha: Sua senha do PostgreSQL

Imagem 8 - Guia de conexão do pgAdmin

Por fim, clique em "Save" (Salvar) para se conectar:

Imagem 9 - Conexão bem-sucedida

Quando estiver conectado, você poderá começar a trabalhar com o banco de dados da mesma forma que faria com uma instância do PostgreSQL instalada localmente ou provisionada na nuvem. A beleza do Docker é que, do ponto de vista do seu aplicativo ou cliente, não há diferença - é apenas um banco de dados PostgreSQL acessível no endereço especificado.

>Você precisa de acesso programático ao seu banco de dados PostgreSQL? Saiba como acessá-lo no Python.

Na próxima seção, falarei sobre como gerenciar o contêiner do PostgreSQL, incluindo como pará-lo, iniciá-lo e monitorá-lo.

Gerenciando o PostgreSQL no Docker

Uma coisa é executar um banco de dados PostgreSQL em um contêiner e conectar-se a ele, mas o gerenciamento é algo totalmente diferente. Felizmente para você, há uma série de comandos à sua disposição.

Nesta seção, abordarei operações essenciais, como parar e iniciar o contêiner, examinar os logs e manter a versão do PostgreSQL atualizada.

Interromper, reiniciar e remover o contêiner do PostgreSQL

As ferramentas de linha de comando do Docker permitem que você gerencie o ciclo de vida do seu contêiner do PostgreSQL.

Para interromper um contêiner do PostgreSQL em execução, execute o seguinte:

docker stop postgres-db

Da mesma forma, execute o seguinte comando quando você precisar iniciá-lo novamente:

docker start postgres-db

Imagem 10 - Parando e iniciando o contêiner

Se você quiser reiniciar um contêiner em execução, o que pode ser útil depois de alterar determinadas configurações, execute o seguinte comando:

docker restart postgres-db

Nos casos em que você tiver terminado completamente com um contêiner e quiser removê-lovocê não precisa procurar mais do que esses dois comandos:

docker stop postgres-db
docker rm postgres-db

Lembre-se de que a remoção de um contêiner não exclui seus dados se você tiver configurado um volume corretamente. Seus dados ainda estarão no volume postgres-data criado anteriormente.

Você pode verificar se o contêiner foi removido executando:

docker ps -a

O sinalizador -a mostra todos os contêineres, inclusive os parados. Se o seu contêiner foi removido com sucesso, ele não aparecerá nessa lista:

Imagem 11 - Listagem de todos os contêineres

Inspecionar os registros

Quando algo dá errado ou você deseja monitorar a atividade do banco de dados, verificar os logs é uma boa primeira etapa.

Execute esse comando para visualizar os logs do seu contêiner PostgreSQL:

docker logs postgres-db

Isso mostra todos os registros desde que o contêiner foi iniciado. Para uma grande quantidade de logs, você pode querer limitar a saída, digamos, para incluir apenas os últimos 50 logs:

docker logs --tail 50 postgres-db

Imagem 12 - Visualização de registros de contêineres

Por outro lado, se você quiser acompanhar os registros em tempo realeste é o comando que você deseja executar:

docker logs -f postgres-db

Imagem 13 - Visualização de registros de contêineres em tempo real

Isso é particularmente útil para depurar problemas de conexão ou observar a atividade do banco de dados durante o desenvolvimento.

Pressione Ctrl+C/CMD+C para parar de seguir os registros.

Atualizando o PostgreSQL no Docker

Com o tempo, você desejará atualizar sua versão do PostgreSQL para obter os recursos, as melhorias de desempenho e os patches de segurança mais recentes.

No momento em que este artigo foi escrito, postgres:17.4 é a versão mais recente, mas vamos supor que, teoricamente, postgres:17.5 tenha sido lançado. Esta seção mostrará a você como atualizar a versão do banco de dados no seu contêiner.

Para começar, obtenha a imagem mais recente do PostgreSQL (ou uma versão específica):

docker pull postgres:17.5

Em seguida, pare e remova o contêiner existente:

docker stop postgres-db
docker rm postgres-db

Por fim, crie um novo contêiner com o mesmo volume:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -v postgres-data:/var/lib/postgresql/data \
  -p 5432:5432 \
  -d postgres:17.5

Como você está usando o mesmo volume (postgres-data), todos os dados que você já possui serão preservados.

Se você estiver atualizando para uma nova versão principal (como 17 para 18), o PostgreSQL executará automaticamente todas as migrações de dados necessárias quando for iniciado. Basta que você tenha em mente esses aspectos:

• As atualizações de versões principais devem ser testadas primeiro em um ambiente que não seja de produção.
• Sempre faça backup do seu volume de dados antes de fazer uma atualização de versão principal.
• Verifique as notas de versão do PostgreSQL para ver se há alterações significativas.

Para criar um backup antes de fazer o upgradeexecute o seguinte comando:

docker run --rm -v postgres-data:/data -v $(pwd):/backup postgres:17.4 \
  bash -c "pg_dumpall -U myuser > /backup/postgres_backup.sql"

Isso cria um arquivo de backup SQL no diretório atual que você pode usar para restaurar os dados se algo der errado.

>Você pode achar nossa Folha de dicas básicas do PostgreSQL útil comoVocê pode achar que a nossa Folha de consulta de fundamentos do PostgreSQL é útil como referência rápida ao trabalhar no Docker.

Na próxima seção, abordarei as práticas recomendadas para usar o PostgreSQL no Docker, incluindo considerações de segurança e dicas de otimização.

Práticas recomendadas para usar o PostgreSQL no Docker

A flexibilidade do Docker vem acompanhada de responsabilidade. Nesta seção, compartilharei algumas práticas recomendadas para garantir que sua configuração do PostgreSQL em contêiner seja confiável, segura e siga os padrões do setor.

Mantenha seus dados seguros com backups regulares

Independentemente de como você executa o PostgreSQL, os backups regulares são obrigatórios. Mencionei os backups na seção anterior, mas é aqui que vou dar um passo adiante. 

A maneira mais simples de fazer backup de um banco de dados PostgreSQL em execução no Docker é usar pg_dump:

docker exec -t postgres-db pg_dump -U myuser mydatabase > backup.sql

Imagem 14 - Backup do PostgreSQL

Para obter um backup completo de todos os bancos de dados, incluindo funções e tablespaces, use pg_dumpall:

docker exec -t postgres-db pg_dumpall -U myuser > full_backup.sql

Imagem 15 - Backup completo do banco de dados PostgreSQL

Esta imagem mostra apenas alguns comandos de backup, pois não é possível encaixar tudo na tela.

Para automatizar seus backupsvocê pode criar um script de shell simples e executá-lo com o cron:

#!/bin/bash
# backup.sh
TIMESTAMP=$(date +"%Y%m%d")
BACKUP_DIR="/Users/dradecic/Documents/pg-backups"

# Make sure the backup directory exists
mkdir -p $BACKUP_DIR

# Create the backup
docker exec postgres-db pg_dumpall -U myuser | gzip > $BACKUP_DIR/postgres_$TIMESTAMP.sql.gz

# Remove backups older than 30 days
find $BACKUP_DIR -name "postgres_*.sql.gz" -mtime +30 -delete

Torne o script executável e o execute:

chmod +x backup.sh

bash backup.sh

Figura 16 - Execução de um script de backup de banco de dados PostgreSQL

Para automatizar totalmente o backup, você pode adicionar o script ao seu arquivo crontab para que você o execute diariamente:

0 3 * * * /path/to/backup.sh

Essa programação executa o backup todos os dias às 3h da manhã, mas é claro que você pode ajustar o tempo e a frequência conforme necessário. 

>Confira meu guia completo sobreguia completo sobre cron jobs para você para saber mais sobre essa útil ferramenta de automação.

Para ambientes de produção, considere armazenar backups fora do local ou em um armazenamento em nuvem para recuperação de desastres.

Use volumes nomeados para persistência de dados

Embora eu tenha abordado os volumes brevemente anteriormente, vale a pena analisá-los com mais profundidade.

Como regra geral, você nuncadeve executar o PostgreSQL no Docker sem um volume configurado adequadamente. Se você fizer isso, seus dados serão perdidos quando o contêiner for removido ou quando o Docker realizar operações de limpeza.

O uso de volumes nomeados (em vez de volumes anônimos) facilita muito o backup e o gerenciamento de dados:

# Create a named volume
docker volume create postgres-data

# Use it when running the container
docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Nada de novo aqui.

Os volumes nomeados também são mais fáceis de fazer backup. Para criar um backup de todo o volume, execute o seguinte comando:

docker run --rm -v postgres-data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-data-backup.tar.gz /data

Isso criará um arquivo postgres-data-backup.tar.gz na mesma pasta em que você executou o comando.

Agora, para restaurar esse volume, execute o seguinte:

docker run --rm -v postgres-data:/data -v $(pwd):/backup alpine sh -c "cd /data && tar xzf /backup/postgres-data-backup.tar.gz --strip 1"

É isso aí!

Protegendo o PostgreSQL no Docker

Quando se trata de bancos de dados, a segurança nunca deve ser uma reflexão tardia. Esta subseção orientará você sobre algumas práticas essenciais para proteger o seu contêiner do PostgreSQL.

Use senhas fortes e exclusivas

Evite senhas padrão ou fracas. Gere uma senha forte e aleatória para o superusuário do PostgreSQL:

export POSTGRES_PASSWORD=$(openssl rand -base64 32)
echo "$POSTGRES_PASSWORD" > postgres-password.txt

docker run --name postgres-db \
  -e POSTGRES_PASSWORD="$POSTGRES_PASSWORD" \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Imagem 17 - Uso de uma senha segura

Armazene essa senha com segurança, por exemplo, em um gerenciador de senhas ou em um arquivo de variável de ambiente que não seja verificado no controle de versão.

Restringir o acesso à rede

Por padrão, o Docker expõe a porta do PostgreSQL em todas as interfaces. Para aumentar a segurança, especialmente na produção, restrinja o acesso ao localhost:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 127.0.0.1:5432:5432 \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Usar a configuração personalizada do PostgreSQL

Crie uma configuração mais segura do PostgreSQL modificando parâmetros como os abaixo:

# Require SSL
ssl = on
ssl_cert_file = '/etc/ssl/certs/ssl-cert-snakeoil.pem'
ssl_key_file = '/etc/ssl/private/ssl-cert-snakeoil.key'

# Limit connection attempts
max_connections = 100
authentication_timeout = 1min

# Restrict access
listen_addresses = 'localhost'

Monte esse arquivo de configuração ao iniciar o contêiner:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v ./pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf \
  -v ./postgresql.conf:/var/lib/postgresql/data/postgresql.conf \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Atualize regularmente sua imagem do PostgreSQL

Mantenha sua versão do PostgreSQL atualizada para obter os patches de segurança mais recentes:

docker pull postgres:latest
docker stop postgres-db
docker rm postgres-db
# Then recreate with the latest image

Essas práticas recomendadas permitirão que você crie um ambiente PostgreSQL mais confiável e seguro no Docker que seja adequado para casos de uso de desenvolvimento e produção.

Na próxima seção, abordarei como solucionar problemas comuns que você pode enfrentar ao executar o PostgreSQL no Docker.

Solução de problemas do PostgreSQL no Docker

Mais cedo ou mais tarde, você terá problemas ao executar o PostgreSQL no Docker. Nesta seção, abordarei problemas comuns e suas soluções, o que poupará a você tempo e frustração ao longo do caminho.

Problemas comuns com contêineres do PostgreSQL

Um problema comum que muitos usuários enfrentam é que o contêiner é encerrado imediatamente após iniciar o. Se esse for o caso para você, verifique os logs para identificar o problema:

docker logs postgres-db

Seu erro pode estar relacionado a problemas de permissão com volumes montados. Se esse for o caso, você verá uma mensagem de log semelhante:

initdb: could not change permissions of directory "/var/lib/postgresql/data": Operation not permitted

Para resolver esse problema, verifique a propriedade e as permissões do volume e, se necessário, corrija-as:

# Check the ownership
docker run --rm -v postgres-data:/data alpine ls -la /data

# Fix the permissions
docker run --rm -v postgres-data:/data alpine chmod 700 /data

Outro problema comum é a falta de variáveis de ambiente necessárias. Uma mensagem de registro típica quando isso acontece é semelhante a esta:

Database is uninitialized and superuser password is not specified

Para resolver isso, verifique se você está definindo a variável de ambiente POSTGRES_PASSWORD necessária ou qualquer outra variável de ambiente:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

O erro "O diretório de dados não está vazio, mas faltam arquivos do PostgreSQL" também é comum. Esta é a mensagem de log que você provavelmente verá:

PostgreSQL Database directory appears to contain a database; Skipping initialization

Seguido de erros sobre arquivos ausentes.

Isso geralmente acontece quando você monta um volume que contém arquivos, mas não um banco de dados PostgreSQL válido. Talvez você precise reinicializar usando um novo volume:

docker volume create postgres-data-new
docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data-new:/var/lib/postgresql/data \
  -d postgres

Resolução de problemas de conectividade

Se você não conseguir se conectar ao seu banco de dados PostgreSQL em execução em um contêiner, comece por confirmando que o contêiner está em execução:

docker ps | grep postgres-db

Se não estiver listado, você pode ter sofrido uma falha. Verifique os registros conforme descrito anteriormente.

Se ele estiver listado, mas você ainda não conseguir se conectar, verifique o mapeamento da porta:

docker port postgres-db

Você deverá ver algo parecido com isto:

Imagem 18 - Mapeamento do porto de contêineres

Caso contrário, o mapeamento da porta pode estar incorreto. Recrie o contêiner com a opção -p adequada.

Se você ainda não conseguir se conectar ao banco de dados, é hora de verificar as configurações de conexão. Verifique esses parâmetros:

• Nome do host: localhost ou 127.0.0.1 (não o nome do contêiner).
• Porto: A porta do host do seu mapeamento (geralmente 5432).
• Nome de usuário: O valor de POSTGRES_USER (o padrão é "postgres").
• Senha: O valor de POSTGRES_PASSWORD.
• Banco de dados: O valor de POSTGRES_DB (o padrão é o mesmo de POSTGRES_USER).

Tente novamente depois de resolver esses problemas. Se o problema persistir, você deve testar a conectividade de dentro do contêiner:

docker exec -it postgres-db psql -U postgres

Se isso funcionar, o problema está no mapeamento da porta ou na rede externa.

Por fim, você pode verificar se há problemas de firewall. O firewall do seu sistema pode estar bloqueando as conexões com a porta do PostgreSQL, portanto, verifique-o:

# Linux
sudo iptables -L | grep 5432

# macOS
sudo pfctl -sr | grep 5432

Ao verificar esses problemas comuns, você deve conseguir identificar e resolver a maioria dos problemas com o PostgreSQL no Docker. Se você ainda estiver com dificuldades, a documentação do PostgreSQL e do Docker e os fóruns da comunidade são excelentes recursos para solucionar problemas mais específicos.

Resumindo o banco de dados PostgreSQL no Docker

E aí está: o guia definitivo para configurar e executar bancos de dados PostgreSQL no Docker! Abordei tudo o que você precisa saber para começar, desde a configuração do seu primeiro contêiner até a configuração, a conexão e o gerenciamento do seu banco de dados. 

As opções tradicionais do PostgreSQL, como instalar o banco de dados localmente ou provisioná-lo na nuvem, não são ideais ou são caras para fins de desenvolvimento. O Docker preenche essa lacuna. Não importa se você o está usando para desenvolvimento local, testes ou mesmo ambientes de produção, o PostgreSQL em contêineres oferece flexibilidade e consistência difíceis de superar.

Agora você está mais do que pronto para integrar o banco de dados Postgres Dockerizado aos seus aplicativos.

Se você quiser se aprofundar mais, recomendo estes cursos da DataCamp:

• Criação de bancos de dados PostgreSQL
• Introdução ao Docker
• SQL para administradores de banco de dados
• Funções para manipulação de dados no PostgreSQL