<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>46.10. Utility Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="plpython-transactions.html" title="46.9. Transaction Management" /><link rel="next" href="plpython-envar.html" title="46.11. Environment Variables" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">46.10. Utility Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="plpython-transactions.html" title="46.9. Transaction Management">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="plpython.html" title="Chapter 46. PL/Python - Python Procedural Language">Up</a></td><th width="60%" align="center">Chapter 46. PL/Python - Python Procedural Language</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 11.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpython-envar.html" title="46.11. Environment Variables">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="PLPYTHON-UTIL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">46.10. Utility Functions</h2></div></div></div><p>
The <code class="literal">plpy</code> module also provides the functions
</p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">plpy.debug(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.log(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.info(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.notice(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.warning(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.error(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr><tr><td><code class="literal">plpy.fatal(<em class="replaceable"><code>msg, **kwargs</code></em>)</code></td></tr></table><p>
<a id="id-1.8.11.18.2.3" class="indexterm"></a>
<code class="function">plpy.error</code> and <code class="function">plpy.fatal</code>
actually raise a Python exception which, if uncaught, propagates out to
the calling query, causing the current transaction or subtransaction to
be aborted. <code class="literal">raise plpy.Error(<em class="replaceable"><code>msg</code></em>)</code> and
<code class="literal">raise plpy.Fatal(<em class="replaceable"><code>msg</code></em>)</code> are
equivalent to calling <code class="literal">plpy.error(<em class="replaceable"><code>msg</code></em>)</code> and
<code class="literal">plpy.fatal(<em class="replaceable"><code>msg</code></em>)</code>, respectively but
the <code class="literal">raise</code> form does not allow passing keyword arguments.
The other functions only generate messages of different priority levels.
Whether messages of a particular priority are reported to the client,
written to the server log, or both is controlled by the
<a class="xref" href="runtime-config-logging.html#GUC-LOG-MIN-MESSAGES">log_min_messages</a> and
<a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a> configuration
variables. See <a class="xref" href="runtime-config.html" title="Chapter 19. Server Configuration">Chapter 19</a> for more information.
</p><p>
The <em class="replaceable"><code>msg</code></em> argument is given as a positional argument. For
backward compatibility, more than one positional argument can be given. In
that case, the string representation of the tuple of positional arguments
becomes the message reported to the client.
</p><p>
The following keyword-only arguments are accepted:
</p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">detail</code></td></tr><tr><td><code class="literal">hint</code></td></tr><tr><td><code class="literal">sqlstate</code></td></tr><tr><td><code class="literal">schema_name</code></td></tr><tr><td><code class="literal">table_name</code></td></tr><tr><td><code class="literal">column_name</code></td></tr><tr><td><code class="literal">datatype_name</code></td></tr><tr><td><code class="literal">constraint_name</code></td></tr></table><p>
The string representation of the objects passed as keyword-only arguments
is used to enrich the messages reported to the client. For example:
</p><pre class="programlisting">
CREATE FUNCTION raise_custom_exception() RETURNS void AS $$
plpy.error("custom exception message",
detail="some info about exception",
hint="hint for users")
$$ LANGUAGE plpythonu;
=# 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"
</pre><p>
</p><p>
Another set of utility functions are
<code class="literal">plpy.quote_literal(<em class="replaceable"><code>string</code></em>)</code>,
<code class="literal">plpy.quote_nullable(<em class="replaceable"><code>string</code></em>)</code>, and
<code class="literal">plpy.quote_ident(<em class="replaceable"><code>string</code></em>)</code>. They
are equivalent to the built-in quoting functions described in <a class="xref" href="functions-string.html" title="9.4. String Functions and Operators">Section 9.4</a>. They are useful when constructing
ad-hoc queries. A PL/Python equivalent of dynamic SQL from <a class="xref" href="plpgsql-statements.html#PLPGSQL-QUOTE-LITERAL-EXAMPLE" title="Example 43.1. Quoting Values In Dynamic Queries">Example 43.1</a> would be:
</p><pre class="programlisting">
plpy.execute("UPDATE tbl SET %s = %s WHERE key = %s" % (
plpy.quote_ident(colname),
plpy.quote_nullable(newvalue),
plpy.quote_literal(keyvalue)))
</pre><p>
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plpython-transactions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="plpython.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpython-envar.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">46.9. Transaction Management </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 46.11. Environment Variables</td></tr></table></div></body></html>
