pgb2 é uma ferramenta de linha de comando (CLI) escrita em Go que facilita o backup de seus bancos de dados PostgreSQL e o upload seguro para um armazenamento compatível com S3, como Backblaze B2 ou DigitalOcean Spaces.

Para construir e executar o pgb2, você precisará:

• Go: Versão 1.25.5 ou superior.
• Ferramentas Cliente PostgreSQL: pg_dump deve estar instalado e acessível no PATH do seu sistema, pois pgb2 o utiliza para gerar os dumps do banco de dados.

pgb2 utiliza o AWS SDK para Go, que procura credenciais na seguinte ordem:

1. Variáveis de ambiente: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION.
2. Arquivo de credenciais ~/.aws/credentials.
3. Perfis de instância IAM (para execução em instâncias EC2).

Para a maioria dos casos de uso, definir as variáveis de ambiente é o método mais simples:

export AWS_ACCESS_KEY_ID="SEU_ACCESS_KEY_ID"
export AWS_SECRET_ACCESS_KEY="SEU_SECRET_ACCESS_KEY"
export AWS_REGION="SUA_REGIÃO_S3" # Ex: us-east-1

pgb2 gera um dump comprimido do seu banco de dados PostgreSQL e o envia para o bucket S3 especificado.

Use pgb2 --help para ver todas as opções.

• -H, --host: Host do banco de dados PostgreSQL (padrão: localhost).
• -p, --port: Porta do banco de dados PostgreSQL (padrão: 5432).
• -U, --user: Nome de usuário do PostgreSQL (padrão: postgres).
• -P, --password: Senha do PostgreSQL. Recomendado usar a variável de ambiente PGPASSWORD para segurança.
• -D, --database: Nome do banco de dados PostgreSQL para backup. Obrigatório.
• -b, --bucket: Nome do bucket S3 de destino. Obrigatório.
• -r, --region: Região S3 (ex: us-east-1). Obrigatório.
• --endpoint-url: URL de endpoint customizada para armazenamento compatível com S3 (ex: Backblaze, MinIO). Obrigatório para serviços não-AWS.
• --dump-command: Comando customizado para o dump (padrão: pg_dump). Permite usar wrappers como docker exec.

Nota: Usar --dump-command permite flexibilidade para ambientes onde o pg_dump não está diretamente no PATH ou precisa ser executado via containers. Porém, certifique-se de que o comando fornecido aceite os mesmos argumentos de linha de comando que o pg_dump padrão espera.

Importante: --dump-command irá executar o comando fornecido e anexará automaticamente os parâmetros de conexão (--host, --port, --username, etc.) ao final dele. Existe o risco de injeção de comandos se o valor passado para --dump-command não for devidamente validado ou se vier de uma fonte não confiável. Use com cautela, isso pode comprometer a segurança do seu sistema e causar danos irreparáveis ao sistema e segurança. Como recomendação, remova esse parametro do código-fonte ou binário se você não tiver controle total sobre quem pode executar a ferramenta e faça a compilação do binário por conta própria.

# Usando variáveis de ambiente para AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION e PGPASSWORD
./pgb2 --database minha_aplicacao_db --bucket meu-bucket-s3 --region us-east-1

# Especificando host e usuário, com senha via variável de ambiente
PGPASSWORD="minha_senha_secreta" ./pgb2 -H meu.host.db -p 5433 -U admin_db -D producao_db -b backups-diarios -r sa-east-1

Se o seu PostgreSQL roda dentro de um container Docker, você pode usar a flag --dump-command para executar o pg_dump de dentro do container.

# Neste exemplo, o 'host' pode ser o nome do serviço/container, e a senha é gerenciada pelo Docker
PGPASSWORD="sua_senha_secreta_aqui" ./pgb2 \
  --host localhost \
  --port 5432 \
  --database meu_db_docker \
  --bucket meu-bucket-s3 \
  --region us-east-1 \
  --dump-command "docker exec meu_container_postgres pg_dump"

Nota: Caso necessário utilizar o pg_dump do container, é necessário exportar a saída do dump para o stdout do host, por exemplo: --dump-command "docker exec meu_container_postgres pg_dump -U postgres meu_db"

Para usar o Backblaze B2, você deve usar a flag --endpoint-url com o "S3 Endpoint" do seu bucket.

# Exemplo para Backblaze B2 (substitua pelos seus dados)
export AWS_ACCESS_KEY_ID="SEU_B2_KEY_ID"
export AWS_SECRET_ACCESS_KEY="SEU_B2_APPLICATION_KEY"
export PGPASSWORD="minha_senha_do_db"

# Supondo que seu endpoint B2 seja 's3.us-west-001.backblazeb2.com'
./pgb2 \
  --database meu_db \
  --bucket meu-bucket-b2 \
  --region us-west-001 \
  --endpoint-url https://s3.us-east-005.backblazeb2.com

A mesma lógica se aplica ao DigitalOcean Spaces. Use a flag --endpoint-url com a URL do endpoint do seu Space.

# Exemplo para DigitalOcean Spaces (substitua pelos seus dados)
export AWS_ACCESS_KEY_ID="SEU_DO_SPACE_KEY"
export AWS_SECRET_ACCESS_KEY="SEU_DO_SPACE_SECRET"
export PGPASSWORD="minha_senha_do_db"

# Supondo que seu endpoint do Space seja 'nyc3.digitaloceanspaces.com'
./pgb2 \
  --database outro_db \
  --bucket meu-space-name \
  --region nyc3 \
  --endpoint-url https://nyc3.digitaloceanspaces.com

Para construir e testar o projeto:

• Build:

  cd pgb2 # Navegue até a raiz do projeto pgb2
  go build -o build/pgb2 .

  Ou compile direto para Linux com make build.

  Isso criará um executável pgb2 no diretório raiz do projeto.

• Testes:

  cd pgb2 # Navegue até a raiz do projeto pgb2
  go test ./...

  Ou execute com make test.

  Executa todos os testes unitários e de integração (se configurados).

• Lint:

  # Instale golangci-lint se ainda não tiver:
  # go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
  
  cd pgb2 # Navegue até a raiz do projeto pgb2
  golangci-lint run ./...
  go vet ./...

  Ou execute com make lint.

  Verifica o código quanto a erros e adere a padrões de estilo.

Agradecemos o seu interesse em contribuir! Siga estas diretrizes:

• Faça um fork do repositório.
• Crie uma branch para sua funcionalidade (git checkout -b feature/minha-funcionalidade).
• Certifique-se de que seu código adere aos padrões de estilo Go (use go fmt).
• Escreva testes unitários e de integração (se aplicável) para suas alterações.
• Certifique-se de que todos os testes passem (go test ./...).
• Crie um Pull Request detalhado.

pgb2/
│
├── cmd/                # Definições de comandos Cobra CLI
│   └── root.go         # Comando raiz principal
│
├── internal/
│   ├── backup/         # Lógica principal de orquestração de backup
│   ├── compress/       # Lógica para compressão de arquivos (Gzip)
│   ├── dump/           # Funções para gerar dumps PostgreSQL (pg_dump)
│   ├── storage/        # Funções para interagir com armazenamento (S3, compatíveis)
│   ├── logutil/        # Utilitários de logging
│   └── testutil/       # Mocks e helpers para testes
│
├── main.go             # Ponto de entrada principal da aplicação
├── go.mod              # Definições do módulo Go
├── go.sum              # Checksums para as dependências do módulo Go
└── README.md           # Este arquivo de documentação

• Email: [development.igorf0660@gmail.com]
• Repositório: https://github.com/GkIgor/pgb2