VACUUM

VACUUM — remove resíduos e, opcionalmente, analisa um banco de dados

Sinopse

VACUUM [ ( opção [, ...] ) ] [ tabela_e_colunas [, ...] ]

onde opção pode ser uma entre:

    FULL [ booleano ]
    FREEZE [ booleano ]
    VERBOSE [ booleano ]
    ANALYZE [ booleano ]
    DISABLE_PAGE_SKIPPING [ booleano ]
    SKIP_LOCKED [ booleano ]
    INDEX_CLEANUP { AUTO | ON | OFF }
    PROCESS_MAIN [ booleano ]
    PROCESS_TOAST [ booleano ]
    TRUNCATE [ booleano ]
    PARALLEL integer
    SKIP_DATABASE_STATS [ booleano ]
    ONLY_DATABASE_STATS [ booleano ]
    BUFFER_USAGE_LIMIT tamanho

e tabela_e_colunas é:

    [ ONLY ] nome_da_tabela [ * ] [ ( nome_da_coluna [, ...] ) ]

Descrição

O comando VACUUM recupera o armazenamento ocupado por tuplas mortas. Na operação normal do PostgreSQL, as tuplas que são excluídas ou se tornam obsoletas por uma atualização não são removidas fisicamente de sua tabela; elas permanecem presentes até que o comando VACUUM seja executado. Portanto, é necessário executar o comando VACUUM periodicamente, especialmente em tabelas atualizadas com frequência.

Sem a lista de tabela_e_colunas, o comando VACUUM processa cada tabela e visão materializada no banco de dados corrente que o usuário corrente tem permissão para limpar. Com a lista, o comando VACUUM processa apenas estas tabelas.

O comando VACUUM ANALYZE realiza o VACUUM, e depois o ANALYZE de cada tabela selecionada. Esta é uma combinação conveniente para scripts de manutenção de rotina. Veja ANALYZE para obter mais detalhes sobre o seu processamento.

O comando VACUUM puro (sem o FULL), simplesmente recupera espaço e o torna disponível para reutilização. Esta forma do comando pode operar em paralelo com a leitura e escrita normal da tabela, porque não é obtido um bloqueio exclusivo. Entretanto, o espaço recuperado não é devolvido ao sistema operacional (geralmente); se torna apenas disponível para reutilização dentro da mesma tabela. Também permite o aproveitamento de várias CPUs para processar os índices. Esta funcionalidade é conhecida como limpeza em paralelo (parallel vacuum). Para desativar esta funcionalidade, pode-se usar a opção PARALLEL, e especificar os processos trabalhadores em paralelo como zero. O comando VACUUM FULL reescreve todo o conteúdo da tabela em um novo arquivo em disco sem espaço extra, permitindo que o espaço não utilizado seja devolvido ao sistema operacional. Esta forma é muito mais lenta, e requer o bloqueio ACCESS EXCLUSIVE em cada tabela enquanto ela está sendo processada.

Parâmetros

FULL

Seleciona a limpeza completa, que pode recuperar mais espaço, mas leva muito mais tempo e bloqueia exclusivamente a tabela. Este método também requer espaço extra em disco, porque escreve uma nova cópia da tabela, sem liberar a cópia antiga até que a operação seja concluída. Normalmente, esta opção só deve ser usada quando uma quantidade significativa de espaço precisa ser recuperada de dentro da tabela.

FREEZE

Seleciona o congelamento agressivo das tuplas. Especificar FREEZE equivale a executar o comando VACUUM com os parâmetros vacuum_freeze_min_age e vacuum_freeze_table_age definidos como zero. O congelamento agressivo é sempre executado quando a tabela é reescrita, então esta opção é redundante quando se especifica a opção FULL.

VERBOSE

Mostra um relatório detalhado da atividade de limpeza para cada tabela no nível INFO.

ANALYZE

Atualiza as estatísticas usadas pelo planejador para determinar a maneira mais eficiente de executar uma consulta.

DISABLE_PAGE_SKIPPING

Normalmente, o comando VACUUM pula páginas com base no mapa de visibilidade. As páginas em que todas as tuplas estão congeladas sempre podem ser ignoradas, e aquelas em que todas as tuplas estão visíveis para todas as transações podem ser ignoradas, exceto ao executar uma limpeza agressiva. Além disso, exceto ao realizar uma limpeza agressiva, algumas páginas podem ser puladas para evitar aguardar que outras sessões terminem de usá-las. Esta opção desativa todos os comportamentos de saltar páginas, devendo ser usada somente quando o conteúdo do mapa de visibilidade for suspeito, o que deve acontecer apenas se houver um problema de hardware ou software causando a corrupção do banco de dados.

SKIP_LOCKED

Especifica que o comando VACUUM não deve aguardar por nenhum bloqueio conflitante ser liberado ao iniciar o trabalho em uma relação: se a relação não puder ser bloqueada imediatamente, a relação será ignorada. Note que mesmo com esta opção, o comando VACUUM ainda pode ficar bloqueado ao abrir os índices da relação. Além disso, o comando VACUUM ANALYZE ainda pode ficar bloqueado ao acessar linhas de amostra de partições, filhas em herança da tabela, e alguns tipos de tabelas estrangeiras. Além disso, embora o comando VACUUM normalmente processe todas as partições das tabelas particionadas especificadas, esta opção fará com que o comando VACUUM ignore todas as partições, se houver um bloqueio conflitante na tabela particionada.

INDEX_CLEANUP

Normalmente, o comando VACUUM ignora a limpeza do índice quando houver muito poucas tuplas mortas na tabela. Espera-se que o custo de processamento de todos os índices da tabela exceda em muito o benefício da remoção de tuplas de índice mortas, quando isto acontece. Esta opção pode ser usada para forçar o comando VACUUM a processar os índices quando houver mais de zero tuplas mortas. O padrão é AUTO, que permite que o comando VACUUM ignore a limpeza do índice quando apropriado. Se INDEX_CLEANUP estiver definido como ON, o comando VACUUM irá remover conservadoramente todas as tuplas mortas dos índices. Pode servir para manter a compatibilidade com versões anteriores do PostgreSQL, onde este era o comportamento padrão.

INDEX_CLEANUP também pode ser definido como OFF, para forçar o comando VACUUM a sempre ignorar a limpeza do índice, mesmo existindo muitas tuplas mortas na tabela. Pode ser útil quando é necessário executar o comando VACUUM o mais rápido possível, para evitar o reinício iminente do ID de transação (veja Prevenção de falhas de recomeço de ID de transação). Entretanto, o mecanismo à prova de falha de reinício controlado por vacuum_failsafe_age será geralmente acionado automaticamente para evitar a falha do reinício de ID de transação, devendo ser o preferido. Se a limpeza do índice não for executada regularmente, o desempenho pode ser prejudicado, porque conforme a tabela é modificada, os índices acumulam tuplas mortas, e a própria tabela acumula ponteiros de linha morta, que não podem ser removidos até que a limpeza do índice seja concluída.

Esta opção não tem efeito para tabelas que não possuem índice, sendo ignorada se a opção FULL for usada. Também não afeta o mecanismo à prova de falhas de reinício do ID da transação. Quando acionado, irá ignorar a limpeza do índice, mesmo quando INDEX_CLEANUP estiver definido como ON.

PROCESS_MAIN

Especifica que o comando VACUUM deve tentar processar a relação principal. Normalmente, este é o comportamento desejado e é o padrão. Definir esta opção como falso pode ser útil quando for necessário apenas limpar a tabela TOAST correspondente a uma relação.

PROCESS_TOAST

Especifica que o comando VACUUM deve tentar processar a tabela TOAST correspondente para cada relação, se houver. Este geralmente é o comportamento desejado, sendo o padrão. Definir esta opção como falso pode ser útil quando for necessário apenas esvaziar a relação principal. Esta opção é necessária quando a opção FULL

TRUNCATE

Especifica que o comando VACUUM deve tentar truncar todas as páginas vazias no final da tabela, e permitir que o espaço em disco para as páginas truncadas seja retornado ao sistema operacional. Este é normalmente o comportamento desejado, sendo o padrão, a menos que vacuum_truncate tenha sido definido como falso ou a opção vacuum_truncate tenha sido definida como falso para a tabela a ser limpa. Definir esta opção como falso pode ser útil para evitar o bloqueio ACCESS EXCLUSIVE na tabela requerida pelo truncamento. Esta opção será ignorada se for usada a opção FULL.

PARALLEL

Executa as fases de limpeza de índice do comando VACUUM em paralelo, usando o valor_inteiro de processos trabalhadores em segundo plano (para conhecer os detalhes de cada fase do comando, veja Fases do VACUUM). O número de processos trabalhadores usados para executar a operação é igual ao número de índices na relação que suportam a limpeza em paralelo, limitado pelo número de processos trabalhadores especificado com a opção PARALLEL se houver, que é ainda mais limitado por max_parallel_maintenance_workers. Um índice pode participar da limpeza em paralelo se, e somente se, o tamanho do índice for maior que min_parallel_index_scan_size. Por favor, note que não há garantia de que o número de processos trabalhadores paralelos especificados por valor_inteiro será usado durante a execução. É possível que a limpeza funcione com menos processos trabalhadores do que o especificado, ou mesmo sem nenhum processo trabalhador. Só pode ser usado um processo trabalhador por índice. Portanto, os processos trabalhadores paralelos são lançados apenas quando há pelo menos 2 índices na tabela. Os processos trabalhadores para a limpeza são lançados antes do início de cada fase, e saem no final da fase. Estes comportamentos podem mudar em uma versão futura. Esta opção não pode ser usada com a opção FULL.

SKIP_DATABASE_STATS

Especifica que o comando VACUUM deve ignorar a atualização das estatísticas de todo o banco de dados tomando como base os XIDs descongelados mais antigos. Normalmente, o comando VACUUM irá atualizar estas estatísticas uma vez ao final do comando. Entretanto, isto pode demorar bastante em um banco de dados com um número muito grande de tabelas, e não terá efeito algum a menos que a tabela contendo o XID descongelado mais antigo esteja entre as tabelas que foram limpas pelo VACUUM. Além disso, se vários comandos VACUUM forem emitidos em paralelo, apenas um deles poderá atualizar as estatísticas de todo o banco de dados por vez. Portanto, se uma aplicação pretende emitir uma série de muitos comandos VACUUM, poderá ser útil definir esta opção em todos os comandos, exceto no último; ou definir em todos os comandos e executar VACUUM (ONLY_DATABASE_STATS) em separado no final.

ONLY_DATABASE_STATS

Especifica que o comando VACUUM não deve fazer nada além de atualizar as estatísticas de todo o banco de dados com base nos XIDs descongelados mais antigos. Quando esta opção é especificada, a lista tabela_e_colunas deve estar vazia, e nenhuma outra opção pode ser ativada, exceto VERBOSE.

BUFFER_USAGE_LIMIT

Especifica o tamanho do buffer circular da Estratégia de Acesso ao Buffer para o comando VACUUM. Este tamanho é usado para calcular o número de buffers compartilhados que serão reutilizados como parte dessa estratégia. 0 desativa a Estratégia de Acesso ao Buffer. Se também for especificada a opção ANALYZE, o valor de BUFFER_USAGE_LIMIT será utilizado tanto para o estágio de limpeza quanto para o estágio de análise. Esta opção não pode ser usada com a opção FULL, exceto se também for especificado ANALYZE. Quando esta opção não for especificada, o comando VACUUM irá utilizar o valor de vacuum_buffer_usage_limit. Definições mais altas podem permitir que o comando VACUUM seja executado mais rapidamente, mas uma configuração muito alta pode fazer com que muitas outras páginas úteis sejam removidas dos buffers compartilhados. O valor mínimo é 128 kB e o valor máximo é 16 GB.

booleano

Especifica se a opção selecionada deve ser ativada ou desativada. Pode ser escrito TRUE, ON, ou 1 para ativar a opção, e FALSE, OFF, ou 0 para desativá-la. O valor booleano também pode ser omitido, caso em que é assumido como TRUE.

valor_inteiro

Especifica o valor inteiro não negativo passado para a opção selecionada.

tamanho

Especifica uma quantidade de memória em kilobytes. Os tamanhos também podem ser especificados como uma cadeia de caracteres contendo o tamanho numérico seguido por qualquer uma das seguintes unidades de memória: B (bytes), kB (kilobytes), MB (megabytes), GB (gigabytes) ou TB (terabytes).

nome_da_tabela

O nome (opcionalmente qualificado pelo esquema) de uma tabela específica ou visão materializada a ser limpa. Se for especificado ONLY antes do nome da tabela, somente esta tabela será limpa. Se não for especificado ONLY, a tabela e todas as suas tabelas filhas de herança ou partições (se houver) também serão limpas. Pode ser especificado opcionalmente * após o nome da tabela para indicar explicitamente que as tabelas filhas de herança (ou partições) devem ser limpas também.

nome_da_coluna

O nome da coluna específica a ser analisada. Por padrão, todas as colunas. Se for especificada uma lista de colunas, então ANALYZE também deverá ser especificado.

Saídas

Quando é especificado VERBOSE, o comando VACUUM emite mensagens de progresso, indicando qual tabela está sendo processada no momento. Também são mostradas várias estatísticas sobre as tabelas.

Notas

Para limpar uma tabela, normalmente é necessário ter o privilégio MANTER na tabela. Entretanto, os donos de bancos de dados têm permissão para limpar todas as tabelas de seus bancos de dados, exceto os catálogos compartilhados. O comando VACUUM irá ignorar quaisquer tabelas que o usuário que está executando o comando não tenha permissão para limpar.

Enquanto o comando VACUUM estiver em execução, o search_path será temporariamente alterado para pg_catalog, pg_temp.

O comando VACUUM não pode ser executado dentro de um bloco de transação.

Para tabelas com índices GIN, o comando VACUUM (em qualquer forma) também completa quaisquer inserções de índice pendentes, movendo as entradas de índice pendentes para os locais apropriados na estrutura principal do índice GIN. Veja Técnica de atualização rápida do GIN para obter detalhes.

è recomendado que todas as bases de dados sejam limpas regularmente para remover linhas inativas. O PostgreSQL inclui uma limpeza automática (autovacuum) que pode automatizar a manutenção de rotina da limpeza. Para obter mais informações sobre a limpeza automática e manual, veja Limpeza de rotina.

A opção FULL não é recomendada para uso rotineiro, mas pode ser útil em casos especiais. Um exemplo é quando se excluiu ou atualizou a maioria das linhas de uma tabela, e se gostaria que a tabela diminuísse fisicamente para ocupar menos espaço em disco, permitindo varreduras de tabela mais rápidas. O comando VACUUM FULL geralmente irá reduzir a tabela mais do que um comando VACUUM puro faria.

A opção PARALLEL é usada apenas para fins de limpeza. Se esta opção for especificada com a opção ANALYZE, ela não afetará o ANALYZE.

O comando VACUUM causa um aumento substancial no tráfego de E/S, o que pode causar baixo desempenho para as outras sessões ativas. Portanto, às vezes é aconselhável usar o recurso de atraso da limpeza baseado no custo. Na limpeza em paralelo, cada processo trabalhador dorme proporcionalmente ao trabalho realizado por ele. Veja Atraso da limpeza baseado em custos para obter detalhes.

Cada processo servidor em segundo plano (backend) executando o comando VACUUM sem a opção FULL irá relatar o seu progresso na visão pg_stat_progress_vacuum. Processos servidor em segundo plano executando VACUUM FULL em vez disso irão relatar seu progresso na visão pg_stat_progress_cluster. Veja Relatório de progresso do VACUUM e Relatório de progresso do CLUSTER para obter detalhes.

Exemplos

Para limpar uma única tabela (onek), analisá-la para o otimizador, e mostrar um relatório detalhado da atividade de limpeza:

VACUUM (VERBOSE, ANALYZE) onek;

Conformidade

Não existe o comando VACUUM no padrão SQL.

A seguinte sintaxe era usada antes da versão 9.0 do PostgreSQL e ainda tem suporte:

VACUUM [ FULL ]
       [ FREEZE ]
       [ VERBOSE ]
       [ ANALYZE ]
       [ tabela_e_colunas [, ...] ]

Note que, nesta sintaxe, as opções devem ser especificadas exatamente na ordem mostrada acima.

Veja também

vacuumdb, Atraso da limpeza baseado em custos, Autovacuum, Relatório de progresso do VACUUM, Relatório de progresso do CLUSTER