O Sistema de Extensões
As extensões do PostgreSQL são o mecanismo sancionado para adicionar tipos, operadores, funções, métodos de acesso a índices e workers de background a um banco de dados em execução sem modificar ou criar forks do próprio servidor.
Cada extensão que uma equipe habilita se torna uma parte permanente e versionada do catálogo desse banco de dados, portanto, entender a engrenagem por trás de CREATE EXTENSION é mais importante do que memorizar a sintaxe do comando.
Esta página constrói o modelo mental do sistema de extensões como um todo: o que uma extensão realmente é no disco, como o servidor decide quando o código precisa ser carregado, como as versões se relacionam umas com as outras e onde o limite de confiança se encontra.
Resumo
- Uma extensão é um pacote versionado de objetos SQL (e opcionalmente código compilado) que o PostgreSQL rastreia como uma única unidade de dependência em seu catálogo.
- Por que Importa: Extensões permitem que um banco de dados cresça com novas capacidades (busca vetorial, tipos geoespaciais, criptografia, agendamento) sem um fork do servidor, ao mesmo tempo em que permanece atualizável, auditável e reversível.
- Conceitos Chave: arquivo de controle, script de extensão,
shared_preload_libraries,pg_extension, grafo de dependência, limite de confiança. - Quando Usar: Recorra a este modelo mental sempre que estiver decidindo se uma extensão precisa de reinicialização, se é seguro concedê-la a uma role de aplicação ou por que um caminho de atualização está bloqueado.
- Limitações / Trade-offs: Extensões são por banco de dados, não globais, e qualquer extensão contendo código C é executada dentro do processo do servidor com o mesmo espaço de memória do PostgreSQL principal.
- Tópicos Relacionados: Mecânica de
CREATE EXTENSION, extensões confiáveis vs. não confiáveis, caminhos de atualização de extensão, governança de lista de permissões de extensão.
Fundamentos
Uma extensão não é um pacote baixado como um pacote npm ou pip; é um conjunto de arquivos que já devem existir no sistema de arquivos da máquina antes que qualquer SQL seja executado.
No mínimo, uma extensão envia um arquivo de controle (extname.control) que declara seu nome, versão padrão, comentário e se é relocável.
Ao lado do arquivo de controle ficam um ou mais scripts SQL que definem os objetos reais: tipos, funções, operadores, casts ou rotinas de suporte a índice.
Algumas extensões adicionam uma terceira peça, uma biblioteca compartilhada compilada (um arquivo .so no Linux), à qual as definições de função do script SQL apontam via AS 'MODULE_PATHNAME'.
CREATE EXTENSION lê o arquivo de controle, executa o script de instalação correspondente dentro de uma transação e registra o resultado como uma única linha no catálogo pg_extension.
Essa linha de catálogo é o que torna uma extensão um objeto de primeira classe e rastreável, em vez de um monte solto de funções que alguém executou uma vez.
pg_available_extensions mostra quais arquivos de controle o servidor pode ver no disco, enquanto pg_extension mostra o que foi realmente instalado no banco de dados atual.
Uma analogia útil é uma arquitetura de plugin: o arquivo de controle é o manifesto, o script SQL é o instalador e a biblioteca compartilhada (quando presente) é o binário compilado do plugin.
Como o manifesto e o instalador são apenas arquivos, o fato de uma extensão estar "disponível" não diz nada sobre se o pacote do sistema operacional subjacente foi instalado naquele host.
Mecânicas e Interações
O servidor trata o código da extensão de duas maneiras muito diferentes, dependendo de quando ele precisa ser executado.
Extensões puramente SQL (tipos, funções escritas em SQL ou PL/pgSQL, views) não precisam de nada além da consulta normal de catálogo que já ocorre para qualquer objeto de banco de dados.
Extensões suportadas por uma biblioteca compartilhada C são carregadas dinamicamente na primeira utilização dentro de um processo backend, da mesma forma que qualquer outro módulo carregável é resolvido.
Um pequeno subconjunto de extensões precisa de algo mais: elas registram workers de background, segmentos de memória compartilhada customizados ou hooks que devem existir antes que o postmaster aceite sua primeira conexão.
Essas extensões devem ser nomeadas em shared_preload_libraries em postgresql.conf, pois o postmaster lê essa configuração uma vez na inicialização e aloca memória compartilhada de acordo.
É por isso que adicionar uma entrada a shared_preload_libraries requer uma reinicialização completa do servidor, enquanto a maioria das chamadas CREATE EXTENSION não.
A relação de dependência entre extensões não é apenas documentação informal, pois o PostgreSQL a registra em pg_depend, e CREATE EXTENSION pode declarar uma lista REQUIRES em seu arquivo de controle para que extensões dependentes sejam instaladas automaticamente ou falhem claramente.
O versionamento segue a mesma lógica de grafo: cada extensão tem uma versão padrão mais um conjunto de scripts de atualização nomeados como extname--1.0--1.1.sql, e ALTER EXTENSION ... UPDATE percorre essa cadeia passo a passo em vez de pular diretamente para a versão de destino.
Se um elo nessa cadeia estiver faltando, por exemplo, um pacote envia 1.0 e 1.2, mas não o script 1.0--1.1 ou 1.1--1.2, a atualização simplesmente não pode prosseguir até que o script ausente seja instalado.
-- O grafo de dependência é consultável, não apenas conceitual
SELECT dep.refobjid::regclass AS depends_on,
ext.extname AS extension
FROM pg_depend dep
JOIN pg_extension ext ON ext.oid = dep.objid
WHERE dep.deptype = 'e';Extensões relocáveis podem ser movidas para um esquema diferente após a instalação, enquanto as não relocáveis (PostGIS é um exemplo comum) codificam referências qualificadas por esquema em seu script de instalação e resistem a uma movimentação limpa.
Considerações Avançadas e Aplicações
Em escala, o sistema de extensões se torna um problema de governança tanto quanto um problema técnico, pois cada extensão baseada em C é executada dentro do mesmo processo e espaço de memória do núcleo do PostgreSQL.
Esse espaço de memória compartilhada é exatamente o motivo pelo qual extensões não confiáveis historicamente exigiam superusuário, pois uma biblioteca compartilhada maliciosa ou com bugs pode ler memória arbitrária do servidor, travar o postmaster ou contornar a segurança em nível de linha.
O mecanismo de extensões confiáveis do PostgreSQL reduz esse risco permitindo que extensões específicas e auditadas sejam instaladas por uma role não superusuária que apenas detém o privilégio CREATE no banco de dados de destino, sem conceder a essa role a capacidade de carregar código C arbitrário.
Provedores de nuvem gerenciados se apoiam nesse mesmo limite da outra direção, curando pg_available_extensions para uma lista de permissões verificada, para que os clientes nunca vejam arquivos de controle para extensões que a plataforma não revisou.
Conflitos de extensão são outra preocupação avançada: duas extensões podem definir um operador ou função com o mesmo nome no mesmo esquema, e a que for instalada por segundo simplesmente falha ou ofusca silenciosamente a primeira, dependendo da ordem do caminho de busca.
A orquestração de atualizações se acumula em um cluster, pois um conjunto de réplicas gerenciado pelo Patroni precisa de binários de biblioteca compartilhada correspondentes em todos os nós antes que ALTER EXTENSION UPDATE seja executado em qualquer lugar, ou a réplica corre o risco de carregar uma versão de biblioteca que seu stream WAL não espera.
O grafo de dependência também é importante para replicação lógica, onde um banco de dados assinante deve ter os mesmos tipos e funções fornecidos pela extensão instalados antes que ele possa aplicar alterações que os referenciem.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| Extensão puramente SQL (sem biblioteca compartilhada) | Sem reinicialização, superfície de ataque mínima, fácil de auditar | Não pode fazer nada em nível de C, como métodos de acesso a índices customizados | Funções utilitárias, wrappers de tipos simples |
| Extensão C sem pré-carga | Funcionalidade rica (tipos, operadores, métodos de índice) | Executa no processo, expande a superfície de revisão de segurança | pgvector, PostGIS, pgcrypto |
Extensão C com shared_preload_libraries | Habilita workers de background e hooks de memória compartilhada | Requer reinicialização planejada para instalação e para cada alteração de configuração | pg_stat_statements, pg_cron |
| Extensão confiável | Instalável sem superusuário, autoatendimento mais rápido | Apenas extensões explicitamente marcadas como confiáveis se qualificam | Equipes delegando instalações limitadas a proprietários de aplicativos |
Conceitos Equivocados Comuns
- "CREATE EXTENSION baixa e compila o código" - não faz isso; o arquivo de controle, os scripts SQL e qualquer biblioteca compartilhada já devem estar presentes no host via um pacote do sistema operacional, e
CREATE EXTENSIONapenas registra e executa o que já existe. - "Toda extensão precisa de uma reinicialização" - apenas extensões listadas em
shared_preload_librariesprecisam, pois essa configuração é lida uma vez na inicialização do postmaster, enquanto a maioria das extensões é ativada imediatamente dentro da sessão atual. - "Extensões são globais para o servidor" - elas são instaladas por banco de dados, então um cluster pode ter
vectorem um banco de dados e nada extra em outro, mesmo que ambos compartilhem o mesmo binário PostgreSQL. - "Confiável significa seguro contra qualquer risco" - confiável apenas significa que a extensão não requer superusuário para ser instalada, não que ela esteja livre de bugs, preocupações com licença ou CVEs.
- "Descartar uma extensão apenas remove seus próprios objetos" -
DROP EXTENSIONpode ser cascateado para qualquer coisa que dependa desses objetos, incluindo views, índices e outras extensões, a menos que você revisepg_dependprimeiro.
FAQs
O que realmente está dentro de uma extensão PostgreSQL?
Um arquivo de controle descrevendo os metadados da extensão, um ou mais scripts SQL de instalação/atualização e, opcionalmente, uma biblioteca compartilhada compilada à qual as definições de função do script SQL se referem.
Onde os arquivos de extensão ficam no disco?
Arquivos de controle e scripts SQL ficam no diretório relatado por pg_config --sharedir, enquanto quaisquer bibliotecas compartilhadas compiladas ficam em pg_config --pkglibdir.
Por que algumas extensões precisam de reinicialização e outras não?
Apenas extensões que registram workers de background, segmentos de memória compartilhada customizados ou hooks de inicialização precisam aparecer em shared_preload_libraries, e essa configuração só é lida quando o postmaster inicia.
CREATE EXTENSION é o mesmo que instalar software?
Não, ele registra e executa scripts SQL contra um conjunto de arquivos já presente; o pacote do sistema operacional subjacente ainda precisa ser instalado separadamente antes que o comando SQL possa ter sucesso.
Como o PostgreSQL sabe que uma extensão depende de outra?
Através da cláusula REQUIRES em um arquivo de controle combinada com linhas de catálogo em pg_depend, que tanto o planejador quanto os comandos DROP/ALTER consultam.
O que acontece se um script de atualização estiver faltando entre duas versões?
ALTER EXTENSION ... UPDATE não pode pular versões, então um script intermediário ausente (por exemplo, 1.1--1.2.sql) bloqueia a cadeia de atualização até que esse arquivo seja instalado.
Extensões são instaladas por banco de dados ou por cluster?
Por banco de dados, com a única exceção de configurações de cluster como shared_preload_libraries que se aplicam a todos os bancos de dados na instância, independentemente de quais realmente usam a extensão.
Qual é a diferença entre uma extensão confiável e uma não confiável?
Uma extensão confiável pode ser instalada por qualquer role com privilégio CREATE no banco de dados, enquanto uma não confiável ainda requer superusuário porque seu script de instalação ou biblioteca compartilhada carrega mais risco.
Duas extensões podem entrar em conflito uma com a outra?
Sim, se elas definirem objetos com o mesmo nome no mesmo esquema, e o PostgreSQL resolver a colisão através das regras normais de caminho de busca e nomenclatura, em vez de qualquer arbitragem ciente de extensão.
Por que provedores de nuvem gerenciada limitam quais extensões posso instalar?
Porque extensões baseadas em C rodam dentro do mesmo processo que o motor do banco de dados, então o provedor curadoria pg_available_extensions para apenas o que sua equipe revisou em termos de estabilidade e segurança.
O sistema de extensões se relaciona com linguagens procedurais como PL/pgSQL?
Sim, linguagens procedurais são instaladas e rastreadas através do mesmo mecanismo pg_extension que qualquer outra extensão.
É seguro apenas usar DROP EXTENSION quando não preciso mais de uma?
Apenas após verificar pg_depend para objetos que a referenciam, pois um descarte em cascata pode remover silenciosamente views, índices ou outras extensões construídas sobre ela.
Relacionados
- Fundamentos de Extensões - a receita passo a passo de
CREATE EXTENSIONeshared_preload_librariespara a qual esta página constrói um modelo mental - Extensões Confiáveis vs. Não Confiáveis - um olhar mais aprofundado sobre o limite de confiança introduzido acima
- Caminho de Atualização de Extensão - o procedimento operacional para percorrer o grafo de atualização de versão
- Política de Lista de Permissões de Extensão - práticas de governança para decidir quais extensões são aprovadas
- Melhores Práticas de Extensões - a lista de verificação operacional que complementa este modelo conceitual
Versões de Stack: 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.