2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.14 2000/05/02 20:02:03 thomas Exp $
6 <refentry id="SQL-CREATEDATABASE">
8 <refentrytitle id="sql-createdatabase-title">
11 <refmiscinfo>SQL - Language Statements</refmiscinfo>
18 Creates a new database
23 <date>1999-12-11</date>
26 CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> [ WITH LOCATION = '<replaceable class="parameter">dbpath</replaceable>' ]
29 <refsect2 id="R2-SQL-CREATEDATABASE-1">
31 <date>1999-12-11</date>
40 <term><replaceable class="parameter">name</replaceable></term>
43 The name of a database to create.
48 <term><replaceable class="parameter">dbpath</replaceable></term>
51 An alternate location where to store the new database in the filesystem.
52 See below for caveats.
60 <refsect2 id="R2-SQL-CREATEDATABASE-2">
62 <date>1999-12-11</date>
71 <term><computeroutput>CREATE DATABASE</computeroutput></term>
74 Message returned if the command completes successfully.
80 <term><computeroutput>ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/drop databases</computeroutput></term>
83 You must have the special CREATEDB privilege to create databases.
84 See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
91 <term><computeroutput>ERROR: createdb: database "<replaceable class="parameter">name</replaceable>" already exists</computeroutput></term>
94 This occurs if a database with the <replaceable class="parameter">name</replaceable>
95 specified already exists.
101 <term><computeroutput>ERROR: Single quotes are not allowed in database names.</computeroutput></term>
102 <term><computeroutput>ERROR: Single quotes are not allowed in database paths.</computeroutput></term>
105 The database <replaceable class="parameter">name</replaceable> and
106 <replaceable class="parameter">dbpath</replaceable> cannot contain
107 single quotes. This is required so that the shell commands that
108 create the database directory can execute safely.
114 <term><computeroutput>ERROR: The path 'xxx' is invalid.</computeroutput></term>
117 The expansion of the specified <replaceable class="parameter">dbpath</replaceable>
118 (see below how) failed. Check the path you entered or make sure that the
119 environment variable you are referencing does exist.
125 <term><computeroutput>ERROR: createdb: May not be called in a transaction block.</computeroutput></term>
128 If you have an explicit transaction block in progress you cannot call
129 <command>CREATE DATABASE</command>. You must finish the transaction first.
135 <term><computeroutput>ERROR: Unable to create database directory '<replaceable>path</replaceable>'.</computeroutput></term>
136 <term><computeroutput>ERROR: Could not initialize database directory.</computeroutput></term>
139 These are most likely related to insufficient permissions on the data
140 directory, a full disk, or other file system problems. The user under
141 which the database server is running, must have access to the location.
151 <refsect1 id="R1-SQL-CREATEDATABASE-1">
153 <date>1999-12-11</date>
159 <command>CREATE DATABASE</command> creates a new
160 <productname>Postgres</productname> database.
161 The creator becomes the owner of the new database.
165 An alternate location can be specified in order to,
166 for example, store the database on a different disk.
167 The path must have been prepared with the
168 <xref linkend="APP-INITLOCATION" endterm="APP-INITLOCATION-title">
172 If the path contains a slash, the leading part is interpreted
173 as an environment variable, which must be known to the
174 server process. This way the database administrator can
175 exercise control over at which locations databases can be created.
176 (A customary choice is, e.g., '<envar>PGDATA2</envar>'.)
177 If the server is compiled with <literal>ALLOW_ABSOLUTE_DBPATHS</literal>
178 (not so by default), absolute path names, as identified by
180 (e.g. '<filename>/usr/local/pgsql/data</filename>'),
184 <refsect2 id="R2-SQL-CREATEDATABASE-3">
186 <date>1999-12-11</date>
192 <command>CREATE DATABASE</command> is a <productname>Postgres</productname>
196 Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
199 The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a
200 shell script wrapper around this command, provided for convenience.
204 There are security and data integrity issues
205 involved with using alternate database locations
206 specified with absolute path names, and by default
207 only an environment variable known to the backend may be
208 specified for an alternate location.
209 See the Administrator's Guide for more information.
213 comment from Olly; response from Thomas...
215 initlocation does not create a PG_VERSION file in the specified location.
216 How will Postgres handle the situation if it is upgraded to an
217 incompatible database version?
219 Hmm. This isn't an issue since the upgrade would do
220 a dump/reload from the main database area also.
221 Not sure if the dump/reload would guarantee that
222 the alternate data area gets refreshed though...
227 <refsect1 id="R1-SQL-CREATEDATABASE-2">
232 To create a new database:
235 <prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
240 To create a new database in an alternate area <filename>~/private_db</filename>:
243 <prompt>$</prompt> <userinput>mkdir private_db</userinput>
244 <prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
245 <computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
247 <prompt>$</prompt> <userinput>psql olly</userinput>
249 Welcome to psql, the PostgreSQL interactive terminal.
251 Type: \copyright for distribution terms
252 \h for help with SQL commands
253 \? for help on internal slash commands
254 \g or terminate with semicolon to execute query
257 <prompt>olly=></prompt></computeroutput> <userinput>CREATE DATABASE elsewhere WITH LOCATION = '/home/olly/private_db';</userinput>
258 <computeroutput>CREATE DATABASE</computeroutput>
263 <refsect1 id="R1-SQL-CREATEDATABASE-4">
268 <refsect2 id="R2-SQL-CREATEDATABASE-4">
270 <date>1998-04-15</date>
276 There is no <command>CREATE DATABASE</command> statement in SQL92.
277 Databases are equivalent to catalogs whose creation is implementation-defined.
283 <!-- Keep this comment at the end of the file
288 sgml-minimize-attributes:nil
289 sgml-always-quote-attributes:t
292 sgml-parent-document:nil
293 sgml-default-dtd-file:"../reference.ced"
294 sgml-exposed-tags:nil
295 sgml-local-catalogs:"/usr/lib/sgml/catalog"
296 sgml-local-ecat-files:nil