granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/createdb.sgml

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.11 2000/11/11 23:01:38 petere Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="APP-CREATEDB" xreflabel="createdb">
   7  <docinfo>
   8   <date>2000-11-11</date>
   9  </docinfo>
  10
  11  <refmeta>
  12   <refentrytitle id="APP-CREATEDB-TITLE"><application>createdb</application></refentrytitle>
  13   <manvolnum>1</manvolnum>
  14   <refmiscinfo>Application</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>createdb</refname>
  19   <refpurpose>Create a new <productname>Postgres</productname> database</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>createdb</command>
  25    <arg rep="repeat"><replaceable>options</replaceable></arg>
  26    <arg choice="plain"><replaceable>dbname</replaceable></arg>
  27    <arg><replaceable>description</replaceable></arg>
  28   </cmdsynopsis>
  29
  30   <refsect2 id="R2-APP-CREATEDB-1">
  31    <title>
  32     Inputs
  33    </title>
  34    <para>
  35
  36     <variablelist>
  37      <varlistentry>
  38       <term>-h, --host <replaceable class="parameter">host</replaceable></term>
  39       <listitem>
  40        <para>
  41         Specifies the hostname of the machine on which the
  42         <application>postmaster</application>
  43         is running.
  44        </para>
  45       </listitem>
  46      </varlistentry>
  47
  48      <varlistentry>
  49       <term>-p, --port <replaceable class="parameter">port</replaceable></term>
  50       <listitem>
  51        <para>
  52         Specifies the Internet TCP/IP port or local Unix domain socket file
  53         extension on which the <application>postmaster</application>
  54         is listening for connections.
  55        </para>
  56       </listitem>
  57      </varlistentry>
  58
  59      <varlistentry>
  60       <term>-U, --username <replaceable class="parameter">username</replaceable></term>
  61       <listitem>
  62        <para>
  63         Username to connect as.
  64        </para>
  65       </listitem>
  66      </varlistentry>
  67
  68      <varlistentry>
  69       <term>-W, --password</term>
  70       <listitem>
  71        <para>
  72         Force password prompt.
  73        </para>
  74       </listitem>
  75      </varlistentry>
  76
  77      <varlistentry>
  78       <term>-e, --echo</term>
  79       <listitem>
  80        <para>
  81         Echo the queries that <application>createdb</application> generates
  82         and sends to the backend.
  83        </para>
  84       </listitem>
  85      </varlistentry>
  86
  87      <varlistentry>
  88       <term>-q, --quiet</term>
  89       <listitem>
  90        <para>
  91         Do not display a response.
  92        </para>
  93       </listitem>
  94      </varlistentry>
  95
  96      <varlistentry>
  97       <term>-D, --location <replaceable class="parameter">datadir</replaceable></term>
  98       <listitem>
  99        <para>
 100         Specifies the alternative database location.  See also <xref
 101         linkend="app-initlocation" endterm="app-initlocation-title">.
 102        </para>
 103       </listitem>
 104      </varlistentry>
 105
 106      <varlistentry>
 107       <term>-E, --encoding <replaceable class="parameter">encoding</replaceable></term>
 108       <listitem>
 109        <para>
 110         Specifies the character encoding scheme to be used with this database.
 111        </para>
 112       </listitem>
 113      </varlistentry>
 114
 115      <varlistentry>
 116       <term><replaceable class="parameter">dbname</replaceable></term>
 117       <listitem>
 118        <para>
 119         Specifies the name of the database to be created.  The name must be
 120         unique among all <productname>Postgres</productname> databases in this installation.
 121         The default is to create a database with the same name as the
 122         current system user.
 123        </para>
 124       </listitem>
 125      </varlistentry>
 126
 127      <varlistentry>
 128       <term><replaceable class="parameter">description</replaceable></term>
 129       <listitem>
 130        <para>
 131         This optionally specifies a comment to be associated with the newly created
 132         database.
 133        </para>
 134       </listitem>
 135      </varlistentry>
 136
 137     </variablelist>
 138
 139     The options <literal>-h</literal>, <literal>-p</literal>, <literal>-U</literal>,
 140     <literal>-W</literal>, and <literal>-e</literal> are passed on literally to
 141     <xref linkend="APP-PSQL" endterm="APP-PSQL-title">.
 142    </para>
 143   </refsect2>
 144
 145   <refsect2 id="R2-APP-CREATEDB-2">
 146    <title>
 147     Outputs
 148    </title>
 149    <para>
 150     <variablelist>
 151      <varlistentry>
 152       <term><computeroutput>CREATE DATABASE</computeroutput></term>
 153       <listitem>
 154        <para>The database was successfully created.</para>
 155       </listitem>
 156      </varlistentry>
 157
 158      <varlistentry>
 159       <term><computeroutput>createdb: Database creation failed.</computeroutput></term>
 160       <listitem>
 161        <para>(Says it all.)</para>
 162       </listitem>
 163      </varlistentry>
 164
 165      <varlistentry>
 166       <term><computeroutput>createdb: Comment creation failed. (Database was created.)</computeroutput></term>
 167       <listitem>
 168        <para>
 169        The comment/description for the database could not be created.
 170        the database itself will have been created already. You can use the
 171        <acronym>SQL</acronym> command <command>COMMENT ON DATABASE</command> to
 172        create the comment later on.
 173        </para>
 174       </listitem>
 175      </varlistentry>
 176     </variablelist>
 177
 178     If there is an error condition, the backend error message will be displayed.
 179     See <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title">
 180     and <xref linkend="APP-PSQL" endterm="APP-PSQL-title"> for possibilities.
 181    </para>
 182   </refsect2>
 183  </refsynopsisdiv>
 184
 185  <refsect1 id="R1-APP-CREATEDB-1">
 186   <title>
 187    Description
 188   </title>
 189   <para>
 190    <application>createdb</application> creates a new <productname>Postgres</productname>
 191    database. The user who executes this command becomes the database owner.
 192   </para>
 193
 194   <para>
 195    <application>createdb</application> is a shell script wrapper around the
 196    <acronym>SQL</acronym> command
 197    <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via
 198    the <productname>Postgres</productname> interactive terminal
 199    <xref linkend="APP-PSQL" endterm="APP-PSQL-title">. Thus, there is nothing
 200    special about creating databases via this or other methods. This means
 201    that the <application>psql</application> must be found by the script and that
 202    a database server is running at the targeted host. Also, any default
 203    settings and environment variables available to <application>psql</application>
 204    and the <application>libpq</application> front-end library do apply.
 205   </para>
 206  </refsect1>
 207
 208  <refsect1 id="R1-APP-CREATEDB-2">
 209   <title>Usage</title>
 210
 211   <informalexample>
 212    <para>
 213     To create the database <literal>demo</literal> using the default
 214     database server:
 215 <screen>
 216 <prompt>$ </prompt><userinput>createdb demo</userinput>
 217 <computeroutput>CREATE DATABASE</computeroutput>
 218 </screen>
 219     The response is the same as you would have gotten from running the
 220     <command>CREATE DATABASE</command> <acronym>SQL</acronym> command.
 221    </para>
 222   </informalexample>
 223
 224   <informalexample>
 225    <para>
 226     To create the database <literal>demo</literal> using the
 227     postmaster on host eden, port 5000, using the
 228     <literal>LATIN1</literal> encoding scheme with a look at the
 229     underlying query:
 230 <screen>
 231 <prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput>
 232 <computeroutput>CREATE DATABASE "demo" WITH ENCODING = 'LATIN1'</computeroutput>
 233 <computeroutput>CREATE DATABASE</computeroutput>
 234 </screen>
 235    </para>
 236   </informalexample>
 237  </refsect1>
 238 </refentry>
 239
 240 <!-- Keep this comment at the end of the file
 241 Local variables:
 242 mode: sgml
 243 sgml-omittag:nil
 244 sgml-shorttag:t
 245 sgml-minimize-attributes:nil
 246 sgml-always-quote-attributes:t
 247 sgml-indent-step:1
 248 sgml-indent-data:t
 249 sgml-parent-document:nil
 250 sgml-default-dtd-file:"../reference.ced"
 251 sgml-exposed-tags:nil
 252 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 253 sgml-local-ecat-files:nil
 254 End:
 255 -->