pgbuild — Ambiente para compilar e estudar PostgreSQL (15.2)

Resumo

Ambiente Docker baseado em Debian para:

• Compilar o PostgreSQL 15.2 a partir do código‑fonte.
• Inicializar o cluster de dados em /db/data.
• Subir o servidor automaticamente.
• Instalar e habilitar a extensão pg_buffercache.
• Usar um shell confortável com zsh, Oh My Zsh e powerlevel10k.

Arquitetura:

• Código‑fonte do PostgreSQL: /usr/local/src/postgres-15 (clonado na imagem).
• Binários instalados do PostgreSQL: /usr/local/pgsql.
• Dados (cluster): /db/data (volume nomeado pgdata).
• Workspace do curso: /workspace (bind mount ./).
• Dotfiles do shell: bind mount ./dotfiles → /workspace/dotfiles.

Persistência

Volumes / mounts principais (ver docker-compose.yml):

• ./:/workspace
  • Código do curso, scripts, logs etc.
  • Logs importantes vão para ./logs:
    • pg_configure.log, pg_make.log, pg_make_check.log, pg_make_install.log
    • pg_buffercache_make.log, pg_buffercache_make_install.log
    • pg_initdb.log
    • pg_buffercache_create_extension.log
• pgdata:/db/data
  • Cluster de dados inicializado com initdb -D /db/data.
• ./dotfiles:/workspace/dotfiles
  • Configurações de zsh/Oh My Zsh/p10k, tanto para aluno quanto para root.

Os scripts do container são montados via bind para facilitar ajustes sem rebuild:

• ./scripts/entrypoint.sh:/usr/local/bin/entrypoint.sh:ro
• ./scripts/build-postgres.sh:/usr/local/bin/build-postgres.sh:ro

Usuários e diretórios

• root
  • PID 1 / dono da maior parte do sistema.
• postgres
  • Dono do diretório de dados /db/data.
  • Roda o servidor PostgreSQL e initdb.
  • .bashrc configurado com:
    • PATH=$PATH:/usr/local/pgsql/bin:$HOME/bin
    • PGDATA=/db/data
• aluno
  • Usuário interativo para o curso.
  • Tem acesso ao /workspace e ao código‑fonte do PostgreSQL.

Diretórios principais:

• /usr/local/src/postgres-15 — código‑fonte do PostgreSQL 15.2 (git clone).
• /usr/local/pgsql — instalação dos binários (make install).
• /db/data — cluster de dados.
• /workspace — diretório de trabalho (pasta do projeto).
• /workspace/logs — logs do build e initdb.
• /workspace/dotfiles — dotfiles persistentes de zsh.

Fluxo de inicialização (entrypoint)

O ENTRYPOINT é scripts/entrypoint.sh e faz:

1. Dotfiles (zsh)

   • Copia defaults de /usr/local/share/dotfiles-defaults para ./dotfiles na primeira execução.
   • Cria symlinks na home de aluno e root apontando para /workspace/dotfiles.

2. Build automático do PostgreSQL (se necessário)

   • Se /usr/local/pgsql/bin/postgres não existir, chama:
     • /usr/local/bin/build-postgres.sh
   • O script de build:
     • Roda como root, mas chama su - aluno para:
       • ./configure --prefix=/usr/local/pgsql
       • make
       • make check
     • Roda como root:
       • make install
       • make e make install em contrib/pg_buffercache
     • Registra logs em:
       • logs/pg_configure.log
       • logs/pg_make.log
       • logs/pg_make_check.log
       • logs/pg_make_install.log
       • logs/pg_buffercache_make.log
       • logs/pg_buffercache_make_install.log

3. Inicialização do cluster (initdb)

   • Diretório de dados: /db/data.
   • Se não existir PG_VERSION em /db/data:
     • Executa como postgres:
       • initdb -D /db/data
     • Log em logs/pg_initdb.log.

4. Start do servidor

   • Ajusta PATH e LD_LIBRARY_PATH.
   • Executa como postgres:
     • pg_ctl -w -D /db/data -l /db/data/logfile start
   • Log do servidor em /db/data/logfile.

5. Criação automática da extensão pg_buffercache

   • Após o servidor estar online, executa como postgres:
     • psql -d postgres -c 'CREATE EXTENSION IF NOT EXISTS pg_buffercache;'
   • Força PATH=/usr/local/pgsql/bin:$PATH no comando.
   • Log em logs/pg_buffercache_create_extension.log.

6. Shell interativo

   • No final, troca para o usuário aluno:
     • exec su - aluno -c "/usr/bin/zsh -l"

Comandos úteis

Subir o ambiente

• Build da imagem e start:

  docker compose up -d --build

• Start sem rebuild:

  docker compose up -d

Parar/remover

• Parar containers (preserva volume pgdata):

  docker compose down

• Parar containers + remover volumes nomeados (inclui dados do cluster):

  docker compose down -v

Acessar o container

• Entrar como aluno (zsh):

  docker compose exec pg-build zsh -l

• Entrar como postgres:

  docker compose exec pg-build bash -lc 'su - postgres'

Logs

• Logs do container:

  docker compose logs -f pg-build

• Logs de build/init/extensão no host:

  ls -l logs
  sed -n '1,40p' logs/pg_configure.log
  sed -n '1,40p' logs/pg_make_check.log
  sed -n '1,40p' logs/pg_initdb.log
  sed -n '1,40p' logs/pg_buffercache_create_extension.log

Debug do entrypoint / build

• Rodar entrypoint manualmente (em um container já em execução):

  docker compose exec pg-build /usr/local/bin/entrypoint.sh /usr/bin/true

• Rodar build manualmente:

  docker compose exec pg-build bash -lc '/usr/local/bin/build-postgres.sh'

Dotfiles (zsh / powerlevel10k)

• Na primeira execução, o entrypoint copia as configs padrão de zsh/p10k para ./dotfiles.
• São criados symlinks nas homes:
  • ~aluno/.zshrc → /workspace/dotfiles/...
  • ~root/.zshrc → /workspace/dotfiles/...
• Qualquer alteração do shell (por exemplo, p10k configure) é salva em ./dotfiles, persistindo entre recriações do container.

Pré‑requisitos

• Docker e Docker Compose v2.
• No host, configurar o terminal com uma Nerd Font (por exemplo, MesloLGS NF) para ver os ícones do powerlevel10k.

Arquivos importantes

• Dockerfile — imagem base, usuários, dependências, clone do PostgreSQL, zsh etc.
• docker-compose.yml — definição do serviço, volumes, networks, binds de scripts.
• scripts/entrypoint.sh — lógica de:
  • dotfiles,
  • build automático,
  • initdb,
  • start do servidor,
  • criação da extensão pg_buffercache,
  • troca para o usuário aluno.
• scripts/build-postgres.sh — build e instalação do PostgreSQL + pg_buffercache.
• logs/*.log — todos os logs relevantes do build, initdb e extensão.
• .env — configura PROJECT_NAME, IMAGE_TAG e timezone (TZ).

Observações

• Fontes instaladas dentro do container não mudam a fonte do terminal host.
  Configure a fonte do seu terminal (host) para MesloLGS NF ou outra Nerd Font.
• Os binários compilados são específicos da arquitetura/ABI da imagem base (Debian bookworm x86_64).
• Como entrypoint.sh e build-postgres.sh são bind mounts, alterações nesses scripts não exigem rebuild da imagem — basta docker compose restart pg-build.