Docker pgAdmin: como configurar uma GUI do PostgreSQL com Docker Compose

Ficar alternando entre sessões, decorar sintaxe e torcer para não digitar uma consulta destrutiva com erro de digitação cansa rápido. Não há plano de execução visual, nem navegador de esquemas, nem uma forma simples de fazer backup do banco. Funciona, mas está longe do ideal.

O pgAdmin 4 resolve isso com uma GUI no navegador feita especificamente para PostgreSQL. E rodá-lo no Docker significa zero instalação local. É só iniciar o contêiner.

Neste artigo, vou mostrar como configurar PostgreSQL e pgAdmin 4 com Docker Compose, conectar os dois contêineres e usar o Query Tool do pgAdmin, o navegador de esquemas e os recursos de backup.

Para acompanhar, você vai precisar do Docker instalado e em execução na sua máquina. Se você está começando com Docker Compose, leia nosso guia para ver como ele simplifica o desenvolvimento com múltiplos contêineres.

O que é o pgAdmin 4?

O pgAdmin 4 é uma plataforma open source, baseada em navegador, para administração e desenvolvimento com PostgreSQL. Você acessa pelo browser, sem precisar instalar app de desktop. Ele oferece uma GUI para gerenciar bancos, executar consultas, inspecionar esquemas e fazer backups — tudo sem encostar no terminal.

A imagem oficial do Docker é dpage/pgadmin4, mantida pela equipe de desenvolvimento do pgAdmin.

Executar o pgAdmin 4 no Docker tem algumas vantagens reais em relação à instalação local. A primeira é portabilidade — todo o seu ambiente de banco vive em um arquivo docker-compose.yml que você pode compartilhar com o time. A segunda é ausência de conflitos de versão — o pgAdmin roda em seu próprio contêiner, totalmente isolado do resto da sua máquina. E quando terminar, docker compose down limpa tudo.

pgAdmin 4 vs. outras GUIs para PostgreSQL

Não faltam GUIs para gerenciamento de bancos. Veja como o pgAdmin 4 se compara a duas alternativas populares.

pgAdmin 4 versus alternativas populares

DBeaver e TablePlus são ótimas ferramentas, mas nenhuma delas tem imagem oficial no Docker. Se sua instância PostgreSQL já está rodando no Docker, o pgAdmin 4 é um encaixe perfeito — basta adicionar um serviço ao seu docker-compose.yml e tudo roda junto na mesma rede.

Configurando o ambiente com Docker Compose

A forma mais rápida de colocar PostgreSQL e pgAdmin 4 para rodar juntos é com um único arquivo docker-compose.yml. Se o tema é novo para você, nosso guia de Docker Compose cobre os fundamentos. Aqui, vou focar na configuração específica do pgAdmin.

Aqui vai o arquivo completo para você copiar e colar:

services:
  postgres:
    image: postgres:18
    container_name: postgres
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql
    networks:
      - pgnetwork

  pgadmin:
    image: dpage/pgadmin4:9.13
    container_name: pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: you@yourdomain.com
      PGADMIN_DEFAULT_PASSWORD: password
      PGADMIN_LISTEN_PORT: 5050 
    ports:
      - "5050:5050"                
    volumes:
      - pgadmin_data:/var/lib/pgadmin
    depends_on:
      - postgres
    networks:
      - pgnetwork

volumes:
  postgres_data:
  pgadmin_data:

networks:
  pgnetwork:

O campo depends_on informa ao Docker Compose para iniciar o contêiner postgres antes do pgadmin. Sem isso, o pgAdmin pode subir antes do PostgreSQL estar pronto e falhar na conexão. Ele não espera o PostgreSQL ficar totalmente saudável — apenas o contêiner iniciar. Ainda assim, é suficiente para evitar a maioria das condições de corrida.

Variáveis de ambiente do pgAdmin 4

Duas variáveis de ambiente são obrigatórias:

• PGADMIN_DEFAULT_EMAIL - o e-mail que você usará para entrar na interface web do pgAdmin
• PGADMIN_DEFAULT_PASSWORD - a senha dessa conta

Uma terceira é opcional, mas vale a pena definir:

• PGADMIN_LISTEN_PORT - a porta em que o pgAdmin escuta dentro do contêiner. O padrão é 80, mas definir como 5050 deixa tudo mais organizado ao mapear portas.

Dito isso, fixar credenciais no arquivo Compose é uma má ideia, especialmente se o arquivo for para o controle de versão. Mova-as para um arquivo .env.

Crie um arquivo .env no mesmo diretório do seu docker-compose.yml:

POSTGRES_USER=admin
POSTGRES_PASSWORD=secret
POSTGRES_DB=mydb
PGADMIN_DEFAULT_EMAIL=admin@example.com
PGADMIN_DEFAULT_PASSWORD=secret

Depois, referencie as variáveis no seu arquivo Compose:

# postgres
environment:
  POSTGRES_USER: ${POSTGRES_USER}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  POSTGRES_DB: ${POSTGRES_DB}
  
# pgadmin
environment:
  PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL}
  PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD}

O Docker Compose reconhece arquivos .env quando você executa o comando, sem precisar de configuração extra. Só não esqueça de adicionar .env ao seu .gitignore para manter as credenciais fora do repositório.

Volumes e persistência de dados

O volume mapeado para /var/lib/pgadmin é onde o pgAdmin armazena dados como sessões, conexões salvas de servidores e configurações. Remover isso do compose significa perder tudo a cada reinício do contêiner.

No arquivo compose atual, você tem um volume nomeado que o Docker gerencia na sua máquina host. Os dados sobrevivem a reinícios, recriações e atualizações de imagem — desde que você não apague explicitamente o volume com docker volume rm.

Iniciando a stack e acessando o pgAdmin 4

Com seu docker-compose.yml pronto, iniciar a stack exige um único comando:

docker compose up -d

A flag -d executa ambos os contêineres em modo destacado — eles sobem em segundo plano e o seu terminal fica livre. Para verificar se ambos estão rodando:

docker ps

Você deve ver postgres e pgadmin listados com status Up.

Status dos contêineres

Se algo parecer estranho, verifique os logs do pgAdmin:

docker logs pgadmin

Uma inicialização saudável se parece com isto:

Logs de inicialização do pgAdmin

Se aparecer um erro, provavelmente será um destes três:

• Falha na autenticação por senha: sua PGADMIN_DEFAULT_PASSWORD está ausente ou malformada no arquivo .env

• Port already allocated: outra coisa está usando a porta 5050; altere a porta do host no seu Compose

• No such file or directory: o caminho do volume está errado ou o contêiner não tem permissão de escrita

Quando ambos os contêineres estiverem de pé e os logs limpos, abra o navegador e acesse http://localhost:5050:

Página de login do pgAdmin

Entre com o e-mail e a senha definidos em PGADMIN_DEFAULT_EMAIL e PGADMIN_DEFAULT_PASSWORD. Você chegará ao dashboard do pgAdmin, pronto para registrar seu servidor PostgreSQL:

Página inicial do pgAdmin

Conectando o pgAdmin 4 ao seu contêiner PostgreSQL

Na sidebar do pgAdmin, clique com o botão direito em Servers - Register - Server. Uma janela se abre com duas abas para preencher: General e Connection.

A aba General

Dê um nome significativo ao servidor — algo como local-dev-postgres. É só um rótulo dentro do pgAdmin, então escolha o que fizer sentido para sua configuração.

Registro do servidor - aba General

A aba Connection

Não use localhost aqui. 

Dentro de uma rede Docker, localhost se refere ao próprio contêiner — não à sua máquina host e nem ao contêiner do PostgreSQL. O Docker tem seu próprio DNS interno, que resolve nomes de contêiner usando os nomes de serviço definidos no seu docker-compose.yml. Então, se o serviço do PostgreSQL se chama postgres, esse é o hostname que você deve usar.

Preencha os campos assim:

• Host name/address: postgres (o nome do serviço no docker-compose.yml)

• Port: 5432

• Maintenance database: o valor de POSTGRES_DB no seu Compose (ex.: mydb)

• Username: o valor de POSTGRES_USER (ex.: admin)

• Password: o valor de POSTGRES_PASSWORD

Clique em Save. 

Registro do servidor - aba Connection

Se estiver tudo certo, o servidor aparecerá na sidebar e você poderá expandi-lo para ver seus bancos de dados:

Registro de servidor bem-sucedido

Isso significa que a conexão está ativa.

Usando o Query Tool

Agora que você está conectado, vou mostrar o básico do pgAdmin 4 e do Postgres em geral.

Abra o Query Tool clicando em Tools - Query Tool no menu superior. A interface tem três painéis:

• Editor: onde você escreve SQL
• Data Output: onde os resultados aparecem depois de executar a consulta
• Messages: onde o PostgreSQL envia mensagens de status, erros e informações de execução

Query tool

Escrevendo e executando SQL

Vamos criar uma tabela simples orders e inserir alguns dados. Você pode executar cada bloco clicando no botão Play ou pressionando F5, que é o atalho.

Execute isto para criar a tabela:

CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    customer_name VARCHAR(100) NOT NULL,
    product VARCHAR(100) NOT NULL,
    quantity INT NOT NULL,
    order_date DATE DEFAULT CURRENT_DATE
);

Insira algumas linhas:

INSERT INTO orders (customer_name, product, quantity)
VALUES
    ('Alice Johnson', 'Wireless Keyboard', 2),
    ('Bob Smith', 'USB-C Hub', 1),
    ('Carol White', 'Mechanical Keyboard', 3);

E agora, consulte os dados:

SELECT * FROM orders;

Consultando dados

Os resultados aparecem no painel Data Output como uma tabela. Você pode ordenar colunas, redimensioná-las e copiar linhas diretamente da grade.

Lendo o plano de consulta visual

Para ver o que acontece nos bastidores ao executar uma consulta, rode EXPLAIN ANALYZE no seu SELECT:

EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_name = 'Alice Johnson';

Resultados do Explain Analyze

O painel Data Output mostra a saída bruta. Mas o pgAdmin tem uma opção melhor. Clique no botão Explain na barra de ferramentas — e o pgAdmin renderiza o plano de consulta como um gráfico interativo.

Plano de consulta em gráfico

Aqui é simples, mas você verá muito mais quando estiver fazendo joins ou agregações de dados mais complexas.

Isso é importante porque ler a saída crua do EXPLAIN é lento e sujeito a erro. O plano visual deixa óbvio quando o PostgreSQL faz um full table scan em uma tabela grande ou quando um índice existe mas não está sendo usado.

Gerenciando o seu schema de banco

A sidebar do pgAdmin mostra toda a estrutura do seu banco — e permite modificá-la pela GUI.

A árvore é: Servers - nome do seu servidor - Databases - seu banco - Schemas - public - Tables. Expanda qualquer tabela e você verá Columns, Indexes e Constraints listados como nós filhos. Clique em qualquer um para ver os detalhes no painel da direita.

Criando e alterando tabelas

Para criar uma nova tabela, clique com o botão direito em Tables dentro do seu schema e selecione Create - Table. Abre-se uma janela com algumas abas.

Criando tabelas

Na aba General, você define o nome da tabela. Troque para a aba Columns para adicionar colunas — cada linha permite definir nome, tipo de dado, tamanho e se é anulável. A aba Constraints cuida de chaves primárias, estrangeiras e restrições de unicidade.

Para adicionar um índice a uma tabela existente, expanda a tabela na sidebar, clique com o botão direito em Indexes e selecione Create - Index. Escolha as colunas e o tipo de índice — btree é o padrão e atende a maioria dos casos.

Criando um índice

Backup e restauração

Para fazer backup de um banco, vá em Tools - Backup. Você precisará escolher um formato:

• Custom: formato binário compactado; é a opção mais flexível e a melhor na maioria dos casos, já que permite restaurar tabelas individuais
• Plain: um script SQL simples que você pode abrir e ler em qualquer editor de texto
• Tar: um arquivo não compactado; menos comum, mas útil em alguns fluxos de restauração

Depois de selecionar o formato e o caminho de destino, o pgAdmin executa o pg_dump em segundo plano e salva o arquivo na sua máquina.

Criando um backup

Para restaurar, vá em Tools - Restore, selecione o arquivo de backup e aponte para o banco de destino.

Restaurando a partir de um backup

Se você está se perguntando por que isso é útil, imagine testar uma migração destrutiva no seu banco de desenvolvimento. Faça um backup antes, rode a migração e, se algo quebrar, restaure o backup para voltar a um estado conhecido.

Boas práticas para rodar o pgAdmin 4 no Docker

Colocar o pgAdmin 4 para rodar é uma coisa. Mantê-lo rodando bem exige saber mais algumas coisinhas. Aqui vão algumas dicas práticas.

Mantenha credenciais fora do seu Compose

Se o seu docker-compose.yml for para o controle de versão — e quase sempre é — senhas hardcoded irão junto. Use um arquivo .env para credenciais e adicione-o ao .gitignore. Em produção, vá além e use Docker secrets, que montam valores sensíveis como arquivos, não como variáveis de ambiente.

Nunca exponha a porta do pgAdmin publicamente

Por padrão, o Docker vincula portas a 0.0.0.0, ou seja, qualquer interface de rede — inclusive as públicas. Em um servidor remoto, isso torna sua instância do pgAdmin acessível pela internet. Faça o bind explicitamente em 127.0.0.1:

ports:
  - "127.0.0.1:5050:5050"

Assim, o pgAdmin fica acessível apenas a partir do próprio servidor. Use um túnel SSH ou um reverse proxy se precisar de acesso remoto.

Fixe as tags das imagens

Usar dpage/pgadmin4:latest vai baixar uma versão nova na próxima vez que alguém rodar docker compose pull. Essa versão pode se comportar diferente, quebrar sua configuração ou trazer mudanças inesperadas. Use uma tag específica como dpage/pgadmin4:9.13 para que todo mundo rode exatamente a mesma versão.

Pré-carregue conexões com servers.json

Se todo o time compartilha a mesma configuração do Compose, não faça cada pessoa registrar o servidor PostgreSQL após subir a stack. O pgAdmin suporta um arquivo servers.json que pré-preenche conexões na inicialização. Monte-o no contêiner assim:

volumes:
  - ./servers.json:/pgadmin4/servers.json

Veja um servers.json mínimo:

{
  "Servers": {
    "1": {
      "Name": "local-dev-postgres",
      "Group": "Servers",
      "Host": "postgres",
      "Port": 5432,
      "MaintenanceDB": "mydb",
      "Username": "admin",
      "SSLMode": "prefer"
    }
  }
}

O servidor aparecerá quando o pgAdmin iniciar — sem necessidade de configuração manual.

Conclusão

Neste artigo, mostrei como configurar o pgAdmin 4 no Docker do zero. Você criou um arquivo Docker Compose que sobe PostgreSQL e pgAdmin 4 juntos, conectou os dois contêineres usando o DNS interno do Docker e usou os recursos principais do pgAdmin — o Query Tool, o navegador de esquemas e o fluxo de backup/restauração.

O princípio central aqui é reprodutibilidade. 

Um docker-compose.yml, um servers.json e um .env são tudo o que você precisa para entregar a alguém do time um ambiente de banco totalmente configurado. Assim, o famoso “funciona na minha máquina” deixa de existir.

Para se aprofundar em Docker e conteinerização, confira nosso curso Intermediate Docker. Ele é recheado de dicas úteis sobre builds multi-stage, networking e um mergulho profundo no Compose.