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

   1 <REFENTRY ID="APP-CREATEDB">
   2 <REFMETA>
   3 <REFENTRYTITLE>
   4 <application>createdb</application>
   5 </REFENTRYTITLE>
   6 <REFMISCINFO>Application</REFMISCINFO>
   7 </REFMETA>
   8 <REFNAMEDIV>
   9 <REFNAME>
  10 <application>createdb</application>
  11 </REFNAME>
  12 <REFPURPOSE>
  13 Create a new <productname>Postgres</productname> database
  14 </REFPURPOSE>
  15 <REFSYNOPSISDIV>
  16 <REFSYNOPSISDIVINFO>
  17 <DATE>1998-10-02</DATE>
  18 </REFSYNOPSISDIVINFO>
  19 <SYNOPSIS>
  20 createdb [ <replaceable class="parameter">dbname</replaceable> ]
  21 createdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
  22     [ -D <replaceable class="parameter">datadir</replaceable> ]
  23     [ -u ] [ <replaceable class="parameter">dbname</replaceable> ]
  24 </SYNOPSIS>
  25
  26 <REFSECT2 ID="R2-APP-CREATEDB-1">
  27 <REFSECT2INFO>
  28 <DATE>1998-10-02</DATE>
  29 </REFSECT2INFO>
  30 <TITLE>
  31 Inputs
  32 </TITLE>
  33 <PARA>
  34
  35 <variablelist>
  36 <varlistentry>
  37 <term>
  38 -h <replaceable class="parameter">host</replaceable>
  39 </term>
  40 <listitem>
  41 <para>
  42 Specifies the hostname of the machine on which the
  43 <application>postmaster</application>
  44 is running.  Defaults to using a local Unix domain socket
  45  rather than an IP connection..
  46
  47 <varlistentry>
  48 <term>
  49 -p <replaceable class="parameter">port</replaceable>
  50 </term>
  51 <listitem>
  52 <para>
  53 Specifies the Internet TCP/IP port or local Unix domain socket file
  54 extension on which the <application>postmaster</application>
  55 is listening for connections.  The port number defaults to 5432,
  56  or the value of the <envar>PGPORT</envar>
  57 environment variable (if set).
  58
  59 <varlistentry>
  60 <term>
  61 -u
  62 </term>
  63 <listitem>
  64 <para>
  65 Use password authentication.
  66 Prompts for
  67 <replaceable class="parameter">username</replaceable>
  68  and <replaceable class="parameter">password</replaceable>.
  69
  70 <varlistentry>
  71 <term>
  72 -D <replaceable class="parameter">datadir</replaceable>
  73 </term>
  74 <listitem>
  75 <para>
  76 Specifies the alternate database location for this database installation.
  77 This is the location of the installation system tables, not the location
  78 of this specific database, which may be different.
  79
  80 <varlistentry>
  81 <term>
  82 <replaceable class="parameter">dbname</replaceable>
  83 </term>
  84 <listitem>
  85 <para>
  86 Specifies the name of the database to be created.  The name must be
  87 unique among all <productname>Postgres</productname> databases in this installation.
  88 <replaceable class="parameter">dbname</replaceable>
  89 defaults to the value of the
  90 <envar>USER</envar>
  91 environment variable.
  92
  93 </variablelist>
  94
  95 <REFSECT2 ID="R2-APP-CREATEDB-2">
  96 <REFSECT2INFO>
  97 <DATE>1998-10-02</DATE>
  98 </REFSECT2INFO>
  99 <TITLE>
 100 Outputs
 101 </TITLE>
 102 <PARA>
 103 <application>createdb</application> will create files in the
 104 <filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
 105 data area for the new database.
 106
 107 <variablelist>
 108 <varlistentry>
 109 <term>
 110 Connection to database 'template1' failed.
 111 connectDB() failed: Is the postmaster running and accepting connections
 112  at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
 113 createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
 114 <listitem>
 115 <para>
 116 <application>createdb</application> could not attach to the
 117 <application>postmaster</application>
 118 process on the specified host and port.  If you see this message,
 119 ensure that the <application>postmaster</application>
 120 is running on the proper host and that you have specified the proper
 121 port.  If your site uses an authentication system, ensure that you
 122 have obtained the required authentication credentials.
 123
 124 <varlistentry>
 125 <term>
 126 Connection to database 'template1' failed.
 127 FATAL 1:  SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
 128 createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
 129 <listitem>
 130 <para>
 131 You do not have a valid entry in the relation <literal>pg_shadow</literal>
 132 and and will not be allowed to access <productname>Postgres</productname>.
 133 Contact your <productname>Postgres</productname> administrator.
 134
 135 <varlistentry>
 136 <term>
 137 ERROR:  user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
 138 createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
 139 <listitem>
 140 <para>
 141 You do not have permission to create new databases.
 142 Contact your <productname>Postgres</productname> site administrator.
 143
 144 <varlistentry>
 145 <term>
 146 ERROR:  createdb: database '<replaceable class="parameter">dbname</replaceable>' already exists.
 147 createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
 148 <listitem>
 149 <para>
 150 The database already exists.
 151
 152 <varlistentry>
 153 <term>
 154 createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
 155 <listitem>
 156 <para>
 157 An internal error occurred in <application>psql</application>
 158 or in the backend server.  Ensure that your site administrator has
 159 properly installed <productname>Postgres</productname>and initialized the site with
 160 <application>initdb</application>.
 161
 162 </variablelist>
 163
 164 <note>
 165 <para>
 166 <application>createdb</application> internally runs
 167 CREATE DATABASE from <application>psql</application>
 168 while connected to the <literal>template1</literal> database.
 169 </note>
 170
 171 <REFSECT1 ID="R1-APP-CREATEDB-1">
 172 <REFSECT1INFO>
 173 <DATE>1998-10-02</DATE>
 174 </REFSECT1INFO>
 175 <TITLE>
 176 Description
 177 </TITLE>
 178 <PARA>
 179 <application>createdb</application> creates a new
 180 <productname>Postgres</productname> database.
 181 The person who executes this command becomes
 182 the database administrator, or <acronym>DBA</acronym>,
 183  for this database and is the only
 184 person, other than the <productname>Postgres</productname> super-user,
 185  who can destroy it.
 186
 187 <para>
 188 <application>createdb</application> is a shell script that invokes
 189 <application>psql</application>.
 190 Hence, a <application>postmaster</application>
 191 process must be running on the database server host before
 192 <application>createdb</application>
 193 is executed. The
 194 <envar>PGOPTION</envar>
 195 and
 196 <envar>PGREALM</envar>
 197 environment variables will be passed on to
 198 <application>psql</application>
 199 and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
 200
 201 <REFSECT1 ID="R1-APP-CREATEDB-2">
 202 <REFSECT1INFO>
 203 <DATE>1998-10-02</DATE>
 204 </REFSECT1INFO>
 205 <TITLE>
 206 Usage
 207 </TITLE>
 208 <PARA>
 209 To create the database <literal>demo</literal>
 210  using the postmaster on the local host, port 5432:
 211 <programlisting>
 212 createdb demo
 213 </programlisting>
 214
 215 To create the database <literal>demo</literal>
 216  using the postmaster on host eden, port 5000:
 217 <programlisting>
 218 createdb -p 5000 -h eden demo
 219 </programlisting>
 220
 221 </REFENTRY>