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>--no-password</></term>
 145       <listitem>
 146        <para>
 147         Never issue a password prompt.  If the server requires
 148         password authentication and a password is not available by
 149         other means such as a <filename>.pgpass</filename> file, the
 150         connection attempt will fail.  This option can be useful in
 151         batch jobs and scripts where no user is present to enter a
 152         password.
 153        </para>
 154       </listitem>
 155      </varlistentry>
 156
 157      <varlistentry>
 158       <term><option>-W</></term>
 159       <term><option>--password</></term>
 160       <listitem>
 161        <para>
 162         Force <application>createlang</application> to prompt for a
 163         password before connecting to a database.
 164        </para>
 165
 166        <para>
 167         This option is never essential, since
 168         <application>createlang</application> will automatically prompt
 169         for a password if the server demands password authentication.
 170         However, <application>createlang</application> will waste a
 171         connection attempt finding out that the server wants a password.
 172         In some cases it is worth typing <option>-W</> to avoid the extra
 173         connection attempt.
 174        </para>
 175       </listitem>
 176      </varlistentry>
 177
 178     </variablelist>
 179    </para>
 180  </refsect1>
 181
 182
 183  <refsect1>
 184   <title>Environment</title>
 185
 186   <variablelist>
 187    <varlistentry>
 188     <term><envar>PGDATABASE</envar></term>
 189     <term><envar>PGHOST</envar></term>
 190     <term><envar>PGPORT</envar></term>
 191     <term><envar>PGUSER</envar></term>
 192
 193     <listitem>
 194      <para>
 195       Default connection parameters
 196      </para>
 197     </listitem>
 198    </varlistentry>
 199   </variablelist>
 200
 201   <para>
 202    This utility, like most other <productname>PostgreSQL</> utilities,
 203    also uses the environment variables supported by <application>libpq</>
 204    (see <xref linkend="libpq-envars">).
 205   </para>
 206
 207  </refsect1>
 208
 209
 210  <refsect1>
 211   <title>Diagnostics</title>
 212
 213    <para>
 214     Most error messages are self-explanatory. If not, run
 215     <application>createlang</application> with the <option>--echo</option>
 216     option and see under the respective <acronym>SQL</acronym> command
 217     for details.  Also, any default connection settings and environment
 218     variables used by the <application>libpq</application> front-end
 219     library will apply.
 220    </para>
 221  </refsect1>
 222
 223
 224  <refsect1>
 225   <title>Notes</title>
 226
 227   <para>
 228    Use <xref linkend="app-droplang"> to remove a language.
 229   </para>
 230  </refsect1>
 231
 232
 233  <refsect1>
 234   <title>Examples</title>
 235
 236    <para>
 237     To install the language <literal>pltcl</literal> into the database
 238     <literal>template1</literal>:
 239 <screen>
 240 <prompt>$ </prompt><userinput>createlang pltcl template1</userinput>
 241 </screen>
 242     Note that installing the language into <literal>template1</literal>
 243     will cause it to be automatically installed into subsequently-created
 244     databases as well.
 245    </para>
 246  </refsect1>
 247
 248  <refsect1>
 249   <title>See Also</title>
 250
 251   <simplelist type="inline">
 252    <member><xref linkend="app-droplang"></member>
 253    <member><xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"></member>
 254   </simplelist>
 255  </refsect1>
 256
 257 </refentry>