Caminho de Upgrade de Extensão

As versões das extensões se movem independentemente das versões principais do Postgres. Planeje upgrades de pacotes do sistema operacional, ALTER EXTENSION UPDATE e testes de regressão como uma única janela de mudança, especialmente para pgvector e PostGIS.

Receita

-- Verifica a versão atual vs. a versão de destino
SELECT extname, extversion
FROM pg_extension
WHERE extname = 'vector';
 
SELECT name, default_version
FROM pg_available_extensions
WHERE name = 'vector';
 
-- Aplica scripts de upgrade disponíveis
ALTER EXTENSION vector UPDATE TO '0.8.0';
 
-- Verifica
SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';

Quando usar isso: Após aplicar patches no Postgres, implantar novos pacotes de extensão ou antes de construir índices HNSW que exigem uma versão mínima do pgvector.

Exemplo de Trabalho

-- Runbook seguro de upgrade (execute primeiro no staging)
BEGIN;
 
-- 1) Inventário de snapshot
CREATE TEMP TABLE ext_before AS
SELECT extname, extversion FROM pg_extension;
 
-- 2) Atualiza uma extensão
ALTER EXTENSION postgis UPDATE;
 
-- 3) Compara
SELECT b.extname,
       b.extversion AS before_version,
       e.extversion AS after_version
FROM ext_before b
JOIN pg_extension e ON e.extname = b.extname
WHERE b.extversion IS DISTINCT FROM e.extversion;
 
-- 4) Teste de fumaça
SELECT PostGIS_Version();
SELECT ST_Distance(
  ST_MakePoint(-73.9857, 40.7484)::geography,
  ST_MakePoint(-118.2437, 34.0522)::geography
) AS nyc_to_la_meters;
 
COMMIT;

O que isso demonstra:

• O inventário antes e depois evita omissões silenciosas
• ALTER EXTENSION UPDATE sem TO aplica o script mais recente disponível
• Consultas funcionais de teste de fumaça capturam incompatibilidades de SONAME quebradas precocemente
• A transação envolve a mudança de metadados; as bibliotecas do SO já devem corresponder

Análise Detalhada

Mecânicas de Upgrade

1. Camada de SO / pacote - Instale postgresql-18-postgis-3.5 (ou equivalente do fornecedor) em cada nó.
2. Camada de banco de dados - ALTER EXTENSION name UPDATE [TO 'version'] executa scripts de migração SQL em EXTENSION(name)/.
3. Camada de índice - Alguns upgrades exigem REINDEX (mudanças na opclass do índice pgvector). Leia as notas de lançamento.

-- Lista os scripts do caminho de upgrade enviados com a extensão
SELECT version, relocatable
FROM pg_available_extension_versions
WHERE name = 'vector'
ORDER BY version;

Versões Menores vs. Maiores de Extensão

Clusters Multi-Nó

• Primário primeiro - Aplique pacotes e ALTER EXTENSION no primário.
• Réplicas - Os pacotes devem existir antes que a replicação reproduza consultas dependentes de extensão.
• Patroni - Sincronização de pacotes do SO em rolling, depois ALTER EXTENSION controlado durante a janela de manutenção.
• Nuvem gerenciada - O fornecedor atualiza o catálogo de extensões; você ainda executa ALTER EXTENSION em cada banco de dados.

Realidade do Rollback

Não existe ALTER EXTENSION DOWNGRADE. Rollback significa restaurar a partir de um backup ou recriar índices após reinstalar pacotes mais antigos (alto risco). Teste upgrades em um clone de snapshot.

Armadilhas

• Incompatibilidade binário/SQL - Novo script SQL com arquivo .so antigo causa falhas em tempo de execução. Correção: Atualize os pacotes em todos os nós antes de ALTER EXTENSION.
• Reindexação de longa duração - A reconstrução do índice HNSW do pgvector bloqueia ou consome I/O. Correção: REINDEX CONCURRENTLY onde suportado; agende fora do horário de pico.
• Bancos de dados esquecidos - Extensão atualizada em appdb, mas não em analytics. Correção: Percorra todos os bancos de dados: \l + ALTER EXTENSION por banco de dados.
• Nomes de opclass que quebram - Consultas do cliente referenciam classes de operador antigas. Correção: Pesquise o codebase em busca de definições de índice; migre em fases de expansão-contração.
• Extras de topologia PostGIS - Extensões separadas (postgis_topology) precisam de seu próprio UPDATE. Correção: Inventarie todas as linhas postgis* em pg_extension.
• Derivação de replicação lógica - O assinante não possui a versão da extensão. Correção: Corresponda às versões das extensões antes de assinar publicações com muitas DDLs.

Alternativas

FAQs

Relacionados

• Noções Básicas de Extensões - instalar e pré-carregar
• Extensões Confiáveis vs. Não Confiáveis - revisão de segurança
• Índices IVFFlat vs HNSW - implicações de reconstrução de índice
• Flyway e Liquibase - automação de migração
• Melhores Práticas de Extensões - fixar versões em IaC

Versões da Pilha: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PostGIS 3.5+, pgbouncer 1.x e Patroni 3.x.