doc/src/sgml/ref/createlang.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="APP-CREATELANG">
   7  <refmeta>
   8   <refentrytitle id="APP-CREATELANG-TITLE"><application>createlang</application></refentrytitle>
   9   <manvolnum>1</manvolnum>
  10   <refmiscinfo>Application</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>createlang</refname>
  15   <refpurpose>define a new <productname>PostgreSQL</productname> procedural language</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="app-createlang">
  19   <primary>createlang</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>createlang</command>
  25    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
  26    <arg choice="plain"><replaceable>langname</replaceable></arg>
  27    <arg><replaceable>dbname</replaceable></arg>
  28    <sbr>
  29    <command>createlang</command>
  30    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
  31    <group choice="plain"><arg>--list</arg><arg>-l</arg></group>
  32    <arg choice="plain"><replaceable>dbname</replaceable></arg>
  33   </cmdsynopsis>
  34  </refsynopsisdiv>
  35
  36
  37  <refsect1>
  38   <title>Description</title>
  39
  40   <para>
  41    <application>createlang</application> is a utility for adding a new
  42    programming language to a <productname>PostgreSQL</productname> database.
  43    <application>createlang</application> is just a wrapper around the
  44    <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
  45    command.
  46   </para>
  47  </refsect1>
  48
  49
  50  <refsect1>
  51   <title>Options</title>
  52
  53    <para>
  54     <application>createlang</application> accepts the following command-line arguments:
  55
  56     <variablelist>
  57      <varlistentry>
  58       <term><replaceable class="parameter">langname</replaceable></term>
  59       <listitem>
  60        <para>
  61         Specifies the name of the procedural programming language to be
  62         defined.
  63        </para>
  64       </listitem>
  65      </varlistentry>
  66
  67      <varlistentry>
  68       <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></></term>
  69       <term><option><optional>--dbname</> <replaceable class="parameter">dbname</replaceable></></term>
  70       <listitem>
  71        <para>
  72         Specifies to which database the language should be added.
  73         The default is to use the database with the same name as the
  74         current system user.
  75        </para>
  76       </listitem>
  77      </varlistentry>
  78
  79      <varlistentry>
  80       <term><option>-e</></term>
  81       <term><option>--echo</></term>
  82       <listitem>
  83        <para>
  84         Display SQL commands as they are executed.
  85        </para>
  86       </listitem>
  87      </varlistentry>
  88
  89      <varlistentry>
  90       <term><option>-l</></term>
  91       <term><option>--list</></term>
  92       <listitem>
  93        <para>
  94         Show a list of already installed languages in the target database.
  95        </para>
  96       </listitem>
  97      </varlistentry>
  98
  99     </variablelist>
 100    </para>
 101
 102    <para>
 103     <application>createlang</application> also accepts
 104     the following command-line arguments for connection parameters:
 105
 106     <variablelist>
 107      <varlistentry>
 108       <term><option>-h <replaceable class="parameter">host</replaceable></></term>
 109       <term><option>--host <replaceable class="parameter">host</replaceable></></term>
 110       <listitem>
 111        <para>
 112         Specifies the host name of the machine on which the
 113         server
 114         is running.  If the value begins with a slash, it is used
 115         as the directory for the Unix domain socket.
 116        </para>
 117       </listitem>
 118      </varlistentry>
 119
 120      <varlistentry>
 121       <term><option>-p <replaceable class="parameter">port</replaceable></></term>
 122       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
 123       <listitem>
 124        <para>
 125         Specifies the TCP port or local Unix domain socket file
 126         extension on which the server
 127         is listening for connections.
 128        </para>
 129       </listitem>
 130      </varlistentry>
 131
 132      <varlistentry>
 133       <term><option>-U <replaceable class="parameter">username</replaceable></></term>
 134       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
 135       <listitem>
 136        <para>
 137         User name to connect as.
 138        </para>
 139       </listitem>
 140      </varlistentry>
 141
 142      <varlistentry>
 143       <term><option>-W</></term>
 144       <term><option>--password</></term>
 145       <listitem>
 146        <para>
 147         Force <application>createlang</application> to prompt for a
 148         password before connecting to a database.
 149        </para>
 150
 151        <para>
 152         This option is never essential, since
 153         <application>createlang</application> will automatically prompt
 154         for a password if the server demands password authentication.
 155         However, <application>createlang</application> will waste a
 156         connection attempt finding out that the server wants a password.
 157         In some cases it is worth typing <option>-W</> to avoid the extra
 158         connection attempt.
 159        </para>
 160       </listitem>
 161      </varlistentry>
 162
 163     </variablelist>
 164    </para>
 165  </refsect1>
 166
 167
 168  <refsect1>
 169   <title>Environment</title>
 170
 171   <variablelist>
 172    <varlistentry>
 173     <term><envar>PGDATABASE</envar></term>
 174     <term><envar>PGHOST</envar></term>
 175     <term><envar>PGPORT</envar></term>
 176     <term><envar>PGUSER</envar></term>
 177
 178     <listitem>
 179      <para>
 180       Default connection parameters
 181      </para>
 182     </listitem>
 183    </varlistentry>
 184   </variablelist>
 185
 186   <para>
 187    This utility, like most other <productname>PostgreSQL</> utilities,
 188    also uses the environment variables supported by <application>libpq</>
 189    (see <xref linkend="libpq-envars">).
 190   </para>
 191
 192  </refsect1>
 193
 194
 195  <refsect1>
 196   <title>Diagnostics</title>
 197
 198    <para>
 199     Most error messages are self-explanatory. If not, run
 200     <application>createlang</application> with the <option>--echo</option>
 201     option and see under the respective <acronym>SQL</acronym> command
 202     for details.  Also, any default connection settings and environment
 203     variables used by the <application>libpq</application> front-end
 204     library will apply.
 205    </para>
 206  </refsect1>
 207
 208
 209  <refsect1>
 210   <title>Notes</title>
 211
 212   <para>
 213    Use <xref linkend="app-droplang"> to remove a language.
 214   </para>
 215  </refsect1>
 216
 217
 218  <refsect1>
 219   <title>Examples</title>
 220
 221    <para>
 222     To install the language <literal>pltcl</literal> into the database
 223     <literal>template1</literal>:
 224 <screen>
 225 <prompt>$ </prompt><userinput>createlang pltcl template1</userinput>
 226 </screen>
 227     Note that installing the language into <literal>template1</literal>
 228     will cause it to be automatically installed into subsequently-created
 229     databases as well.
 230    </para>
 231  </refsect1>
 232
 233  <refsect1>
 234   <title>See Also</title>
 235
 236   <simplelist type="inline">
 237    <member><xref linkend="app-droplang"></member>
 238    <member><xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"></member>
 239   </simplelist>
 240  </refsect1>
 241
 242 </refentry>