44.9. Funções utilitárias #

O módulo plpy também fornece as funções

plpy.debug(msg, **kwargs)
plpy.log(msg, **kwargs)
plpy.info(msg, **kwargs)
plpy.notice(msg, **kwargs)
plpy.warning(msg, **kwargs)
plpy.error(msg, **kwargs)
plpy.fatal(msg, **kwargs)

As funções plpy.error e plpy.fatal na verdade, geram uma exceção do Python que, se não for capturada, se propaga para a consulta de chamada, fazendo com que a transação ou a subtransação corrente seja interrompida. As funções raise plpy.Error(msg) e raise plpy.Fatal(msg) são equivalentes a chamar plpy.error(msg) e plpy.fatal(msg), respectivamente, mas a forma raise não permite a passagem de argumentos de palavra-chave. As demais funções apenas geram mensagens com diferentes níveis de prioridade. Se as mensagens de uma determinada prioridade serão mostradas ao cliente, escritas no arquivo de registro de eventos do servidor (log), ou as duas coisas, são controlados pelas variáveis de configuração log_min_messages e client_min_messages. Veja Configuração do servidor para obter mais informações.

O argumento msg é fornecido como um argumento posicional. Para manter a compatibilidade com as versões anteriores, pode ser fornecido mais de um argumento posicional. Neste caso, a representação em cadeia de caracteres da tupla de argumentos posicionais torna-se a mensagem mostrada ao cliente.

São aceitos os seguintes argumentos somente de palavra-chave:

detail
hint
sqlstate
schema_name
table_name
column_name
datatype_name
constraint_name

A representação de cadeia de caracteres dos objetos passados ​​como argumentos apenas de palavra-chave é usada para enriquecer as mensagens mostradas ao cliente. Por exemplo:

CREATE FUNCTION raise_custom_exception()
  RETURNS void
AS $$
plpy.error("custom exception message",
           detail="some info about exception",
           hint="hint for users")
$$ LANGUAGE plpython3u;

=# SELECT raise_custom_exception();
ERROR:  plpy.Error: custom exception message
DETAIL:  some info about exception
HINT:  hint for users
CONTEXT:  Traceback (most recent call last):
  PL/Python function "raise_custom_exception", line 4, in <module>
    hint="hint for users")
PL/Python function "raise_custom_exception"

Outro conjunto de funções utilitárias são plpy.quote_literal(string), plpy.quote_nullable(string), e plpy.quote_ident(string). São equivalentes às funções de delimitação nativas descritas em Funções e operadores de cadeia de caracteres. Elas são úteis ao construir consultas ad hoc. Uma instrução PL/Python equivalente ao SQL dinâmico do Exemplo 41.2 seria:

plpy.execute("UPDATE tbl SET %s = %s WHERE key = %s" % (
    plpy.quote_ident(colname),
    plpy.quote_nullable(newvalue),
    plpy.quote_literal(keyvalue)))