Define o diretório de destino para escrever a saída. O utilitário pg_basebackup irá criar este diretório (e qualquer diretório ancestral ausente) se este não existir. Se já existir, deverá estar vazio.

Quando a cópia de segurança está no formato tar, o diretório de destino pode ser especificado como - (hífen), fazendo com que o arquivo tar seja escrito na stdout.

Esta opção é requerida.

Seleciona o formato para a saída. O formato pode ser um dos seguintes:

Realiza uma cópia de segurança incremental. O manifesto da cópia de segurança para a cópia de segurança de referência deve ser fornecido e será carregado no servidor, que responderá enviando a cópia de segurança incremental solicitada.

Cria o arquivo standby.signal e anexa as definições de conexão ao arquivo postgresql.auto.conf no diretório de destino (ou dentro do arquivo base ao usar o formato tar). Isto facilita a configuração de um servidor em-espera usando os resultados da cópia de segurança base.

O arquivo postgresql.auto.conf irá registrar as definições de conexão e, se especificado, o encaixe de replicação que o pg_basebackup está usando, para que a replicação por fluxo (streaming) e a sincronização de encaixes de replicação lógica usem as mesmas definições posteriormente. O nome do banco de dados será registrado somente se tiver sido especificado explicitamente na cadeia de caracteres de conexão ou na variável de ambiente..

Indica ao servidor onde colocar a cópia de segurança base. O destino padrão é client, especificando que a cópia de segurança deve ser enviada para a máquina onde pg_basebackup está sendo executado. se o destino for definido como servidor:/algum/caminho, a cópia de segurança será armazenada na máquina onde o servidor está sendo executado, no diretório /algum/caminho. Armazenar uma cópia de segurança no servidor requer privilégios de superusuário ou privilégios da função de banco de dados pg_write_server_files. Se o destino for definido como blackhole (buraco negro), o conteúdo será descartado e não armazenado em nenhum lugar. Isto deve ser usado apenas para fins de teste, porque não haverá uma cópia de segurança real.

Como o fluxo do WAL é implementado pelo pg_basebackup em vez do servidor, esta opção não pode ser usada junto com -Xstream. Como esta é a opção padrão, ao especificá-la também deverá ser especificado -Xfetch ou -Xnone.

Realoca o espaço de tabelas no diretório olddir para newdir durante a cópia de segurança. Para ser eficaz, olddir deve corresponder exatamente à especificação do caminho do espaço de tabelas, conforme definido no servidor de origem. (Mas não é um erro se não houver um espaço de tabelas em olddir no servidor de origem.) Enquanto isto, newdir é um diretório no sistema de arquivos do hospedeiro receptor. Como no diretório de destino principal, newdir não precisa existir, mas se existir, deverá estar vazio. Tanto olddir quanto newdir devem ser caminhos absolutos. Se um dos caminhos precisar conter o sinal de igual (=), este deverá ser precedido por uma contrabarra. Esta opção pode ser especificada várias vezes para vários espaços de tabela.

Se um espaço de tabelas for realocado dessa maneira, os vínculos simbólicos dentro do diretório de dados principal serão atualizados para apontar para o novo local. Portanto, o novo diretório de dados estará pronto para ser usado pela nova instância do servidor, com todos os espaços de tabelas nos locais atualizados.

No momento, esta opção funciona apenas com formato de saída simples; será ignorada se for selecionado o formato tar.

Define o diretório para escrever os arquivos de WAL (write-ahead log). Por padrão, os arquivos de WAL são colocados no subdiretório pg_wal do diretório de destino, mas pode ser usada esta opção para colocá-los em outro lugar. waldir deve ser um caminho absoluto. Como o caso do diretório de destino principal, waldir não precisa existir, mas se existir, deverá estar vazio. Esta opção só pode ser especificada quando a cópia de segurança estiver no formato simples.

Inclui os arquivos de WAL (write-ahead log) necessários na cópia de segurança. Isto incluirá todos os registros de transação gerados durante a cópia de segurança. A menos que seja especificado o método none, é possível iniciar o postmaster no diretório de destino sem necessidade de consultar os registros de transação, tornando a saída uma cópia de segurança inteiramente autônoma.

Os seguintes métodos para coletar registros de transação têm suporte:

Ativa a compressão gzip da saída do arquivo tar, com o nível de compressão padrão. A compressão só está disponível ao usar o formato tar, sendo adicionado automaticamente o sufixo .gz a todos os nomes de arquivo tar.

Requer a compressão da cópia de segurança. Se for incluído client ou server, isto especifica onde a compressão deve ser realizada. A compressão no servidor reduzirá a largura de banda de transferência, mas aumentará o consumo de CPU do servidor. O padrão é client exceto quando é usado --target. Neste caso, a cópia de segurança não está sendo enviado para o cliente, então somente a compressão no servidor faz sentido. Quando é usado -Xstream, que é o padrão, a compressão do lado do servidor não será aplicada ao WAL. Para comprimir o WAL, deve ser usada a compressão do lado do cliente ou especificado -Xfetch.

O método de compressão pode ser definido como gzip, lz4, zstd, none para nenhuma compressão, ou um número inteiro (sem compressão se for 0, ou gzip se for maior que 0). Opcionalmente, pode-se especificar uma cadeia de caracteres com detalhes da compressão. Se a cadeia de caracteres de detalhes for um número inteiro, ela especifica o nível de compressão. Caso contrário, deve ser uma lista de itens separados por vírgulas, cada um com o formato palavra-chave ou palavra-chave=valor. No momento, as palavras-chave com suporte são: level, long e workers. A cadeia de caracteres de detalhes não pode ser usada quando o método de compressão é especificado como um número inteiro simples.

Caso não seja especificado nenhum nível de compressão, será utilizado o nível de compressão padrão. Se for especificado apenas o nível sem mencionar um algoritmo, será usada a compressão gzip se o nível for maior que 0, e nenhuma compressão será usada se o nível for igual a 0.

Quando é usado o formato tar juntamente com gzip, lz4 ou zstd, será adicionado automaticamente o sufixo .gz, .lz4 ou .zst, respectivamente, a todos os nomes de arquivo tar. Quando é usado o formato simples, a compressão do lado cliente pode não ser especificada, mas ainda será possível solicitar a compressão do lado do servidor. Se isto for feito, o servidor irá comprimir a cópia de segurança para transmissão e o cliente irá descomprimir e extrair.

Quando esta opção é usada em combinação com -Xstream, o arquivo pg_wal.tar será comprimido usando o gzip se estiver selecionada a compressão gzip do lado do cliente, mas não será comprimido se for selecionado qualquer outro algoritmo de compressão, ou se a compressão do lado do servidor estiver selecionada.

Define o modo de ponto de verificação como fast (rápido/imediato), ou spread (disperso, o padrão) (veja Seção 25.3.4).

Especifica que o encaixe (slot) de replicação indicado pela opção --slot deve ser criado antes de iniciar a cópia de segurança. É relatado um erro se o encaixe já existir.

Define o rótulo para a cópia de segurança. Se não for especificado nenhum rótulo, será usado o valor padrão “pg_basebackup base backup”.

Por padrão, quando o utilitário pg_basebackup termina com um erro, ele remove todos os diretórios que possa ter criado antes de descobrir que não pode terminar seu trabalho (por exemplo, o diretório de destino e o diretório de WAL). Esta opção inibe a limpeza e, portanto, serve para depuração.

Note que os diretórios do espaço de tabelas não são limpos de nenhuma maneira.

Por padrão, o utilitário pg_basebackup irá aguardar que todos os arquivos sejam escritos com segurança no disco. Esta opção faz com que o pg_basebackup retorne sem esperar, o que é mais rápido, mas significa que uma falha subsequente do sistema operacional poderá deixar a cópia de segurança base corrompida. Geralmente, esta opção serve para testes, mas não deve ser usada ao criar uma instalação de produção.

Ativa o relatório de progresso, que produz um relatório de progresso aproximado durante a cópia de segurança. Como o banco de dados pode mudar durante a cópia de segurança, é apenas uma aproximação, podendo não terminar exatamente em 100%. Em particular, quando o registro do WAL é incluído na cópia de segurança, a quantidade total de dados não pode ser estimada com antecedência e, neste caso, o tamanho estimado do destino aumentará assim que ultrapassar a estimativa total sem WAL.

Define a taxa de transferência máxima na qual os dados são coletados no servidor de origem. Pode servir para limitar o impacto do utilitário pg_basebackup no servidor. Os valores são em kilobytes por segundo. Deve ser usado o sufixo M para indicar megabytes por segundo. O sufixo k também é aceito, mas não tem efeito. Os valores válidos estão entre 32 kilobytes e 1024 megabytes por segundo.

Esta opção sempre afeta a transferência do diretório de dados. A transferência de arquivos de WAL só será afetada se o método de coleta for fetch.

Esta opção só pode ser usada em conjunto com -X stream. Faz com que o fluxo do WAL use o encaixe de replicação especificado. Se a cópia de segurança base for usada por um servidor em-espera de replicação por fluxo usando um encaixe de replicação, o servidor em-espera deverá usar o mesmo nome do encaixe de replicação que primary_slot_name. Isto garante que o servidor principal não irá remover nenhum dado do WAL necessário, no período entre o final da cópia de segurança base e o início da replicação por fluxo no novo servidor em-espera.

O encaixe de replicação especificado deve existir, a menos que também seja usada a opção -C.

Se esta opção não for especificada, e o servidor oferecer suporte a encaixes de replicação temporários (versão 10 e posterior), um encaixe de replicação temporário será usado automaticamente para transmissão do WAL.

Quando definido como fsync, que é o padrão, o utilitário pg_basebackup irá abrir e sincronizar recursivamente todos os arquivos no diretório de cópia de segurança. Quando é usado o formato simples (plain), a busca por arquivos seguirá os links simbólicos para o diretório do WAL e para cada espaço de tabelas configurado.

No Linux, pode ser usado o utilitário syncfs para solicitar ao sistema operacional que sincronize todo o sistema de arquivos que contém o diretório de cópia de segurança. Quando é usado o formato simples, o utilitário pg_basebackup também irá sincronizar os sistemas de arquivos que contêm os arquivos do WAL e cada espaço de tabelas. Veja recovery_init_sync_method para obter informações sobre as ressalvas a serem consideradas ao usar o syncfs.

Esta opção não tem efeito quando é usado --no-sync.

Ativa o modo verboso. Mostra algumas etapas extras durante o início e o término, além de mostrar o nome exato do arquivo que está sendo processado no momento, se o relatório de progresso também estiver ativo.

Especifica o algoritmo de soma de verificação (checksum) que deve ser aplicado a cada arquivo incluído no manifesto da cópia de segurança No momento, os algoritmos disponíveis são NONE, CRC32C, SHA224, SHA256, SHA384, e SHA512. O valor padrão é CRC32C.

Se for usado NONE, o manifesto da cópia de segurança não conterá nenhuma soma de verificação. Caso contrário, irá conter a soma de verificação de cada arquivo na cópia de segurança usando o algoritmo especificado. Além disso, o manifesto sempre conterá a soma de verificação SHA256 de seu próprio conteúdo. Os algoritmos SHA consomem muito mais CPU do que CRC32C, portanto, selecionar um deles pode aumentar o tempo necessário para concluir a cópia de segurança.

O uso de uma função de hash SHA fornece um resumo criptograficamente seguro de cada arquivo para usuários que desejam verificar se a cópia de segurança não foi adulterada, enquanto o algoritmo CRC32C fornece uma soma de verificação muito mais rápida de calcular; serve para detectar erros devido a alterações acidentais, mas não é resistente a modificações maliciosas. Note que, para ser útil contra um agressor que tenha acesso à cópia de segurança, o manifesto da cópia de segurança precisa ser armazenado com segurança em outro lugar, ou verificado de outra forma, para não ter sido modificado desde que a cópia de segurança foi feita.

Pode ser usado o utilitário pg_verifybackup para verificar a integridade da cópia de segurança em relação ao manifesto da cópia de segurança.

Força todos os nomes de arquivo no manifesto da cópia de segurança serem codificados em hexadecimal. Se esta opção não for especificada, apenas nomes de arquivos não UTF8 serão codificados em hexadecimal. Esta opção destina-se, principalmente, para testar se as ferramentas que leem o arquivo de manifesto de cópia de segurança lidam adequadamente com este caso.

Impede que o servidor estime a quantidade total de dados da cópia de segurança que serão transmitidos, resultando com que a coluna backup_total da visão pg_stat_progress_basebackup seja sempre NULL.

Sem esta opção, a cópia de segurança começará enumerando o tamanho de todo o banco de dados e, em seguida, voltará e transmitirá o conteúdo real. Isto pode fazer com que a cópia de segurança demore um pouco mais e, em particular, levará mais tempo até que os primeiros dados sejam transmitidos. Esta opção serve para evitar este tempo de estimativa, caso seja muito longo.

Esta opção não é permitida ao usar --progress.

Desativa a geração do manifesto da cópia de segurança. Se esta opção não for especificada, o servidor irá gerar e enviar um manifesto da cópia de segurança que poderá ser verificado usando o utilitário pg_verifybackup. O manifesto é uma lista de todos os arquivos presentes na cópia de segurança, com exceção de quaisquer arquivos de WAL que possam ser incluídos. Também armazena o tamanho, a hora da última modificação, e uma soma de verificação opcional para cada arquivo.

Impede a criação de um encaixe de replicação temporário para a cópia de segurança.

Por padrão, se for selecionado o fluxo dos registros de transação, mas não for fornecido nenhum nome de encaixe com a opção -S, será criado um encaixe de replicação temporário (se tiver suporte no servidor de origem).

O objetivo principal dessa opção é permitir produzir uma cópia de segurança base quando o servidor não tiver encaixes de replicação livres. Usar um encaixe de replicação é quase sempre o preferido, porque evita que o WAL necessário seja removido pelo servidor durante a cópia de segurança.

Desativa a verificação de somas de verificação, se estiverem ativas no servidor de onde a cópia de segurança base é obtida.

Por padrão, as somas de verificação são verificadas, e as falhas de soma de verificação resultarão em um status de saída diferente de zero. Entretanto, a cópia de segurança base não será removida neste caso, como se a opção --no-clean tivesse sido usada. As falhas de verificação da soma de verificação também são relatadas na visão pg_stat_database.

Especifica os parâmetros usados para conectar ao servidor como uma cadeia de caracteres de conexão; os parâmetros da cadeia de caracteres de conexão têm precedência sobre quaisquer opções de linha de comando conflitantes.

Esta opção se chama --dbname para manter a consistência com outras aplicações cliente, mas como o utilitário pg_basebackup não se conecta a nenhum banco de dados específico no agrupamento, qualquer nome de banco de dados incluído na cadeia de caracteres de conexão será ignorado pelo servidor. Entretanto, um nome de banco de dados fornecido dessa forma substitui o nome de banco de dados padrão (replication) para fins de consulta da senha da conexão de replicação em ~/.pgpass. Da mesma forma, os intermediários (middlewares) ou procuradores (proxies) usados ​​na conexão com o PostgreSQL podem utilizar o nome para fins como roteamento de conexão. O nome do banco de dados também pode ser usado pela sincronização de encaixes de replicação lógica.

Especifica o nome do hospedeiro da máquina na qual o servidor está sendo executado. Se começar com uma barra, será usado como o diretório para o soquete de domínio Unix. O padrão é obtido da variável de ambiente PGHOST, se definida, caso contrário, é tentada uma conexão de soquete de domínio Unix.

Especifica a porta TCP, ou extensão de arquivo de soquete de domínio Unix local, na qual o servidor está aguardando conexões. O padrão é usar a variável de ambiente PGPORT, se estiver definida, ou o padrão compilado.

Especifica o número de segundos entre os pacotes de status enviados de volta ao servidor de origem. Valores menores permitem monitoramento mais preciso do andamento da cópia de segurança do servidor. O valor zero desativa completamente as atualizações periódicas de status, embora uma atualização ainda seja enviada quando solicitada pelo servidor, para evitar desconexões baseadas em tempo esgotado (timeout). O valor padrão é de 10 segundos.

Nome de usuário para se conectar como.

Nunca emite uma solicitação de senha. Se o servidor exigir autenticação por senha, e uma senha não estiver disponível por outros meios, como o arquivo .pgpass, a tentativa de conexão irá falhar. Esta opção pode ser útil em tarefas em lote e scripts nos quais nenhum usuário está presente para inserir uma senha.

Força o pg_basebackup solicitar a senha antes de conectar ao banco de dados.

Esta opção nunca é essencial, porque o pg_basebackup solicita automaticamente a senha se o servidor exigir autenticação por senha. No entanto, o pg_basebackup irá desperdiçar uma tentativa de conexão ao descobrir que o servidor pede uma senha. Em alguns casos vale a pena digitar -W para evitar a tentativa extra de conexão.

Mostra a versão do pg_basebackup, e termina.

Mostra ajuda sobre os argumentos de linha de comando do utilitário pg_basebackup, e termina.