# PostgreSQL com Docker Compose: customize o arquivo de configuração

> Suba um PostgreSQL com docker-compose e troque configurações, como o shared_buffers, editando o postgresql.conf local e reiniciando o container.

- Autor: Henrylle Maia, consultor AWS
- Publicado em: 2026-10-15
- Assuntos: Containers, Banco de dados
- URL: https://pages.formacaoaws.com.br/blog/postgresql-com-docker-compose/
- Aula de origem: "Como rodar e customizar o Postgresql com docker e docker-compose" (https://www.youtube.com/watch?v=Qzfb3yx2OI4)

Mudar uma configuração do PostgreSQL no Aurora exige parameter group e reinício do banco, e isso atrapalha quem faz teste em sequência. Com Docker Compose, você edita o `postgresql.conf` na sua máquina, derruba o container, sobe de novo e consulta o valor novo. Abaixo eu monto esse ambiente, usando o `shared_buffers` como exemplo.

## Por que rodar o PostgreSQL em container para testar

Numa migração de SQL Server para Babelfish, que roda em cima de PostgreSQL, um cenário se repetiu muito depois de terminar: testes contínuos e rápidos. Fazer isso no Aurora, na AWS, não escalava: cada mudança exigia mexer no parameter group, reiniciar o banco e conectar de novo. Era um processo chato, demorado e oneroso.

A alternativa foi um PostgreSQL com Docker e Docker Compose, com o arquivo de configuração compartilhado por volume com uma pasta local. Assim eu derrubo o container, mudo o arquivo e subo de novo rapidamente. Pesquisei bastante na internet e não achei nada pronto que fizesse isso com Compose, então montei o meu.

## Passo 1: subir o PostgreSQL com docker-compose

Numa pasta vazia, crie o `docker-compose.yml`. O Compose serve para documentar os serviços que você quer lançar em container e reutilizar depois com facilidade. O serviço se chama `database`, e eu uso a versão 10.17 do PostgreSQL, mas você pode usar a que fizer sentido para a sua realidade.

```yaml
version: "3"
services:
  database:
    image: postgres:10.17
    environment:
      - "POSTGRES_USER=postgres"
      - "POSTGRES_PASSWORD=postgres"
      - "POSTGRES_DB=bia"
    ports:
      - 5441:5432
    volumes:
      - pg-data:/var/lib/postgresql/data
volumes:
  pg-data:
```

- `POSTGRES_USER`, `POSTGRES_PASSWORD` e `POSTGRES_DB`: usuário, senha e nome do banco. Usei o mesmo nome de banco dos nossos eventos, o da BIA. No exemplo, usuário e senha são `postgres`.
- `5441:5432`: porta 5441 na minha máquina, 5432 no container.
- `pg-data`: volume nomeado para os dados do banco, para eu não perdê-los quando encerrar o container. No container, ele fica no caminho onde o PostgreSQL guarda os dados.

Suba com `docker compose up`. Quando o log disser que o sistema está pronto para aceitar conexões, o container está de pé.

## Passo 2: conectar e consultar o shared_buffers

Conectei pelo DBeaver: PostgreSQL, host `localhost`, porta `5441`, banco `bia`, usuário e senha `postgres`. Testei a conexão e deu certo.

A configuração que eu precisava mudar era o `shared_buffers`, a área de memória do PostgreSQL onde ficam os blocos lidos nas consultas. Quanto maior, mais memória você dá ao banco e mais informação ele guarda, e isso trabalha em conjunto com os índices. Para ver o valor, abra um console SQL e rode:

```sql
show shared_buffers;
```

Com o container padrão, o resultado foi 128 MB. Era isso que eu queria alterar.

## Passo 3: levar o postgresql.conf para uma pasta local

Pare o container. Crie, na pasta do projeto, uma pasta chamada `postgres_custom` e coloque nela o `postgresql.conf`, o arquivo com todas as configurações do PostgreSQL. Você encontra esse arquivo na internet. Dentro dele, procure o `shared_buffers`, que vem em 128 MB, e troque para 256 MB.

![No postgresql.conf, a linha 114 com shared_buffers = 256MB](https://pages.formacaoaws.com.br/blog/assets/posts/postgresql-com-docker-compose/shared-buffers.webp)

Por enquanto isso é só um arquivo local, sem efeito nenhum. Falta dizer ao Compose para compartilhá-lo com o container.

## Passo 4: compartilhar a pasta com um volume bind

No `docker-compose.yml`, crie um segundo volume, o `pg-config`, com driver local e opções para mapear a pasta:

```yaml
volumes:
  pg-data:
  pg-config:
    driver: local
    driver_opts:
      type: "none"
      o: "bind"
      device: "$PWD/postgres_custom"
```

O `type: "none"` com `o: "bind"` faz o bind da pasta. No `device` eu uso a variável de ambiente `$PWD`, que traz o diretório atual, e assim o projeto funciona em qualquer lugar. Depois, use o volume no serviço, apontando para a pasta de configuração do PostgreSQL no container:

```yaml
    volumes:
      - pg-data:/var/lib/postgresql/data
      - pg-config:/etc/postgresql
```

![Os dois volumes no serviço e a definição do pg-config: driver local, type none, o bind e device apontando para $PWD/postgres_custom](https://pages.formacaoaws.com.br/blog/assets/posts/postgresql-com-docker-compose/volume-bind.webp)

Suba de novo e consulte o `shared_buffers`: continua em 128 MB. O volume está compartilhado, mas o PostgreSQL ainda não usa o arquivo. Para conferir que o arquivo chegou, rode `docker ps`, pegue o ID do container mais recente, entre nele com `docker exec -ti <id> bash` e dê `cat` no `/etc/postgresql/postgresql.conf`. O `shared_buffers = 256MB` está lá, só não está em uso.

## Passo 5: iniciar o PostgreSQL com o seu arquivo de configuração

A imagem do PostgreSQL usa o `docker-entrypoint.sh` para iniciar o banco, e você pode passar configurações para ele com `-c`. Acrescente no serviço o `entrypoint`, dizendo onde está o arquivo:

```yaml
    entrypoint: docker-entrypoint.sh -c 'config_file=/etc/postgresql/postgresql.conf'
```

**Fluxo:** docker-compose.yml (serviço database) → Volume bind (pasta postgres_custom) → postgresql.conf (shared_buffers = 256MB) → Container PostgreSQL (sobe com config_file)

Pare o ambiente com Ctrl+C e suba de novo. Consulte o `shared_buffers`: agora o resultado é 256 MB. Eu subi em primeiro plano para parar só com Ctrl+C, mas daria para subir em modo detached.

## Passo 6: mudar a configuração e repetir

Esse é o ganho. Para o meu teste, eu precisava saber como o `shared_buffers` se comportava e o que acontecia quando ele enchia, então queria um cache pequeno. Basta parar o container, editar o arquivo para 64 MB, por exemplo, subir de novo e consultar. Sem parameter group e sem reiniciar o banco.

A aula é de junho de 2022 e usa o formato de Compose e a imagem 10.17 daquela época. Se for repetir hoje, confira a [referência do arquivo Compose](https://docs.docker.com/reference/compose-file/) e as [tags da imagem oficial do PostgreSQL](https://hub.docker.com/_/postgres).

## Checklist

- Crie o `docker-compose.yml` com o serviço `database`, a imagem do PostgreSQL, usuário, senha, banco e porta.
- Use um volume nomeado para os dados, para não perdê-los ao parar o container.
- Consulte o valor atual com `show shared_buffers;`.
- Coloque o `postgresql.conf` numa pasta do projeto e altere o `shared_buffers`.
- Crie o volume `pg-config` com bind para essa pasta e monte-o em `/etc/postgresql`.
- Confirme com `docker exec` que o arquivo chegou ao container.
- Adicione o `entrypoint` com `-c 'config_file=/etc/postgresql/postgresql.conf'`.
- Suba de novo e confira o novo valor com `show shared_buffers;`.

Com esse ambiente, cada mudança de configuração vira editar um arquivo e subir o container de novo, sem parameter group e sem reiniciar banco gerenciado.