Add server support for "plugin" libraries that can be used for add-on tasks

such as debugging and performance measurement.  This consists of two features:
a table of "rendezvous variables" that allows separately-loaded shared
libraries to communicate, and a new GUC setting "local_preload_libraries"
that allows libraries to be loaded into specific sessions without explicit
cooperation from the client application.  To make local_preload_libraries
as flexible as possible, we do not restrict its use to superusers; instead,
it is restricted to load only libraries stored in $libdir/plugins/.  The
existing LOAD command has also been modified to allow non-superusers to
LOAD libraries stored in this directory.

This patch also renames the existing GUC variable preload_libraries to
shared_preload_libraries (after a suggestion by Simon Riggs) and does some
code refactoring in dfmgr.c to improve clarity.

Korry Douglas, with a little help from Tom Lane.

2 files changed, 73 insertions, 5 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 706ccba56c8..b35fa9c1ccf 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.73 2006/08/08 19:15:07 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.74 2006/08/15 18:26:58 tgl Exp $ -->
 
 <chapter Id="runtime-config">
   <title>Server Configuration</title>
@@ -949,10 +949,10 @@ SET ENABLE_SEQSCAN TO OFF;
       </listitem>
      </varlistentry>
      
-     <varlistentry id="guc-preload-libraries" xreflabel="preload_libraries">
-      <term><varname>preload_libraries</varname> (<type>string</type>)</term>
+     <varlistentry id="guc-shared-preload-libraries" xreflabel="shared_preload_libraries">
+      <term><varname>shared_preload_libraries</varname> (<type>string</type>)</term>
       <indexterm>
-       <primary><varname>preload_libraries</> configuration parameter</primary>
+       <primary><varname>shared_preload_libraries</> configuration parameter</primary>
       </indexterm>
       <listitem>
        <para>
@@ -963,6 +963,7 @@ SET ENABLE_SEQSCAN TO OFF;
         <literal>mylib.so</> (or on some platforms,
         <literal>mylib.sl</>) to be preloaded from the installation's
         standard library directory.
+        This parameter can only be set at server start.
        </para>
 
        <para>
@@ -3642,6 +3643,60 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
        </para>
       </listitem>
      </varlistentry>
+     
+     <varlistentry id="guc-local-preload-libraries" xreflabel="local_preload_libraries">
+      <term><varname>local_preload_libraries</varname> (<type>string</type>)</term>
+      <indexterm>
+       <primary><varname>local_preload_libraries</> configuration parameter</primary>
+      </indexterm>
+      <indexterm>
+       <primary><filename>$libdir/plugins</></primary>
+      </indexterm>
+      <listitem>
+       <para>
+        This variable specifies one or more shared libraries that are
+        to be preloaded at connection start.  If more than one library
+        is to be loaded, separate their names with commas.
+        This parameter cannot be changed after the start of a particular
+        session.
+       </para>
+
+       <para>
+        Because this is not a superuser-only option, the libraries
+        that can be loaded are restricted to those appearing in the
+        <filename>plugins</> subdirectory of the installation's
+        standard library directory.  (It is the database administrator's
+        responsibility to ensure that only <quote>safe</> libraries
+        are installed there.)  Entries in <varname>local_preload_libraries</>
+        can specify this directory explicitly, for example
+        <literal>$libdir/plugins/mylib</literal>, or just specify
+        the library name &mdash; <literal>mylib</literal> would have
+        the same effect as <literal>$libdir/plugins/mylib</literal>.
+       </para>
+
+       <para>
+        There is no performance advantage to loading a library at session
+        start rather than when it is first used.  Rather, the intent of
+        this feature is to allow debugging or performance-measurement
+        libraries to be loaded into specific sessions without an explicit
+        <command>LOAD</> command being given.  For example, debugging could
+        be enabled for all sessions under a given user name by setting
+        this parameter with <command>ALTER USER SET</>.
+       </para>
+
+       <para>
+        If a specified library is not found,
+        the connection attempt will fail.
+       </para>
+
+       <para>
+        Every  PostgreSQL-supported library has a <quote>magic
+        block</> that is checked to guarantee compatibility.  
+        For this reason, non-PostgreSQL libraries cannot be 
+        loaded in this way.
+       </para>
+      </listitem>
+     </varlistentry>
 
      </variablelist>
     </sect2>
diff --git a/doc/src/sgml/ref/load.sgml b/doc/src/sgml/ref/load.sgml
index b29dfd4ed41..6a6e9d9098e 100644
--- a/doc/src/sgml/ref/load.sgml
+++ b/doc/src/sgml/ref/load.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/load.sgml,v 1.21 2005/01/04 00:39:53 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/load.sgml,v 1.22 2006/08/15 18:26:58 tgl Exp $
 -->
 
 <refentry id="SQL-LOAD">
@@ -44,6 +44,19 @@ LOAD '<replaceable class="PARAMETER">filename</replaceable>'
    shared library file name extension.  See <xref linkend="xfunc-c"> for
    more information on this topic.
   </para>
+
+  <indexterm>
+   <primary><filename>$libdir/plugins</></primary>
+  </indexterm>
+
+  <para>
+   Non-superusers may only apply <command>LOAD</> to library files
+   located in <filename>$libdir/plugins/</> &mdash; the specified
+   <replaceable class="PARAMETER">filename</replaceable> must begin
+   with exactly that string.  (It is the database administrator's
+   responsibility to ensure that only <quote>safe</> libraries
+   are installed there.)
+  </para>
  </refsect1>
 
  <refsect1 id="sql-load-compat">