← Back to branch summary

~ubuntu-branches/ubuntu/natty/postgresql-8.4/natty-updates

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/createdb.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2009-03-20 12:00:13 UTC
  • Revision ID: james.westby@ubuntu.com-20090320120013-hogj7egc5mjncc5g
Tags: upstream-8.4~0cvs20090328
Import upstream version 8.4~0cvs20090328

Show diffs side-by-side

added added

removed removed

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