database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-08-09 17:03:00 +03:00
Code Activity

Clean up treatment of creating/dropping databases in User's Guide and

Browse Source 
Admin Guide.  Move discussion of template databases out of footnotes
in CREATE DATABASE ref page and into a section of the Admin Guide.
Clean up various obsolete claims, do some copy-editing.
This commit is contained in:
Tom Lane
2001-11-18 00:38:00 +00:00
parent c9a85cb276
commit 0729c4a61f
4 changed files with 188 additions and 335 deletions
Download Patch File Download Diff File Expand all files Collapse all files

261
doc/src/sgml/manage-ag.sgml
View File

@@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.17 2001/11/12 19:19:39 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.18 2001/11/18 00:38:00 tgl Exp $
--> -->
<chapter id="managing-databases"> <chapter id="managing-databases">
@@ -9,9 +9,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.17 2001/11/12 19:19:39 p
<para> <para>
A database is a named collection of SQL objects (<quote>database A database is a named collection of SQL objects (<quote>database
objects</quote>); every database object (tables, function, etc.) objects</quote>). Generally, every database object (tables, functions,
belongs to one and only one database. An application that connects etc.) belongs to one and only one database. (But there are a few system
to the database server specifies with its connection request the catalogs, for example <literal>pg_database</>, that belong to a whole
installation and are accessible from each database within the
installation.)
An application that connects
to the database server specifies in its connection request the
name of the database it wants to connect to. It is not possible to name of the database it wants to connect to. It is not possible to
access more than one database per connection. (But an application access more than one database per connection. (But an application
is not restricted in the number of connections it opens to the same is not restricted in the number of connections it opens to the same
@@ -40,7 +44,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.17 2001/11/12 19:19:39 p
<synopsis> <synopsis>
CREATE DATABASE <replaceable>name</> CREATE DATABASE <replaceable>name</>
</synopsis> </synopsis>
where <replaceable>name</> can be chosen freely. (Depending on the where <replaceable>name</> follows the usual rules for SQL identifiers.
(Depending on the
current implementation, certain characters that are special to the current implementation, certain characters that are special to the
underlying operating system might be prohibited. There will be underlying operating system might be prohibited. There will be
run-time checks for that.) The current user automatically becomes run-time checks for that.) The current user automatically becomes
@@ -51,7 +56,7 @@ CREATE DATABASE <replaceable>name</>
<para> <para>
The creation of databases is a restricted operation. See <xref The creation of databases is a restricted operation. See <xref
linkend="user-attributes"> how to grant permission. linkend="user-attributes"> for how to grant permission.
</para> </para>
<formalpara> <formalpara>
@@ -62,8 +67,8 @@ CREATE DATABASE <replaceable>name</>
question remains how the <emphasis>first</> database at any given question remains how the <emphasis>first</> database at any given
site can be created. The first database is always created by the site can be created. The first database is always created by the
<command>initdb</> command when the data storage area is <command>initdb</> command when the data storage area is
initialized. (See <xref linkend="creating-cluster">.) This initialized. (See <xref linkend="creating-cluster">.) By convention
database is called <literal>template1</> and cannot be deleted. So this database is called <literal>template1</>. So
to create the first <quote>real</> database you can connect to to create the first <quote>real</> database you can connect to
<literal>template1</>. <literal>template1</>.
</para> </para>
@@ -75,7 +80,8 @@ CREATE DATABASE <replaceable>name</>
This means that any changes you make in <literal>template1</> are This means that any changes you make in <literal>template1</> are
propagated to all subsequently created databases. This implies that propagated to all subsequently created databases. This implies that
you should not use the template database for real work, but when you should not use the template database for real work, but when
used judiciously this feature can be convenient. used judiciously this feature can be convenient. More details appear
below.
</para> </para>
<para> <para>
@@ -88,29 +94,130 @@ createdb <replaceable class="parameter">dbname</replaceable>
</synopsis> </synopsis>
<command>createdb</> does no magic. It connects to the template1 <command>createdb</> does no magic. It connects to the template1
database and executes the <command>CREATE DATABASE</> command, database and issues the <command>CREATE DATABASE</> command,
exactly as described above. It uses <application>psql</> program exactly as described above. It uses the <application>psql</> program
internally. The reference page on <command>createdb</> contains the invocation internally. The reference page on <command>createdb</> contains the invocation
details. In particular, <command>createdb</> without any arguments will create details. Note that <command>createdb</> without any arguments will create
a database with the current user name, which may or may not be what a database with the current user name, which may or may not be what
you want. you want.
</para> </para>
<sect2> <sect2 id="manage-ag-templatedbs">
<title>Template Databases</title>
<para>
<command>CREATE DATABASE</> actually works by copying an existing
database. By default, it copies the standard system database named
<literal>template1</>. Thus that database is the <quote>template</>
from which new databases are made. If you add objects to
<literal>template1</>, these objects
will be copied into subsequently created user databases. This
behavior allows site-local modifications to the standard set of
objects in databases. For example, if you install the procedural
language <literal>plpgsql</> in <literal>template1</>, it will
automatically be available in user databases without any extra action
being taken when those databases are made.
</para>
<para>
There is a second standard system database named <literal>template0</>.
This database contains the same data as the initial contents of
<literal>template1</>, that is, only the standard objects predefined by
your version of Postgres. <literal>template0</> should never be changed
after <literal>initdb</>. By instructing <command>CREATE DATABASE</> to
copy <literal>template0</> instead of <literal>template1</>, you can
create a <quote>virgin</> user database that contains none of the
site-local additions in <literal>template1</>. This is particularly
handy when restoring a <literal>pg_dump</> dump: the dump script should
be restored in a virgin database to ensure that one recreates the
correct contents of the dumped database, without any conflicts with
additions that may now be present in <literal>template1</>.
</para>
<para>
It is possible to create additional template databases, and indeed
one might copy any database in an installation by specifying its name
as the template for <command>CREATE DATABASE</>. It is important to
understand, however, that this is not (yet) intended as
a general-purpose COPY DATABASE facility. In particular, it is
essential that the source database be idle (no data-altering transactions
in progress)
for the duration of the copying operation. <command>CREATE DATABASE</>
will check
that no backend processes (other than itself) are connected to
the source database at the start of the operation, but this does not
guarantee that changes cannot be made while the copy proceeds, which
would result in an inconsistent copied database. Therefore,
we recommend that databases used as templates be treated as read-only.
</para>
<para>
Two useful flags exist in <literal>pg_database</literal> for each
database: <literal>datistemplate</literal> and
<literal>datallowconn</literal>. <literal>datistemplate</literal>
may be set to indicate that a database is intended as a template for
<command>CREATE DATABASE</>. If this flag is set, the database may be
cloned by
any user with CREATEDB privileges; if it is not set, only superusers
and the owner of the database may clone it.
If <literal>datallowconn</literal> is false, then no new connections
to that database will be allowed (but existing sessions are not killed
simply by setting the flag false). The <literal>template0</literal>
database is normally marked <literal>datallowconn</literal> =
<literal>false</> to prevent modification of it.
Both <literal>template0</literal> and <literal>template1</literal>
should always be marked with <literal>datistemplate</literal> =
<literal>true</>.
</para>
<para>
After preparing a template database, or making any changes to one,
it is a good idea to perform
<command>VACUUM FREEZE</> or <command>VACUUM FULL FREEZE</> in that
database. If this is done when there are no other open transactions
in the same database, then it is guaranteed that all tuples in the
database are <quote>frozen</> and will not be subject to transaction
ID wraparound problems. This is particularly important for a database
that will have <literal>datallowconn</literal> set to false, since it
will be impossible to do routine maintenance <command>VACUUM</>s on
such a database.
See <xref linkend="vacuum-for-wraparound"> for more information.
</para>
<note>
<para>
<literal>template1</> and <literal>template0</> do not have any special
status beyond the fact that the name <literal>template1</> is the default
source database name for <command>CREATE DATABASE</> and the default
database-to-connect-to for various scripts such as <literal>createdb</>.
For example, one could drop <literal>template1</> and recreate it from
<literal>template0</> without any ill effects. This course of action
might be advisable if one has carelessly added a bunch of junk in
<literal>template1</>.
</para>
</note>
</sect2>
<sect2 id="manage-ag-alternate-locs">
<title>Alternative Locations</title> <title>Alternative Locations</title>
<para> <para>
It is possible to create a database in a location other than the It is possible to create a database in a location other than the
default. Remember that all database access occurs through the default location for the installation. Remember that all database access
database server backend, so that any location specified must be occurs through the
accessible by the backend. database server, so any location specified must be
accessible by the server.
</para> </para>
<para> <para>
Alternative database locations are referenced by an environment Alternative database locations are referenced by an environment
variable which gives the absolute path to the intended storage variable which gives the absolute path to the intended storage
location. This environment variable must have been defined before location. This environment variable must be present in the server's
the backend was started. Any valid environment variable name may environment, so it must have been defined before the server
was started. (Thus, the set of available alternative locations is
under the site administrator's control; ordinary users can't
change it.) Any valid environment variable name may
be used to reference an alternative location, although using be used to reference an alternative location, although using
variable names with a prefix of <literal>PGDATA</> is recommended variable names with a prefix of <literal>PGDATA</> is recommended
to avoid confusion and conflict with other variables. to avoid confusion and conflict with other variables.
@@ -144,7 +251,8 @@ setenv PGDATA2 /home/postgres/data
<para> <para>
<indexterm><primary>initlocation</></> <indexterm><primary>initlocation</></>
To create a data storage area in <envar>PGDATA2</>, ensure that To create a data storage area in <envar>PGDATA2</>, ensure that
<filename>/home/postgres</filename> already exists and is writable the containing directory (here, <filename>/home/postgres</filename>)
already exists and is writable
by the user account that runs the server (see <xref by the user account that runs the server (see <xref
linkend="postgres-user">). Then from the command line, type linkend="postgres-user">). Then from the command line, type
<informalexample> <informalexample>
@@ -156,7 +264,7 @@ initlocation PGDATA2
</para> </para>
<para> <para>
To create a database at the new location, use the command To create a database within the new location, use the command
<synopsis> <synopsis>
CREATE DATABASE <replaceable>name</> WITH LOCATION = '<replaceable>location</>' CREATE DATABASE <replaceable>name</> WITH LOCATION = '<replaceable>location</>'
</synopsis> </synopsis>
@@ -166,7 +274,7 @@ CREATE DATABASE <replaceable>name</> WITH LOCATION = '<replaceable>location</>'
</para> </para>
<para> <para>
Database created at alternative locations using this method can be Databases created in alternative locations can be
accessed and dropped like any other database. accessed and dropped like any other database.
</para> </para>
@@ -188,107 +296,6 @@ gmake CPPFLAGS=-DALLOW_ABSOLUTE_DBPATHS all
</sect2> </sect2>
</sect1> </sect1>
<sect1 id="manage-ag-accessdb">
<title>Accessing a Database</title>
<para>
Once you have constructed a database, you can access it by:
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<para>
running the <productname>Postgres</productname> terminal monitor program
(<application>psql</application>) which allows you to interactively
enter, edit, and execute <acronym>SQL</acronym> commands.
</para>
</listitem>
<listitem>
<para>
writing a C program using the <literal>libpq</literal> subroutine
library. This allows you to submit <acronym>SQL</acronym> commands
from C and get answers and status messages back to
your program. This interface is discussed further
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
</para>
</listitem>
</itemizedlist>
You might want to start up <application>psql</application>,
to try out the examples in this manual. It can be activated for the
<replaceable class="parameter">dbname</replaceable> database by typing the command:
<programlisting>
psql <replaceable class="parameter">dbname</replaceable>
</programlisting>
You will be greeted with the following message:
<programlisting>
Welcome to psql, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help on internal slash commands
\g or terminate with semicolon to execute query
\q to quit
<replaceable>dbname</replaceable>=&gt;
</programlisting>
</para>
<para>
This prompt indicates that the terminal monitor is listening
to you and that you can type <acronym>SQL</acronym> queries into a
workspace maintained by the terminal monitor.
The <application>psql</application> program responds to escape
codes that begin
with the backslash character, <literal>\</literal>. For example, you
can get help on the syntax of various
<productname>Postgres</productname> <acronym>SQL</acronym> commands by typing:
<programlisting>
<replaceable>dbname</replaceable>=> \h
</programlisting>
Once you have finished entering your queries into the
workspace, you can pass the contents of the workspace
to the <productname>Postgres</productname> server by typing:
<programlisting>
<replaceable>dbname</replaceable>=> \g
</programlisting>
This tells the server to process the query. If you
terminate your query with a semicolon, the backslash-g is not
necessary. <application>psql</application> will automatically
process semicolon terminated queries.
To read queries from a file, instead of
entering them interactively, type:
<programlisting>
<replaceable>dbname</replaceable>=> \i <replaceable class="parameter">filename</replaceable>
</programlisting>
To get out of <application>psql</application> and return to Unix, type
<programlisting>
<replaceable>dbname</replaceable>=&gt; \q
</programlisting>
and <application>psql</application> will quit and return
you to your command shell. (For more escape codes, type
backslash-h at the monitor prompt.)
White space (i.e., spaces, tabs and newlines) may be
used freely in <acronym>SQL</acronym> queries.
Single-line comments are denoted by two dashes
("<literal>--</literal>"). Everything after the dashes up to the end of the
line is ignored. Multiple-line comments, and comments within a line,
are denoted by <literal>/* ... */</literal>, a convention borrowed
from <productname>Ingres</productname>.
</para>
</sect1>
<sect1 id="manage-ag-dropdb"> <sect1 id="manage-ag-dropdb">
<title>Destroying a Database</title> <title>Destroying a Database</title>
@@ -297,8 +304,9 @@ Type: \copyright for distribution terms
<synopsis> <synopsis>
DROP DATABASE <replaceable>name</> DROP DATABASE <replaceable>name</>
</synopsis> </synopsis>
Only the owner of the database (i.e., the user that created it) can Only the owner of the database (i.e., the user that created it), or
drop databases. Dropping a databases removes all objects that were a superuser, can drop a database. Dropping a database removes all objects
that were
contained within the database. The destruction of a database cannot contained within the database. The destruction of a database cannot
be undone. be undone.
</para> </para>
@@ -306,8 +314,9 @@ DROP DATABASE <replaceable>name</>
<para> <para>
You cannot execute the <command>DROP DATABASE</command> command You cannot execute the <command>DROP DATABASE</command> command
while connected to the victim database. You can, however, be while connected to the victim database. You can, however, be
connected to any other database, including the template1 database, connected to any other database, including the <literal>template1</>
which would be the only option for dropping the last database of a database,
which would be the only option for dropping the last user database of a
given cluster. given cluster.
</para> </para>

150
doc/src/sgml/manage.sgml
View File

@@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.17 2001/09/28 08:15:35 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.18 2001/11/18 00:38:00 tgl Exp $
--> -->
<Chapter Id="manage"> <Chapter Id="manage">
@@ -18,22 +18,25 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.17 2001/09/28 08:15:3
designated the <FirstTerm>database administrator</FirstTerm>. designated the <FirstTerm>database administrator</FirstTerm>.
This assignment of responsibilities occurs when a database is created. This assignment of responsibilities occurs when a database is created.
A user may be assigned explicit privileges to create databases and/or to create new users. A user may be assigned explicit privileges to create databases and/or to create new users.
A user assigned both privileges can perform most administrative task A user assigned both privileges can perform most administrative tasks
within <ProductName>Postgres</ProductName>, but will within <ProductName>Postgres</ProductName>, but will
not by default have the same operating system privileges as the site administrator. not by default have the same operating system privileges as the site administrator.
</Para> </Para>
<Para> <Para>
The Database Administrator's Guide covers these topics in more detail. The <citetitle>Administrator's Guide</> covers these topics in
more detail.
</Para> </Para>
<Sect1 id="db-creation"> <Sect1 id="db-creation">
<Title>Database Creation</Title> <Title>Database Creation</Title>
<Para> <Para>
Databases are created by the <Command>CREATE DATABASE</Command> issued from Databases are created by the <Command>CREATE DATABASE</Command>
within <ProductName>Postgres</ProductName>. <Application>createdb</Application> is a command-line command issued from within
utility provided to give the same functionality from outside <ProductName>Postgres</ProductName>. <ProductName>Postgres</ProductName>. <Application>createdb</Application>
is a shell script provided to give the same functionality from the
Unix command line.
</Para> </Para>
<Para> <Para>
@@ -64,111 +67,19 @@ ERROR: CREATE DATABASE: Permission denied.
</Para> </Para>
<Para> <Para>
<ProductName>Postgres</ProductName> allows you to create any number of databases You automatically become the
at a given site and you automatically become the
database administrator of the database you just created. database administrator of the database you just created.
Database names must have an alphabetic first Database names must have an alphabetic first
character and are limited to 32 characters in length. character and are limited to 31 characters in length.
<ProductName>Postgres</ProductName> allows you to create any number of
databases at a given site.
</Para> </Para>
</Sect1> <Para>
The <citetitle>Administrator's Guide</> discusses database creation
<Sect1 id="altern-locations"> in more detail, including advanced options of the <command>CREATE
<Title>Alternate Database Locations</Title> DATABASE</> command.
</Para>
<Para>
It is possible to create a database in a location other than the default
location for the installation. Remember that all database access actually
occurs through the database backend, so that any location specified must
be accessible by the backend.
</Para>
<Para>
Alternate database locations are created and referenced by an environment variable
which gives the absolute path to the intended storage location.
This environment variable must have been defined before the postmaster was started
and the location it points to must be writable by the administrator account.
Consult with the site administrator
regarding preconfigured alternative database locations.
Any valid environment variable name may be used to reference an alternate location,
although using variable names with a prefix of <envar>PGDATA</envar> is recommended
to avoid confusion
and conflict with other variables.
</Para>
<Note>
<Para>
In previous versions of <ProductName>Postgres</ProductName>,
it was also permissible to use an absolute path name to specify
an alternate storage location.
Although the environment variable style of specification
is to be preferred since it allows the site administrator more flexibility in
managing disk storage, it is also possible to use an absolute path
to specify an alternate location.
The administrator's guide discusses how to enable this feature.
</Para>
</Note>
<Para>
For security and integrity reasons,
any path or environment variable specified has some
additional path fields appended.
Alternate database locations must be prepared by running
<Application>initlocation</Application>.
</Para>
<Para>
To create a data storage area using the environment variable
<envar>PGDATA2</envar> (for this example set to <filename>/alt/postgres</filename>),
ensure that <FileName>/alt/postgres</FileName> already exists and is writable by
the Postgres administrator account.
Then, from the command line, type
<ProgramListing>
% initlocation PGDATA2
The location will be initialized with username "postgres".
This user will own all the files and must also own the server process.
Creating directory /alt/postgres/data
Creating directory /alt/postgres/data/base
initlocation is complete.
You can now create a database using
CREATE DATABASE &lt;name&gt; WITH LOCATION = 'PGDATA2'
in SQL, or
createdb &lt;name&gt; -D 'PGDATA2'
from the shell.
</ProgramListing>
</Para>
<Para>
To create a database in the alternate storage area <envar>PGDATA2</envar>
from the command line, use the following command:
<ProgramListing>
% createdb -D PGDATA2 mydb
</ProgramListing>
and to do the same from within <Application>psql</Application> type
<ProgramListing>
=> CREATE DATABASE mydb WITH LOCATION = 'PGDATA2';
</ProgramListing>
</Para>
<Para>
If you do not have the privileges required to create a database, you will see
the following:
<ProgramListing>
ERROR: CREATE DATABASE: permission denied
</ProgramListing>
</Para>
<Para>
If the specified location does not exist or the database backend does not have
permission to access it or to write to directories under it, you will see
the following:
<ProgramListing>
ERROR: The database path '/no/where' is invalid. This may be due to a character that is not allowed or because the chosen path isn't permitted for databases.
</ProgramListing>
</Para>
</Sect1> </Sect1>
@@ -189,11 +100,17 @@ enter, edit, and execute <Acronym>SQL</Acronym> commands.
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
writing a C program using the <application>LIBPQ</application> subroutine writing a C program using the <application>LIBPQ</application> subroutine
library. This allows you to submit <Acronym>SQL</Acronym> commands library. This allows you to submit <Acronym>SQL</Acronym> commands
from C and get answers and status messages back to from C and get answers and status messages back to
your program. This interface is discussed further your program. This interface is discussed further
in <citetitle>The PostgreSQL Programmer's Guide</citetitle>. in <citetitle>The PostgreSQL Programmer's Guide</citetitle>.
</Para>
</ListItem>
<ListItem>
<Para>
writing a program in other languages for which there are available interface
libraries.
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
@@ -224,7 +141,8 @@ mydb=>
This prompt indicates that <command>psql</command> is listening This prompt indicates that <command>psql</command> is listening
to you and that you can type <Acronym>SQL</Acronym> queries into a to you and that you can type <Acronym>SQL</Acronym> queries into a
workspace maintained by the terminal monitor. workspace maintained by the terminal monitor.
The <Application>psql</Application> program responds to escape codes that begin The <Application>psql</Application> program itself responds to special
commands that begin
with the backslash character, <literal>\</literal>. For example, you with the backslash character, <literal>\</literal>. For example, you
can get help on the syntax of various can get help on the syntax of various
<ProductName>PostgreSQL</ProductName> <Acronym>SQL</Acronym> commands by typing: <ProductName>PostgreSQL</ProductName> <Acronym>SQL</Acronym> commands by typing:
@@ -271,7 +189,11 @@ mydb=> \q
<Para> <Para>
If you are the owner of the database If you are the owner of the database
<Database>mydb</Database>, you can destroy it using the following Unix command: <Database>mydb</Database>, you can destroy it using the SQL command
<ProgramListing>
=> DROP DATABASE mydb;
</ProgramListing>
or the Unix shell script
<ProgramListing> <ProgramListing>
% dropdb mydb % dropdb mydb
</ProgramListing> </ProgramListing>

48
doc/src/sgml/ref/create_database.sgml
View File

@@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.20 2001/09/13 15:55:24 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.21 2001/11/18 00:38:00 tgl Exp $
Postgres documentation Postgres documentation
--> -->
@@ -202,7 +202,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
by writing <literal>TEMPLATE = template0</>, you can create a virgin by writing <literal>TEMPLATE = template0</>, you can create a virgin
database containing only the standard objects predefined by your database containing only the standard objects predefined by your
version of Postgres. This is useful if you wish to avoid copying version of Postgres. This is useful if you wish to avoid copying
any installation-local objects that may have been added to template1. any installation-local objects that may have been added to
<literal>template1</>.
</para> </para>
<para> <para>
@@ -259,44 +260,11 @@ comment from Olly; response from Thomas...
--> -->
<para> <para>
Although it is possible to copy a database other than template1 by Although it is possible to copy a database other than <literal>template1</>
specifying its name as the template, this is not (yet) intended as by specifying its name as the template, this is not (yet) intended as
a general-purpose COPY DATABASE facility. In particular, it is a general-purpose COPY DATABASE facility.
essential that the source database be idle (no data-altering transactions We recommend that databases used as templates be treated as read-only.
in progress) See the <citetitle>Administrator's Guide</> for more information.
for the duration of the copying operation. CREATE DATABASE will check
that no backend processes (other than itself) are connected to
the source database at the start of the operation, but this does not
guarantee that changes cannot be made while the copy proceeds. Therefore,
we recommend that databases used as templates be treated as read-only.
</para>
<para>
Two useful flags exist in <literal>pg_database</literal> for each
database: <literal>datistemplate</literal> and
<literal>datallowconn</literal>. <literal>datistemplate</literal>
may be set to indicate that a database is intended as a template for
CREATE DATABASE. If this flag is set, the database may be cloned by
any user with CREATEDB privileges; if it is not set, only superusers
and the owner of the database may clone it.
If <literal>datallowconn</literal> is false, then no new connections
to that database will be allowed (but existing sessions are not killed
simply by setting the flag false). The <literal>template0</literal>
database is normally marked this way to prevent modification of it.
</para>
<para>
After preparing a template database, or making any changes to one,
it is a good idea to perform
<command>VACUUM FREEZE</> or <command>VACUUM FULL FREEZE</> in that
database. If this is done when there are no other open transactions
in the same database, then it is guaranteed that all tuples in the
database are <quote>frozen</> and will not be subject to transaction
ID wraparound problems. This is particularly important for a database
that will have <literal>datallowconn</literal> set to false, since it
will be impossible to do routine maintenance <command>VACUUM</>s on
such a database.
See the Administrator's Guide for more information.
</para> </para>
</refsect2> </refsect2>
</refsect1> </refsect1>

64
doc/src/sgml/ref/drop_database.sgml
View File

@@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.12 2001/09/03 12:57:49 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.13 2001/11/18 00:38:00 tgl Exp $
Postgres documentation Postgres documentation
--> -->
@@ -68,57 +68,18 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><computeroutput>ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/drop databases</computeroutput></term> <term><computeroutput>DROP DATABASE: cannot be executed on the currently open database</computeroutput></term>
<listitem> <listitem>
<para> <para>
You must have the special CREATEDB privilege to drop databases. You cannot be connected to the database you are about to remove.
See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">. Instead, connect to <literal>template1</literal> or any other
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: dropdb: cannot be executed on the template database</computeroutput></term>
<listitem>
<para>
The <literal>template1</literal> database cannot be removed. It's not in
your interest.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: dropdb: cannot be executed on an open database</computeroutput></term>
<listitem>
<para>
You cannot be connected to the database your are about to remove.
Instead, you could connect to <literal>template1</literal> or any other
database and run this command again. database and run this command again.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><computeroutput>ERROR: dropdb: database '<replaceable class="parameter">name</replaceable>' does not exist</computeroutput></term> <term><computeroutput>DROP DATABASE: may not be called in a transaction block</computeroutput></term>
<listitem>
<para>
This message occurs if the specified database does not exist.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: dropdb: database '<replaceable class="parameter">name</replaceable>' is not owned by you</computeroutput></term>
<listitem>
<para>
You must be the owner of the database. Being the owner usually means that
you created it as well.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: dropdb: May not be called in a transaction block.</computeroutput></term>
<listitem> <listitem>
<para> <para>
You must finish the transaction in progress before you can call this command. You must finish the transaction in progress before you can call this command.
@@ -126,17 +87,6 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term><computeroutput>NOTICE: The database directory 'xxx' could not be removed.</computeroutput></term>
<listitem>
<para>
The database was dropped (unless other error messages came up), but the
directory where the data is stored could not be removed. You must delete
it manually.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para> </para>
</refsect2> </refsect2>
@@ -156,6 +106,10 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
it). it).
</para> </para>
<para>
<command>DROP DATABASE</command> cannot be undone. Use it with care!
</para>
<refsect2 id="R2-SQL-DROPDATABASE-3"> <refsect2 id="R2-SQL-DROPDATABASE-3">
<refsect2info> <refsect2info>
<date>1999-12-11</date> <date>1999-12-11</date>