ApsaraDB RDS:Introdução ao relatório de verificação para upgrade de versão principal de uma instância ApsaraDB RDS for PostgreSQL

Aviso de disco

Formato do aviso: Total disk space: {*} GB; Used disk: {*} GB; Used inodes: {*}; bytes-per-nodes: {*}; Minimum disk space required for upgrade: {*} GB

Causa: A instância possui objetos em excesso; o armazenamento atual é insuficiente para o upgrade.

Solução:

• Blue-green deployment mode: Defina a capacidade de armazenamento da nova instância com um valor maior ou igual ao espaço mínimo em disco necessário para o upgrade.

• Local upgrade mode: Expanda a capacidade de armazenamento da instância para um valor maior ou igual ao espaço mínimo em disco necessário para o upgrade antes de iniciar o upgrade. Para mais informações, consulte Alterar a configuração.

Aviso de memória

Formato do aviso: Current memory: {*} GB; Recommended memory: {*} GB; Minimum memory: {*} GB

Causa: A instância possui objetos em excesso; a memória atual é insuficiente para minimizar o tempo de somente leitura durante o upgrade.

Solução:

• Blue-green deployment mode: Defina as especificações da nova instância de modo que a memória atinja ou supere o requisito mínimo de memória.

• Local upgrade mode: Faça upgrade das especificações da instância se a memória atual for inferior à capacidade de memória recomendada. Para mais informações, consulte Alterar a configuração.

Aviso de assinatura

Formato do aviso: The instance has replication slot subscribers. To prevent subscription data inconsistency, see the Alibaba Cloud documentation

Causa: A instância possui assinantes de slot de replicação. Execute a seguinte consulta para verificar:

SELECT * FROM pg_subscription;

Solução: Siga as etapas no tópico Fazer upgrade da versão principal do banco de dados para lidar com assinantes de slot de replicação.

Aviso de sequência (somente modo zero-downtime)

Formato do aviso: Total Sequence tables: {0}. Too many Sequence tables will extend the switchover time for logical replication major version upgrade.

Causa: A instância contém sequências. Execute a seguinte consulta para listá-las:

SELECT * FROM pg_sequences;

Solução: Se a instância tiver um grande número de sequências, clone a instância e execute um upgrade de teste para medir o tempo real de troca antes de fazer upgrade da produção.

Erro de conta

Formato do erro: Invalid superuser account: {*}; Invalid account: {*}; Please see the Alibaba Cloud documentation

Causa: A instância possui contas de superusuário redundantes ou contas padrão com configurações de criptografia inválidas.

Solução:

• Contas de superusuário redundantes: Abra um ticket para solicitar a exclusão.

• Contas padrão inválidas: Redefina as senhas das contas afetadas.

Erro de pré-verificação

Formato do erro: pg_upgrade pre-check task failed, need to check [pg_upgrade error log] and [pg_upgrade-related files and errors]

Causa: A pré-verificação do pg_upgrade falhou.

Solução: Revise a seção do log de erros pg_upgrade no relatório de verificação para identificar e resolver o problema específico.

Erro da extensão pgcrypto

Formato do erro: The pg_crypto extension is installed in schema: pg_catalog in database: {*}, please see the Alibaba Cloud documentation

Causa: A extensão pgcrypto cria funções no pg_catalog que existem apenas em versões posteriores do PostgreSQL. Isso faz com que o upgrade da versão principal do mecanismo falhe.

Solução: Em cada banco de dados afetado, exclua a extensão pgcrypto e recrie-a em um schema diferente de pg_catalog.

Erro de versão secundária (somente modo zero-downtime)

Formato do erro: Zero-downtime major version upgrade requires minimum minor version 20250228

Causa: A versão secundária do mecanismo da instância é anterior a 20250228.

Solução: Faça upgrade da versão secundária do mecanismo para 20250228 ou posterior.

loadable_libraries.txt: extensões incompatíveis

O arquivo loadable_libraries.txt lista os arquivos de biblioteca que não podem ser carregados pela versão PostgreSQL de destino. Cada biblioteca normalmente corresponde a uma extensão.

Causa: Uma ou mais extensões instaladas são incompatíveis com a versão principal do mecanismo de destino.

Solução: Verifique as extensões listadas em loadable_libraries.txt. Para cada extensão, confirme se sua aplicação depende dela e decida se deve excluí-la antes do upgrade. Para a lista de extensões suportadas em cada versão, consulte Extensões suportadas.

As seções a seguir descrevem as extensões incompatíveis mais comuns.

tables_with_oids.txt: tabelas com OIDs

O arquivo tables_with_oids.txt lista as tabelas criadas com a declaração WITH OIDS. O PostgreSQL 12 e versões posteriores não suportam WITH OIDS.

Causa: Uma ou mais tabelas usam a declaração WITH OIDS, que não é suportada na versão de destino.

Solução:

• Opção 1 (recomendada): Faça upgrade para o PostgreSQL 11, que ainda suporta WITH OIDS.

• Opção 2: Revise as tabelas listadas em tables_with_oids.txt e confirme que sua aplicação não depende de valores OID. Em seguida, execute o seguinte comando para cada tabela afetada:

  ALTER TABLE {table_name} SET WITHOUT OIDS;

Tabelas estrangeiras

Formato do erro: Foreign tables in database: {0}. Total databases: {1}

Causa: A instância contém tabelas estrangeiras, que a replicação lógica não consegue replicar.

Solução: Exclua todas as tabelas estrangeiras.

1. Em cada banco de dados, identifique as tabelas estrangeiras:

   SELECT COUNT(*) AS count, relkind
   FROM pg_class
   WHERE relkind IN ('f')
   GROUP BY relkind;

2. Exclua as tabelas estrangeiras:

   DROP FOREIGN TABLE [ IF EXISTS ] name [ CASCADE | RESTRICT ];

Para mais informações, consulte a documentação do PostgreSQL sobre DROP FOREIGN TABLE.

Tabelas sem chave primária ou chave única

Formato do erro: Tables without primary key or unique key in database: {0}. Total databases: {1}

Causa: A replicação lógica exige que cada tabela tenha uma chave primária, uma chave única ou REPLICA IDENTITY FULL para identificar linhas durante a replicação.

Solução: Adicione uma chave primária ou chave única a cada tabela afetada, ou defina REPLICA IDENTITY FULL.

1. Em cada banco de dados, identifique as tabelas sem chave primária ou chave única:

   SELECT COUNT(*) AS count
   FROM information_schema.tables t
   LEFT JOIN information_schema.table_constraints tc
       ON t.table_name = tc.table_name
       AND t.table_schema = tc.table_schema
       AND (tc.constraint_type = 'PRIMARY KEY' OR tc.constraint_type = 'UNIQUE')
   JOIN pg_class c
       ON t.table_name = c.relname
   JOIN pg_namespace ns
       ON c.relnamespace = ns.oid
       AND ns.nspname = t.table_schema
   WHERE t.table_type = 'BASE TABLE'
       AND tc.constraint_type IS NULL
       AND t.table_schema NOT IN ('pg_catalog', 'information_schema')
       AND c.relreplident != 'f';

2. Defina REPLICA IDENTITY FULL na tabela (se não for viável adicionar uma chave):

   ALTER TABLE name REPLICA IDENTITY FULL;

3. Ou adicione uma chave primária ou chave única:

   -- Primary key
   ALTER TABLE name
       ADD CONSTRAINT constraint_name PRIMARY KEY (column_name);
   
   -- Unique key
   ALTER TABLE name
       ADD CONSTRAINT constraint_name UNIQUE (column_name);

Para mais informações, consulte a documentação do PostgreSQL sobre restrições de unicidade.

Visualizações materializadas

Formato do erro: Materialized views in database: {0}. Total databases: {1}

Causa: A replicação lógica não consegue replicar visualizações materializadas.

Solução: Exclua todas as visualizações materializadas.

1. Em cada banco de dados, identifique as visualizações materializadas:

   SELECT COUNT(*) AS count, relkind
   FROM pg_class
   WHERE relkind IN ('m')
   GROUP BY relkind;

2. Exclua as visualizações materializadas:

   DROP MATERIALIZED VIEW IF EXISTS name;

Objetos grandes

Formato do erro: Large objects in database: {0}. Total databases: {1}

Causa: A replicação lógica não consegue replicar objetos grandes armazenados no pg_largeobject.

Solução: Exclua os objetos grandes.

1. Em cada banco de dados, contabilize os objetos grandes:

   SELECT COUNT(*) AS count
   FROM pg_largeobject_metadata;

2. Exclua cada objeto grande:

   SELECT lo_unlink(largeobject_oid);

Extensões proibidas

Formato do erro: Logical replication prohibited extensions in database: {0}. Total databases: {1}

Causa: As seguintes extensões são incompatíveis com a replicação lógica e não podem estar presentes durante um upgrade no modo zero-downtime: pg_partman, pg_cron, pg_active e pglogical.

Solução: Exclua temporariamente as extensões incompatíveis.

1. Em cada banco de dados, verifique se alguma extensão proibida está instalada:

   SELECT COUNT(*) AS count
   FROM pg_extension
   WHERE extname IN ('pg_partman', 'pg_cron', 'pg_active', 'pglogical');

2. Exclua cada extensão proibida:

   DROP EXTENSION extension_name;

Requisitos de parâmetros não atendidos

Formato do erro: Logical replication requires wal_level to be logical, max_wal_sender and max_replication_slots to be at least {0}, instance wal_level is: {1}, max_wal_sender is: {2}, max_replication_slots is: {3}

Causa: Um ou mais dos seguintes parâmetros não atendem aos requisitos de replicação lógica: wal_level, max_wal_sender ou max_replication_slots.

Solução: Atualize os valores dos parâmetros. Algumas alterações exigem reinicialização para entrar em vigor. Para mais informações, consulte Definir os parâmetros de uma instância.