Noções Básicas de Extensões

Extensões do PostgreSQL adicionam tipos, funções e workers em segundo plano sem precisar fazer fork do servidor. Instale-as deliberadamente, acompanhe as versões e saiba quais exigem reinicialização via shared_preload_libraries.

Receita

-- Lista extensões disponíveis no cluster
SELECT name, default_version, installed_version, comment
FROM pg_available_extensions
ORDER BY name;
 
-- Instala em um schema (padrão comum para PostGIS, pgvector)
CREATE SCHEMA IF NOT EXISTS extensions;
CREATE EXTENSION IF NOT EXISTS vector
  WITH SCHEMA extensions
  VERSION '0.8.0';
 
-- Extensões que precisam de preload (exemplo: pg_stat_statements)
-- postgresql.conf:
-- shared_preload_libraries = 'pg_stat_statements'
-- Em seguida, reinicie e, depois:
CREATE EXTENSION pg_stat_statements;

Quando usar isso: Você precisa de funcionalidades além do SQL principal (vetores, geoespacial, estatísticas, auditoria) e deseja que elas sejam versionadas como dependências de aplicativos.

Exemplo de Trabalho

-- Inicializa um novo banco de dados com extensões fixadas
BEGIN;
 
CREATE SCHEMA IF NOT EXISTS extensions;
GRANT USAGE ON SCHEMA extensions TO app_role;
 
CREATE EXTENSION IF NOT EXISTS pgcrypto WITH SCHEMA extensions;
CREATE EXTENSION IF NOT EXISTS vector WITH SCHEMA extensions VERSION '0.8.0';
 
-- Verifica o que está instalado
SELECT e.extname,
       e.extversion,
       n.nspname AS schema
FROM pg_extension e
JOIN pg_namespace n ON n.oid = e.extnamespace
WHERE e.extname IN ('pgcrypto', 'vector');
 
COMMIT;

O que isso demonstra:

Schema extensions dedicado mantém o public limpo
VERSION fixa a extensão no momento da instalação
pg_extension é a fonte de verdade do inventário
Algumas extensões são agnósticas de schema; outras (PostGIS) têm requisitos de ordenação

Mergulho Profundo

Como as Extensões Funcionam

Extensões enviam scripts SQL mais bibliotecas C opcionais registradas em pg_available_extensions.
CREATE EXTENSION executa o script de instalação e registra metadados em pg_extension.
ALTER EXTENSION ... UPDATE aplica scripts de migração entre versões.
DROP EXTENSION remove objetos que a extensão possui; use CASCADE apenas após revisão.

shared_preload_libraries

Extensão	Preload necessário?	Notas
`pg_stat_statements`	Sim	Rastreia estatísticas de consulta normalizadas
`pg_cron`	Sim	Agendador de tarefas em segundo plano
`vector` (pgvector)	Não	Carrega ao `CREATE EXTENSION`
`postgis`	Não	Instalação SQL pesada, sem preload

Extensões de preload exigem uma reinicialização completa do servidor. Planeje janelas de manutenção antes de ativá-las em produção.

Versão e Empacotamento

-- Vê instalado vs disponível
SELECT extname,
       extversion AS installed,
       (SELECT default_version
        FROM pg_available_extensions a
        WHERE a.name = e.extname) AS available_default
FROM pg_extension e;

Em Postgres gerenciado (RDS, Cloud SQL, Neon), apenas extensões pré-aprovadas aparecem em pg_available_extensions. Clusters auto-hospedados instalam pacotes via SO (postgresql-18-pgvector, postgis) antes que CREATE EXTENSION seja bem-sucedido.

Notas SQL

Conceda USAGE no schema da extensão; evite conceder CREATE em public para roles de aplicativo.
Use IF NOT EXISTS em scripts de migração idempotentes.
Documente as versões das extensões em infraestrutura como código junto com a versão principal do Postgres.

Armadilhas

Pacote de SO ausente - CREATE EXTENSION vector falha com "could not open extension control file." Correção: Instale primeiro o pacote de extensão para sua versão principal do Postgres.
Schema errado - Objetos PostGIS caem em public por padrão e poluem os caminhos de busca. Correção: CREATE EXTENSION postgis WITH SCHEMA extensions; em bancos de dados novos.
Preload sem reinicialização - Adicionar shared_preload_libraries e executar CREATE EXTENSION imediatamente falha. Correção: Reinicie o Postgres, depois crie a extensão.
Instalação apenas para superusuário - A maioria das extensões requer privilégios elevados. Correção: DBA instala; role do aplicativo recebe apenas USAGE do schema.
Discrepância de versão entre réplicas - Standby tem binários de extensão mais antigos após um upgrade do primário. Correção: Atualize todos os nós para pacotes de extensão correspondentes antes de ALTER EXTENSION UPDATE.
DROP EXTENSION CASCADE - Remove objetos dependentes que você não esperava. Correção: Audite pg_depend antes de remover; prefira atualizações ALTER EXTENSION em vez de reinstalar.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Apenas Postgres Core	CRUD simples, sem tipos especiais	Você precisa de vetores, GIS ou estatísticas avançadas
Bibliotecas em camada de aplicativo	Extensão não disponível no host gerenciado	Você precisa de pesquisa indexada em SQL
Foreign data wrappers	Dados vivem em outro sistema	Latência e complexidade de junção são inaceitáveis
Serviço de busca/OLAP separado	Escala massiva, equipe dedicada	O custo operacional de outro datastore é muito alto

FAQs

Posso instalar extensões sem ser superusuário?

PostgreSQL 18 suporta extensões confiáveis para não superusuários quando o privilégio `CREATE` é concedido na extensão. A maioria das organizações ainda centraliza as instalações com a role de DBA.

Onde ficam os arquivos de extensão no disco?

Arquivos de controle e SQL ficam em `SHAREDIR/extension/`. Bibliotecas ficam em `PKGLIBDIR`. Use `pg_config --sharedir` para localizá-los.

CREATE EXTENSION é executado em uma transação?

Sim. Uma instalação falha reverte. Mudanças de configuração de preload ainda exigem reinicialização fora de qualquer transação.

Como movo uma extensão para outro schema?

Não suportado diretamente. Remova e recrie em bancos de dados vazios, ou aceite o schema original em sistemas existentes.

Qual a diferença entre extensão e linguagem procedural?

`plpgsql` é instalado como uma extensão. Linguagens e tipos seguem o mesmo modelo de inventário `pg_extension`.

Duas bases de dados podem ter extensões diferentes?

Sim. Extensões são por banco de dados. Configurações de cluster como `shared_preload_libraries` se aplicam a todos os bancos de dados na instância.

Como bloqueio extensões?

Ignore `allow_in_place_tablespaces`; use hooks `pg_extension_config` ou revogue `CREATE` em extensões não confiáveis. Veja o artigo sobre política de lista de permissões.

Extensões sobrevivem ao pg_upgrade?

Geralmente sim se os pacotes existirem para a nova versão principal. Execute `ALTER EXTENSION UPDATE` novamente após o upgrade.

E extensões em templates?

Instale em `template1` para que novos bancos de dados as herdem. Tenha cuidado: cada novo DB paga o custo de instalação.

Como listo objetos de propriedade de extensão?

`SELECT * FROM pg_depend WHERE refobjid = (SELECT oid FROM pg_extension WHERE extname = 'vector');`

Relacionados

Extensões Confiáveis vs Não Confiáveis - revisão de segurança antes da instalação
Caminho de Upgrade de Extensão - atualizações de versão menor e maior
Política de Lista de Permissões de Extensão - governança corporativa
Melhores Práticas de Extensões - checklist operacional
Noções Básicas de pgvector - tipo de vetor e operadores

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.

Noções Básicas de Extensões

Receita

-- Lista extensões disponíveis no cluster
SELECT name, default_version, installed_version, comment
FROM pg_available_extensions
ORDER BY name;
 
-- Instala em um schema (padrão comum para PostGIS, pgvector)
CREATE SCHEMA IF NOT EXISTS extensions;
CREATE EXTENSION IF NOT EXISTS vector
  WITH SCHEMA extensions
  VERSION '0.8.0';
 
-- Extensões que precisam de preload (exemplo: pg_stat_statements)
-- postgresql.conf:
-- shared_preload_libraries = 'pg_stat_statements'
-- Em seguida, reinicie e, depois:
CREATE EXTENSION pg_stat_statements;

Quando usar isso: Você precisa de funcionalidades além do SQL principal (vetores, geoespacial, estatísticas, auditoria) e deseja que elas sejam versionadas como dependências de aplicativos.

Exemplo de Trabalho

-- Inicializa um novo banco de dados com extensões fixadas
BEGIN;
 
CREATE SCHEMA IF NOT EXISTS extensions;
GRANT USAGE ON SCHEMA extensions TO app_role;
 
CREATE EXTENSION IF NOT EXISTS pgcrypto WITH SCHEMA extensions;
CREATE EXTENSION IF NOT EXISTS vector WITH SCHEMA extensions VERSION '0.8.0';
 
-- Verifica o que está instalado
SELECT e.extname,
       e.extversion,
       n.nspname AS schema
FROM pg_extension e
JOIN pg_namespace n ON n.oid = e.extnamespace
WHERE e.extname IN ('pgcrypto', 'vector');
 
COMMIT;

O que isso demonstra:

Schema extensions dedicado mantém o public limpo
VERSION fixa a extensão no momento da instalação
pg_extension é a fonte de verdade do inventário
Algumas extensões são agnósticas de schema; outras (PostGIS) têm requisitos de ordenação

Mergulho Profundo

Como as Extensões Funcionam

Extensões enviam scripts SQL mais bibliotecas C opcionais registradas em pg_available_extensions.
CREATE EXTENSION executa o script de instalação e registra metadados em pg_extension.
ALTER EXTENSION ... UPDATE aplica scripts de migração entre versões.
DROP EXTENSION remove objetos que a extensão possui; use CASCADE apenas após revisão.

shared_preload_libraries

Extensão	Preload necessário?	Notas
`pg_stat_statements`	Sim	Rastreia estatísticas de consulta normalizadas
`pg_cron`	Sim	Agendador de tarefas em segundo plano
`vector` (pgvector)	Não	Carrega ao `CREATE EXTENSION`
`postgis`	Não	Instalação SQL pesada, sem preload

Extensões de preload exigem uma reinicialização completa do servidor. Planeje janelas de manutenção antes de ativá-las em produção.

Versão e Empacotamento

-- Vê instalado vs disponível
SELECT extname,
       extversion AS installed,
       (SELECT default_version
        FROM pg_available_extensions a
        WHERE a.name = e.extname) AS available_default
FROM pg_extension e;

Notas SQL

Conceda USAGE no schema da extensão; evite conceder CREATE em public para roles de aplicativo.
Use IF NOT EXISTS em scripts de migração idempotentes.
Documente as versões das extensões em infraestrutura como código junto com a versão principal do Postgres.

Armadilhas

Pacote de SO ausente - CREATE EXTENSION vector falha com "could not open extension control file." Correção: Instale primeiro o pacote de extensão para sua versão principal do Postgres.
Schema errado - Objetos PostGIS caem em public por padrão e poluem os caminhos de busca. Correção: CREATE EXTENSION postgis WITH SCHEMA extensions; em bancos de dados novos.
Preload sem reinicialização - Adicionar shared_preload_libraries e executar CREATE EXTENSION imediatamente falha. Correção: Reinicie o Postgres, depois crie a extensão.
Instalação apenas para superusuário - A maioria das extensões requer privilégios elevados. Correção: DBA instala; role do aplicativo recebe apenas USAGE do schema.
Discrepância de versão entre réplicas - Standby tem binários de extensão mais antigos após um upgrade do primário. Correção: Atualize todos os nós para pacotes de extensão correspondentes antes de ALTER EXTENSION UPDATE.
DROP EXTENSION CASCADE - Remove objetos dependentes que você não esperava. Correção: Audite pg_depend antes de remover; prefira atualizações ALTER EXTENSION em vez de reinstalar.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Apenas Postgres Core	CRUD simples, sem tipos especiais	Você precisa de vetores, GIS ou estatísticas avançadas
Bibliotecas em camada de aplicativo	Extensão não disponível no host gerenciado	Você precisa de pesquisa indexada em SQL
Foreign data wrappers	Dados vivem em outro sistema	Latência e complexidade de junção são inaceitáveis
Serviço de busca/OLAP separado	Escala massiva, equipe dedicada	O custo operacional de outro datastore é muito alto

FAQs

Posso instalar extensões sem ser superusuário?

Onde ficam os arquivos de extensão no disco?

Arquivos de controle e SQL ficam em `SHAREDIR/extension/`. Bibliotecas ficam em `PKGLIBDIR`. Use `pg_config --sharedir` para localizá-los.

CREATE EXTENSION é executado em uma transação?

Sim. Uma instalação falha reverte. Mudanças de configuração de preload ainda exigem reinicialização fora de qualquer transação.

Como movo uma extensão para outro schema?

Não suportado diretamente. Remova e recrie em bancos de dados vazios, ou aceite o schema original em sistemas existentes.

Qual a diferença entre extensão e linguagem procedural?

`plpgsql` é instalado como uma extensão. Linguagens e tipos seguem o mesmo modelo de inventário `pg_extension`.

Duas bases de dados podem ter extensões diferentes?

Sim. Extensões são por banco de dados. Configurações de cluster como `shared_preload_libraries` se aplicam a todos os bancos de dados na instância.

Como bloqueio extensões?

Ignore `allow_in_place_tablespaces`; use hooks `pg_extension_config` ou revogue `CREATE` em extensões não confiáveis. Veja o artigo sobre política de lista de permissões.

Extensões sobrevivem ao pg_upgrade?

Geralmente sim se os pacotes existirem para a nova versão principal. Execute `ALTER EXTENSION UPDATE` novamente após o upgrade.

E extensões em templates?

Instale em `template1` para que novos bancos de dados as herdem. Tenha cuidado: cada novo DB paga o custo de instalação.

Como listo objetos de propriedade de extensão?

`SELECT * FROM pg_depend WHERE refobjid = (SELECT oid FROM pg_extension WHERE extname = 'vector');`

Relacionados

Extensões Confiáveis vs Não Confiáveis - revisão de segurança antes da instalação
Caminho de Upgrade de Extensão - atualizações de versão menor e maior
Política de Lista de Permissões de Extensão - governança corporativa
Melhores Práticas de Extensões - checklist operacional
Noções Básicas de pgvector - tipo de vetor e operadores

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.

Noções Básicas de Extensões

Buscar na documentação

Noções Básicas de Extensões