granicus.if.org Git - postgresql/blob - doc/src/sgml/plpython.sgml

   1 <!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.20 2003/09/12 22:17:23 tgl Exp $ -->
   2
   3 <chapter id="plpython">
   4  <title>PL/Python - Python Procedural Language</title>
   5
   6  <indexterm zone="plpython"><primary>PL/Python</></>
   7  <indexterm zone="plpython"><primary>Python</></>
   8
   9  <para>
  10   The <application>PL/Python</application> procedural language allows
  11   <productname>PostgreSQL</productname> functions to be written in the
  12   <ulink url="http://www.python.org">Python</ulink> language.
  13  </para>
  14
  15  <para>
  16   To install PL/Python in a particular database, use
  17   <literal>createlang plpythonu <replaceable>dbname</></literal>.
  18  </para>
  19
  20  <note>
  21   <para>
  22    As of <productname>PostgreSQL</productname> 7.4,
  23    PL/Python is only available as an <quote>untrusted</> language
  24    (meaning it does not offer any way of restricting what users
  25    can do in it).  It has therefore been renamed to <literal>plpythonu</>.
  26    The trusted variant <literal>plpython</> may become available again in
  27    future, if a new secure execution mechanism is developed by the Python
  28    community.
  29   </para>
  30  </note>
  31
  32   <tip>
  33    <para>
  34     If a language is installed into <literal>template1</>, all subsequently
  35     created databases will have the language installed automatically.
  36    </para>
  37   </tip>
  38
  39  <note>
  40   <para>
  41    Users of source packages must specially enable the build of
  42    PL/Python during the installation process.  (Refer to the
  43    installation instructions for more information.)  Users of binary
  44    packages might find PL/Python in a separate subpackage.
  45   </para>
  46  </note>
  47
  48  <sect1 id="plpython-funcs">
  49   <title>PL/Python Functions</title>
  50
  51   <para>
  52    The Python code you write gets transformed into a Python function.  E.g.,
  53 <programlisting>
  54 CREATE FUNCTION myfunc(text) RETURNS text
  55     AS 'return args[0]'
  56     LANGUAGE plpythonu;
  57 </programlisting>
  58
  59    gets transformed into
  60
  61 <programlisting>
  62 def __plpython_procedure_myfunc_23456():
  63         return args[0]
  64 </programlisting>
  65
  66    assuming that 23456 is the OID of the function.
  67   </para>
  68
  69   <para>
  70    If you do not provide a return value, Python returns the default
  71    <symbol>None</symbol>. The language module translates Python's
  72    <symbol>None</symbol> into the SQL null
  73    value.<indexterm><primary>null value</><secondary
  74    sortas="PL/Python">in PL/Python</></indexterm>
  75   </para>
  76
  77   <para>
  78    The <productname>PostgreSQL</> function parameters are available in
  79    the global <varname>args</varname> list.  In the
  80    <function>myfunc</function> example, <varname>args[0]</> contains
  81    whatever was passed in as the text argument.  For
  82    <literal>myfunc2(text, integer)</literal>, <varname>args[0]</>
  83    would contain the <type>text</type> argument and
  84    <varname>args[1]</varname> the <type>integer</type> argument.
  85   </para>
  86
  87   <para>
  88    The global dictionary <varname>SD</varname> is available to store
  89    data between function calls.  This variable is private static data.
  90    The global dictionary <varname>GD</varname> is public data,
  91    available to all Python functions within a session.  Use with
  92    care.<indexterm><primary>global data</><secondary>in
  93    PL/Python</></indexterm>
  94   </para>
  95
  96   <para>
  97    Each function gets its own execution environment in the
  98    Python interpreter, so that global data and function arguments from
  99    <function>myfunc</function> are not available to
 100    <function>myfunc2</function>.  The exception is the data in the
 101    <varname>GD</varname> dictionary, as mentioned above.
 102   </para>
 103  </sect1>
 104
 105  <sect1 id="plpython-trigger">
 106   <title>Trigger Functions</title>
 107
 108   <indexterm zone="plpython-trigger">
 109    <primary>trigger</primary>
 110    <secondary>in PL/Python</secondary>
 111   </indexterm>
 112
 113   <para>
 114    When a function is used in a trigger, the dictionary
 115    <literal>TD</literal> contains trigger-related values.  The trigger
 116    rows are in <literal>TD["new"]</> and/or <literal>TD["old"]</>
 117    depending on the trigger event.  <literal>TD["event"]</> contains
 118    the event as a string (<literal>INSERT</>, <literal>UPDATE</>,
 119    <literal>DELETE</>, or <literal>UNKNOWN</>).
 120    <literal>TD["when"]</> contains one of <literal>BEFORE</>,
 121    <literal>AFTER</>, and <literal>UNKNOWN</>.
 122    <literal>TD["level"]</> contains one of <literal>ROW</>,
 123    <literal>STATEMENT</>, and <literal>UNKNOWN</>.
 124    <literal>TD["name"]</> contains the trigger name, and
 125    <literal>TD["relid"]</> contains the OID of the table on
 126    which the trigger occurred.  If the trigger was called with
 127    arguments they are available in <literal>TD["args"][0]</> to
 128    <literal>TD["args"][(n-1)]</>.
 129   </para>
 130
 131   <para>
 132    If <literal>TD["when"]</literal> is <literal>BEFORE</>, you may
 133    return <literal>None</literal> or <literal>"OK"</literal> from the
 134    Python function to indicate the row is unmodified,
 135    <literal>"SKIP"</> to abort the event, or <literal>"MODIFY"</> to
 136    indicate you've modified the row.
 137   </para>
 138  </sect1>
 139
 140  <sect1 id="plpython-database">
 141   <title>Database Access</title>
 142
 143   <para>
 144    The PL/Python language module automatically imports a Python module
 145    called <literal>plpy</literal>.  The functions and constants in
 146    this module are available to you in the Python code as
 147    <literal>plpy.<replaceable>foo</replaceable></literal>.  At present
 148    <literal>plpy</literal> implements the functions
 149    <literal>plpy.debug("msg")</literal>,
 150    <literal>plpy.log("msg")</literal>,
 151    <literal>plpy.info("msg")</literal>,
 152    <literal>plpy.notice("msg")</literal>,
 153    <literal>plpy.warning("msg")</literal>,
 154    <literal>plpy.error("msg")</literal>, and
 155    <literal>plpy.fatal("msg")</literal>.  They are mostly equivalent
 156    to calling <literal>elog(<replaceable>LEVEL</>, "msg")</literal>
 157    from C code.<indexterm><primary>elog</><secondary>in
 158    PL/Python</></indexterm>  <function>plpy.error</function> and
 159    <function>plpy.fatal</function> actually raise a Python exception
 160    which, if uncaught, causes the PL/Python module to call
 161    <literal>elog(ERROR, msg)</literal> when the function handler
 162    returns from the Python interpreter.  Long-jumping out of the
 163    Python interpreter is probably not good.  <literal>raise
 164    plpy.ERROR("msg")</literal> and <literal>raise
 165    plpy.FATAL("msg")</literal> are equivalent to calling
 166    <function>plpy.error</function> and
 167    <function>plpy.fatal</function>, respectively.
 168   </para>
 169
 170   <para>
 171    Additionally, the <literal>plpy</literal> module provides two
 172    functions called <function>execute</function> and
 173    <function>prepare</function>.  Calling
 174    <function>plpy.execute</function> with a query string and an
 175    optional limit argument causes that query to be run and the result
 176    to be returned in a result object.  The result object emulates a
 177    list or dictionary object.  The result object can be accessed by
 178    row number and column name.  It has these additional methods:
 179    <function>nrows</function> which returns the number of rows
 180    returned by the query, and <function>status</function> which is the
 181    <function>SPI_exec()</function> return value.  The result object
 182    can be modified.
 183   </para>
 184
 185   <para>
 186    For example,
 187 <programlisting>
 188 rv = plpy.execute("SELECT * FROM my_table", 5)
 189 </programlisting>
 190    returns up to 5 rows from <literal>my_table</literal>.  If
 191    <literal>my_table</literal> has a column
 192    <literal>my_column</literal>, it would be accessed as
 193 <programlisting>
 194 foo = rv[i]["my_column"]
 195 </programlisting>
 196   </para>
 197
 198   <para>
 199    <indexterm><primary>preparing a query</><secondary>in PL/Python</></indexterm>
 200    The second function, <function>plpy.prepare</function>, prepares
 201    the execution plan for a query.  It is called with a query string
 202    and a list of parameter types, if you have parameter references in
 203    the query.  For example:
 204 <programlisting>
 205 plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", [ "text" ])
 206 </programlisting>
 207    <literal>text</literal> is the type of the variable you will be
 208    passing for <literal>$1</literal>.  After preparing a statement, you
 209    use the function <function>plpy.execute</function> to run it:
 210 <programlisting>
 211 rv = plpy.execute(plan, [ "name" ], 5)
 212 </programlisting>
 213    The third argument is the limit and is optional.
 214   </para>
 215
 216   <para>
 217    In the current version, any database error encountered while
 218    running a <application>PL/Python</application> function will result
 219    in the immediate termination of that function by the server; it is
 220    not possible to trap error conditions using Python <literal>try
 221    ... catch</literal> constructs.  For example, a syntax error in an
 222    SQL statement passed to the <literal>plpy.execute</literal> call
 223    will terminate the function.  This behavior may be changed in a
 224    future release.
 225   </para>
 226
 227   <para>
 228    When you prepare a plan using the PL/Python module it is
 229    automatically saved.  Read the SPI documentation (<xref
 230    linkend="spi">) for a description of what this means.
 231    In order to make effective use of this across function calls
 232    one needs to use one of the persistent storage dictionaries
 233    <literal>SD</literal> or <literal>GD</literal> (see
 234    <xref linkend="plpython-funcs">). For example:
 235 <programlisting>
 236 CREATE FUNCTION usesavedplan() RETURNS trigger AS '
 237     if SD.has_key("plan"):
 238         plan = SD["plan"]
 239     else:
 240         plan = plpy.prepare("SELECT 1")
 241         SD["plan"] = plan
 242     # rest of function
 243 ' LANGUAGE plpythonu;
 244 </programlisting>
 245   </para>
 246  </sect1>
 247
 248 <![IGNORE[
 249  <!-- NOT CURRENTLY SUPPORTED -->
 250
 251  <sect1 id="plpython-trusted">
 252   <title>Restricted Environment</title>
 253
 254   <para>
 255    The current version of <application>PL/Python</application>
 256    functions as a trusted language only; access to the file system and
 257    other local resources is disabled.  Specifically,
 258    <application>PL/Python</application> uses the Python restricted
 259    execution environment, further restricts it to prevent the use of
 260    the file <function>open</> call, and allows only modules from a
 261    specific list to be imported.  Presently, that list includes:
 262    <literal>array</>, <literal>bisect</>, <literal>binascii</>,
 263    <literal>calendar</>, <literal>cmath</>, <literal>codecs</>,
 264    <literal>errno</>, <literal>marshal</>, <literal>math</>, <literal>md5</>,
 265    <literal>mpz</>, <literal>operator</>, <literal>pcre</>,
 266    <literal>pickle</>, <literal>random</>, <literal>re</>, <literal>regex</>,
 267    <literal>sre</>, <literal>sha</>, <literal>string</>, <literal>StringIO</>,
 268    <literal>struct</>, <literal>time</>, <literal>whrandom</>, and
 269    <literal>zlib</>.
 270   </para>
 271  </sect1>
 272
 273 ]]>
 274
 275 </chapter>