pg_upgrade

pg_upgrade
Anterior	Acima	Aplicações relacionadas ao servidor PostgreSQL	Principal	Próxima

pg_upgrade — atualiza uma instância do servidor PostgreSQL

Sinopse

pg_upgrade -b dir_bin_ant [-B dir_bin_novo] -d dir_conf_ant -D dir_conf_novo [opção...]

Descrição

O utilitário pg_upgrade (anteriormente chamado pg_migrator) permite que os dados armazenados em arquivos de dados do PostgreSQL sejam atualizados para uma versão principal posterior do PostgreSQL, sem salvar/recuperar os dados, o que normalmente é necessário para atualizações de versões principais como, por exemplo, da 12.14 para a 13.10, ou da 14.9 para a 15.5. Não é necessário para atualizações de versões secundárias como, por exemplo, da 12.7 para a 12.8, ou da 14.1 para a 14.5.

As versões principais do PostgreSQL adicionam regularmente novos recursos que geralmente alteram a disposição das tabelas do sistema, mas o formato interno de armazenamento dos dados raramente muda. O pg_upgrade usa este fato para executar atualizações rápidas, criando novas tabelas do sistema, e simplesmente reutilizando os arquivos de dados antigos do usuário. Se uma versão principal futura alterar o formato do armazenamento de dados de uma forma que torne o formato dos dados antigo ilegível, o utilitário pg_upgrade não poderá ser usado nessas atualizações. (A comunidade tentará evitar que isto ocorra.)

O utilitário pg_upgrade faz o melhor que pode para garantir que as instâncias antigas e novas sejam binariamente compatíveis, por exemplo, verificando se as configurações de tempo de compilação são compatíveis, incluindo binários de 32/64 bits. É importante que todos os módulos externos também sejam binariamente compatíveis, embora isto não possa ser verificado pelo pg_upgrade.

O utilitário pg_upgrade oferece suporte para atualizações da versão 9.2.X e posteriores para a versão principal atual de PostgreSQL, incluindo imagens e versões beta.

Atenção

A atualização de um agrupamento de bancos de dados faz com que o destino execute código arbitrário escolhido pelos superusuários de origem. Deve-se ter certeza de que os superusuários de origem sejam confiáveis antes de atualizar.

Opções

O utilitário pg_upgrade aceita os seguintes argumentos de linha de comando:

-b dir_bin_ant --old-bindir=dir_bin_ant

o antigo diretório de executáveis do PostgreSQL; variável de ambiente PGBINOLD

-B dir_bin_novo --new-bindir=dir_bin_novo

o novo diretório de executáveis do PostgreSQL; por padrão, o diretório onde o pg_upgrade reside; variável de ambiente PGBINNEW

-c --check

apenas verifica as instâncias, não altera nenhum dado

-d dir_conf_ant --old-datadir=dir_conf_ant

o diretório de configuração da instância antiga; variável de ambiente PGDATAOLD

-D dir_conf_novo --new-datadir=dir_conf_novo

o diretório de configuração da nova instância; variável de ambiente PGDATANEW

-j njobs --jobs=njobs

Número de conexões simultâneas e processos/threads a serem usados.

-k --link

usa ligações físicas em vez de copiar os arquivos para a nova instância

-N --no-sync

Por padrão, o utilitário pg_upgrade irá aguardar até que todos os arquivos da instância atualizada sejam escritos com segurança no disco. Esta opção faz com que o utilitário pg_upgrade retorne sem esperar, que é mais rápido, mas significa que uma falha posterior do sistema operacional poderá corromper o diretório de dados. Geralmente esta opção é útil para testes, mas não deve ser usada em uma instalação de produção.

-o opções --old-options opções

opções a serem passadas diretamente para o antigo comando postgres; as múltiplas chamadas dessa opção serão anexadas

-O opções --new-options opções

opções a serem passadas diretamente para o novo comando postgres; as múltiplas chamadas dessa opção serão anexadas

-p porta --old-port=porta

o número da porta da instância antiga; variável de ambiente PGPORTOLD

-P porta --new-port=porta

o número da porta da nova instância; variável de ambiente PGPORTNEW

-r --retain

conserva os arquivos SQL e de registro, mesmo após a conclusão bem-sucedida

-s diretório --socketdir=diretório

diretório a ser usado para os soquetes do postmaster durante a atualização; o padrão é o diretório de trabalho corrente; variável de ambiente PGSOCKETDIR

-U nome_do_usuário --username=nome_do_usuário

nome do usuário de instalação da instância; variável de ambiente PGUSER

-v --verbose

ativa o registro interno verboso

-V --version

mostra as informações da versão, e termina

--clone

Usa a clonagem de arquivo eficiente (também conhecida como reflinks em alguns sistemas), em vez de copiar os arquivos para a nova instância. Isto pode resultar em uma cópia quase instantânea dos arquivos de dados, oferecendo as vantagens de velocidade da opção -k/--link, enquanto deixa a instância antiga intocada.

A clonagem de arquivos tem suporte em apenas alguns sistemas operacionais e sistemas de arquivos. Se for selecionado, mas não houver suporte, a execução do pg_upgrade irá relatar um erro. No momento, é suportado no Linux (kernel 4.5 ou posterior) com Btrfs e XFS (em sistemas de arquivos criados com suporte a reflink), e no macOS com APFS.

--copy

Copia os arquivos para a nova instância. Este é o padrão (Veja também --link, --clone, --copy-file-range e --swap.)

--copy-file-range

Usa a chamada de sistema copy_file_range para uma cópia eficiente. Em alguns sistemas de arquivos, produz resultados semelhantes a --clone, compartilhando blocos de disco físico, enquanto em outros sistemas ainda poderá copiar blocos, mas o fará através de um caminho otimizado. No momento, tem suporte no Linux e no FreeBSD.

--no-statistics

Não restaura as estatísticas da instância antiga para a nova instância.

--set-char-signedness=opção

Define manualmente o especificador padrão para novas instâncias. Os valores possíveis são signed e unsigned ^[226] ^[227].

Na linguagem C, o especificador padrão do tipo de dados char (quando não especificado explicitamente) varia entre plataformas. Por exemplo, o tipo de dados char tem como padrão signed char nas CPUs x86, mas tem como padrão unsigned char nas CPUs ARM.

A partir do PostgreSQL 18, as instâncias mantêm sua própria definição padrão do especificador do tipo de dados char, que pode ser usado para garantir um comportamento consistente entre plataformas com diferentes especificações para o tipo de dados char. Por padrão, o utilitário pg_upgrade preserva a definição do especificador do tipo de dados char ao atualizar de uma instância existente. Entretanto, ao atualizar do PostgreSQL versão 17 ou anterior, o utilitário pg_upgrade adota a especificação do tipo de dados char da plataforma na qual foi construído.

Esta opção permite definir explicitamente a especificação do tipo de dados char padrão para a nova instância, substituindo quaisquer valores herdados. Existem dois cenários específicos onde esta opção é relevante:

Caso se planeje migrar para uma plataforma diferente após a atualização, não se deve usar esta opção. O comportamento padrão está correto neste caso. Em vez disso, deve-se executar a atualização na plataforma original sem esta opção e, depois, migrar a instância. Esta é a abordagem recomendada e mais segura.
Se a instância já foi migrada para uma plataforma com uma especificação do tipo de dados char diferente, isto poderá ser alterado (por exemplo, de um sistema baseado em x86 para um sistema baseado em ARM), deve-se usar esta opção para definir uma especificação do tipo de dados char que corresponda à especificação do tipo de dados char padrão da plataforma original. Além disso, é essencial não modificar nenhum arquivo de dados entre a migração dos arquivos de dados e a execução do utilitário pg_upgrade. O utilitário pg_upgrade deverá ser a primeira operação que inicia a instância na nova plataforma.

--swap

Move os diretórios de dados da instância antiga para a nova instância. Em seguida, substitui os arquivos de catálogo pelos gerados para a nova instância. Este modo pode apresentar um desempenho melhor do que --link, --clone, --copy e --copy-file-range, especialmente em instâncias com muitas relações.

Entretanto, este modo cria muitos arquivos inúteis na instância antiga, o que pode prolongar a etapa de sincronização de arquivos se for usado --sync-method=syncfs. Portanto, recomenda-se usar --sync-method=fsync com --swap.

Além disso, assim que a etapa de transferência de arquivos for iniciada, a instância antiga será modificada de forma destrutiva e, portanto, não será mais segura para ser iniciada. Veja Passo 17 para obter mais informações.

--sync-method=método

Quando definido como fsync, que é o padrão, o utilitário pg_upgrade irá abrir e sincronizar recursivamente todos os arquivos no diretório de dados da instância atualizada. A busca por arquivos seguirá as ligações simbólicas para o diretório de WAL e para cada espaço de tabelas configurado.

No Linux, pode ser usado syncfs em vez de solicitar ao sistema operacional que sincronize todo o sistema de arquivos que contém o diretório de dados da instância atualizada, seus arquivos de WAL e cada espaço de tabelas. Veja recovery_init_sync_method para obter mais informações sobre as ressalvas a serem consideradas ao usar syncfs.

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

-? --help

mostra a ajuda, e termina

Utilização

A seguir estão os passos para realizar a atualização usando o utilitário pg_upgrade:

Nota

Os passos para atualizar Agrupamento de replicação lógica não estão cobertos aqui; veja Atualização para obter mais informações.

Se necessário, mover a instância antiga
Se estiver sendo usado um diretório de instalação específico da versão, por exemplo, /opt/PostgreSQL/18, não será necessário mover a instância antiga. Todos os instaladores gráficos usam diretórios de instalação específicos da versão.
Se o diretório de instalação não for específico da versão, por exemplo, /usr/local/pgsql, é necessário mover o diretório de instalação corrente do PostgreSQL para não interferir com a instalação do novo PostgreSQL. Assim que o servidor PostgreSQL corrente estiver parado, será seguro mudar o nome do diretório de instalação do PostgreSQL; assumindo que o diretório antigo seja /usr/local/pgsql, pode-se executar
```
mv /usr/local/pgsql /usr/local/pgsql.old
```
para mudar o nome do diretório.
Para instalações a partir do código-fonte, deverá ser construída a nova versão
O código-fonte da nova versão do PostgreSQL deverá ser construído com sinalizadores para o comando configure compatíveis com os da instância antiga. O utilitário pg_upgrade irá executar o pg_controldata para garantir que todas as configurações sejam compatíveis, antes de iniciar a atualização.
Instalação dos novos binários do PostgreSQL
Devem ser Instalados os binários do novo servidor, e os arquivos de suporte. O utilitário pg_upgrade está incluído na instalação padrão.
Para instalações a partir do código-fonte, se for desejado instalar o novo servidor em um local personalizado, deve ser usada a variável prefix na construção:
```
make prefix=/usr/local/pgsql.new install
```
Inicialização da nova instância do PostgreSQL
A nova instância deve ser inicializada usando o comando initdb. Novamente, devem ser usados sinalizadores para o comando initdb compatíveis, que correspondam à instância antiga. Muitos instaladores pré-construídos executam esta etapa automaticamente. Não há necessidade de ativar a nova instância.
Instalação dos arquivos objeto compartilhados de extensão
Muitas extensões e módulos personalizados, seja do contrib ou de outra fonte, usam arquivos objeto compartilhados (ou DLLs), por exemplo, pgcrypto.so. Se a instância antiga os usava, os arquivos objeto compartilhados correspondentes ao novo binário do servidor devem ser instalados na nova instância, geralmente por meio de comandos do sistema operacional. Não devem ser carregadas as definições do esquema, por exemplo, CREATE EXTENSION pgcrypto, porque estas serão duplicadas da instância antiga. Se estiverem disponíveis atualizações de extensão, o pg_upgrade irá relatar isto e criar um script que poderá ser executado posteriormente para atualizá-las.
Cópia dos arquivos de procura de texto completo personalizados
Devem ser copiados todos os arquivos de procura de texto completo personalizados (dicionários, sinônimos, thesaurus, palavras de parada) da instância antiga para a nova.
Ajuste da autenticação
O utilitário pg_upgrade irá se conectar aos servidores antigo e novo várias vezes, então pode-se desejar configurar a autenticação como peer no arquivo pg_hba.conf, ou usar o arquivo ~/.pgpass (veja a O arquivo de senhas).
Parar os dois servidores
Certifique-se de que os dois servidores de banco de dados estejam parados usando, por exemplo, no Unix
```
pg_ctl -D /opt/PostgreSQL/12 stop
pg_ctl -D /opt/PostgreSQL/18 stop
```
ou no Windows, usando os nomes de serviço apropriados:
```
NET STOP postgresql-12
NET STOP postgresql-18
```
Os servidores em espera (standby) para replicação por fluxo (streaming) e envio dos registros do WAL devem permanecer em execução durante este desligamento para que recebam todas as alterações.
Preparar para as atualizações de servidor em espera
Se os servidores em espera estiverem sendo atualizados usando os métodos descritos no Passo 11, deve-se verificar se os servidores em espera antigos estão atualizados, executando o pg_controldata nas instâncias primária e em espera antigas. Deve-se verificar se os valores do “Latest checkpoint location” correspondem em todas as instâncias. Além disso, deve-se certificar de que o wal_level não esteja definido como minimal no arquivo postgresql.conf na nova instância primária.
Execução do pg_upgrade
O utilitário pg_upgrade deve ser executado sempre a partir do novo servidor, e não do antigo. O utilitário pg_upgrade requer a especificação dos diretórios de dados e executáveis (bin) da instância antiga e da nova. Também podem ser especificados os valores de usuário e porta, e se é desejado que os arquivos de dados sejam vinculados (linked), clonados (cloned) ou trocados (swapped) em vez do comportamento de cópia padrão.
Se for usado o modo vinculado (link), a atualização será muito mais rápida (sem cópia de arquivo), e usará menos espaço em disco, mas não será possível acessar a instância antiga após ativar a nova instância depois da atualização. O modo vinculado também requer que os diretórios de dados da instância antiga e nova estejam no mesmo sistema de arquivos. (Os espaços de tabelas e o pg_wal podem estar em sistemas de arquivos diferentes.) O modo de clonagem fornece as mesmas vantagens de velocidade e espaço em disco, mas não inutiliza a instância antiga depois que a nova instância é ativada. O modo de clonagem também requer que os diretórios de dados antigos e novos estejam no mesmo sistema de arquivos. Este modo está disponível apenas em determinados sistemas operacionais e sistemas de arquivos. O modo de troca (swap) pode ser o mais rápido se houver muitas relações, mas não será possível acessar a instância antiga assim que a etapa de transferência de arquivos começar. O modo de troca também exige que os diretórios de dados da instância antiga e da nova estejam no mesmo sistema de arquivos.
Definir --jobs como 2 ou maior permite ao utilitário pg_upgrade processar vários bancos de dados e espaços de tabelas em paralelo. Um bom ponto de partida é o número de núcleos de CPU na máquina. Esta opção pode reduzir substancialmente o tempo de atualização para servidores com múltiplos bancos de dados e múltiplos espaços de tabela.
Para os usuários do Windows é necessário estar conectado a uma conta de administrador e, em seguida, executar o utilitário pg_upgrade com os diretórios entre aspas como, por exemplo:
```
pg_upgrade.exe
        --old-datadir "C:/Program Files/PostgreSQL/12/data"
        --new-datadir "C:/Program Files/PostgreSQL/18/data"
        --old-bindir "C:/Program Files/PostgreSQL/12/bin"
        --new-bindir "C:/Program Files/PostgreSQL/18/bin"
```
Uma vez iniciado, o pg_upgrade irá verificar se as duas instâncias são compatíveis e fará a atualização. Pode ser usado pg_upgrade --check para executar apenas as verificações, mesmo que o servidor antigo ainda esteja em execução. O pg_upgrade --check também descreve quaisquer ajustes manuais que serão necessários fazer após a atualização. Se estiver sendo usado o modo link, clone, copy-file-range ou swap, deverá ser usada a opção --link, --clone, --copy-file-range ou --swap junto com a opção --check para ativar verificações específicas do modo. O utilitário pg_upgrade requer permissão de escrita no diretório corrente.
É claro que ninguém deve acessar as instâncias durante a atualização. O padrão para o pg_upgrade é executar os servidores na porta 50432, para evitar conexões indesejadas de clientes. Pode ser usado o mesmo número de porta para as duas instâncias ao fazer a atualização, porque as instâncias antiga e nova não serão executadas ao mesmo tempo. Entretanto, ao verificar um servidor antigo em execução, os números da porta do antigo e do novo devem ser diferentes.
Se ocorrer um erro durante a recuperação do esquema do banco de dados, o pg_upgrade será finalizado, e será necessário reverter para a instância antiga conforme descrito no Passo 17 abaixo. Para tentar executar o pg_upgrade novamente, será necessário modificar a instância antiga para que a recuperação do esquema de pg_upgrade seja bem-sucedida. Se o problema for num módulo do contrib, poderá ser necessário desinstalar o módulo do contrib da instância antiga, e instalá-lo na nova instância após a atualização, supondo que o módulo não esteja sendo usado para armazenar dados do usuário.
Atualizar os servidores em espera de replicação por fluxo e envio de registro
Se for usado o modo de vinculação, e há servidores em espera para replicação por fluxo (veja Replicação por fluxo), ou envio de registro (veja Servidores em-espera de envio de registros), podem ser seguidos os passos a seguir para atualizá-los rapidamente. Não será executado o pg_upgrade nos servidores em espera, mas sim o rsync no servidor primário. Não deverá ser ativado nenhum servidor ainda.
Se não for usado o modo de vinculação, não se possuir ou desejar usar o rsync, ou querer uma solução mais fácil, devem ser saltadas as instruções nesta seção, e simplesmente recriados o modo de espera nos servidores assim que o pg_upgrade for concluído, e o novo servidor primário estiver em execução.
1. Instalação dos novos binários do PostgreSQL nos servidores em espera
  Deve-se certificar que os novos arquivos binários e de suporte estejam instalados em todos os servidores em espera.
2. Certifique-se de que os novos diretórios de dados de espera não existem
  Deve-se certificar que os diretórios de dados dos novos servidores em espera não existam, ou estejam vazios. Se foi executado o initdb, devem ser excluídos os diretórios de dados dos novos servidores em espera.
3. Instalação dos arquivos objeto compartilhados de extensão
  Devem ser instalados os mesmos arquivos objeto compartilhados de extensão, instalados na nova instância primária, nos novos servidores em espera.
4. Parar os servidores em espera
  Se os servidores em espera ainda estiverem em execução, estes deverão ser parados agora usando as instruções mostradas acima.
5. Salvar os arquivos de configuração
  Devem ser salvos todos os arquivos de configuração presentes nos diretórios de configuração dos servidores em modo de espera antigos que se precise manter, por exemplo, o postgresql.conf (e quaisquer arquivos incluídos por ele), o postgresql.auto.conf, e o pg_hba.conf, porque estes serão substituídos ou excluídos no próximo passo.
6. Executar o rsync
  Ao usar o modo de vinculação, os servidores em espera podem ser atualizados rapidamente usando o rsync. Para fazer isto, a partir de um diretório no servidor principal, situado acima dos diretórios das instâncias de banco de dados antiga e nova, deve ser executado o seguinte comando no servidor principal, e para cada servidor em espera
```
rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir
```
  onde old_cluster e new_cluster são relativos ao diretório corrente no servidor primário, e remote_dir está acima dos diretórios da instância antiga e da nova no modo de espera. A estrutura de diretórios nos diretórios especificados no servidor primário e nos em espera devem corresponder. Veja a página do manual de rsync para obter detalhes sobre como especificar o diretório remoto. Por exemplo,
```
rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/PostgreSQL/12 \
      /opt/PostgreSQL/18 standby.example.com:/opt/PostgreSQL
```
  Pode-se verificar o que o comando rsync fará usando a opção --dry-run. Embora o rsync deva ser executado a partir do servidor primário para pelo menos um servidor no modo de espera, é possível executar o rsync a partir de um servidor no modo de espera atualizado para atualizar os outros servidores no modo de espera, desde que o servidor no modo de espera atualizado não tenha sido ativado.
  O que isto faz é registrar os links criados pelo modo de vinculação do pg_upgrade, que conecta os arquivos nas instâncias antigas e novas no servidor principal. Em seguida, são localizados os arquivos correspondentes na instância antiga do servidor em espera, e criados links para eles na nova instância do servidor em espera. Os arquivos que não foram vinculados no servidor primário são copiados do servidor primário para o servidor em espera. (Eles geralmente são pequenos.) Isto fornece atualizações rápidas para servidores em espera. Infelizmente, o rsync copia desnecessariamente arquivos associados a tabelas temporárias e sem registro, porque estes arquivos normalmente não existem em servidores em espera.
  Se existirem espaços de tabelas, será necessário executar um comando rsync semelhante para cada diretório de espaço de tabelas. Por exemplo:
```
rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_12_201909212 \
      /vol1/pg_tblsp/PG_18_202307071 standby.example.com:/vol1/pg_tblsp
```
  Se o pg_wal foi realocado para fora dos diretórios de dados, o rsync também deverá ser executado nesses diretórios.
7. Configurar os servidores em espera para replicação por fluxo e envio de registro
  Configurar os servidores para envio de registro. (Não é preciso executar pg_start_backup() e pg_stop_backup(), ou fazer uma cópia de segurança do sistema de arquivos, porque os servidores em espera ainda estão sincronizados com o servidor primário.) Se o servidor primário antigo for anterior à versão 17.0, nenhum encaixe do servidor primário será copiado para o novo servidor em espera, portanto, todos os encaixes do servidor em espera antigo deverão ser recriados manualmente. Se o servidor primário antigo for da versão 17.0 ou posterior, apenas os encaixes lógicos do servidor primário serão copiados para o novo servidor em espera, mas os demais encaixes do servidor em espera antigo não serão copiados e, portanto, deverão ser recriados manualmente.
Restaurar o arquivo pg_hba.conf
Se o arquivo pg_hba.conf foi modificado, então suas configurações originais deverão ser restauradas. Também pode ser necessário ajustar outros arquivos de configuração na nova instância para corresponder à instância antiga, por exemplo, o arquivo postgresql.conf (e quaisquer arquivos incluídos por ele), e postgresql.auto.conf.
Ativar o novo servidor
O novo servidor agora pode ser ativado com segurança e, em seguida, qualquer servidor em espera que foi sincronizado com o rsync.
Processamento pós-atualização
Se for necessário algum processamento pós-atualização, o pg_upgrade emitirá avisos conforme for concluído. Também irá gerar arquivos de script que devem ser executados pelo administrador. Os arquivos de script irão se conectar a cada banco de dados que precisa de processamento pós-atualização. Cada script deve ser executado usando:
```
psql --username=postgres --file=script.sql postgres
```
Os scripts podem ser executados em qualquer ordem, podendo ser excluídos depois de executados.
Cuidado
Em geral, não é seguro acessar tabelas referenciadas em scripts de reconstrução, até que os scripts de reconstrução tenham sido executados até o fim; fazer isto pode gerar resultados incorretos, ou baixo desempenho. As tabelas não referenciadas por scripts de reconstrução podem ser acessadas imediatamente.
Estatísticas
A menos que seja especificada a opção --no-statistics, o utilitário pg_upgrade irá transferir a maioria das estatísticas do otimizador da instância antiga para a nova instância. Não são transferidas todas as estatísticas, como aquelas criadas explicitamente por CREATE STATISTICS, estatísticas personalizadas adicionadas por uma extensão, ou estatísticas coletadas pelo sistema de estatísticas cumulativas.
Como nem todas as estatísticas são transferidas pelo utilitário pg_upgrade, serão recebidas instruções para executar comandos para regenerar estas informações ao final da atualização. Pode ser necessário configurar os parâmetros de conexão para que correspondam à nova instância.
Primeiro deve ser usado vacuumdb --all --analyze-in-stages --missing-stats-only para gerar rapidamente estatísticas mínimas de otimização para relações que não tenham nenhuma estatística. Depois, usado vacuumdb --all --analyze-only para garantir que todas as relações tenham estatísticas cumulativas atualizadas para acionar a limpeza e analisar. Para os dois comandos, o uso de --jobs pode acelerá-los. Se vacuum_cost_delay for definido com um valor diferente de zero, isto pode ser sobrescrito para acelerar a geração de estatísticas usando PGOPTIONS como, por exemplo, PGOPTIONS='-c vacuum_cost_delay=0' vacuumdb ....
Exclusão da instância antiga
Uma vez que se esteja satisfeito com a atualização, podem ser excluídos os diretórios de dados da instância antiga executando o script mencionado quando o pg_upgrade foi concluído. (A exclusão automática não será possível se houver espaços de tabelas definidos pelo usuário dentro do antigo diretório de dados.) Também podem ser excluídos os diretórios de instalação antigos (por exemplo, bin, share).
Volta para a instância antiga
Se, após executar o utilitário pg_upgrade, se desejar voltar para a instância antiga, existem várias opções:
- Se foi usada a opção --check, a instância antiga não foi modificada; ela pode ser reiniciada.
- Se nem --link nem --swap foi usada, a instância antiga permaneceu inalterada e pode ser reiniciada.
- Se foi usada a opção --link, os arquivos de dados podem ser compartilhados entre a instância antiga e a nova:
  - Se o utilitário pg_upgrade foi interrompido antes do início da vinculação, a instância antiga não foi modificada; ela pode ser reiniciada.
  - Se a nova instância não foi ativada, a instância antiga não foi modificada, exceto que, quando a vinculação foi iniciada, um sufixo .old foi anexado a $PGDATA/global/pg_control. Para reutilizar a instância antiga, deve ser removido o sufixo .old de $PGDATA/global/pg_control; a instância antiga pode ser reiniciada.
  - Se a nova instância foi ativada, ela escreveu em arquivos compartilhados, não sendo mais seguro usar a instância antiga. A instância antiga precisará ser recuperada da cópia de segurança neste caso.
- Se foi usada a opção --swap, a instância antiga pode ter sido modificada de forma destrutiva:
  - Se o utilitário pg_upgrade foi interrompido antes de informar que a instância antiga não é mais segura para iniciar, significa que a instância antiga não foi modificada e pode ser reiniciada.
  - Se o utilitário pg_upgrade reportou que a instância antiga não é mais segura para iniciar, significa que a instância antiga foi modificada de forma destrutiva. Neste caso, será necessário restaurar a instância antiga a partir da cópia de segurança.

Variáveis de ambiente

Podem ser usadas algumas variáveis de ambiente para fornecer valores padrão para opções de linha de comando:

PGBINOLD: O diretório de executável antigo do PostgreSQL; opção -b/--old-bindir.
PGBINNEW: O novo diretório de executável do PostgreSQL; opção -B/--new-bindir.
PGDATAOLD: O diretório de configuração antigo da instância; opção -d/--old-datadir.
PGDATANEW: O novo diretório de configuração da instância; opção -D/--new-datadir.
PGPORTOLD: O número antigo da porta da instância; opção -p/--old-port.
PGPORTNEW: O número novo da porta da instância; opção -P/--new-port.
PGSOCKETDIR: Diretório a ser usado para os soquetes do postmaster durante a atualização; opção -s/--socketdir.
PGUSER: Nome de usuário de instalação da instância; opção -U/--username.

Notas

O utilitário pg_upgrade cria vários arquivos de trabalho, como descargas de esquema, armazenados em pg_upgrade_output.d no diretório da nova instância. Cada execução cria um novo subdiretório com um nome e um carimbo de data/hora formatados de acordo com a norma ISO 8601 (%Y%m%dT%H%M%S), onde todos os arquivos gerados são armazenados. O diretório pg_upgrade_output.d e os arquivos contidos nele serão removidos automaticamente se o utilitário pg_upgrade for concluído com sucesso; mas, em caso de problemas, os arquivos ali presentes podem fornecer informações úteis para depuração.

O pg_upgrade inicia servidores de curta duração nos diretórios de dados antigos e novos. Os arquivos de soquete Unix temporários para comunicação com estes servidores são, por padrão, criados no diretório de trabalho corrente. Em algumas situações, o nome do caminho para o diretório corrente pode ser muito longo para ser um nome de soquete válido. Neste caso, pode-se usar a opção -s para colocar os arquivos de soquete em algum diretório com um nome de caminho mais curto. Por segurança, deve-se certificar de que este diretório não seja legível ou possa ser escrito por nenhum outro usuário. (Isto não tem suporte no Windows.)

Todos os casos de falha, reconstrução e reindexação serão relatados pelo pg_upgrade, se afetarem sua instalação; os scripts pós-atualização para reconstruir tabelas e índices serão gerados automaticamente. Se estiver sendo tentado automatizar a atualização de muitas instâncias, deve-se descobrir que as instâncias com esquemas de banco de dados idênticos requerem as mesmas etapas de pós-atualização para todas as atualizações de instância; isto acontece porque as etapas pós-atualização são baseadas nos esquemas do banco de dados, e não nos dados do usuário.

Para teste de atualização, deve ser criada uma cópia somente do esquema da instância antiga, inserido dados fictícios, e feita a atualização.

O utilitário pg_upgrade não oferece suporte para a atualização de bancos de dados que contenham colunas de tabela usando estes tipos de dados do sistema que fazem referência a OIDs do tipo reg*:

regcollation

regconfig

regdictionary

regnamespace

regoper

regoperator

regproc

regprocedure

(regclass, regrole e regtype podem ser atualizados)

Se for desejado usar o modo de vinculação (link) e não se desejar que a instância antiga seja modificada quando a nova instância for ativada, deve-se considerar o uso do modo de clonagem. Se este não estiver disponível, deve-se fazer uma cópia da instância antiga e atualizá-la no modo de vinculação. Para criar uma cópia válida da instância antiga, deve-se usar o rsync para criar uma cópia suja da instância antiga enquanto o servidor estiver em execução, e depois parar o servidor antigo e executar rsync --checksum novamente para atualizar a cópia com quaisquer alterações para torná-la consistente. (A opção --checksum é necessária, porque o rsync possui uma granularidade de apenas um segundo para o tempo de modificação de arquivo.) Pode-se querer excluir alguns arquivos como, por exemplo, postmaster.pid, conforme documentado em Criação de cópia de segurança base usando API de baixo nível. Se o sistema de arquivos oferecer suporte a instantâneos (snapshots) ou cópias de arquivos ao escrever (copy-on-write), pode-se usar este recurso para fazer uma cópia de segurança da instância e dos espaços de tabelas antigos, embora o instantâneo e as cópias devam ser criados simultaneamente ou enquanto o servidor de banco de dados estiver inativo.

Veja também

initdb, pg_ctl, pg_dump, postgres

^[226] Os tipos de dados caracteres são tipos de dados inteiros usados para representar caracteres. Fundamental types (N. T.)

^[227] Um tipo de dados inteiro sem sinal pode representar apenas números positivos e zero. Um tipo de dados com sinal pode representar números positivos e negativos. Signed and Unsigned Types (N. T.)