Introdução
Neste laboratório, você explorará técnicas de tratamento de erros no PostgreSQL usando sua linguagem procedural, PL/pgSQL. Você aprenderá a criar funções que podem lidar com erros potenciais de forma elegante, em vez de falhar. O laboratório abrange o envio de mensagens informativas, a captura de exceções específicas como "divisão por zero" e o registro de detalhes de erros em uma tabela de banco de dados para revisão posterior. Ao final, você entenderá como construir funções de banco de dados mais robustas e confiáveis.
Emitindo Avisos (Notices) e Alertas (Warnings)
Nesta etapa, você aprenderá a usar a instrução RAISE em uma função PL/pgSQL. A instrução RAISE é útil para fornecer mensagens informativas, avisos ou saída de depuração sem interromper a execução da função.
Primeiro, conecte-se ao terminal interativo do PostgreSQL, psql, como o usuário postgres. Todos os comandos SQL subsequentes neste laboratório serão executados dentro deste terminal.
sudo -u postgres psql
Agora você verá o prompt do psql, que se parece com postgres=#.
Vamos criar uma função chamada greet que recebe um nome como entrada e emite um NOTICE. Notices são mensagens de baixa prioridade.
Execute o seguinte comando SQL no shell psql:
CREATE OR REPLACE FUNCTION greet(name TEXT)
RETURNS TEXT AS $$
BEGIN
RAISE NOTICE 'Greeting function called with name: %', name;
RETURN 'Hello, ' || name;
END;
$$ LANGUAGE plpgsql;
Esta função recebe um argumento name. A linha RAISE NOTICE '...', name; gera uma mensagem de aviso (notice). O % é um placeholder que é substituído pelo valor da variável name.
Agora, chame a função para vê-la em ação:
SELECT greet('LabEx');
A saída mostra tanto a mensagem de aviso (notice) quanto o valor de retorno da função:
NOTICE: Greeting function called with name: LabEx
greet
-----------
Hello, LabEx
(1 row)
Você também pode emitir mensagens com um nível de severidade mais alto, como WARNING. Vamos modificar a função para emitir um aviso se o nome de entrada estiver vazio.
CREATE OR REPLACE FUNCTION greet(name TEXT)
RETURNS TEXT AS $$
BEGIN
IF name IS NULL OR name = '' THEN
RAISE WARNING 'Input name is empty or NULL.';
RETURN 'Hello, stranger';
ELSE
RAISE NOTICE 'Greeting function called with name: %', name;
RETURN 'Hello, ' || name;
END IF;
END;
$$ LANGUAGE plpgsql;
Agora, chame a função com uma string vazia para acionar o aviso:
SELECT greet('');
Desta vez, você verá uma mensagem WARNING em vez de um NOTICE:
WARNING: Input name is empty or NULL.
greet
------------------
Hello, stranger
(1 row)
Você usou com sucesso RAISE para gerar diferentes tipos de mensagens de dentro de uma função.
Disparando e Capturando uma Exceção
Nesta etapa, você aprenderá a lidar com erros de tempo de execução, conhecidos como exceções. Uma exceção não tratada encerrará imediatamente sua função. Primeiro, você criará uma função que falha e, em seguida, a modificará para capturar a exceção de forma elegante.
Vamos criar uma função simple_divide que realiza divisão inteira. Esta função tem uma falha potencial: ela travará se você tentar dividir por zero.
CREATE OR REPLACE FUNCTION simple_divide(numerator INTEGER, denominator INTEGER)
RETURNS INTEGER AS $$
BEGIN
RETURN numerator / denominator;
END;
$$ LANGUAGE plpgsql;
Primeiro, chame a função com entradas válidas para confirmar que ela funciona corretamente:
SELECT simple_divide(10, 2);
A saída será o resultado da divisão:
simple_divide
---------------
5
(1 row)
Agora, chame a função com um denominador zero para acionar uma exceção:
SELECT simple_divide(10, 0);
Este comando falhará e retornará uma mensagem de erro. A execução da função é abortada.
ERROR: division by zero
CONTEXT: PL/pgSQL function simple_divide(integer,integer) line 3 at RETURN
Esta é uma exceção não tratada. Para evitar que a função trave, você pode usar um bloco EXCEPTION. Vamos criar uma nova função safe_divide que inclua tratamento de erros.
CREATE OR REPLACE FUNCTION safe_divide(numerator INTEGER, denominator INTEGER)
RETURNS INTEGER AS $$
BEGIN
RETURN numerator / denominator;
EXCEPTION
WHEN division_by_zero THEN
RAISE NOTICE 'Error: Cannot divide by zero.';
RETURN NULL;
END;
$$ LANGUAGE plpgsql;
Veja como o bloco EXCEPTION funciona:
BEGIN...END;: Isso define um bloco de código.EXCEPTION: Esta palavra-chave inicia a seção de tratamento de exceções.WHEN division_by_zero THEN: Isso especifica que o código a seguir deve ser executado apenas quando ocorrer um errodivision_by_zero.- O código dentro do manipulador emite um aviso (notice) e retorna
NULLem vez de travar.
Agora, chame a nova função safe_divide com um denominador zero:
SELECT safe_divide(10, 0);
Desta vez, a função não trava. Ela captura a exceção, exibe seu aviso personalizado e retorna NULL.
NOTICE: Error: Cannot divide by zero.
safe_divide
-------------
(1 row)
Você capturou com sucesso uma exceção específica e controlou a saída da função.
Registrando Erros em uma Tabela
Capturar exceções é bom, mas para auditoria e depuração, geralmente é melhor registrar erros em um local persistente, como uma tabela. Nesta etapa, você modificará a função safe_divide para gravar detalhes do erro na tabela error_log que foi criada durante a configuração do laboratório.
Primeiro, vamos examinar a estrutura da tabela error_log usando o comando \d no psql.
\d error_log
Você verá as colunas da tabela, que incluem um id auto-incrementável, um timestamp, a message de erro e o function_name.
Table "public.error_log"
Column | Type | Collation | Nullable | Default
---------------+-----------------------------+-----------+----------+----------------------------------------------------
id | integer | | not null | nextval('error_log_id_seq'::regclass)
timestamp | timestamp without time zone | | | (now() AT TIME ZONE 'utc'::text)
message | text | | |
function_name | text | | |
Indexes:
"error_log_pkey" PRIMARY KEY, btree (id)
Agora, vamos modificar a função safe_divide. No bloco EXCEPTION, você adicionará uma instrução INSERT para registrar o erro antes de retornar.
CREATE OR REPLACE FUNCTION safe_divide(numerator INTEGER, denominator INTEGER)
RETURNS INTEGER AS $$
BEGIN
RETURN numerator / denominator;
EXCEPTION
WHEN division_by_zero THEN
INSERT INTO error_log (message, function_name)
VALUES ('Division by zero occurred!', 'safe_divide');
RAISE NOTICE 'Error: Cannot divide by zero. Details logged.';
RETURN NULL;
END;
$$ LANGUAGE plpgsql;
Agora, chame a função novamente para acionar o erro e a nova lógica de registro:
SELECT safe_divide(10, 0);
A função retornará NULL como antes, mas também realizou uma escrita no banco de dados. Para verificar isso, consulte a tabela error_log para ver a nova entrada.
SELECT function_name, message FROM error_log;
A saída deve mostrar o erro registrado:
function_name | message
---------------+----------------------------
safe_divide | Division by zero occurred!
(1 row)
Isso confirma que sua lógica de tratamento de erros agora é capaz de persistir informações de erro para análise posterior.
Tratando Exceções Gerais com OTHERS
Até agora, você lidou com um erro muito específico: division_by_zero. Mas e quanto a outros erros inesperados? PL/pgSQL fornece um manipulador de exceção de propósito geral OTHERS para capturar qualquer erro que não tenha sido capturado por uma cláusula WHEN mais específica.
Nesta etapa, você aprimorará a função safe_divide para lidar com qualquer exceção possível. Você também usará duas variáveis especiais, SQLSTATE (o código de erro SQL) e SQLERRM (a mensagem de erro SQL), para registrar informações mais detalhadas.
Vamos modificar a função safe_divide mais uma vez.
CREATE OR REPLACE FUNCTION safe_divide(numerator INTEGER, denominator INTEGER)
RETURNS INTEGER AS $$
BEGIN
RETURN numerator / denominator;
EXCEPTION
WHEN division_by_zero THEN
INSERT INTO error_log (message, function_name)
VALUES ('Division by zero occurred!', 'safe_divide');
RAISE NOTICE 'Error: Cannot divide by zero. Details logged.';
RETURN NULL;
WHEN OTHERS THEN
INSERT INTO error_log (message, function_name)
VALUES ('An unexpected error occurred: ' || SQLSTATE || ' - ' || SQLERRM, 'safe_divide');
RAISE NOTICE 'An unexpected error occurred. Details logged.';
RETURN -1;
END;
$$ LANGUAGE plpgsql;
O novo bloco WHEN OTHERS capturará qualquer outro erro. Ele constrói uma mensagem detalhada usando as variáveis SQLSTATE e SQLERRM e a insere no log. Em seguida, retorna -1 para sinalizar que ocorreu um erro genérico.
Embora nossa função atual só possa acionar um erro division_by_zero, essa estrutura a torna muito mais robusta contra modificações futuras ou entradas inesperadas. Por exemplo, se os tipos de entrada fossem alterados para um tipo que pudesse causar overflow, o bloco OTHERS capturaria o erro numeric_value_out_of_range.
Vamos testar o caminho division_by_zero novamente para garantir que ele ainda funcione como esperado. Primeiro, limpe a tabela de log para um teste limpo.
TRUNCATE error_log;
Agora, chame a função:
SELECT safe_divide(10, 0);
Finalmente, verifique o log. Ele deve conter a mensagem específica "Division by zero", confirmando que o primeiro bloco WHEN foi escolhido corretamente.
SELECT message FROM error_log;
message
----------------------------
Division by zero occurred!
(1 row)
Você agora construiu uma função resiliente que lida tanto com erros específicos e antecipados quanto com erros gerais e inesperados.
Resumo
Neste laboratório, você aprendeu os fundamentos do tratamento de erros em PL/pgSQL do PostgreSQL. Você começou usando a instrução RAISE para emitir mensagens NOTICE e WARNING para fins de depuração e informativos. Em seguida, progrediu para o tratamento de exceções em tempo de execução, criando uma função que poderia falhar e, em seguida, implementando um bloco BEGIN...EXCEPTION...END para capturar um erro específico de division_by_zero. Com base nisso, você aprimorou a função para registrar detalhes do erro em uma tabela de banco de dados, fornecendo um registro persistente para auditoria. Finalmente, você tornou a função mais robusta adicionando um manipulador geral WHEN OTHERS para capturar quaisquer erros inesperados, garantindo que sua função possa falhar graciosamente sob várias condições.
