Como Instalar PostgreSQL e pgAdmin 4 no WSL2 (Sem Dor de Cabeça)

Se você desenvolve no Windows, usar o WSL2 (Windows Subsystem for Linux) é uma das melhores formas de manter o sistema limpo, aproveitando a performance e as ferramentas nativas do ecossistema Linux.

No entanto, configurar o PostgreSQL junto com a interface gráfica do pgAdmin 4 dentro do WSL e acessá-lo pelo navegador do Windows pode trazer pequenos obstáculos, desde repositórios não encontrados até serviços que não sobem sozinhos.

Neste tutorial prático, você vai aprender a instalar a stack completa, configurar a conexão e contornar os principais erros do processo.

1. Instalando e Configurando o PostgreSQL no WSL

Abra o terminal da sua distribuição (Ubuntu/Debian) no WSL e siga os passos:

Passo 1: Instalação dos pacotes

sudo apt update && sudo apt install postgresql postgresql-contrib -y

Passo 2: Iniciar o serviço do banco

No WSL, os serviços nem sempre iniciam automaticamente no boot da máquina. Inicie o PostgreSQL manualmente:

sudo service postgresql start

Passo 3: Definir a senha do usuário padrão (postgres)

Por padrão, o usuário postgres não tem uma senha definida para autenticação por senha. Defina uma senha segura:

sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'sua_senha_segura';"

2. Instalando o pgAdmin 4 (Modo Web)

Embora exista o pgAdmin Desktop, a versão pgAdmin 4 Web é muito mais leve e estável no WSL: ela roda acoplada ao Apache local e você acessa a interface diretamente pelo navegador do Windows.

Passo 1: Configurar a chave GPG e o repositório oficial

Muitos erros de instalação acontecem aqui por conta do codinome da distribuição. Para evitar falhas, use a detecção automática com fallback:

# 1. Instalar dependências básicas
sudo apt install curl ca-certificates gnupg lsb-release -y

# 2. Baixar a chave GPG do repositório oficial
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://www.pgadmin.org/static/packages_pgadmin_org.pub | sudo gpg --dearmor --yes -o /etc/apt/keyrings/packages-pgadmin-org.gpg

# 3. Detectar o codinome (ex: jammy, noble, bookworm) e adicionar a fonte
CODENAME=$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
echo "deb [signed-by=/etc/apt/keyrings/packages-pgadmin-org.gpg] https://ftp.postgresql.org/pub/pgadmin/pgadmin4/apt/$CODENAME pgadmin4 main" | sudo tee /etc/apt/sources.list.d/pgadmin4.list

# 4. Atualizar os índices
sudo apt update

Passo 2: Instalar o pacote Web

sudo apt install pgadmin4-web -y

Passo 3: Executar o assistente de configuração

Execute o script de provisionamento:

sudo /usr/pgadmin4/bin/setup-web.sh

• nforme o e-mail e a senha que serão usados para logar no painel.
• Quando o assistente perguntar Restart Apache2? (y/n), digite y.

3. Acessando e Conectando no Navegador

1. No Windows, abra o navegador (Chrome, Edge, Firefox) e acesse:

http://localhost/pgadmin4

Faça login com o e-mail e a senha criados no passo anterior.

No menu lateral esquerdo, clique com o botão direito em Servers > Register > Server….

Configure as abas:

• General: Dê um nome para a conexão (ex: PostgreSQL WSL).
• Connection:
  • Host name/address: 127.0.0.1 (ou localhost)
  • Port: 5432
  • Maintenance database: postgres
  • Username: postgres
  • Password: A senha que você definiu no PostgreSQL.

Clique em Save. Pronto! Suas tabelas, schemas e bancos já estarão visíveis.

4. Problemas Comuns e Como Resolver

❌ Erro 1: Unable to locate package pgadmin4-web

• Causa: O repositório não foi adicionado corretamente ou o codinome retornado pelo lsb_release foi incompatível (ou nulo).
• Solução: Verifique o arquivo gerado com cat /etc/apt/sources.list.d/pgadmin4.list. Se a linha contiver algo como /apt/ pgadmin4 (sem o nome da versão) ou der erro 404 no apt update, edite o arquivo manualmente e substitua pelo codinome LTS correspondente (ex: noble para Ubuntu 24.04 ou jammy para Ubuntu 22.04).

❌ Erro 2: A página http://localhost/pgadmin4 não carrega

• Causa: O Apache não está em execução no WSL ou há conflito de porta com serviços nativos do Windows (como IIS ou Skype).
• Solução:
  1. No WSL, certifique-se de que o serviço está ativo:

sudo service apache2 status
sudo service apache2 start

• Tente acessar usando o IP de loopback explícito: [http://127.0.0.1/pgadmin4](http://127.0.0.1/pgadmin4).

❌ Erro 3: FATAL: password authentication failed for user "postgres"

• Causa: A senha informada no pgAdmin não confere com a gravada na base de dados do PostgreSQL.
• Solução: Redefina a senha diretamente pelo terminal sem precisar da senha antiga:

sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'nova_senha_aqui';"

❌ Erro 4: could not connect to server: Connection refused

• Causa: O serviço do PostgreSQL está pausado no WSL.
• Solução: Suba o serviço:

sudo service postgresql start

Dica Bônus: Inicialização Automática no WSL2

Por padrão, sempre que você fechar o terminal ou reiniciar o Windows, os serviços do WSL param. Se a sua versão do WSL2 suporta systemd (padrão nas versões recentes do Windows 10/11), você pode automatizar a inicialização:

1- Edite o arquivo /etc/wsl.conf:

2- Adicione as seguintes linhas:

Ini, TOML

[boot]
systemd=true

3- Reinicie o WSL pelo PowerShell do Windows com wsl --shutdown.

4- Ao reabrir, habilite os serviços para subirem com o sistema:

sudo systemctl enable postgresql
sudo systemctl enable apache2

Conclusão

Com essa arquitetura, você tem todo o poder do PostgreSQL e a comodidade visual do pgAdmin sem poluir o registro ou os serviços de segundo plano do Windows.

Gostou do tutorial? Deixe suas dúvidas ou sugestões nos comentários!