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 choice="opt"><replaceable>dbname</replaceable>
  28    <arg choice="opt"><replaceable>description</replaceable></arg></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. (This name
  94         is processed as a double-quoted identifier.)
  95        </para>
  96       </listitem>
  97      </varlistentry>
  98
  99      <varlistentry>
 100       <term><option>-e</></term>
 101       <term><option>--echo</></term>
 102       <listitem>
 103        <para>
 104         Echo the commands that <application>createdb</application> generates
 105         and sends to the server.
 106        </para>
 107       </listitem>
 108      </varlistentry>
 109
 110      <varlistentry>
 111       <term><option>-E <replaceable class="parameter">encoding</replaceable></></term>
 112       <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></></term>
 113       <listitem>
 114        <para>
 115         Specifies the character encoding scheme to be used in this
 116         database. The character sets supported by the
 117         <productname>PostgreSQL</productname> server are described in
 118         <xref linkend="multibyte-charset-supported">.
 119        </para>
 120       </listitem>
 121      </varlistentry>
 122
 123      <varlistentry>
 124       <term><option>-l <replaceable class="parameter">locale</replaceable></></term>
 125       <term><option>--locale=<replaceable class="parameter">locale</replaceable></></term>
 126       <listitem>
 127        <para>
 128         Specifies the locale to be used in this database.  This is equivalent
 129         to specifying both <option>--lc-collate</option> and <option>--lc-ctype</option>.
 130        </para>
 131       </listitem>
 132      </varlistentry>
 133
 134      <varlistentry>
 135       <term><option>--lc-collate=<replaceable class="parameter">locale</replaceable></></term>
 136       <listitem>
 137        <para>
 138         Specifies the LC_COLLATE setting to be used in this database.
 139        </para>
 140       </listitem>
 141      </varlistentry>
 142
 143      <varlistentry>
 144       <term><option>--lc-ctype=<replaceable class="parameter">locale</replaceable></></term>
 145       <listitem>
 146        <para>
 147         Specifies the LC_CTYPE setting to be used in this database.
 148        </para>
 149       </listitem>
 150      </varlistentry>
 151
 152      <varlistentry>
 153       <term><option>-O <replaceable class="parameter">owner</replaceable></></term>
 154       <term><option>--owner=<replaceable class="parameter">owner</replaceable></></term>
 155       <listitem>
 156        <para>
 157         Specifies the database user who will own the new database.
 158         (This name is processed as a double-quoted identifier.)
 159        </para>
 160       </listitem>
 161      </varlistentry>
 162
 163      <varlistentry>
 164       <term><option>-T <replaceable class="parameter">template</replaceable></></term>
 165       <term><option>--template=<replaceable class="parameter">template</replaceable></></term>
 166       <listitem>
 167        <para>
 168         Specifies the template database from which to build this
 169         database.  (This name is processed as a double-quoted identifier.)
 170        </para>
 171       </listitem>
 172      </varlistentry>
 173
 174      <varlistentry>
 175        <term><option>-V</></term>
 176        <term><option>--version</></term>
 177        <listitem>
 178        <para>
 179        Print the <application>createdb</application> version and exit.
 180        </para>
 181        </listitem>
 182      </varlistentry>
 183
 184     <varlistentry>
 185       <term><option>-?</></term>
 186       <term><option>--help</></term>
 187       <listitem>
 188       <para>
 189       Show help about <application>createdb</application> command line
 190       arguments, and exit.
 191       </para>
 192       </listitem>
 193     </varlistentry>
 194
 195     </variablelist>
 196    </para>
 197
 198    <para>
 199     The options <option>-D</option>, <option>-l</option>, <option>-E</option>,
 200     <option>-O</option>, and
 201     <option>-T</option> correspond to options of the underlying
 202     SQL command <xref linkend="SQL-CREATEDATABASE">; see there for more information
 203     about them.
 204    </para>
 205
 206    <para>
 207     <application>createdb</application> also accepts the following
 208     command-line arguments for connection parameters:
 209
 210     <variablelist>
 211      <varlistentry>
 212       <term><option>-h <replaceable class="parameter">host</replaceable></></term>
 213       <term><option>--host=<replaceable class="parameter">host</replaceable></></term>
 214       <listitem>
 215        <para>
 216         Specifies the host name of the machine on which the
 217         server is running.  If the value begins with a slash, it is used
 218         as the directory for the Unix domain socket.
 219        </para>
 220       </listitem>
 221      </varlistentry>
 222
 223      <varlistentry>
 224       <term><option>-p <replaceable class="parameter">port</replaceable></></term>
 225       <term><option>--port=<replaceable class="parameter">port</replaceable></></term>
 226       <listitem>
 227        <para>
 228         Specifies the TCP port or the local Unix domain socket file
 229         extension on which the server is listening for connections.
 230        </para>
 231       </listitem>
 232      </varlistentry>
 233
 234      <varlistentry>
 235       <term><option>-U <replaceable class="parameter">username</replaceable></></term>
 236       <term><option>--username=<replaceable class="parameter">username</replaceable></></term>
 237       <listitem>
 238        <para>
 239         User name to connect as.
 240        </para>
 241       </listitem>
 242      </varlistentry>
 243
 244      <varlistentry>
 245       <term><option>-w</></term>
 246       <term><option>--no-password</></term>
 247       <listitem>
 248        <para>
 249         Never issue a password prompt.  If the server requires
 250         password authentication and a password is not available by
 251         other means such as a <filename>.pgpass</filename> file, the
 252         connection attempt will fail.  This option can be useful in
 253         batch jobs and scripts where no user is present to enter a
 254         password.
 255        </para>
 256       </listitem>
 257      </varlistentry>
 258
 259      <varlistentry>
 260       <term><option>-W</></term>
 261       <term><option>--password</></term>
 262       <listitem>
 263        <para>
 264         Force <application>createdb</application> to prompt for a
 265         password before connecting to a database.
 266        </para>
 267
 268        <para>
 269         This option is never essential, since
 270         <application>createdb</application> will automatically prompt
 271         for a password if the server demands password authentication.
 272         However, <application>createdb</application> will waste a
 273         connection attempt finding out that the server wants a password.
 274         In some cases it is worth typing <option>-W</> to avoid the extra
 275         connection attempt.
 276        </para>
 277       </listitem>
 278      </varlistentry>
 279
 280      <varlistentry>
 281       <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term>
 282       <listitem>
 283        <para>
 284          Specifies the name of the database to connect to when creating the
 285          new database. If not specified, the <literal>postgres</literal>
 286          database will be used; if that does not exist (or if it is the name
 287          of the new database being created), <literal>template1</literal> will
 288          be used.
 289        </para>
 290       </listitem>
 291      </varlistentry>
 292     </variablelist>
 293    </para>
 294
 295  </refsect1>
 296
 297
 298  <refsect1>
 299   <title>Environment</title>
 300
 301   <variablelist>
 302    <varlistentry>
 303     <term><envar>PGDATABASE</envar></term>
 304     <listitem>
 305      <para>
 306       If set, the name of the database to create, unless overridden on
 307       the command line.
 308      </para>
 309     </listitem>
 310    </varlistentry>
 311
 312    <varlistentry>
 313     <term><envar>PGHOST</envar></term>
 314     <term><envar>PGPORT</envar></term>
 315     <term><envar>PGUSER</envar></term>
 316
 317     <listitem>
 318      <para>
 319       Default connection parameters.  <envar>PGUSER</envar> also
 320       determines the name of the database to create, if it is not
 321       specified on the command line or by <envar>PGDATABASE</envar>.
 322      </para>
 323     </listitem>
 324    </varlistentry>
 325   </variablelist>
 326
 327   <para>
 328    This utility, like most other <productname>PostgreSQL</> utilities,
 329    also uses the environment variables supported by <application>libpq</>
 330    (see <xref linkend="libpq-envars">).
 331   </para>
 332
 333  </refsect1>
 334
 335
 336  <refsect1>
 337   <title>Diagnostics</title>
 338
 339   <para>
 340    In case of difficulty, see <xref linkend="SQL-CREATEDATABASE">
 341    and <xref linkend="APP-PSQL"> for
 342    discussions of potential problems and error messages.
 343    The database server must be running at the
 344    targeted host.  Also, any default connection settings and environment
 345    variables used by the <application>libpq</application> front-end
 346    library will apply.
 347   </para>
 348
 349  </refsect1>
 350
 351
 352  <refsect1>
 353   <title>Examples</title>
 354
 355    <para>
 356     To create the database <literal>demo</literal> using the default
 357     database server:
 358 <screen>
 359 <prompt>$ </prompt><userinput>createdb demo</userinput>
 360 </screen>
 361    </para>
 362
 363    <para>
 364     To create the database <literal>demo</literal> using the
 365     server on host <literal>eden</>, port 5000, using the
 366     <literal>LATIN1</literal> encoding scheme with a look at the
 367     underlying command:
 368 <screen>
 369 <prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput>
 370 <computeroutput>CREATE DATABASE demo ENCODING 'LATIN1';</computeroutput>
 371 </screen></para>
 372  </refsect1>
 373
 374
 375  <refsect1>
 376   <title>See Also</title>
 377
 378   <simplelist type="inline">
 379    <member><xref linkend="app-dropdb"></member>
 380    <member><xref linkend="sql-createdatabase"></member>
 381   </simplelist>
 382  </refsect1>
 383
 384 </refentry>