PostgreSQL • Funções

As funções (SQL/PLpgSQL, entre outras linguagens) encapsulam regras de negócio e retornam um valor (escalares, registros, SETOF). São chamadas em SELECT, WHERE, ORDER BY, JOIN, triggers e até DEFAULT de colunas (quando apropriado). Aqui você lista, cria, edita e remove funções.

Abrir a área de Funções

1. Conecte-se à sua conexão PostgreSQL e selecione o banco.
2. Escolha o schema (ex.: public).
3. Na árvore, abra Funções para listar as existentes e toque em uma para ver assinatura, retorno e definição.

Componentes de uma função

• Nome e schema: qualificam a função (ex.: public.fn_total_pedidos).
• Parâmetros: nome + tipo (ex.: p_cliente_id INTEGER).
• Tipo de retorno: escalar (INTEGER, NUMERIC(12,2), TEXT, BOOLEAN, TIMESTAMP), TABLE(...) ou SETOF.
• Linguagem: sql, plpgsql (mais comum), entre outras habilitadas.
• Volatilidade: IMMUTABLE, STABLE ou VOLATILE (impacta plano de execução/cache).
• Security: SECURITY INVOKER (padrão) ou SECURITY DEFINER (executa com permissões do dono).
• Paralelismo/Custo (quando configurável): dicas para o otimizador.

Criar função

1. Na seção Funções, toque em Criar Função.
2. Preencha:
   • Nome e schema.
   • Parâmetros (nome e tipo) e o tipo de retorno.
   • Linguagem (plpgsql para blocos; sql para expressões simples).
   • Corpo (código) — no PL/pgSQL, use DECLARE (opcional) e BEGIN ... END.
   • (Opcional) Volatilidade e SECURITY DEFINER (use com cuidado).
3. Revise o resumo e toque em Criar.

Dica: Teste a lógica no Executar SELECT com entradas reais antes de publicar em produção.

Editar função

• Abra a função e toque em Editar.
• Atualize parâmetros, retorno, volatilidade, security ou o corpo.
• Confirme em Salvar. Em geral, a alteração é aplicada via CREATE OR REPLACE FUNCTION.

Atenção: mudar assinatura (tipos/ordem de parâmetros) pode quebrar chamadas existentes. Prefira novas versões quando possível.

Remover função

1. Selecione a função e toque em Remover.
2. Confirme a exclusão. Verifique dependências (views, triggers) antes de remover.

Volatilidade (como escolher)

• IMMUTABLE: mesmo input ⇒ mesmo output, sem ler tabelas (ex.: formatações, cálculos puros). Permite otimizações agressivas.
• STABLE: não muda dentro da mesma consulta, mas pode ler tabelas (ex.: configurações). Cache por execução.
• VOLATILE: pode mudar a qualquer momento (ex.: now(), leituras dinâmicas). É o padrão.

Security Definer (quando usar)

SECURITY DEFINER executa com as permissões do dono da função. Útil para expor operações controladas a usuários com acesso restrito.

• Crie um papel dedicado como owner da função.
• Restrinja o que a função faz e valide parâmetros — evite SQL dinâmico inseguro.
• Conceda EXECUTE apenas aos papéis que precisam.

Retorno de conjuntos (SETOF / TABLE)

• Use SETOF ou RETURNS TABLE(...) para retornar linhas múltiplas.
• Chame com SELECT * FROM minha_funcao(...). Combine com filtros/ordenação conforme necessário.

Performance

• Evite loops linha a linha sobre tabelas grandes; prefira SQL set-based.
• Marque corretamente a volatilidade para permitir cache do plano.
• Funções em WHERE/ORDER BY podem impedir uso de índices; considere colunas derivadas/indexadas.

Erros comuns (e soluções)

“Função não existe / assinatura incorreta”

• Confirme o schema e os tipos dos parâmetros (Postgres diferencia por assinatura).

“Permissão negada”

• Garanta EXECUTE na função e SELECT/UPDATE nas tabelas acessadas por ela.

“Mutating table / recursão não intencional”

• Evite a função alterar e ler a mesma linha sem controle; revise triggers relacionadas.

“Queda de desempenho após usar função”

• Troque lógica para set-based, ajuste índices, revise volatilidade e avalie materializações/temporárias.

Boas práticas

• Nomeie padronizado (ex.: fn_ para funções puras, fx_ para utilitárias).
• Documente com COMMENT ON FUNCTION (parâmetros, retorno, exemplos).
• Mantenha funções curtas e específicas; reutilize componentes.
• Teste em homolog e monitore nos primeiros usos em produção.

Ferramentas relacionadas

• Usar função em triggers: PostgreSQL • Triggers.
• Ver estrutura e constraints: Estrutura / Constraints.
• Executar consultas de teste: Executar SELECT.

Próximo: PostgreSQL • Executar SELECT • Voltar: PostgreSQL • Triggers