Debian Codegraph @

doc/src/sgml/ref/createdb.sgml

raw
1 <!--
2 doc/src/sgml/ref/createdb.sgml
3 PostgreSQL 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>Description</title>
35 <para>
36 <application>createdb</application> creates a new <productname>PostgreSQL</productname>
37 database.
38 </para>
39
40 <para>
41 Normally, the database user who executes this command becomes the owner of
42 the new database.
43 However, a different owner can be specified via the <option>-O</option>
44 option, if the executing user has appropriate privileges.
45 </para>
46
47 <para>
48 <application>createdb</application> is a wrapper around the
49 <acronym>SQL</acronym> command <link linkend="sql-createdatabase"><command>CREATE DATABASE</command></link>.
50 There is no effective difference between creating databases via
51 this utility and via other methods for accessing the server.
52 </para>
53
54 </refsect1>
55
56
57 <refsect1>
58 <title>Options</title>
59
60 <para>
61 <application>createdb</application> accepts the following command-line arguments:
62
63 <variablelist>
64 <varlistentry>
65 <term><replaceable class="parameter">dbname</replaceable></term>
66 <listitem>
67 <para>
68 Specifies the name of the database to be created. The name must be
69 unique among all <productname>PostgreSQL</productname> databases in this cluster.
70 The default is to create a database with the same name as the
71 current system user.
72 </para>
73 </listitem>
74 </varlistentry>
75
76 <varlistentry>
77 <term><replaceable class="parameter">description</replaceable></term>
78 <listitem>
79 <para>
80 Specifies a comment to be associated with the newly created
81 database.
82 </para>
83 </listitem>
84 </varlistentry>
85
86 <varlistentry>
87 <term><option>-D <replaceable class="parameter">tablespace</replaceable></option></term>
88 <term><option>--tablespace=<replaceable class="parameter">tablespace</replaceable></option></term>
89 <listitem>
90 <para>
91 Specifies the default tablespace for the database. (This name
92 is processed as a double-quoted identifier.)
93 </para>
94 </listitem>
95 </varlistentry>
96
97 <varlistentry>
98 <term><option>-e</option></term>
99 <term><option>--echo</option></term>
100 <listitem>
101 <para>
102 Echo the commands that <application>createdb</application> generates
103 and sends to the server.
104 </para>
105 </listitem>
106 </varlistentry>
107
108 <varlistentry>
109 <term><option>-E <replaceable class="parameter">encoding</replaceable></option></term>
110 <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term>
111 <listitem>
112 <para>
113 Specifies the character encoding scheme to be used in this
114 database. The character sets supported by the
115 <productname>PostgreSQL</productname> server are described in
116 <xref linkend="multibyte-charset-supported"/>.
117 </para>
118 </listitem>
119 </varlistentry>
120
121 <varlistentry>
122 <term><option>-l <replaceable class="parameter">locale</replaceable></option></term>
123 <term><option>--locale=<replaceable class="parameter">locale</replaceable></option></term>
124 <listitem>
125 <para>
126 Specifies the locale to be used in this database. This is equivalent
127 to specifying <option>--lc-collate</option>,
128 <option>--lc-ctype</option>, and <option>--icu-locale</option> to the
129 same value. Some locales are only valid for ICU and must be set with
130 <option>--icu-locale</option>.
131 </para>
132 </listitem>
133 </varlistentry>
134
135 <varlistentry>
136 <term><option>--lc-collate=<replaceable class="parameter">locale</replaceable></option></term>
137 <listitem>
138 <para>
139 Specifies the LC_COLLATE setting to be used in this database.
140 </para>
141 </listitem>
142 </varlistentry>
143
144 <varlistentry>
145 <term><option>--lc-ctype=<replaceable class="parameter">locale</replaceable></option></term>
146 <listitem>
147 <para>
148 Specifies the LC_CTYPE setting to be used in this database.
149 </para>
150 </listitem>
151 </varlistentry>
152
153 <varlistentry>
154 <term><option>--builtin-locale=<replaceable class="parameter">locale</replaceable></option></term>
155 <listitem>
156 <para>
157 Specifies the locale name when the builtin provider is used. Locale support
158 is described in <xref linkend="locale"/>.
159 </para>
160 </listitem>
161 </varlistentry>
162
163 <varlistentry>
164 <term><option>--icu-locale=<replaceable class="parameter">locale</replaceable></option></term>
165 <listitem>
166 <para>
167 Specifies the ICU locale ID to be used in this database, if the
168 ICU locale provider is selected.
169 </para>
170 </listitem>
171 </varlistentry>
172
173 <varlistentry>
174 <term><option>--icu-rules=<replaceable class="parameter">rules</replaceable></option></term>
175 <listitem>
176 <para>
177 Specifies additional collation rules to customize the behavior of the
178 default collation of this database. This is supported for ICU only.
179 </para>
180 </listitem>
181 </varlistentry>
182
183 <varlistentry>
184 <term><option>--locale-provider={<literal>builtin</literal>|<literal>libc</literal>|<literal>icu</literal>}</option></term>
185 <listitem>
186 <para>
187 Specifies the locale provider for the database's default collation.
188 </para>
189 </listitem>
190 </varlistentry>
191
192 <varlistentry>
193 <term><option>-O <replaceable class="parameter">owner</replaceable></option></term>
194 <term><option>--owner=<replaceable class="parameter">owner</replaceable></option></term>
195 <listitem>
196 <para>
197 Specifies the database user who will own the new database.
198 (This name is processed as a double-quoted identifier.)
199 </para>
200 </listitem>
201 </varlistentry>
202
203 <varlistentry>
204 <term><option>-S <replaceable class="parameter">strategy</replaceable></option></term>
205 <term><option>--strategy=<replaceable class="parameter">strategy</replaceable></option></term>
206 <listitem>
207 <para>
208 Specifies the database creation strategy. See
209 <xref linkend="create-database-strategy" /> for more details.
210 </para>
211 </listitem>
212 </varlistentry>
213
214 <varlistentry>
215 <term><option>-T <replaceable class="parameter">template</replaceable></option></term>
216 <term><option>--template=<replaceable class="parameter">template</replaceable></option></term>
217 <listitem>
218 <para>
219 Specifies the template database from which to build this
220 database. (This name is processed as a double-quoted identifier.)
221 </para>
222 </listitem>
223 </varlistentry>
224
225 <varlistentry>
226 <term><option>-V</option></term>
227 <term><option>--version</option></term>
228 <listitem>
229 <para>
230 Print the <application>createdb</application> version and exit.
231 </para>
232 </listitem>
233 </varlistentry>
234
235 <varlistentry>
236 <term><option>-?</option></term>
237 <term><option>--help</option></term>
238 <listitem>
239 <para>
240 Show help about <application>createdb</application> command line
241 arguments, and exit.
242 </para>
243 </listitem>
244 </varlistentry>
245
246 </variablelist>
247 </para>
248
249 <para>
250 The options <option>-D</option>, <option>-l</option>, <option>-E</option>,
251 <option>-O</option>, and
252 <option>-T</option> correspond to options of the underlying
253 SQL command <link linkend="sql-createdatabase"><command>CREATE DATABASE</command></link>; see there for more information
254 about them.
255 </para>
256
257 <para>
258 <application>createdb</application> also accepts the following
259 command-line arguments for connection parameters:
260
261 <variablelist>
262 <varlistentry>
263 <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
264 <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
265 <listitem>
266 <para>
267 Specifies the host name of the machine on which the
268 server is running. If the value begins with a slash, it is used
269 as the directory for the Unix domain socket.
270 </para>
271 </listitem>
272 </varlistentry>
273
274 <varlistentry>
275 <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
276 <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
277 <listitem>
278 <para>
279 Specifies the TCP port or the local Unix domain socket file
280 extension on which the server is listening for connections.
281 </para>
282 </listitem>
283 </varlistentry>
284
285 <varlistentry>
286 <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
287 <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
288 <listitem>
289 <para>
290 User name to connect as.
291 </para>
292 </listitem>
293 </varlistentry>
294
295 <varlistentry>
296 <term><option>-w</option></term>
297 <term><option>--no-password</option></term>
298 <listitem>
299 <para>
300 Never issue a password prompt. If the server requires
301 password authentication and a password is not available by
302 other means such as a <filename>.pgpass</filename> file, the
303 connection attempt will fail. This option can be useful in
304 batch jobs and scripts where no user is present to enter a
305 password.
306 </para>
307 </listitem>
308 </varlistentry>
309
310 <varlistentry>
311 <term><option>-W</option></term>
312 <term><option>--password</option></term>
313 <listitem>
314 <para>
315 Force <application>createdb</application> to prompt for a
316 password before connecting to a database.
317 </para>
318
319 <para>
320 This option is never essential, since
321 <application>createdb</application> will automatically prompt
322 for a password if the server demands password authentication.
323 However, <application>createdb</application> will waste a
324 connection attempt finding out that the server wants a password.
325 In some cases it is worth typing <option>-W</option> to avoid the extra
326 connection attempt.
327 </para>
328 </listitem>
329 </varlistentry>
330
331 <varlistentry>
332 <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
333 <listitem>
334 <para>
335 Specifies the name of the database to connect to when creating the
336 new database. If not specified, the <literal>postgres</literal>
337 database will be used; if that does not exist (or if it is the name
338 of the new database being created), <literal>template1</literal> will
339 be used.
340 This can be a <link linkend="libpq-connstring">connection
341 string</link>. If so, connection string parameters will override any
342 conflicting command line options.
343 </para>
344 </listitem>
345 </varlistentry>
346 </variablelist>
347 </para>
348
349 </refsect1>
350
351
352 <refsect1>
353 <title>Environment</title>
354
355 <variablelist>
356 <varlistentry>
357 <term><envar>PGDATABASE</envar></term>
358 <listitem>
359 <para>
360 If set, the name of the database to create, unless overridden on
361 the command line.
362 </para>
363 </listitem>
364 </varlistentry>
365
366 <varlistentry>
367 <term><envar>PGHOST</envar></term>
368 <term><envar>PGPORT</envar></term>
369 <term><envar>PGUSER</envar></term>
370
371 <listitem>
372 <para>
373 Default connection parameters. <envar>PGUSER</envar> also
374 determines the name of the database to create, if it is not
375 specified on the command line or by <envar>PGDATABASE</envar>.
376 </para>
377 </listitem>
378 </varlistentry>
379
380 <varlistentry>
381 <term><envar>PG_COLOR</envar></term>
382 <listitem>
383 <para>
384 Specifies whether to use color in diagnostic messages. Possible values
385 are <literal>always</literal>, <literal>auto</literal> and
386 <literal>never</literal>.
387 </para>
388 </listitem>
389 </varlistentry>
390 </variablelist>
391
392 <para>
393 This utility, like most other <productname>PostgreSQL</productname> utilities,
394 also uses the environment variables supported by <application>libpq</application>
395 (see <xref linkend="libpq-envars"/>).
396 </para>
397
398 </refsect1>
399
400
401 <refsect1>
402 <title>Diagnostics</title>
403
404 <para>
405 In case of difficulty, see <xref linkend="sql-createdatabase"/>
406 and <xref linkend="app-psql"/> for
407 discussions of potential problems and error messages.
408 The database server must be running at the
409 targeted host. Also, any default connection settings and environment
410 variables used by the <application>libpq</application> front-end
411 library will apply.
412 </para>
413
414 </refsect1>
415
416
417 <refsect1>
418 <title>Examples</title>
419
420 <para>
421 To create the database <literal>demo</literal> using the default
422 database server:
423 <screen>
424 <prompt>$ </prompt><userinput>createdb demo</userinput>
425 </screen>
426 </para>
427
428 <para>
429 To create the database <literal>demo</literal> using the
430 server on host <literal>eden</literal>, port 5000, using the
431 <literal>template0</literal> template database, here is the
432 command-line command and the underlying SQL command:
433 <screen>
434 <prompt>$ </prompt><userinput>createdb -p 5000 -h eden -T template0 -e demo</userinput>
435 <computeroutput>CREATE DATABASE demo TEMPLATE template0;</computeroutput>
436 </screen></para>
437 </refsect1>
438
439
440 <refsect1>
441 <title>See Also</title>
442
443 <simplelist type="inline">
444 <member><xref linkend="app-dropdb"/></member>
445 <member><xref linkend="sql-createdatabase"/></member>
446 </simplelist>
447 </refsect1>
448
449 </refentry>