codekingpro/portable-devtools

1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!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>Chapter 58. Writing a Procedural Language Handler</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="nls-programmer.html" title="57.2. For the Programmer" /><link rel="next" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 58. Writing a Procedural Language Handler</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="nls-programmer.html" title="57.2. For the Programmer">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Next</a></td></tr></table><hr /></div><div class="chapter" id="PLHANDLER"><div class="titlepage"><div><div><h2 class="title">Chapter 58. Writing a Procedural Language Handler</h2></div></div></div><a id="id-1.10.9.2" class="indexterm"></a><p>3    All calls to functions that are written in a language other than4    the current <span class="quote">“<span class="quote">version 1</span>”</span> interface for compiled5    languages (this includes functions in user-defined procedural languages6    and functions written in SQL) go through a <em class="firstterm">call handler</em>7    function for the specific language.  It is the responsibility of8    the call handler to execute the function in a meaningful way, such9    as by interpreting the supplied source text.  This chapter outlines10    how a new procedural language's call handler can be written.11   </p><p>12    The call handler for a procedural language is a13    <span class="quote">“<span class="quote">normal</span>”</span> function that must be written in a compiled14    language such as C, using the version-1 interface, and registered15    with <span class="productname">PostgreSQL</span> as taking no arguments16    and returning the type <code class="type">language_handler</code>.  This17    special pseudo-type identifies the function as a call handler and18    prevents it from being called directly in SQL commands.19    For more details on C language calling conventions and dynamic loading,20    see <a class="xref" href="xfunc-c.html" title="38.10. C-Language Functions">Section 38.10</a>.21   </p><p>22    The call handler is called in the same way as any other function:23    It receives a pointer to a24    <code class="structname">FunctionCallInfoBaseData</code> <code class="type">struct</code> containing25    argument values and information about the called function, and it26    is expected to return a <code class="type">Datum</code> result (and possibly27    set the <code class="structfield">isnull</code> field of the28    <code class="structname">FunctionCallInfoBaseData</code> structure, if it wishes29    to return an SQL null result).  The difference between a call30    handler and an ordinary callee function is that the31    <code class="structfield">flinfo-&gt;fn_oid</code> field of the32    <code class="structname">FunctionCallInfoBaseData</code> structure will contain33    the OID of the actual function to be called, not of the call34    handler itself.  The call handler must use this field to determine35    which function to execute.  Also, the passed argument list has36    been set up according to the declaration of the target function,37    not of the call handler.38   </p><p>39    It's up to the call handler to fetch the entry of the function from the40    <code class="classname">pg_proc</code> system catalog and to analyze the argument41    and return types of the called function. The <code class="literal">AS</code> clause from the42    <code class="command">CREATE FUNCTION</code> command for the function will be found43    in the <code class="literal">prosrc</code> column of the44    <code class="classname">pg_proc</code> row. This is commonly source45    text in the procedural language, but in theory it could be something else,46    such as a path name to a file, or anything else that tells the call handler47    what to do in detail.48   </p><p>49    Often, the same function is called many times per SQL statement.50    A call handler can avoid repeated lookups of information about the51    called function by using the52    <code class="structfield">flinfo-&gt;fn_extra</code> field.  This will53    initially be <code class="symbol">NULL</code>, but can be set by the call handler to point at54    information about the called function.  On subsequent calls, if55    <code class="structfield">flinfo-&gt;fn_extra</code> is already non-<code class="symbol">NULL</code>56    then it can be used and the information lookup step skipped.  The57    call handler must make sure that58    <code class="structfield">flinfo-&gt;fn_extra</code> is made to point at59    memory that will live at least until the end of the current query,60    since an <code class="structname">FmgrInfo</code> data structure could be61    kept that long.  One way to do this is to allocate the extra data62    in the memory context specified by63    <code class="structfield">flinfo-&gt;fn_mcxt</code>; such data will64    normally have the same lifespan as the65    <code class="structname">FmgrInfo</code> itself.  But the handler could66    also choose to use a longer-lived memory context so that it can cache67    function definition information across queries.68   </p><p>69    When a procedural-language function is invoked as a trigger, no arguments70    are passed in the usual way, but the71    <code class="structname">FunctionCallInfoBaseData</code>'s72    <code class="structfield">context</code> field points at a73    <code class="structname">TriggerData</code> structure, rather than being <code class="symbol">NULL</code>74    as it is in a plain function call.  A language handler should75    provide mechanisms for procedural-language functions to get at the trigger76    information.77   </p><p>78    A template for a procedural-language handler written as a C extension is79    provided in <code class="literal">src/test/modules/plsample</code>.  This is a80    working sample demonstrating one way to create a procedural-language81    handler, process parameters, and return a value.82   </p><p>83    Although providing a call handler is sufficient to create a minimal84    procedural language, there are two other functions that can optionally85    be provided to make the language more convenient to use.  These86    are a <em class="firstterm">validator</em> and an87    <em class="firstterm">inline handler</em>.  A validator can be provided88    to allow language-specific checking to be done during89    <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>.90    An inline handler can be provided to allow the language to support91    anonymous code blocks executed via the <a class="xref" href="sql-do.html" title="DO"><span class="refentrytitle">DO</span></a> command.92   </p><p>93    If a validator is provided by a procedural language, it94    must be declared as a function taking a single parameter of type95    <code class="type">oid</code>.  The validator's result is ignored, so it is customarily96    declared to return <code class="type">void</code>.  The validator will be called at97    the end of a <code class="command">CREATE FUNCTION</code> command that has created98    or updated a function written in the procedural language.99    The passed-in OID is the OID of the function's <code class="classname">pg_proc</code>100    row.  The validator must fetch this row in the usual way, and do101    whatever checking is appropriate.102    First, call <code class="function">CheckFunctionValidatorAccess()</code> to diagnose103    explicit calls to the validator that the user could not achieve through104    <code class="command">CREATE FUNCTION</code>.  Typical checks then include verifying105    that the function's argument and result types are supported by the106    language, and that the function's body is syntactically correct107    in the language.  If the validator finds the function to be okay,108    it should just return.  If it finds an error, it should report that109    via the normal <code class="function">ereport()</code> error reporting mechanism.110    Throwing an error will force a transaction rollback and thus prevent111    the incorrect function definition from being committed.112   </p><p>113    Validator functions should typically honor the <a class="xref" href="runtime-config-client.html#GUC-CHECK-FUNCTION-BODIES">check_function_bodies</a> parameter: if it is turned off then114    any expensive or context-sensitive checking should be skipped.  If the115    language provides for code execution at compilation time, the validator116    must suppress checks that would induce such execution.  In particular,117    this parameter is turned off by <span class="application">pg_dump</span> so that it can118    load procedural language functions without worrying about side effects or119    dependencies of the function bodies on other database objects.120    (Because of this requirement, the call handler should avoid121    assuming that the validator has fully checked the function.  The point122    of having a validator is not to let the call handler omit checks, but123    to notify the user immediately if there are obvious errors in a124    <code class="command">CREATE FUNCTION</code> command.)125    While the choice of exactly what to check is mostly left to the126    discretion of the validator function, note that the core127    <code class="command">CREATE FUNCTION</code> code only executes <code class="literal">SET</code> clauses128    attached to a function when <code class="varname">check_function_bodies</code> is on.129    Therefore, checks whose results might be affected by GUC parameters130    definitely should be skipped when <code class="varname">check_function_bodies</code> is131    off, to avoid false failures when restoring a dump.132   </p><p>133    If an inline handler is provided by a procedural language, it134    must be declared as a function taking a single parameter of type135    <code class="type">internal</code>.  The inline handler's result is ignored, so it is136    customarily declared to return <code class="type">void</code>.  The inline handler137    will be called when a <code class="command">DO</code> statement is executed specifying138    the procedural language.  The parameter actually passed is a pointer139    to an <code class="structname">InlineCodeBlock</code> struct, which contains information140    about the <code class="command">DO</code> statement's parameters, in particular the141    text of the anonymous code block to be executed.  The inline handler142    should execute this code and return.143   </p><p>144    It's recommended that you wrap all these function declarations,145    as well as the <code class="command">CREATE LANGUAGE</code> command itself, into146    an <em class="firstterm">extension</em> so that a simple <code class="command">CREATE EXTENSION</code>147    command is sufficient to install the language.  See148    <a class="xref" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Section 38.17</a> for information about writing149    extensions.150   </p><p>151    The procedural languages included in the standard distribution152    are good references when trying to write your own language handler.153    Look into the <code class="filename">src/pl</code> subdirectory of the source tree.154    The <a class="xref" href="sql-createlanguage.html" title="CREATE LANGUAGE"><span class="refentrytitle">CREATE LANGUAGE</span></a>155    reference page also has some useful details.156   </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="nls-programmer.html" title="57.2. For the Programmer">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="fdwhandler.html" title="Chapter 59. Writing a Foreign Data Wrapper">Next</a></td></tr><tr><td width="40%" align="left" valign="top">57.2. For the Programmer </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 59. Writing a Foreign Data Wrapper</td></tr></table></div></body></html>