Create the pg_pltemplate system catalog to hold template information

for procedural languages.  This replaces the hard-wired table I had
originally proposed as a stopgap solution.  For the moment, the initial
contents only include languages shipped with the core distribution.

3 files changed, 126 insertions, 26 deletions

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 6260c25445a..c813ba98ded 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1,6 +1,6 @@
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.112 2005/08/24 17:24:17 tgl Exp $
+ $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.113 2005/09/08 20:07:41 tgl Exp $
  -->
 
 <chapter id="catalogs">
@@ -169,6 +169,11 @@
      </row>
 
      <row>
+      <entry><link linkend="catalog-pg-pltemplate"><structname>pg_pltemplate</structname></link></entry>
+      <entry>template data for procedural languages</entry>
+     </row>
+
+     <row>
       <entry><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link></entry>
       <entry>functions and procedures</entry>
      </row>
@@ -3027,6 +3032,106 @@
  </sect1>
 
 
+ <sect1 id="catalog-pg-pltemplate">
+  <title><structname>pg_pltemplate</structname></title>
+
+  <indexterm zone="catalog-pg-pltemplate">
+   <primary>pg_pltemplate</primary>
+  </indexterm>
+
+  <para>
+   The catalog <structname>pg_pltemplate</structname> stores
+   <quote>template</> information for procedural languages.
+   A template for a language allows the language to be created in a
+   particular database by a simple <command>CREATE LANGUAGE</> command,
+   with no need to specify implementation details.
+  </para>
+
+  <para>
+   Unlike most system catalogs, <structname>pg_pltemplate</structname>
+   is shared across all databases of a cluster: there is only one
+   copy of <structname>pg_pltemplate</structname> per cluster, not
+   one per database.  This allows the information to be accessible in
+   each database as it is needed.
+  </para>
+
+  <table>
+   <title><structname>pg_pltemplate</> Columns</title>
+
+   <tgroup cols=4>
+    <thead>
+     <row>
+      <entry>Name</entry>
+      <entry>Type</entry>
+      <entry>References</entry>
+      <entry>Description</entry>
+     </row>
+    </thead>
+
+    <tbody>
+     <row>
+      <entry><structfield>tmplname</structfield></entry>
+      <entry><type>name</type></entry>
+      <entry></entry>
+      <entry>Name of the language this template is for</entry>
+     </row>
+
+     <row>
+      <entry><structfield>tmpltrusted</structfield></entry>
+      <entry><type>boolean</type></entry>
+      <entry></entry>
+      <entry>True if language is considered trusted</entry>
+     </row>
+
+     <row>
+      <entry><structfield>tmplhandler</structfield></entry>
+      <entry><type>text</type></entry>
+      <entry></entry>
+      <entry>Name of call handler function</entry>
+     </row>
+
+     <row>
+      <entry><structfield>tmplvalidator</structfield></entry>
+      <entry><type>text</type></entry>
+      <entry></entry>
+      <entry>Name of validator function, or NULL if none</entry>
+     </row>
+
+     <row>
+      <entry><structfield>tmpllibrary</structfield></entry>
+      <entry><type>text</type></entry>
+      <entry></entry>
+      <entry>Path of shared library that implements language</entry>
+     </row>
+
+     <row>
+      <entry><structfield>tmplacl</structfield></entry>
+      <entry><type>aclitem[]</type></entry>
+      <entry></entry>
+      <entry>Access privileges for template (not yet used)</entry>
+     </row>
+
+    </tbody>
+   </tgroup>
+  </table>
+
+  <para>
+   There are not currently any commands that manipulate procedural language
+   templates; to change the built-in information, a superuser must modify
+   the table using ordinary INSERT, DELETE, or UPDATE commands.  It is
+   likely that a future release of <productname>PostgreSQL</productname>
+   will offer commands to change the entries in a cleaner fashion.
+  </para>
+
+  <para>
+   When implemented, the <structfield>tmplacl</structfield> field will provide
+   access control for the template itself (i.e., the right to create a
+   language using it), not for the languages created from the template.
+  </para>
+
+ </sect1>
+
+
  <sect1 id="catalog-pg-proc">
   <title><structname>pg_proc</structname></title>
 
diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml
index 29bcade195d..e76dd58687a 100644
--- a/doc/src/sgml/ref/create_language.sgml
+++ b/doc/src/sgml/ref/create_language.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.40 2005/09/05 23:50:48 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.41 2005/09/08 20:07:41 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -48,22 +48,19 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
 
   <para>
    There are two forms of the <command>CREATE LANGUAGE</command> command.
-   In the first form, the user merely supplies the name of the desired
+   In the first form, the user supplies just the name of the desired
    language, and the <productname>PostgreSQL</productname> server consults
-   an internal table to determine the correct parameters.  In
-   the second form, the user supplies the language parameters along with
-   the language name.  The second form must be used to create a language
-   that is not present in the internal table, but this form is considered
-   obsolescent.  (It is expected that future releases of
-   <productname>PostgreSQL</productname> will replace the internal table
-   with a system catalog that can be extended to support additional
-   languages.)
+   the <link linkend="catalog-pg-pltemplate"><structname>pg_pltemplate</structname></link>
+   system catalog to determine the correct parameters.  In the second form,
+   the user supplies the language parameters along with the language name.
+   The second form can be used to create a language that is not defined in
+   <structname>pg_pltemplate</>, but this approach is considered obsolescent.
   </para>
 
   <para>
-   When the server finds an entry in its internal table for the given
-   language name, it will use the table data even if the given command
-   includes language parameters.  This behavior simplifies loading of
+   When the server finds an entry in the <structname>pg_pltemplate</> catalog
+   for the given language name, it will use the catalog data even if the
+   command includes language parameters.  This behavior simplifies loading of
    old dump files, which are likely to contain out-of-date information
    about language support functions.
   </para>
@@ -165,8 +162,8 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
 
   <para>
    The <literal>TRUSTED</> option and the support function name(s) are
-   ignored if the server has information about the specified language
-   name in its internal table.
+   ignored if the server has an entry for the specified language
+   name in <structname>pg_pltemplate</>.
   </para>
  </refsect1>
 
@@ -207,9 +204,9 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
 
   <para>
    The call handler function and the validator function (if any)
-   must already exist if the server does not have information about
-   the language in its internal table.  But when there is an entry
-   in the internal table, the functions need not already exist;
+   must already exist if the server does not have an entry for the language
+   in <structname>pg_pltemplate</>.  But when there is an entry,
+   the functions need not already exist;
    they will be automatically defined if not present in the database.
    (This can result in <command>CREATE LANGUAGE</> failing, if the
    shared library that implements the language is not available in
@@ -239,8 +236,8 @@ CREATE LANGUAGE plpgsql;
   </para>
 
   <para>
-   For a language not known in the server's internal table, a sequence
-   such as this is needed:
+   For a language not known in the <structname>pg_pltemplate</> catalog, a
+   sequence such as this is needed:
 <programlisting>
 CREATE FUNCTION plsample_call_handler() RETURNS language_handler
     AS '$libdir/plsample'
diff --git a/doc/src/sgml/ref/createlang.sgml b/doc/src/sgml/ref/createlang.sgml
index f9f8dc1ea78..0e613caf003 100644
--- a/doc/src/sgml/ref/createlang.sgml
+++ b/doc/src/sgml/ref/createlang.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.36 2005/09/05 23:50:48 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.37 2005/09/08 20:07:41 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -40,11 +40,9 @@ PostgreSQL documentation
   <para>
    <application>createlang</application> is a utility for adding a new 
    programming language to a <productname>PostgreSQL</productname> database.
-   <application>createlang</application> can handle all the languages
-   supplied in the default <productname>PostgreSQL</> distribution, but
-   not languages provided by other parties.  See
+   <application>createlang</application> is just a wrapper around the
    <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
-   for additional information.
+   command, which see for additional information.
   </para>
  </refsect1>