Skip to content

About

Utilitários Python para manipulação cirúrgica de dumps SQL do PostgreSQL de grande porte.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SQL Cleaner Utility

Utilitários Python para manipulação cirúrgica de dumps SQL do PostgreSQL de grande porte. Processam arquivos via stream, sem carregar o conteúdo na memória — testados com arquivos de 30GB+. Não exigem nenhuma dependência para rodar (somente biblioteca padrão do Python 3); o pigz é opcional e só acelera o processamento de arquivos .gz.

AVISO: Este é um software experimental. Desenvolvido principalmente com IA. Use por sua conta e risco. WARNING: This is experimental software. Primarily built with AI. Use at your own risk.

Dependências

Só precisa de Python 3 — nenhuma instalação extra é obrigatória.

Opcionalmente, os scripts detectam o pigz (gzip paralelo) no PATH e o usam automaticamente para ler/escrever arquivos .sql.gz, aproveitando todos os núcleos da máquina. Isso reduz bastante o tempo de processamento de dumps grandes comprimidos. Se o pigz não for encontrado, os scripts caem de volta para o módulo gzip padrão do Python — mais lento, porém sem exigir nada extra.

macOS:

brew install pigz

Linux:

# Debian/Ubuntu
sudo apt install pigz

# Fedora/RHEL
sudo dnf install pigz

# Arch
sudo pacman -S pigz

Windows não é suportado por essa aceleração. A integração com pigz usa subprocess/pipes no estilo Unix; no Windows os scripts continuam funcionando normalmente, mas sempre pelo gzip padrão do Python (mais lento em arquivos grandes).

Exemplo de uso

# 1. descobre quais tabelas são gigantes
make analisar IN=dump.sql.gz N=20

# 2a. remove as tabelas completamente (estrutura + dados)
make remover  IN=dump.sql.gz OUT=dump_limpo.sql.gz T=log,cache

# 2b. apaga apenas os dados, mantendo a estrutura
make esvaziar IN=dump.sql.gz OUT=dump_vazio.sql.gz T=log,cache

# 2c. mantém apenas N registros por tabela (os primeiros, por padrão)
make truncar  IN=dump.sql.gz OUT=dump_truncado.sql.gz T=log:1000,cache N=500

# 2d. mantém os ÚLTIMOS N registros de log (ex: eventos mais recentes)
make truncar  IN=dump.sql.gz OUT=dump_truncado.sql.gz T=log:1000:DESC

# 2e. remove "SET transaction_timeout = ...;" de um dump gerado por PG mais novo
make set      IN=dump.sql.gz OUT=dump_compat.sql.gz

Scripts

analisar_tabelas.py — lista tabelas por tamanho

Faz streaming do arquivo e mede o tamanho em bytes e o número de registros de cada bloco COPY, retornando a lista ordenada da maior para a menor. Útil para identificar quais tabelas ocupam mais espaço antes de decidir o que remover ou esvaziar.

python3 analisar_tabelas.py <arquivo>              # todas as tabelas
python3 analisar_tabelas.py <arquivo> -n 20        # top 20 maiores

Aceita .sql e .sql.gz diretamente.


truncar_tabelas.py — limita o número de registros

Mantém estrutura e N registros de cada tabela-alvo, descartando o restante. O limite pode ser o mesmo para todas as tabelas (-n) ou definido individualmente por tabela (tabela:N), ou ambos combinados.

Formato de cada entrada em -t:

Formato Limite Ordem
tabela usa -n ASC (padrão)
tabela:N N ASC (padrão)
tabela:ORDEM usa -n ASC ou DESC
tabela:N:ORDEM N ASC ou DESC
  • ASC (padrão) mantém as primeiras N linhas do bloco COPY — equivalente a um "topo" do dump.
  • DESC mantém as últimas N linhas do bloco COPY — útil quando o dump preserva ordem de inserção (ex: tabelas log, audit, events) e você quer os registros mais recentes em vez dos mais antigos.

Atenção: a ordem se refere à posição física das linhas dentro do bloco COPY do dump, não a um ORDER BY de coluna — o script não reordena nem inspeciona valores. Se o dump não foi gerado em ordem cronológica/sequencial (pg_dump normalmente segue a ordem física da tabela ou do índice), DESC não garante "os mais recentes por data", apenas "os últimos que aparecem no arquivo".

# mesmo limite para todas (ASC, padrão)
python3 truncar_tabelas.py dump.sql -o saida.sql -t log,cache -n 1000

# limite por tabela
python3 truncar_tabelas.py dump.sql -o saida.sql -t log:1000,cache:500

# mistura: log tem limite próprio, cache usa o padrão
python3 truncar_tabelas.py dump.sql -o saida.sql -t log:1000,cache -n 500

# mantém os ÚLTIMOS 1000 registros de log (DESC) e os primeiros 500 de cache (ASC, padrão)
python3 truncar_tabelas.py dump.sql -o saida.sql -t log:1000:DESC,cache:500

# ordem sem limite explícito: log usa -n como limite, mas em DESC
python3 truncar_tabelas.py dump.sql -o saida.sql -t log:DESC,cache -n 500

# só os 100 registros mais recentes de audit_log, descartando o histórico antigo
python3 truncar_tabelas.py dump.sql -o saida.sql -t audit_log:100:DESC

Aceita .sql e .sql.gz.


limpar_sql.py — remove tabelas por completo

Remove as tabelas-alvo inteiramente: dados (COPY), estrutura (CREATE TABLE, CREATE SEQUENCE) e objetos relacionados (ALTER TABLE, ALTER SEQUENCE, CREATE INDEX).

python3 limpar_sql.py <arquivo_entrada> -o <arquivo_saida> -t <tabelas_separadas_por_virgula>

Exemplos:

python3 limpar_sql.py dump.sql -o clean_dump.sql -t table1,table2
python3 limpar_sql.py dump.sql -o clean_dump.sql -t table1,table2,table3,table4

Atenção: não remove tabelas com dependências de chave estrangeira em tabelas que permanecem no dump. Verifique a integridade antes de importar.


esvaziar_tabelas.py — apaga apenas os dados

Mantém toda a estrutura intacta (CREATE TABLE, sequências, índices, constraints) e remove somente as linhas de dados dentro dos blocos COPY … \.. O cabeçalho COPY e o terminador \. são preservados, deixando o dump válido com as tabelas vazias.

python3 esvaziar_tabelas.py <arquivo_entrada> -o <arquivo_saida> -t <tabelas_separadas_por_virgula>

Exemplo:

python3 esvaziar_tabelas.py dump.sql -o no_data_dump.sql -t table1,table2

remover_set.py — remove parâmetros SET

Remove linhas SET <parametro> = ...; (ou SET <parametro> TO ...;) de um dump SQL. Útil quando o dump foi gerado por uma versão do PostgreSQL mais nova que o servidor de destino — parâmetros como transaction_timeout não existem em versões antigas e fazem o psql falhar ao restaurar.

python3 remover_set.py <arquivo_entrada> -o <arquivo_saida> [-p parametros_separados_por_virgula]

Exemplos:

python3 remover_set.py dump.sql -o dump_limpo.sql
python3 remover_set.py dump.sql.gz -o dump_limpo.sql.gz -p transaction_timeout,idle_in_transaction_session_timeout

O padrão de -p (se omitido) é transaction_timeout. Aceita .sql e .sql.gz.


Funcionalidades comuns

  • Processamento em stream: capaz de processar arquivos de qualquer tamanho.
  • Suporte a gzip: entrada e saída podem ser .sql ou .sql.gz — detecção automática pela extensão.
  • Inteligência de schema: reconhece tanto tabela quanto public.tabela, além de nomes com maiúsculas/mistas e schemas diferentes de public (o pg_dump cita esses identificadores entre aspas duplas — ex.: "ticketsDW", "Schema"."Tabela").
  • Nomes com ponto literal: um ponto sem aspas em -t é sempre interpretado como separador schema.tabela. Se a tabela tiver um ponto no próprio nome (ex.: DW.ticketsDW dentro do schema public), cite o nome inteiro entre aspas duplas: -t '"DW.ticketsDW"'.
  • Relatório de performance: tempo de execução, linhas processadas e espaço em disco economizado.

Exemplos com gzip:

python3 limpar_sql.py dump.sql.gz    -o saida.sql    -t log
python3 limpar_sql.py dump.sql.gz    -o saida.sql.gz -t log
python3 esvaziar_tabelas.py dump.sql -o saida.sql.gz -t log

Makefile

make test                                                      # roda os testes
make analisar IN=dump.sql                                      # lista tabelas por tamanho
make analisar IN=dump.sql N=20                                 # top 20 maiores
make truncar  IN=dump.sql OUT=saida.sql T=log:1000,cache N=500      # limita registros por tabela (primeiros N)
make truncar  IN=dump.sql OUT=saida.sql T=log:1000:DESC,cache N=500 # log: últimos N; cache: primeiros N (padrão)
make remover  IN=dump.sql OUT=saida.sql T=tabela               # remove tabelas (estrutura + dados)
make esvaziar IN=dump.sql OUT=saida.sql T=tabela               # apaga apenas os dados das tabelas
make set      IN=dump.sql OUT=saida.sql P=transaction_timeout  # remove parâmetros SET (padrão: transaction_timeout)

Múltiplas tabelas: separe por vírgula sem espaços no parâmetro T:

make remover  IN=dump.sql OUT=saida.sql T=log,log_2,cache
make esvaziar IN=dump.sql OUT=saida.sql T=log,log_2,cache

About

Utilitários Python para manipulação cirúrgica de dumps SQL do PostgreSQL de grande porte.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages