← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

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

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/create_database.sgml
 
1
<!--
 
2
$PostgreSQL: pgsql/doc/src/sgml/ref/create_database.sgml,v 1.43 2004-10-29 03:17:22 neilc Exp $
 
3
PostgreSQL documentation
 
4
-->
 
5
 
 
6
<refentry id="SQL-CREATEDATABASE">
 
7
 <refmeta>
 
8
  <refentrytitle id="sql-createdatabase-title">CREATE DATABASE</refentrytitle>
 
9
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 
10
 </refmeta>
 
11
 
 
12
 <refnamediv>
 
13
  <refname>CREATE DATABASE</refname>
 
14
  <refpurpose>create a new database</refpurpose>
 
15
 </refnamediv>
 
16
 
 
17
 <indexterm zone="sql-createdatabase">
 
18
  <primary>CREATE DATABASE</primary>
 
19
 </indexterm>
 
20
 
 
21
 <refsynopsisdiv>
 
22
<synopsis>
 
23
CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
 
24
    [ [ WITH ] [ OWNER [=] <replaceable class="parameter">dbowner</replaceable> ]
 
25
           [ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ]
 
26
           [ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ]
 
27
           [ TABLESPACE [=] <replaceable class="parameter">tablespace</replaceable> ] ]
 
28
</synopsis>
 
29
 </refsynopsisdiv>
 
30
 
 
31
 <refsect1>
 
32
  <title>Description</title>
 
33
 
 
34
  <para>
 
35
   <command>CREATE DATABASE</command> creates a new
 
36
   <productname>PostgreSQL</productname> database.
 
37
  </para>
 
38
 
 
39
  <para>
 
40
   To create a database, you must be a superuser or have the special
 
41
   <literal>CREATEDB</> privilege.
 
42
   See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
 
43
  </para>
 
44
 
 
45
  <para>
 
46
   Normally, the creator becomes the owner of the new database.
 
47
   Superusers can create databases owned by other users using the
 
48
   <literal>OWNER</> clause. They can even create databases owned by
 
49
   users with no special privileges. Non-superusers with <literal>CREATEDB</>
 
50
   privilege can only create databases owned by themselves.
 
51
  </para>
 
52
 
 
53
  <para>
 
54
   By default, the new database will be created by cloning the standard
 
55
   system database <literal>template1</>.  A different template can be
 
56
   specified by writing <literal>TEMPLATE
 
57
   <replaceable class="parameter">name</replaceable></literal>.  In particular,
 
58
   by writing <literal>TEMPLATE template0</>, you can create a virgin
 
59
   database containing only the standard objects predefined by your
 
60
   version of <productname>PostgreSQL</productname>.  This is useful
 
61
   if you wish to avoid copying
 
62
   any installation-local objects that may have been added to
 
63
   <literal>template1</>.
 
64
  </para>
 
65
 </refsect1>
 
66
 
 
67
 <refsect1>
 
68
  <title>Parameters</title>
 
69
 
 
70
    <variablelist>
 
71
     <varlistentry>
 
72
      <term><replaceable class="parameter">name</replaceable></term>
 
73
      <listitem>
 
74
       <para>
 
75
        The name of a database to create.
 
76
       </para>
 
77
      </listitem>
 
78
     </varlistentry>
 
79
     <varlistentry>
 
80
      <term><replaceable class="parameter">dbowner</replaceable></term>
 
81
      <listitem>
 
82
       <para>
 
83
        The name of the database user who will own the new database,
 
84
        or <literal>DEFAULT</literal> to use the default (namely, the
 
85
        user executing the command).
 
86
       </para>
 
87
      </listitem>
 
88
     </varlistentry>
 
89
     <varlistentry>
 
90
      <term><replaceable class="parameter">template</replaceable></term>
 
91
      <listitem>
 
92
       <para>
 
93
        The name of the template from which to create the new database,
 
94
        or <literal>DEFAULT</literal> to use the default template
 
95
        (<literal>template1</literal>).
 
96
       </para>
 
97
      </listitem>
 
98
     </varlistentry>
 
99
     <varlistentry>
 
100
      <term><replaceable class="parameter">encoding</replaceable></term>
 
101
      <listitem>
 
102
       <para>
 
103
        Character set encoding to use in the new database.  Specify
 
104
        a string constant (e.g., <literal>'SQL_ASCII'</literal>),
 
105
        or an integer encoding number, or <literal>DEFAULT</literal>
 
106
        to use the default encoding. The character sets supported by the
 
107
        <productname>PostgreSQL</productname> server are described in
 
108
        <xref linkend="multibyte-charset-supported">.
 
109
       </para>
 
110
      </listitem>
 
111
     </varlistentry>
 
112
     <varlistentry>
 
113
      <term><replaceable class="parameter">tablespace</replaceable></term>
 
114
      <listitem>
 
115
       <para>
 
116
        The name of the tablespace that will be associated with the
 
117
        new database, or <literal>DEFAULT</literal> to use the
 
118
        template database's tablespace. This
 
119
        tablespace will be the default tablespace used for objects
 
120
        created in this database. See
 
121
        <xref linkend="sql-createtablespace" endterm="sql-createtablespace-title">
 
122
        for more information.
 
123
       </para>
 
124
      </listitem>
 
125
     </varlistentry>
 
126
    </variablelist>
 
127
 
 
128
  <para>
 
129
   Optional parameters can be written in any order, not only the order
 
130
   illustrated above.
 
131
  </para>
 
132
 </refsect1>
 
133
 
 
134
 <refsect1>
 
135
  <title>Notes</title>
 
136
 
 
137
   <para>
 
138
    <command>CREATE DATABASE</> cannot be executed inside a transaction
 
139
    block.
 
140
   </para>
 
141
 
 
142
   <para>
 
143
    Errors along the line of <quote>could not initialize database directory</>
 
144
    are most likely related to insufficient permissions on the data
 
145
    directory, a full disk, or other file system problems.
 
146
   </para>
 
147
 
 
148
   <para>
 
149
    Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
 
150
   </para>
 
151
 
 
152
   <para>
 
153
    The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a
 
154
    wrapper program around this command, provided for convenience.
 
155
   </para>
 
156
 
 
157
  <para>
 
158
   Although it is possible to copy a database other than <literal>template1</>
 
159
   by specifying its name as the template, this is not (yet) intended as
 
160
   a general-purpose <quote><command>COPY DATABASE</command></quote> facility.
 
161
   We recommend that databases used as templates be treated as read-only.
 
162
   See <xref linkend="manage-ag-templatedbs"> for more information.
 
163
  </para>
 
164
 </refsect1>
 
165
 
 
166
 <refsect1>
 
167
  <title>Examples</title>
 
168
 
 
169
  <para>
 
170
   To create a new database:
 
171
 
 
172
<programlisting>
 
173
CREATE DATABASE lusiadas;
 
174
</programlisting>
 
175
  </para>
 
176
 
 
177
  <para>
 
178
   To create a database <literal>sales</> owned by user <literal>salesapp</>
 
179
   with a default tablespace of <literal>salesspace</>:
 
180
 
 
181
<programlisting>
 
182
CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace;
 
183
</programlisting>
 
184
  </para>
 
185
 
 
186
  <para>
 
187
   To create a database <literal>music</> which supports the ISO-8859-1 
 
188
   character set:
 
189
 
 
190
<programlisting>
 
191
CREATE DATABASE music ENCODING 'LATIN1';
 
192
</programlisting>
 
193
  </para>
 
194
 </refsect1>
 
195
 
 
196
 <refsect1>
 
197
  <title>Compatibility</title>
 
198
 
 
199
  <para>
 
200
   There is no <command>CREATE DATABASE</command> statement in the SQL
 
201
   standard.  Databases are equivalent to catalogs, whose creation is
 
202
   implementation-defined.
 
203
  </para>
 
204
 </refsect1>
 
205
</refentry>
 
206
 
 
207
<!-- Keep this comment at the end of the file
 
208
Local variables:
 
209
mode: sgml
 
210
sgml-omittag:nil
 
211
sgml-shorttag:t
 
212
sgml-minimize-attributes:nil
 
213
sgml-always-quote-attributes:t
 
214
sgml-indent-step:1
 
215
sgml-indent-data:t
 
216
sgml-parent-document:nil
 
217
sgml-default-dtd-file:"../reference.ced"
 
218
sgml-exposed-tags:nil
 
219
sgml-local-catalogs:"/usr/lib/sgml/catalog"
 
220
sgml-local-ecat-files:nil
 
221
End:
 
222
-->