begriffs open source - ai-pg/blob - full-docs/txt/plpython-util.txt

   1
   2 44.9. Utility Functions #
   3
   4    The plpy module also provides the functions
   5    plpy.debug(msg, **kwargs)
   6    plpy.log(msg, **kwargs)
   7    plpy.info(msg, **kwargs)
   8    plpy.notice(msg, **kwargs)
   9    plpy.warning(msg, **kwargs)
  10    plpy.error(msg, **kwargs)
  11    plpy.fatal(msg, **kwargs)
  12
  13    plpy.error and plpy.fatal actually raise a Python exception which, if
  14    uncaught, propagates out to the calling query, causing the current
  15    transaction or subtransaction to be aborted. raise plpy.Error(msg) and
  16    raise plpy.Fatal(msg) are equivalent to calling plpy.error(msg) and
  17    plpy.fatal(msg), respectively but the raise form does not allow passing
  18    keyword arguments. The other functions only generate messages of
  19    different priority levels. Whether messages of a particular priority
  20    are reported to the client, written to the server log, or both is
  21    controlled by the log_min_messages and client_min_messages
  22    configuration variables. See Chapter 19 for more information.
  23
  24    The msg argument is given as a positional argument. For backward
  25    compatibility, more than one positional argument can be given. In that
  26    case, the string representation of the tuple of positional arguments
  27    becomes the message reported to the client.
  28
  29    The following keyword-only arguments are accepted:
  30    detail
  31    hint
  32    sqlstate
  33    schema_name
  34    table_name
  35    column_name
  36    datatype_name
  37    constraint_name
  38
  39    The string representation of the objects passed as keyword-only
  40    arguments is used to enrich the messages reported to the client. For
  41    example:
  42 CREATE FUNCTION raise_custom_exception() RETURNS void AS $$
  43 plpy.error("custom exception message",
  44            detail="some info about exception",
  45            hint="hint for users")
  46 $$ LANGUAGE plpython3u;
  47
  48 =# SELECT raise_custom_exception();
  49 ERROR:  plpy.Error: custom exception message
  50 DETAIL:  some info about exception
  51 HINT:  hint for users
  52 CONTEXT:  Traceback (most recent call last):
  53   PL/Python function "raise_custom_exception", line 4, in <module>
  54     hint="hint for users")
  55 PL/Python function "raise_custom_exception"
  56
  57    Another set of utility functions are plpy.quote_literal(string),
  58    plpy.quote_nullable(string), and plpy.quote_ident(string). They are
  59    equivalent to the built-in quoting functions described in Section 9.4.
  60    They are useful when constructing ad-hoc queries. A PL/Python
  61    equivalent of dynamic SQL from Example 41.1 would be:
  62 plpy.execute("UPDATE tbl SET %s = %s WHERE key = %s" % (
  63     plpy.quote_ident(colname),
  64     plpy.quote_nullable(newvalue),
  65     plpy.quote_literal(keyvalue)))