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

   1 <!--
   2 doc/src/sgml/ref/createdb.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="APP-CREATEDB">
   7  <refmeta>
   8   <refentrytitle><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>connection-option</replaceable></arg>
  26    <arg rep="repeat"><replaceable>option</replaceable></arg>
  27    <arg><replaceable>dbname</replaceable></arg>
  28    <arg><replaceable>description</replaceable></arg>
  29   </cmdsynopsis>
  30  </refsynopsisdiv>
  31
  32
  33  <refsect1 id="R1-APP-CREATEDB-1">
  34   <title>
  35    Description
  36   </title>
  37   <para>
  38    <application>createdb</application> creates a new <productname>PostgreSQL</productname>
  39    database.
  40   </para>
  41
  42   <para>
  43    Normally, the database user who executes this command becomes the owner of
  44    the new database.
  45    However, a different owner can be specified via the <option>-O</option>
  46    option, if the executing user has appropriate privileges.
  47   </para>
  48
  49   <para>
  50    <application>createdb</application> is a wrapper around the
  51    <acronym>SQL</acronym> command <xref linkend="SQL-CREATEDATABASE">.
  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>-l <replaceable class="parameter">locale</replaceable></></term>
 124       <term><option>--locale=<replaceable class="parameter">locale</replaceable></></term>
 125       <listitem>
 126        <para>
 127         Specifies the locale to be used in this database.  This is equivalent
 128         to specifying both <option>--lc-collate</option> and <option>--lc-ctype</option>.
 129        </para>
 130       </listitem>
 131      </varlistentry>
 132
 133      <varlistentry>
 134       <term><option>--lc-collate=<replaceable class="parameter">locale</replaceable></></term>
 135       <listitem>
 136        <para>
 137         Specifies the LC_COLLATE setting to be used in this database.
 138        </para>
 139       </listitem>
 140      </varlistentry>
 141
 142      <varlistentry>
 143       <term><option>--lc-ctype=<replaceable class="parameter">locale</replaceable></></term>
 144       <listitem>
 145        <para>
 146         Specifies the LC_CTYPE setting to be used in this database.
 147        </para>
 148       </listitem>
 149      </varlistentry>
 150
 151      <varlistentry>
 152       <term><option>-O <replaceable class="parameter">owner</replaceable></></term>
 153       <term><option>--owner=<replaceable class="parameter">owner</replaceable></></term>
 154       <listitem>
 155        <para>
 156         Specifies the database user who will own the new database.
 157        </para>
 158       </listitem>
 159      </varlistentry>
 160
 161      <varlistentry>
 162       <term><option>-T <replaceable class="parameter">template</replaceable></></term>
 163       <term><option>--template=<replaceable class="parameter">template</replaceable></></term>
 164       <listitem>
 165        <para>
 166         Specifies the template database from which to build this database.
 167        </para>
 168       </listitem>
 169      </varlistentry>
 170
 171      <varlistentry>
 172        <term><option>-V</></term>
 173        <term><option>--version</></term>
 174        <listitem>
 175        <para>
 176        Print the <application>createdb</application> version and exit.
 177        </para>
 178        </listitem>
 179      </varlistentry>
 180
 181     <varlistentry>
 182       <term><option>-?</></term>
 183       <term><option>--help</></term>
 184       <listitem>
 185       <para>
 186       Show help about <application>createdb</application> command line
 187       arguments, and exit.
 188       </para>
 189       </listitem>
 190     </varlistentry>
 191
 192     </variablelist>
 193    </para>
 194
 195    <para>
 196     The options <option>-D</option>, <option>-l</option>, <option>-E</option>,
 197     <option>-O</option>, and
 198     <option>-T</option> correspond to options of the underlying
 199     SQL command <xref linkend="SQL-CREATEDATABASE">; see there for more information
 200     about them.
 201    </para>
 202
 203    <para>
 204     <application>createdb</application> also accepts the following
 205     command-line arguments for connection parameters:
 206
 207     <variablelist>
 208      <varlistentry>
 209       <term><option>-h <replaceable class="parameter">host</replaceable></></term>
 210       <term><option>--host=<replaceable class="parameter">host</replaceable></></term>
 211       <listitem>
 212        <para>
 213         Specifies the host name of the machine on which the
 214         server is running.  If the value begins with a slash, it is used
 215         as the directory for the Unix domain socket.
 216        </para>
 217       </listitem>
 218      </varlistentry>
 219
 220      <varlistentry>
 221       <term><option>-p <replaceable class="parameter">port</replaceable></></term>
 222       <term><option>--port=<replaceable class="parameter">port</replaceable></></term>
 223       <listitem>
 224        <para>
 225         Specifies the TCP port or the local Unix domain socket file
 226         extension on which the server is listening for connections.
 227        </para>
 228       </listitem>
 229      </varlistentry>
 230
 231      <varlistentry>
 232       <term><option>-U <replaceable class="parameter">username</replaceable></></term>
 233       <term><option>--username=<replaceable class="parameter">username</replaceable></></term>
 234       <listitem>
 235        <para>
 236         User name to connect as.
 237        </para>
 238       </listitem>
 239      </varlistentry>
 240
 241      <varlistentry>
 242       <term><option>-w</></term>
 243       <term><option>--no-password</></term>
 244       <listitem>
 245        <para>
 246         Never issue a password prompt.  If the server requires
 247         password authentication and a password is not available by
 248         other means such as a <filename>.pgpass</filename> file, the
 249         connection attempt will fail.  This option can be useful in
 250         batch jobs and scripts where no user is present to enter a
 251         password.
 252        </para>
 253       </listitem>
 254      </varlistentry>
 255
 256      <varlistentry>
 257       <term><option>-W</></term>
 258       <term><option>--password</></term>
 259       <listitem>
 260        <para>
 261         Force <application>createdb</application> to prompt for a
 262         password before connecting to a database.
 263        </para>
 264
 265        <para>
 266         This option is never essential, since
 267         <application>createdb</application> will automatically prompt
 268         for a password if the server demands password authentication.
 269         However, <application>createdb</application> will waste a
 270         connection attempt finding out that the server wants a password.
 271         In some cases it is worth typing <option>-W</> to avoid the extra
 272         connection attempt.
 273        </para>
 274       </listitem>
 275      </varlistentry>
 276     </variablelist>
 277    </para>
 278
 279  </refsect1>
 280
 281
 282  <refsect1>
 283   <title>Environment</title>
 284
 285   <variablelist>
 286    <varlistentry>
 287     <term><envar>PGDATABASE</envar></term>
 288     <listitem>
 289      <para>
 290       If set, the name of the database to create, unless overridden on
 291       the command line.
 292      </para>
 293     </listitem>
 294    </varlistentry>
 295
 296    <varlistentry>
 297     <term><envar>PGHOST</envar></term>
 298     <term><envar>PGPORT</envar></term>
 299     <term><envar>PGUSER</envar></term>
 300
 301     <listitem>
 302      <para>
 303       Default connection parameters.  <envar>PGUSER</envar> also
 304       determines the name of the database to create, if it is not
 305       specified on the command line or by <envar>PGDATABASE</envar>.
 306      </para>
 307     </listitem>
 308    </varlistentry>
 309   </variablelist>
 310
 311   <para>
 312    This utility, like most other <productname>PostgreSQL</> utilities,
 313    also uses the environment variables supported by <application>libpq</>
 314    (see <xref linkend="libpq-envars">).
 315   </para>
 316
 317  </refsect1>
 318
 319
 320  <refsect1>
 321   <title>Diagnostics</title>
 322
 323   <para>
 324    In case of difficulty, see <xref linkend="SQL-CREATEDATABASE">
 325    and <xref linkend="APP-PSQL"> for
 326    discussions of potential problems and error messages.
 327    The database server must be running at the
 328    targeted host.  Also, any default connection settings and environment
 329    variables used by the <application>libpq</application> front-end
 330    library will apply.
 331   </para>
 332
 333  </refsect1>
 334
 335
 336  <refsect1>
 337   <title>Examples</title>
 338
 339    <para>
 340     To create the database <literal>demo</literal> using the default
 341     database server:
 342 <screen>
 343 <prompt>$ </prompt><userinput>createdb demo</userinput>
 344 </screen>
 345    </para>
 346
 347    <para>
 348     To create the database <literal>demo</literal> using the
 349     server on host <literal>eden</>, port 5000, using the
 350     <literal>LATIN1</literal> encoding scheme with a look at the
 351     underlying command:
 352 <screen>
 353 <prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput>
 354 <computeroutput>CREATE DATABASE demo ENCODING 'LATIN1';</computeroutput>
 355 </screen></para>
 356  </refsect1>
 357
 358
 359  <refsect1>
 360   <title>See Also</title>
 361
 362   <simplelist type="inline">
 363    <member><xref linkend="app-dropdb"></member>
 364    <member><xref linkend="sql-createdatabase"></member>
 365   </simplelist>
 366  </refsect1>
 367
 368 </refentry>