path: root/doc/src/sgml/plperl.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.20.2.1 2010/05/13 16:44:35 adunstan Exp $
-->

 <chapter id="plperl">
  <title>PL/Perl - Perl Procedural Language</title>

  <indexterm zone="plperl">
   <primary>PL/Perl</primary>
  </indexterm>

  <indexterm zone="plperl">
   <primary>Perl</primary>
  </indexterm>

  <para>
   PL/Perl is a loadable procedural language that enables you to write
   <productname>PostgreSQL</productname> functions in the <ulink
   url="http://www.perl.com">Perl</ulink> programming language.
  </para>

  <para>
   To install PL/Perl in a particular database, use
   <literal>createlang plperl <replaceable>dbname</></literal>.
  </para>

  <tip>
   <para>
    If a language is installed into <literal>template1</>, all subsequently
    created databases will have the language installed automatically.
   </para>
  </tip>

  <note>
   <para>
    Users of source packages must specially enable the build of
    PL/Perl during the installation process.  (Refer to the installation
    instructions for more information.)  Users of binary packages
    might find PL/Perl in a separate subpackage.
   </para>
  </note>

 <sect1 id="plperl-funcs">
  <title>PL/Perl Functions and Arguments</title>

  <para>
   To create a function in the PL/Perl language, use the standard syntax:
<programlisting>
CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS '
    # PL/Perl function body
' LANGUAGE plperl;
</programlisting>
   The body of the function is ordinary Perl code.
  </para>

  <para>
   Arguments and results are handled as in any other Perl subroutine:
   Arguments are passed in <varname>@_</varname>, and a result value
   is returned with <literal>return</> or as the last expression
   evaluated in the function.
  </para>

  <para>
   For example, a function returning the greater of two integer values
   could be defined as:

<programlisting>
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
    if ($_[0] > $_[1]) { return $_[0]; }
    return $_[1];
' LANGUAGE plperl;
</programlisting>
  </para>

  <para>
   If an SQL null value<indexterm><primary>null value</><secondary
   sortas="PL/Perl">in PL/Perl</></indexterm> is passed to a function,
   the argument value will appear as <quote>undefined</> in Perl.  The
   above function definition will not behave very nicely with null
   inputs (in fact, it will act as though they are zeroes).  We could
   add <literal>STRICT</> to the function definition to make
   <productname>PostgreSQL</productname> do something more reasonable:
   if a null value is passed, the function will not be called at all,
   but will just return a null result automatically.  Alternatively,
   we could check for undefined inputs in the function body.  For
   example, suppose that we wanted <function>perl_max</function> with
   one null and one non-null argument to return the non-null argument,
   rather than a null value:

<programlisting>
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
    my ($a,$b) = @_;
    if (! defined $a) {
        if (! defined $b) { return undef; }
        return $b;
    }
    if (! defined $b) { return $a; }
    if ($a > $b) { return $a; }
    return $b;
' LANGUAGE plperl;
</programlisting>
  </para>

  <para>
   As shown above, to return an SQL null value from a PL/Perl
   function, return an undefined value.  This can be done whether the
   function is strict or not.
  </para>

  <para>
   Composite-type arguments are passed to the function as references
   to hashes.  The keys of the hash are the attribute names of the
   composite type.  Here is an example:

<programlisting>
CREATE TABLE employee (
    name text,
    basesalary integer,
    bonus integer
);

CREATE FUNCTION empcomp(employee) RETURNS integer AS '
    my ($emp) = @_;
    return $emp->{''basesalary''} + $emp->{''bonus''};
' LANGUAGE plperl;

SELECT name, empcomp(employee) FROM employee;
</programlisting>
  </para>

  <para>
   There is currently no support for returning a composite-type result
   value.
  </para>

  <tip>
   <para>
    Because the function body is passed as an SQL string literal to
    <command>CREATE FUNCTION</command>, you have to escape single
    quotes and backslashes within your Perl source, typically by
    doubling them as shown in the above example.  Another possible
    approach is to avoid writing single quotes by using Perl's
    extended quoting operators (<literal>q[]</literal>,
    <literal>qq[]</literal>, <literal>qw[]</literal>).
   </para>
  </tip>
 </sect1>

 <sect1 id="plperl-data">
  <title>Data Values in PL/Perl</title>

  <para>
   The argument values supplied to a PL/Perl function's code are
   simply the input arguments converted to text form (just as if they
   had been displayed by a <literal>SELECT</literal> statement).
   Conversely, the <literal>return</> command will accept any string
   that is acceptable input format for the function's declared return
   type.  So, the PL/Perl programmer can manipulate data values as if
   they were just text.
  </para>
 </sect1>

 <sect1 id="plperl-database">
  <title>Database Access from PL/Perl</title>

  <para>
   Access to the database itself from your Perl function can be done via
   an experimental module <ulink
   url="http://www.cpan.org/modules/by-module/DBD/APILOS/"><literal>DBD::PgSPI</literal></ulink>
   (also available at <ulink url="http://www.cpan.org/SITES.html"><acronym>CPAN</>
   mirror sites</ulink>). This module makes available a
   <acronym>DBI</>-compliant database-handle named
   <varname>$pg_dbh</varname> that can be used to perform queries
   with normal <acronym>DBI</> syntax.<indexterm><primary>DBI</></indexterm>
  </para>

  <para>
   PL/Perl itself presently provides only one additional Perl command:

   <variablelist>
    <varlistentry>
     <indexterm>
      <primary>elog</primary>
      <secondary>in PL/Perl</secondary>
     </indexterm>

     <term><function>elog</> <replaceable>level</replaceable>, <replaceable>msg</replaceable></term>
     <listitem>
      <para>
       Emit a log or error message. Possible levels are
       <literal>DEBUG</>, <literal>LOG</>, <literal>INFO</>,
       <literal>NOTICE</>, <literal>WARNING</>, and <literal>ERROR</>.
       <literal>ERROR</> raises an error condition: further execution
       of the function is abandoned, and the current transaction is
       aborted.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </sect1>

 <sect1 id="plperl-trusted">
  <title>Trusted and Untrusted PL/Perl</title>

  <indexterm zone="plperl-trusted">
   <primary>trusted</primary>
   <secondary>PL/Perl</secondary>
  </indexterm>

  <para>
   Normally, PL/Perl is installed as a <quote>trusted</> programming
   language named <literal>plperl</>.  In this setup, certain Perl
   operations are disabled to preserve security.  In general, the
   operations that are restricted are those that interact with the
   environment. This includes file handle operations,
   <literal>require</literal>, and <literal>use</literal> (for
   external modules).  There is no way to access internals of the
   database server process or to gain OS-level access with the
   permissions of the server process,
   as a C function can do.  Thus, any unprivileged database user may
   be permitted to use this language.
  </para>

  <para>
   Here is an example of a function that will not work because file
   system operations are not allowed for security reasons:
<programlisting>
CREATE FUNCTION badfunc() RETURNS integer AS '
    open(TEMP, ">/tmp/badfile");
    print TEMP "Gotcha!\n";
    return 1;
' LANGUAGE plperl;
</programlisting>
   The creation of the function will succeed, but executing it will not.
  </para>

  <para>
   Sometimes it is desirable to write Perl functions that are not
   restricted.  For example, one might want a Perl function that sends
   mail.  To handle these cases, PL/Perl can also be installed as an
   <quote>untrusted</> language (usually called
   <application>PL/PerlU</application><indexterm><primary>PL/PerlU</></indexterm>).
   In this case the full Perl language is available.  If the
   <command>createlang</command> program is used to install the
   language, the language name <literal>plperlu</literal> will select
   the untrusted PL/Perl variant.
  </para>

  <para>
   The writer of a <application>PL/PerlU</> function must take care that the function
   cannot be used to do anything unwanted, since it will be able to do
   anything that could be done by a user logged in as the database
   administrator.  Note that the database system allows only database
   superusers to create functions in untrusted languages.
  </para>

  <para>
   If the above function was created by a superuser using the language
   <literal>plperlu</>, execution would succeed.
  </para>

  <note>
    <para>
          For security reasons, to stop a leak of privileged operations from
      <application>PL/PerlU</> to <application>PL/Perl</>, these two languages
          have to run in separate instances of the Perl interpreter. If your
          Perl installation has been appropriately compiled, this is not a problem.
          However, not all installations are compiled with the requisite flags.
          If <productname>PostgreSQL</> detects that this is the case then it will
          not start a second interpreter, but instead create an error. In
          consequence, in such an installation, you cannot use both 
          <application>PL/PerlU</> and <application>PL/Perl</> in the same backend
          process. The remedy for this is to obtain a Perl installation created
          with the appropriate flags, namely either <literal>usemultiplicity</> or
          both <literal>usethreads</> and <literal>useithreads</>. 
          For more details,see the <literal>perlembed</> manual page.
    </para>
  </note>
  
</sect1>

 <sect1 id="plperl-missing">
  <title>Missing Features</title>

  <para>
   The following features are currently missing from PL/Perl, but they
   would make welcome contributions.

   <itemizedlist>
    <listitem>
     <para>
      PL/Perl functions cannot call each other directly (because they
      are anonymous subroutines inside Perl).  There's presently no
      way for them to share global variables, either.
     </para>
    </listitem>

    <listitem>
     <para>
      PL/Perl cannot be used to write trigger
      functions.<indexterm><primary>trigger</><secondary>in
      PL/Perl</></indexterm>
     </para>
    </listitem>

    <listitem>
     <para>
      <application>DBD::PgSPI</applicatioN> or similar capability
      should be integrated into the standard
      <productname>PostgreSQL</productname> distribution.
     </para>
    </listitem>
   </itemizedlist>
  </para>
 </sect1>

</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->