doc/src/sgml/ref/createdb.sgml

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/createdb.sgml,v 1.46 2007/06/21 10:43:09 petere Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="APP-CREATEDB">
   7  <refmeta>
   8   <refentrytitle id="APP-CREATEDB-TITLE"><application>createdb</application></refentrytitle>
   9   <manvolnum>1</manvolnum>
  10   <refmiscinfo>Application</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>createdb</refname>
  15   <refpurpose>create a new <productname>PostgreSQL</productname> database</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="app-createdb">
  19   <primary>createdb</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>createdb</command>
  25    <arg rep="repeat"><replaceable>option</replaceable></arg>
  26    <arg><replaceable>dbname</replaceable></arg>
  27    <arg><replaceable>description</replaceable></arg>
  28   </cmdsynopsis>
  29  </refsynopsisdiv>
  30
  31
  32  <refsect1 id="R1-APP-CREATEDB-1">
  33   <title>
  34    Description
  35   </title>
  36   <para>
  37    <application>createdb</application> creates a new <productname>PostgreSQL</productname>
  38    database.
  39   </para>
  40
  41   <para>
  42    Normally, the database user who executes this command becomes the owner of
  43    the new database.
  44    However a different owner can be specified via the <option>-O</option>
  45    option, if the executing user has appropriate privileges.
  46   </para>
  47
  48   <para>
  49    <application>createdb</application> is a wrapper around the
  50    <acronym>SQL</acronym> command <xref linkend="SQL-CREATEDATABASE"
  51    endterm="SQL-CREATEDATABASE-title">.
  52    There is no effective difference between creating databases via
  53    this utility and via other methods for accessing the server.
  54   </para>
  55
  56  </refsect1>
  57
  58
  59  <refsect1>
  60   <title>Options</title>
  61
  62   <para>
  63    <application>createdb</application> accepts the following command-line arguments:
  64
  65     <variablelist>
  66      <varlistentry>
  67       <term><replaceable class="parameter">dbname</replaceable></term>
  68       <listitem>
  69        <para>
  70         Specifies the name of the database to be created.  The name must be
  71         unique among all <productname>PostgreSQL</productname> databases in this cluster.
  72         The default is to create a database with the same name as the
  73         current system user.
  74        </para>
  75       </listitem>
  76      </varlistentry>
  77
  78      <varlistentry>
  79       <term><replaceable class="parameter">description</replaceable></term>
  80       <listitem>
  81        <para>
  82         Specifies a comment to be associated with the newly created
  83         database.
  84        </para>
  85       </listitem>
  86      </varlistentry>
  87
  88      <varlistentry>
  89       <term><option>-D <replaceable class="parameter">tablespace</replaceable></></term>
  90       <term><option>--tablespace <replaceable class="parameter">tablespace</replaceable></></term>
  91       <listitem>
  92        <para>
  93         Specifies the default tablespace for the database.
  94        </para>
  95       </listitem>
  96      </varlistentry>
  97
  98      <varlistentry>
  99       <term><option>-e</></term>
 100       <term><option>--echo</></term>
 101       <listitem>
 102        <para>
 103         Echo the commands that <application>createdb</application> generates
 104         and sends to the server.
 105        </para>
 106       </listitem>
 107      </varlistentry>
 108
 109      <varlistentry>
 110       <term><option>-E <replaceable class="parameter">encoding</replaceable></></term>
 111       <term><option>--encoding <replaceable class="parameter">encoding</replaceable></></term>
 112       <listitem>
 113        <para>
 114         Specifies the character encoding scheme to be used in this
 115         database. The character sets supported by the
 116         <productname>PostgreSQL</productname> server are described in
 117         <xref linkend="multibyte-charset-supported">.
 118        </para>
 119       </listitem>
 120      </varlistentry>
 121
 122      <varlistentry>
 123       <term><option>-O <replaceable class="parameter">owner</replaceable></></term>
 124       <term><option>--owner <replaceable class="parameter">owner</replaceable></></term>
 125       <listitem>
 126        <para>
 127         Specifies the database user who will own the new database.
 128        </para>
 129       </listitem>
 130      </varlistentry>
 131
 132      <varlistentry>
 133       <term><option>-T <replaceable class="parameter">template</replaceable></></term>
 134       <term><option>--template <replaceable class="parameter">template</replaceable></></term>
 135       <listitem>
 136        <para>
 137         Specifies the template database from which to build this database.
 138        </para>
 139       </listitem>
 140      </varlistentry>
 141     </variablelist>
 142    </para>
 143
 144    <para>
 145     The options <option>-D</option>, <option>-E</option>,
 146     <option>-O</option>, and
 147     <option>-T</option> correspond to options of the underlying
 148     SQL command <xref linkend="SQL-CREATEDATABASE"
 149     endterm="SQL-CREATEDATABASE-title">; see there for more information
 150     about them.
 151    </para>
 152
 153    <para>
 154     <application>createdb</application> also accepts the following
 155     command-line arguments for connection parameters:
 156
 157     <variablelist>
 158      <varlistentry>
 159       <term><option>-h <replaceable class="parameter">host</replaceable></></term>
 160       <term><option>--host <replaceable class="parameter">host</replaceable></></term>
 161       <listitem>
 162        <para>
 163         Specifies the host name of the machine on which the
 164         server is running.  If the value begins with a slash, it is used
 165         as the directory for the Unix domain socket.
 166        </para>
 167       </listitem>
 168      </varlistentry>
 169
 170      <varlistentry>
 171       <term><option>-p <replaceable class="parameter">port</replaceable></></term>
 172       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
 173       <listitem>
 174        <para>
 175         Specifies the TCP port or the local Unix domain socket file
 176         extension on which the server is listening for connections.
 177        </para>
 178       </listitem>
 179      </varlistentry>
 180
 181      <varlistentry>
 182       <term><option>-U <replaceable class="parameter">username</replaceable></></term>
 183       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
 184       <listitem>
 185        <para>
 186         User name to connect as
 187        </para>
 188       </listitem>
 189      </varlistentry>
 190
 191      <varlistentry>
 192       <term><option>-W</></term>
 193       <term><option>--password</></term>
 194       <listitem>
 195        <para>
 196         Force password prompt.
 197        </para>
 198       </listitem>
 199      </varlistentry>
 200     </variablelist>
 201    </para>
 202
 203  </refsect1>
 204
 205
 206  <refsect1>
 207   <title>Environment</title>
 208
 209   <variablelist>
 210    <varlistentry>
 211     <term><envar>PGDATABASE</envar></term>
 212     <listitem>
 213      <para>
 214       If set, the name of the database to create, unless overridden on
 215       the command line.
 216      </para>
 217     </listitem>
 218    </varlistentry>
 219
 220    <varlistentry>
 221     <term><envar>PGHOST</envar></term>
 222     <term><envar>PGPORT</envar></term>
 223     <term><envar>PGUSER</envar></term>
 224
 225     <listitem>
 226      <para>
 227       Default connection parameters.  <envar>PGUSER</envar> also
 228       determines the name of the database to create, if it is not
 229       specified on the command line or by <envar>PGDATABASE</envar>.
 230      </para>
 231     </listitem>
 232    </varlistentry>
 233   </variablelist>
 234
 235   <para>
 236    This utility, like most other <productname>PostgreSQL</> utilities,
 237    also uses the environment variables supported by <application>libpq</>
 238    (see <xref linkend="libpq-envars">).
 239   </para>
 240
 241  </refsect1>
 242
 243
 244  <refsect1>
 245   <title>Diagnostics</title>
 246
 247   <para>
 248    In case of difficulty, see <xref linkend="SQL-CREATEDATABASE"
 249    endterm="sql-createdatabase-title"> and <xref linkend="APP-PSQL"> for
 250    discussions of potential problems and error messages.
 251    The database server must be running at the
 252    targeted host.  Also, any default connection settings and environment
 253    variables used by the <application>libpq</application> front-end
 254    library will apply.
 255   </para>
 256
 257  </refsect1>
 258
 259
 260  <refsect1>
 261   <title>Examples</title>
 262
 263    <para>
 264     To create the database <literal>demo</literal> using the default
 265     database server:
 266 <screen>
 267 <prompt>$ </prompt><userinput>createdb demo</userinput>
 268 </screen>
 269    </para>
 270
 271    <para>
 272     To create the database <literal>demo</literal> using the
 273     server on host <literal>eden</>, port 5000, using the
 274     <literal>LATIN1</literal> encoding scheme with a look at the
 275     underlying command:
 276 <screen>
 277 <prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput>
 278 <computeroutput>CREATE DATABASE demo ENCODING 'LATIN1';</computeroutput>
 279 </screen>
 280    </para>
 281  </refsect1>
 282
 283
 284  <refsect1>
 285   <title>See Also</title>
 286
 287   <simplelist type="inline">
 288    <member><xref linkend="app-dropdb"></member>
 289    <member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member>
 290   </simplelist>
 291  </refsect1>
 292
 293 </refentry>