Tu já passou pela situação de instalar PHP, Postgres e um gerenciador de banco direto na máquina e, três projetos depois, nada mais bate com nada? Pois é. Neste artigo tu sai com um ambiente completo rodando em um único docker compose up: PHP 8.3 com Apache, PostgreSQL 16 e pgAdmin, tudo conversando entre si e com o banco persistindo os dados. É pra quem programa em PHP e quer parar de sofrer com versão de banco e extensão faltando.
O que a gente vai montar
Três containers, uma rede interna e um volume:
- app: PHP 8.3 + Apache, com a extensão
pdo_pgsqlinstalada. - db: PostgreSQL 16, com healthcheck pra app só subir quando o banco estiver pronto.
- pgadmin: interface web pra tu enxergar e mexer no banco.
- volume
pgdata: pra não perder os dados quando derrubar o container.
Se tu ainda não tem o Docker instalado, dá uma olhada no meu texto O que é Docker? e depois volta aqui. Pra quem usa Linux, tem também o ambiente de desenvolvimento PHP no Linux.
1. Estrutura de pastas
Cria uma pasta pro projeto e deixa assim:
meu-projeto/
├── docker-compose.yml
├── Dockerfile
├── .env
├── .gitignore
└── src/
└── index.php
2. Dockerfile do PHP com Apache
A imagem oficial php:8.3-apache não vem com driver do Postgres. Sem ele, tu toma o famoso could not find driver na primeira conexão. Então a gente instala:
FROM php:8.3-apache
RUN apt-get update \
&& apt-get install -y --no-install-recommends libpq-dev \
&& docker-php-ext-install pdo pdo_pgsql \
&& a2enmod rewrite \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /var/www/html
O a2enmod rewrite já deixa o mod_rewrite ligado, porque cedo ou tarde tu vai querer URL amigável ou um framework.
3. Variáveis de ambiente (.env)
Nada de senha escrita direto no docker-compose.yml. Cria o arquivo .env:
POSTGRES_DB=app_db
POSTGRES_USER=app_user
POSTGRES_PASSWORD=troque_essa_senha
[email protected]
PGADMIN_DEFAULT_PASSWORD=troque_essa_tambem
E no .gitignore, bota:
.env
Por fora, se tu quiser compartilhar o projeto, cria um .env.example com valores de mentirinha e sobe esse no Git.
4. docker-compose.yml
Agora a parte principal:
services:
app:
build: .
container_name: php_app
ports:
- "8080:80"
volumes:
- ./src:/var/www/html
env_file:
- .env
environment:
DB_HOST: db
DB_PORT: 5432
depends_on:
db:
condition: service_healthy
db:
image: postgres:16-alpine
container_name: pg_db
restart: unless-stopped
env_file:
- .env
ports:
- "127.0.0.1:5432:5432"
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 5s
timeout: 5s
retries: 10
pgadmin:
image: dpage/pgadmin4:8.14
container_name: pg_admin
restart: unless-stopped
env_file:
- .env
ports:
- "127.0.0.1:5050:80"
volumes:
- pgadmin_data:/var/lib/pgadmin
depends_on:
- db
volumes:
pgdata:
pgadmin_data:
Pontos que merecem atenção:
depends_oncomservice_healthy: sem isso, o PHP sobe antes do Postgres terminar de inicializar e a primeira requisição quebra.$${...}no healthcheck: o$$escapa o cifrão pro Compose não tentar substituir a variável ele mesmo.127.0.0.1:5432:5432: expõe o banco só pra tua máquina. Se tu deixar só5432:5432, o banco fica aberto pra rede toda. Em notebook em rede de café, isso é pedir problema.- Versão da imagem fixa:
postgres:16-alpineepgadmin4:8.14em vez delatest. Assim o ambiente de hoje é o mesmo do mês que vem. - Dois volumes: um pros dados do Postgres e outro pras configurações do pgAdmin, pra tu não precisar cadastrar o servidor toda vez.
5. Testando a conexão com PDO
Cria o src/index.php:
<?php
declare(strict_types=1);
$host = getenv('DB_HOST') ?: 'db';
$port = getenv('DB_PORT') ?: '5432';
$name = getenv('POSTGRES_DB');
$user = getenv('POSTGRES_USER');
$pass = getenv('POSTGRES_PASSWORD');
$dsn = "pgsql:host={$host};port={$port};dbname={$name}";
try {
$pdo = new PDO($dsn, $user, $pass, [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);
$versao = $pdo->query('SELECT version()')->fetchColumn();
echo '<h1>Conectou, bichinho!</h1>';
echo '<p>PHP ' . htmlspecialchars(PHP_VERSION, ENT_QUOTES, 'UTF-8') . '</p>';
echo '<p>' . htmlspecialchars((string) $versao, ENT_QUOTES, 'UTF-8') . '</p>';
} catch (PDOException $e) {
http_response_code(500);
echo 'Falha na conexão. Veja os logs do container.';
error_log($e->getMessage());
}
Repara que a mensagem de erro do banco vai pro log e não pra tela. Mostrar $e->getMessage() pro usuário vaza host, usuário e às vezes mais coisa. Se tu quer entender melhor o PDO, tem o O que é PDO em PHP? aqui no blog.
6. Subindo tudo
docker compose up -d --build
docker compose ps
Quando os três aparecerem como running (e o db como healthy), abre:
- App:
http://localhost:8080 - pgAdmin:
http://localhost:5050
Se aparecer a versão do PHP e do PostgreSQL na tela, está tudo certo.
7. Conectando o pgAdmin no banco
Entra no pgAdmin com o e-mail e a senha do .env, clica em Add New Server e preenche:
- Name: o que tu quiser (ex.:
Local) - Aba Connection:
- Host name/address:
db - Port:
5432 - Maintenance database: o valor de
POSTGRES_DB - Username e Password: os do
.env
- Host name/address:
O erro clássico aqui é botar localhost no host. Dentro do container do pgAdmin, localhost é ele mesmo, e não o teu computador nem o Postgres. O nome certo é o nome do serviço no Compose: db.
8. Meu perrengue (e o que eu aprendi)
Troca este bloco pela tua experiência real: versão que tu usou, o erro que deu e o print. Abaixo vai a base que eu sugiro, edita no teu jeito.
Na primeira vez que montei esse ambiente, bati em três coisas:
could not find driver: esqueci de instalar opdo_pgsqlno Dockerfile. Só com a imagem pura do PHP não funciona.- pgAdmin não subia com o e-mail
[email protected]: as versões mais novas rejeitam domínio.localno e-mail padrão. Usar um domínio com cara de real (comoexemplo.com) resolveu. - Mudei a senha no
.enve o banco continuou com a antiga: o Postgres só lê essas variáveis na primeira inicialização do volume. Pra recriar do zero em ambiente de desenvolvimento:
docker compose down -v
docker compose up -d --build
Cuidado: o -v apaga os volumes, ou seja, apaga os dados. Só usa isso em dev.
9. Comandos que tu vai usar todo dia
# ver logs de um serviço
docker compose logs -f db
# abrir o psql dentro do container
docker compose exec db psql -U app_user -d app_db
# entrar no container do PHP
docker compose exec app bash
# parar tudo sem apagar dados
docker compose down
10. Boas práticas antes de levar pra produção
Esse setup é pra desenvolvimento. Pra produção, muda pelo menos:
- Não expor a porta do Postgres nem do pgAdmin pra internet.
- Senhas fortes e guardadas em um gerenciador de segredos, não em arquivo solto.
- Criar um usuário de aplicação com permissão mínima, em vez de usar o dono do banco pra tudo.
- Backup automático do volume (
pg_dumpagendado, por exemplo). - Remover o pgAdmin da stack ou colocar atrás de autenticação forte.
Próximos passos
Com o ambiente de pé, tu já pode treinar de verdade. Dois caminhos que combinam com esse setup:
- Ver o Sistema de Login com PHP e MySQL (PDO) e adaptar pro PostgreSQL.
- Aprender a criar e otimizar índices no PostgreSQL e a identificar consultas lentas com EXPLAIN ANALYZE.
Se tu fez, deu certo ou deu ruim em algum ponto, deixa nos comentários que eu respondo.