Noções Básicas de Ferramentas

10 exemplos para construir um kit de ferramentas de DBA com versões fixadas em clusters PostgreSQL 18.4 - backup, análise de logs, controle de bloat e ferramentas de consultoria que sua equipe pode reproduzir em laptop, staging e bastion de produção.

Pré-requisitos

Acesso SSH ou kubectl exec a um host que possa alcançar o Postgres (bastion ou pod de depuração).
Binários cliente instalados nas versões documentadas em seu repositório.
Política de acesso somente leitura à produção para juniores; ferramentas de escrita restritas ao plantão.

# tools/versions.env (faça commit deste arquivo)
PG_VERSION=18.4
PGBACKREST_VERSION=2.55.0
PGBADGER_VERSION=12.4
PG_REPACK_VERSION=1.5.2
PSQL_CLIENT=18.4

Escopo: Esta seção cobre ferramentas operacionais, não drivers de aplicação. Veja Noções Básicas de psql para fluxos de trabalho de cliente interativos.

Exemplos Básicos

1. Kit de Ferramentas Mínimo por Função

Função	Ferramenta	Propósito
Backup / PITR	pgBackRest	Backup base físico + arquivo WAL
Descoberta de consulta lenta	pgbadger	Analisa logs CSV de `log_min_duration_statement`
Controle de bloat	pg_repack	Repack de heap/índice online sem `ACCESS EXCLUSIVE` longo
Revisão de plano	`psql` + `EXPLAIN (ANALYZE, BUFFERS)`	Planos de consulta verificados manualmente
Consultoria (opcional)	pganalyze / OtterTune	Sugestões de índice e knobs - verifique manualmente

Uma ferramenta por preocupação; evite agentes de backup sobrepostos no mesmo cluster
RDS/Aurora gerenciado: use APIs de backup nativas; pgBackRest aplica-se a clusters auto-hospedados e algumas imagens de VM

2. Verificar se as Versões do Cliente Correspondem ao Servidor

psql "$DATABASE_URL" -c "SHOW server_version;"
psql --version
pgbackrest version
pgbadger --version

-- Em psql
SELECT version();
SHOW server_version_num;  -- 180004 para 18.4

A versão principal do cliente deve corresponder à versão principal do servidor para compatibilidade pg_dump/pg_restore
Desvio menor (cliente 18.3, servidor 18.4) geralmente é aceitável para consultas psql

3. Padrão de Instalação em Bastion Linux

#!/usr/bin/env bash
set -euo pipefail
source tools/versions.env
 
# Exemplo: pgBackRest de pacote ou versão de origem fixada
sudo apt-get install -y "pgbackrest=${PGBACKREST_VERSION}*"
 
# pgbadger (Perl)
sudo apt-get install -y pgbadger
 
# Extensão pg_repack + CLI (o cluster deve executar CREATE EXTENSION)
sudo apt-get install -y "postgresql-${PG_VERSION%%.*}-repack"

Documente os comandos de instalação em docs/runbooks/tooling.md
Imagens de contêiner: incorpore versões no Dockerfile; nunca use apt install sem fixar em hosts de produção

4. Matriz de Acesso a Ferramentas

| Ferramenta      | Laptop Dev | Bastion Staging | Bastion Prod | CI |
|-----------------|------------|-----------------|--------------|----|
| psql            | sim        | sim             | somente leitura | job de migração |
| pgBackRest      | não        | sim (simulação de restauração) | somente plantão | verificação de backup |
| pgbadger        | sim (logs de amostra) | sim      | sim (ler logs) | não |
| pg_repack       | apenas local | sim (janela de alteração) | plantão + ticket | não |

Ferramentas de escrita em produção exigem ticket de alteração e pareamento para operadores de primeira viagem
CI executa lint de migração e pgbackrest check contra um sandbox de restauração, não produção

5. Envio de Logs para pgbadger

-- postgresql.conf (staging/prod)
ALTER SYSTEM SET log_destination = 'csvlog';
ALTER SYSTEM SET logging_collector = on;
ALTER SYSTEM SET log_min_duration_statement = '500ms';
ALTER SYSTEM SET log_line_prefix = '%m [%p] %u@%d ';
SELECT pg_reload_conf();

# Relatório noturno no bastion
pgbadger /var/log/postgresql/postgresql-*.csv \
  -o /var/reports/pgbadger/$(date +%F) \
  --incremental

pgbadger precisa do formato de log CSV ou padrão com linhas de duração
Envie relatórios para armazenamento de objetos; vincule consultas lentas a tickets

Relacionado: pgbadger

6. Limite da Ferramenta de Backup

# Auto-hospedado: stanza do pgBackRest
pgbackrest --stanza=main info
pgbackrest --stanza=main check

# RDS: use aws rds describe-db-snapshots (não pgBackRest)
aws rds describe-db-snapshots --db-instance-identifier myapp-prod

Escolha um sistema de backup físico por cluster
O nome da stanza do pgBackRest corresponde à função Patroni pg1 em topologias HA

Relacionado: pgBackRest, Noções Básicas de PITR

7. Ferramentas de Extensão Requerem Aprovação do DBA

-- pg_repack requer a extensão em cada banco de dados
CREATE EXTENSION IF NOT EXISTS pg_repack;

CREATE EXTENSION é um evento de governança - rastreie em um ADR de lista de permissões de extensões
A versão do pg_repack deve corresponder à versão principal do servidor (extensão 18.x para PG 18)

Exemplos Intermediários

8. Layout do Diretório Monorepo tools/

tools/
├── versions.env
├── bin/
│   ├── pg-health.sh
│   ├── run-pgbadger.sh
│   └── verify-backup.sh
└── README.md

#!/usr/bin/env bash
# tools/bin/pg-health.sh
set -euo pipefail
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -c "
SELECT datname, numbackends, xact_commit, blks_hit::float / NULLIF(blks_hit + blks_read, 0) AS cache_hit
FROM pg_stat_database
WHERE datname = current_database();"

Scripts usam set -euo pipefail e ON_ERROR_STOP=1
O mesmo script é executado localmente contra o Docker Postgres e em testes de fumaça de staging

9. Checklist de Auditoria Trimestral de Ferramentas

- [ ] versions.env corresponde a server_version de produção
- [ ] pgbackrest check retorna 0 em todas as stanzas
- [ ] Relatório pgbadger gerado nos últimos 7 dias
- [ ] Extensão pg_repack presente apenas onde aprovado
- [ ] Nenhum cron de backup duplicado (pg_basebackup E pgBackRest)
- [ ] Pacotes do bastion correspondem a versions.env

Anexe os resultados da auditoria ao ticket de governança
Atualize as ferramentas após a janela de validação de atualização menor do Postgres

10. Quando Não Adicionar uma Ferramenta

Situação	Pular nova ferramenta	Usar em vez disso
Neon/Supabase hobby gerenciado	pgBackRest	UI PITR do provedor
Banco de dados de desenvolvimento pequeno e único	assinatura pganalyze	`EXPLAIN` em CI
Tabela com bloat menor que 100 MB	pg_repack	`VACUUM (FULL)` na janela de manutenção

FAQs

Os desenvolvedores de aplicativos precisam ter o pgBackRest instalado?

Não. Desenvolvedores precisam de psql, executor de migração e hábitos de EXPLAIN. Ferramentas de backup ficam no bastion e em jobs de restauração de CI.

O pgbadger pode substituir o pg_stat_statements?

Não. pg_stat_statements fornece agregações ao vivo; pgbadger analisa arquivos de log históricos. Use ambos.

Com que frequência repinar as versões das ferramentas?

Após cada atualização menor do Postgres e ciclo trimestral de patches de segurança. Atualize tools/versions.env no mesmo PR das alterações do runbook.

Relacionados

pgBackRest - backup físico e PITR
pgbadger - relatórios de logs de consultas lentas
pg_repack - recuperação de bloat online
Melhores Práticas de Ferramentas Essenciais - resumo de 25 itens para a equipe
Noções Básicas de Extensões - política de instalação de extensões

Versões da Stack: Esta página foi escrita para PostgreSQL 18.4, pgBackRest 2.55+, pgBadger 12+, pg_repack 1.5+, e cliente psql 18.4.

Noções Básicas de Ferramentas

Pré-requisitos

Acesso SSH ou kubectl exec a um host que possa alcançar o Postgres (bastion ou pod de depuração).
Binários cliente instalados nas versões documentadas em seu repositório.
Política de acesso somente leitura à produção para juniores; ferramentas de escrita restritas ao plantão.

# tools/versions.env (faça commit deste arquivo)
PG_VERSION=18.4
PGBACKREST_VERSION=2.55.0
PGBADGER_VERSION=12.4
PG_REPACK_VERSION=1.5.2
PSQL_CLIENT=18.4

Escopo: Esta seção cobre ferramentas operacionais, não drivers de aplicação. Veja Noções Básicas de psql para fluxos de trabalho de cliente interativos.

Exemplos Básicos

1. Kit de Ferramentas Mínimo por Função

Função	Ferramenta	Propósito
Backup / PITR	pgBackRest	Backup base físico + arquivo WAL
Descoberta de consulta lenta	pgbadger	Analisa logs CSV de `log_min_duration_statement`
Controle de bloat	pg_repack	Repack de heap/índice online sem `ACCESS EXCLUSIVE` longo
Revisão de plano	`psql` + `EXPLAIN (ANALYZE, BUFFERS)`	Planos de consulta verificados manualmente
Consultoria (opcional)	pganalyze / OtterTune	Sugestões de índice e knobs - verifique manualmente

Uma ferramenta por preocupação; evite agentes de backup sobrepostos no mesmo cluster
RDS/Aurora gerenciado: use APIs de backup nativas; pgBackRest aplica-se a clusters auto-hospedados e algumas imagens de VM

2. Verificar se as Versões do Cliente Correspondem ao Servidor

psql "$DATABASE_URL" -c "SHOW server_version;"
psql --version
pgbackrest version
pgbadger --version

-- Em psql
SELECT version();
SHOW server_version_num;  -- 180004 para 18.4

A versão principal do cliente deve corresponder à versão principal do servidor para compatibilidade pg_dump/pg_restore
Desvio menor (cliente 18.3, servidor 18.4) geralmente é aceitável para consultas psql

3. Padrão de Instalação em Bastion Linux

#!/usr/bin/env bash
set -euo pipefail
source tools/versions.env
 
# Exemplo: pgBackRest de pacote ou versão de origem fixada
sudo apt-get install -y "pgbackrest=${PGBACKREST_VERSION}*"
 
# pgbadger (Perl)
sudo apt-get install -y pgbadger
 
# Extensão pg_repack + CLI (o cluster deve executar CREATE EXTENSION)
sudo apt-get install -y "postgresql-${PG_VERSION%%.*}-repack"

Documente os comandos de instalação em docs/runbooks/tooling.md
Imagens de contêiner: incorpore versões no Dockerfile; nunca use apt install sem fixar em hosts de produção

4. Matriz de Acesso a Ferramentas

| Ferramenta      | Laptop Dev | Bastion Staging | Bastion Prod | CI |
|-----------------|------------|-----------------|--------------|----|
| psql            | sim        | sim             | somente leitura | job de migração |
| pgBackRest      | não        | sim (simulação de restauração) | somente plantão | verificação de backup |
| pgbadger        | sim (logs de amostra) | sim      | sim (ler logs) | não |
| pg_repack       | apenas local | sim (janela de alteração) | plantão + ticket | não |

Ferramentas de escrita em produção exigem ticket de alteração e pareamento para operadores de primeira viagem
CI executa lint de migração e pgbackrest check contra um sandbox de restauração, não produção

5. Envio de Logs para pgbadger

-- postgresql.conf (staging/prod)
ALTER SYSTEM SET log_destination = 'csvlog';
ALTER SYSTEM SET logging_collector = on;
ALTER SYSTEM SET log_min_duration_statement = '500ms';
ALTER SYSTEM SET log_line_prefix = '%m [%p] %u@%d ';
SELECT pg_reload_conf();

# Relatório noturno no bastion
pgbadger /var/log/postgresql/postgresql-*.csv \
  -o /var/reports/pgbadger/$(date +%F) \
  --incremental

pgbadger precisa do formato de log CSV ou padrão com linhas de duração
Envie relatórios para armazenamento de objetos; vincule consultas lentas a tickets

Relacionado: pgbadger

6. Limite da Ferramenta de Backup

# Auto-hospedado: stanza do pgBackRest
pgbackrest --stanza=main info
pgbackrest --stanza=main check

# RDS: use aws rds describe-db-snapshots (não pgBackRest)
aws rds describe-db-snapshots --db-instance-identifier myapp-prod

Escolha um sistema de backup físico por cluster
O nome da stanza do pgBackRest corresponde à função Patroni pg1 em topologias HA

Relacionado: pgBackRest, Noções Básicas de PITR

7. Ferramentas de Extensão Requerem Aprovação do DBA

-- pg_repack requer a extensão em cada banco de dados
CREATE EXTENSION IF NOT EXISTS pg_repack;

CREATE EXTENSION é um evento de governança - rastreie em um ADR de lista de permissões de extensões
A versão do pg_repack deve corresponder à versão principal do servidor (extensão 18.x para PG 18)

Exemplos Intermediários

8. Layout do Diretório Monorepo tools/

tools/
├── versions.env
├── bin/
│   ├── pg-health.sh
│   ├── run-pgbadger.sh
│   └── verify-backup.sh
└── README.md

#!/usr/bin/env bash
# tools/bin/pg-health.sh
set -euo pipefail
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -c "
SELECT datname, numbackends, xact_commit, blks_hit::float / NULLIF(blks_hit + blks_read, 0) AS cache_hit
FROM pg_stat_database
WHERE datname = current_database();"

Scripts usam set -euo pipefail e ON_ERROR_STOP=1
O mesmo script é executado localmente contra o Docker Postgres e em testes de fumaça de staging

9. Checklist de Auditoria Trimestral de Ferramentas

- [ ] versions.env corresponde a server_version de produção
- [ ] pgbackrest check retorna 0 em todas as stanzas
- [ ] Relatório pgbadger gerado nos últimos 7 dias
- [ ] Extensão pg_repack presente apenas onde aprovado
- [ ] Nenhum cron de backup duplicado (pg_basebackup E pgBackRest)
- [ ] Pacotes do bastion correspondem a versions.env

Anexe os resultados da auditoria ao ticket de governança
Atualize as ferramentas após a janela de validação de atualização menor do Postgres

10. Quando Não Adicionar uma Ferramenta

Situação	Pular nova ferramenta	Usar em vez disso
Neon/Supabase hobby gerenciado	pgBackRest	UI PITR do provedor
Banco de dados de desenvolvimento pequeno e único	assinatura pganalyze	`EXPLAIN` em CI
Tabela com bloat menor que 100 MB	pg_repack	`VACUUM (FULL)` na janela de manutenção

FAQs

Os desenvolvedores de aplicativos precisam ter o pgBackRest instalado?

Não. Desenvolvedores precisam de psql, executor de migração e hábitos de EXPLAIN. Ferramentas de backup ficam no bastion e em jobs de restauração de CI.

O pgbadger pode substituir o pg_stat_statements?

Não. pg_stat_statements fornece agregações ao vivo; pgbadger analisa arquivos de log históricos. Use ambos.

Com que frequência repinar as versões das ferramentas?

Após cada atualização menor do Postgres e ciclo trimestral de patches de segurança. Atualize tools/versions.env no mesmo PR das alterações do runbook.

Relacionados

pgBackRest - backup físico e PITR
pgbadger - relatórios de logs de consultas lentas
pg_repack - recuperação de bloat online
Melhores Práticas de Ferramentas Essenciais - resumo de 25 itens para a equipe
Noções Básicas de Extensões - política de instalação de extensões

Versões da Stack: Esta página foi escrita para PostgreSQL 18.4, pgBackRest 2.55+, pgBadger 12+, pg_repack 1.5+, e cliente psql 18.4.

Noções Básicas de Ferramentas

Buscar na documentação

Noções Básicas de Ferramentas