1<!--
2doc/src/sgml/ref/createdb.sgml
3PostgreSQL documentation
4-->
5
6<refentry id="APP-CREATEDB">
7 <indexterm zone="app-createdb">
8  <primary>createdb</primary>
9 </indexterm>
10
11 <refmeta>
12  <refentrytitle><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>PostgreSQL</productname> database</refpurpose>
20 </refnamediv>
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         This can be a <link linkend="libpq-connstring">connection
290         string</link>.  If so, connection string parameters will override any
291         conflicting command line options.
292       </para>
293      </listitem>
294     </varlistentry>
295    </variablelist>
296   </para>
297
298 </refsect1>
299
300
301 <refsect1>
302  <title>Environment</title>
303
304  <variablelist>
305   <varlistentry>
306    <term><envar>PGDATABASE</envar></term>
307    <listitem>
308     <para>
309      If set, the name of the database to create, unless overridden on
310      the command line.
311     </para>
312    </listitem>
313   </varlistentry>
314
315   <varlistentry>
316    <term><envar>PGHOST</envar></term>
317    <term><envar>PGPORT</envar></term>
318    <term><envar>PGUSER</envar></term>
319
320    <listitem>
321     <para>
322      Default connection parameters.  <envar>PGUSER</envar> also
323      determines the name of the database to create, if it is not
324      specified on the command line or by <envar>PGDATABASE</envar>.
325     </para>
326    </listitem>
327   </varlistentry>
328  </variablelist>
329
330  <para>
331   This utility, like most other <productname>PostgreSQL</> utilities,
332   also uses the environment variables supported by <application>libpq</>
333   (see <xref linkend="libpq-envars">).
334  </para>
335
336 </refsect1>
337
338
339 <refsect1>
340  <title>Diagnostics</title>
341
342  <para>
343   In case of difficulty, see <xref linkend="SQL-CREATEDATABASE">
344   and <xref linkend="APP-PSQL"> for
345   discussions of potential problems and error messages.
346   The database server must be running at the
347   targeted host.  Also, any default connection settings and environment
348   variables used by the <application>libpq</application> front-end
349   library will apply.
350  </para>
351
352 </refsect1>
353
354
355 <refsect1>
356  <title>Examples</title>
357
358   <para>
359    To create the database <literal>demo</literal> using the default
360    database server:
361<screen>
362<prompt>$ </prompt><userinput>createdb demo</userinput>
363</screen>
364   </para>
365
366   <para>
367    To create the database <literal>demo</literal> using the
368    server on host <literal>eden</>, port 5000, using the
369    <literal>template0</literal> template database,  here is the
370    command-line command and the underlying SQL command:
371<screen>
372<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -T template0 -e demo</userinput>
373<computeroutput>CREATE DATABASE demo TEMPLATE template0;</computeroutput>
374</screen></para>
375 </refsect1>
376
377
378 <refsect1>
379  <title>See Also</title>
380
381  <simplelist type="inline">
382   <member><xref linkend="app-dropdb"></member>
383   <member><xref linkend="sql-createdatabase"></member>
384  </simplelist>
385 </refsect1>
386
387</refentry>
388