2000-03-31 05:27:42 +02:00
|
|
|
<!--
|
2000-09-29 22:21:34 +02:00
|
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.11 2000/09/29 20:21:34 petere Exp $
|
2000-03-31 05:27:42 +02:00
|
|
|
-->
|
|
|
|
|
2000-06-30 18:14:21 +02:00
|
|
|
<chapter id="managing-databases">
|
|
|
|
<title>Managing Databases</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
A database is a named collection of SQL objects (<quote>database
|
|
|
|
objects</quote>); every database object (tables, function, etc.)
|
|
|
|
belongs to one and only one database. An application that connects
|
|
|
|
to the database server specifies with its connection request the
|
|
|
|
name of the database it wants to connect to. It is not possible to
|
|
|
|
access more than once database per connection. (But an application
|
|
|
|
is not restricted in the number of connections it opens to the same
|
|
|
|
or other databases.)
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
<acronym>SQL</> calls databases <quote>catalogs</>, but there is no
|
|
|
|
difference in practice.
|
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In order to create or drop databases, the <productname>Postgres</>
|
|
|
|
<application>postmaster</> must be up and running (see <xref
|
|
|
|
linkend="postmaster-start">).
|
|
|
|
</para>
|
|
|
|
|
2000-09-29 22:21:34 +02:00
|
|
|
<sect1 id="manage-ag-createdb">
|
2000-06-30 18:14:21 +02:00
|
|
|
<title>Creating a Database</title>
|
1999-06-23 08:15:37 +02:00
|
|
|
|
|
|
|
<para>
|
2000-06-30 18:14:21 +02:00
|
|
|
Databases are created with the query language command
|
|
|
|
<command>CREATE DATABASE</command>:
|
|
|
|
<synopsis>
|
|
|
|
CREATE DATABASE <replaceable>name</>
|
|
|
|
</synopsis>
|
|
|
|
where <replaceable>name</> can be chosen freely. (Depending on the
|
|
|
|
current implementation, certain characters that are special to the
|
|
|
|
underlying operating system might be prohibited. There will be
|
|
|
|
run-time checks for that.) The current user automatically becomes
|
|
|
|
the owner of the new database. It is the privilege of the owner of
|
|
|
|
a database to remove it later on (which also removes all the
|
|
|
|
objects in it, even if they have a different owner).
|
1999-06-23 08:15:37 +02:00
|
|
|
</para>
|
|
|
|
|
2000-06-30 18:14:21 +02:00
|
|
|
<para>
|
|
|
|
The creation of databases is a restricted operation. See <xref
|
|
|
|
linkend="user-attributes"> how to grant permission.
|
|
|
|
</para>
|
1999-06-23 08:15:37 +02:00
|
|
|
|
2000-06-30 18:14:21 +02:00
|
|
|
<formalpara>
|
|
|
|
<title>Bootstrapping</title>
|
1999-06-23 08:15:37 +02:00
|
|
|
<para>
|
2000-06-30 18:14:21 +02:00
|
|
|
Since you need to be connected to the database server in order to
|
|
|
|
execute the <command>CREATE DATABASE</command> command, the
|
|
|
|
question remains how the <emphasis>first</> database at any given
|
|
|
|
site can be created. The first database is always created by the
|
|
|
|
<command>initdb</> command when the data storage area is
|
|
|
|
initialized. (See <xref linkend="creating-cluster">.) This
|
|
|
|
database is called <literal>template1</> and cannot be deleted. So
|
|
|
|
to create the first <quote>real</> database you can connect to
|
|
|
|
<literal>template1</>.
|
|
|
|
</para>
|
|
|
|
</formalpara>
|
1999-06-23 08:15:37 +02:00
|
|
|
|
2000-06-30 18:14:21 +02:00
|
|
|
<para>
|
|
|
|
The name <quote>template1</quote> is no accident: When a new
|
|
|
|
database is created, the template database is essentially cloned.
|
|
|
|
This means that any changes you make in <literal>template1</> are
|
|
|
|
propagated to all subsequently created databases. This implies that
|
|
|
|
you should not use the template database for real work, but when
|
|
|
|
used judiciously this feature can be convenient.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
As an extra convenience, there is also a program that you can
|
|
|
|
execute from the shell to create new databases,
|
|
|
|
<filename>createdb</>.
|
|
|
|
|
|
|
|
<synopsis>
|
|
|
|
createdb <replaceable class="parameter">dbname</replaceable>
|
|
|
|
</synopsis>
|
|
|
|
|
|
|
|
<filename>createdb</> does no magic. It connects to the template1
|
|
|
|
database and executes the <command>CREATE DATABASE</> command,
|
|
|
|
exactly as described above. It uses <application>psql</> program
|
|
|
|
internally. The reference page on createdb contains the invocation
|
|
|
|
details. In particular, createdb without any arguments will create
|
|
|
|
a database with the current user name, which may or may not be what
|
|
|
|
you want.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Alternative Locations</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
It is possible to create a database in a location other than the
|
|
|
|
default. Remember that all database access occurs through the
|
|
|
|
database server backend, so that any location specified must be
|
|
|
|
accessible by the backend.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Alternative database locations are referenced by an environment
|
|
|
|
variable which gives the absolute path to the intended storage
|
|
|
|
location. This environment variable must have been defined before
|
|
|
|
the backend was started. Any valid environment variable name may
|
|
|
|
be used to reference an alternative location, although using
|
|
|
|
variable names with a prefix of <literal>PGDATA</> is recommended
|
|
|
|
to avoid confusion and conflict with other variables.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To create the variable in the environment of the server process
|
|
|
|
you must first shut down the server, define the variable,
|
|
|
|
initialize the data area, and finally restart the server. (See
|
|
|
|
<xref linkend="postmaster-shutdown"> and <xref
|
|
|
|
linkend="postmaster-start">.) To set an environment variable, type
|
|
|
|
<informalexample>
|
|
|
|
<programlisting>
|
|
|
|
PGDATA2=/home/postgres/data
|
|
|
|
</programlisting>
|
|
|
|
</informalexample>
|
|
|
|
in Bourne shells, or
|
|
|
|
<informalexample>
|
|
|
|
<programlisting>
|
|
|
|
setenv PGDATA2 /home/postgres/data
|
|
|
|
</programlisting>
|
|
|
|
</informalexample>
|
|
|
|
in csh or tcsh. You have to make sure that this environment
|
|
|
|
variable is always defined in the server environment, otherwise
|
|
|
|
you won't be able to access that database. Therefore you probably
|
2000-08-29 22:02:09 +02:00
|
|
|
want to set it in some sort of shell start-up file or server
|
|
|
|
start-up script.
|
2000-06-30 18:14:21 +02:00
|
|
|
</para>
|
1999-06-23 08:15:37 +02:00
|
|
|
|
2000-06-30 18:14:21 +02:00
|
|
|
<para>
|
|
|
|
To create a data storage area in <envar>PGDATA2</>, ensure that
|
|
|
|
<filename>/home/postgres</filename> already exists and is writable
|
|
|
|
by the user account that runs the server (see <xref
|
|
|
|
linkend="postgres-user">). Then from the command line, type
|
|
|
|
<informalexample>
|
|
|
|
<programlisting>
|
|
|
|
initlocation PGDATA2
|
|
|
|
</programlisting>
|
|
|
|
</informalexample>
|
|
|
|
The you can restart the server.
|
1999-06-23 08:15:37 +02:00
|
|
|
</para>
|
|
|
|
|
2000-06-30 18:14:21 +02:00
|
|
|
<para>
|
|
|
|
To create a database at the new location, use the command
|
|
|
|
<synopsis>
|
|
|
|
CREATE DATABASE <replaceable>name</> WITH LOCATION = '<replaceable>location</>'
|
|
|
|
</synopsis>
|
|
|
|
where <replaceable>location</> is the environment variable you
|
|
|
|
used, <envar>PGDATA2</> in this example. The <command>createdb</>
|
|
|
|
command has the option <option>-D</> for this purpose.
|
|
|
|
</para>
|
1999-06-23 08:15:37 +02:00
|
|
|
|
|
|
|
<para>
|
2000-06-30 18:14:21 +02:00
|
|
|
Database created at alternative locations using this method can be
|
|
|
|
accessed and dropped like any other database.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
It can also be possible to specify absolute paths directly to the
|
|
|
|
<command>CREATE DATABASE</> command without defining environment
|
|
|
|
variables. This is disallowed by default because it is a security
|
|
|
|
risk. To allow it, you must compile <productname>Postgres</> with
|
|
|
|
the C preprocessor macro <literal>ALLOW_ABSOLUTE_DBPATHS</>
|
|
|
|
defined. One way to do this is to run the compilation step like
|
|
|
|
this: <userinput>gmake COPT=-DALLOW_ABSOLUTE_DBPATHS all</>.
|
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
|
2000-09-29 22:21:34 +02:00
|
|
|
<sect1 id="manage-ag-accessdb">
|
2000-06-30 18:14:21 +02:00
|
|
|
<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:
|
1999-06-23 08:15:37 +02:00
|
|
|
|
2000-03-26 20:32:30 +02:00
|
|
|
<programlisting>
|
|
|
|
psql <replaceable class="parameter">dbname</replaceable>
|
|
|
|
</programlisting>
|
1999-06-23 08:15:37 +02:00
|
|
|
|
2000-06-30 18:14:21 +02:00
|
|
|
You will be greeted with the following message:
|
1999-06-23 08:15:37 +02:00
|
|
|
|
2000-03-26 20:32:30 +02:00
|
|
|
<programlisting>
|
|
|
|
Welcome to psql, the PostgreSQL interactive terminal.
|
1999-06-23 08:15:37 +02:00
|
|
|
|
2000-03-26 20:32:30 +02:00
|
|
|
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
|
1999-06-23 08:15:37 +02:00
|
|
|
|
|
|
|
<replaceable>dbname</replaceable>=>
|
2000-03-26 20:32:30 +02:00
|
|
|
</programlisting>
|
1999-06-23 08:15:37 +02:00
|
|
|
</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, "\". 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>
|
|
|
|
|
1999-10-04 17:18:54 +02:00
|
|
|
To get out of <application>psql</application> and return to Unix, type
|
1999-06-23 08:15:37 +02:00
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
<replaceable>dbname</replaceable>=> \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
|
2000-05-02 22:02:03 +02:00
|
|
|
("<literal>--</literal>"). Everything after the dashes up to the end of the
|
1999-06-23 08:15:37 +02:00
|
|
|
line is ignored. Multiple-line comments, and comments within a line,
|
2000-05-02 22:02:03 +02:00
|
|
|
are denoted by "<literal>/* ... */</literal>", a convention borrowed
|
1999-06-23 08:15:37 +02:00
|
|
|
from <productname>Ingres</productname>.
|
|
|
|
</para>
|
2000-06-30 18:14:21 +02:00
|
|
|
</sect1>
|
1999-06-23 08:15:37 +02:00
|
|
|
|
2000-09-29 22:21:34 +02:00
|
|
|
<sect1 id="manage-ag-dropdb">
|
2000-06-30 18:14:21 +02:00
|
|
|
<title>Destroying a Database</title>
|
1999-06-23 08:15:37 +02:00
|
|
|
|
2000-06-30 18:14:21 +02:00
|
|
|
<para>
|
|
|
|
Databases are destroyed with the command <command>DROP DATABASE</command>:
|
|
|
|
<synopsis>
|
|
|
|
DROP DATABASE <replaceable>name</>
|
|
|
|
</synopsis>
|
|
|
|
Only the owner of the database (i.e., the user that created it) can
|
|
|
|
drop databases. Dropping a databases removes all objects that were
|
|
|
|
contained within the database. The destruction of a database cannot
|
|
|
|
be undone.
|
|
|
|
</para>
|
1999-06-23 08:15:37 +02:00
|
|
|
|
2000-06-30 18:14:21 +02:00
|
|
|
<para>
|
|
|
|
You cannot execute the <command>DROP DATABASE</command> command
|
|
|
|
while connected to the victim database. You can, however, be
|
|
|
|
connected to any other database, including the template1 database,
|
|
|
|
which would be the only option for dropping the last database of a
|
|
|
|
given cluster.
|
|
|
|
</para>
|
1999-06-23 08:15:37 +02:00
|
|
|
|
2000-06-30 18:14:21 +02:00
|
|
|
<para>
|
|
|
|
For convenience, there is also a shell program to drop databases:
|
|
|
|
<synopsis>
|
|
|
|
dropdb <replaceable class="parameter">dbname</replaceable>
|
|
|
|
</synopsis>
|
|
|
|
(Unlike <command>createdb</>, it is not the default action to drop
|
|
|
|
the database with the current user name.)
|
|
|
|
</para>
|
|
|
|
</sect1>
|
1999-06-23 08:15:37 +02:00
|
|
|
</chapter>
|
|
|
|
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
|
|
Local variables:
|
2000-03-31 05:27:42 +02:00
|
|
|
mode:sgml
|
1999-06-23 08:15:37 +02:00
|
|
|
sgml-omittag:nil
|
|
|
|
sgml-shorttag:t
|
|
|
|
sgml-minimize-attributes:nil
|
|
|
|
sgml-always-quote-attributes:t
|
|
|
|
sgml-indent-step:1
|
|
|
|
sgml-indent-data:t
|
|
|
|
sgml-parent-document:nil
|
|
|
|
sgml-default-dtd-file:"./reference.ced"
|
|
|
|
sgml-exposed-tags:nil
|
2000-03-31 05:27:42 +02:00
|
|
|
sgml-local-catalogs:("/usr/lib/sgml/catalog")
|
1999-06-23 08:15:37 +02:00
|
|
|
sgml-local-ecat-files:nil
|
|
|
|
End:
|
|
|
|
-->
|