2000-03-31 05:27:42 +02:00
<!--
2000-05-02 22:02:03 +02:00
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.10 2000/05/02 20:01:52 thomas Exp $
2000-03-31 05:27:42 +02:00
-->
1999-05-04 04:24:26 +02:00
<Chapter Id="manage">
<Title>Managing a Database</Title>
<Note>
<Para>
This section is currently a thinly disguised copy of the
Tutorial. Needs to be augmented.
- thomas 1998-01-12
</Para>
</Note>
<Para>
Although the <FirstTerm>site administrator</FirstTerm> is responsible for overall management
of the <ProductName>Postgres</ProductName> installation, some databases within the
installation may be managed by another person,
designated the <FirstTerm>database administrator</FirstTerm>.
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 assigned both privileges can perform most administrative task
within <ProductName>Postgres</ProductName>, but will
not by default have the same operating system privileges as the site administrator.
</Para>
<Para>
The Database Administrator's Guide covers these topics in more detail.
</Para>
<Sect1>
<Title>Database Creation</Title>
<Para>
Databases are created by the <Command>create database</Command> issued from
within <ProductName>Postgres</ProductName>. <Application>createdb</Application> is a command-line
utility provided to give the same functionality from outside <ProductName>Postgres</ProductName>.
</Para>
<Para>
The <ProductName>Postgres</ProductName> backend must be running for either method
to succeed, and the user issuing the command must be the <ProductName>Postgres</ProductName>
<FirstTerm>superuser</FirstTerm> or have been assigned database creation privileges by the
superuser.
</Para>
<Para>
2000-05-02 22:02:03 +02:00
To create a new database named <literal>mydb</literal> from the command line, type
2000-03-26 20:32:30 +02:00
<ProgramListing>
1998-03-01 09:16:16 +01:00
% createdb mydb
2000-03-26 20:32:30 +02:00
</ProgramListing>
1998-03-01 09:16:16 +01:00
1999-05-04 04:24:26 +02:00
and to do the same from within <Application>psql</Application> type
2000-03-26 20:32:30 +02:00
<ProgramListing>
=> CREATE DATABASE mydb;
</ProgramListing>
1999-05-04 04:24:26 +02:00
</Para>
1998-03-01 09:16:16 +01:00
1999-05-04 04:24:26 +02:00
<Para>
If you do not have the privileges required to create a database, you will see
the following:
2000-03-26 20:32:30 +02:00
<ProgramListing>
ERROR: CREATE DATABASE: Permission denied.
</ProgramListing>
1999-05-04 04:24:26 +02:00
</Para>
<Para>
<ProductName>Postgres</ProductName> allows you to create any number of databases
at a given site and you automatically become the
database administrator of the database you just created.
Database names must have an alphabetic first
character and are limited to 32 characters in length.
</Para>
</Sect1>
<Sect1>
<Title>Alternate Database Locations</Title>
<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 backend was started
and the location it points to must be writable by the postgres administrator account.
Consult with the site administrator
regarding preconfigured alternate database locations.
Any valid environment variable name may be used to reference an alternate location,
2000-05-02 22:02:03 +02:00
although using variable names with a prefix of <envar>PGDATA</envar> is recommended
1999-05-04 04:24:26 +02:00
to avoid confusion
and conflict with other variables.
</Para>
<Note>
<Para>
In previous versions of <ProductName>Postgres</ProductName>,
it was also permissable 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
2000-03-26 20:32:30 +02:00
<ProgramListing>
% initlocation PGDATA2
1998-03-01 09:16:16 +01:00
Creating Postgres database system directory /alt/postgres/data
Creating Postgres database system directory /alt/postgres/data/base
2000-03-26 20:32:30 +02:00
</ProgramListing>
1999-05-04 04:24:26 +02:00
</Para>
1998-03-01 09:16:16 +01:00
1999-05-04 04:24:26 +02:00
<Para>
To create a database in the alternate storage area <envar>PGDATA2</envar>
from the command line, use the following command:
2000-03-26 20:32:30 +02:00
<ProgramListing>
1998-03-01 09:16:16 +01:00
% createdb -D PGDATA2 mydb
2000-03-26 20:32:30 +02:00
</ProgramListing>
1998-03-01 09:16:16 +01:00
1999-05-04 04:24:26 +02:00
and to do the same from within <Application>psql</Application> type
2000-03-26 20:32:30 +02:00
<ProgramListing>
=> CREATE DATABASE mydb WITH LOCATION = 'PGDATA2';
</ProgramListing>
1999-05-04 04:24:26 +02:00
</Para>
1998-03-01 09:16:16 +01:00
1999-05-04 04:24:26 +02:00
<Para>
If you do not have the privileges required to create a database, you will see
the following:
2000-03-26 20:32:30 +02:00
<ProgramListing>
ERROR: CREATE DATABASE: permission denied
</ProgramListing>
1999-05-04 04:24:26 +02:00
</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:
2000-03-26 20:32:30 +02:00
<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>
1999-05-04 04:24:26 +02:00
</Para>
1998-03-01 09:16:16 +01:00
1999-05-04 04:24:26 +02:00
</Sect1>
1998-03-01 09:16:16 +01:00
<Sect1>
<Title>Accessing a Database</Title>
<Para>
Once you have constructed a database, you can access it
by:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
2000-03-26 20:32:30 +02:00
running the <ProductName>PostgreSQL</ProductName> interactive terminal
<Application>psql</Application> which allows you to interactively
enter, edit, and execute <Acronym>SQL</Acronym> commands.
1998-03-01 09:16:16 +01:00
</Para>
</ListItem>
<ListItem>
<Para>
writing a C program using the LIBPQ 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
2000-05-02 22:02:03 +02:00
in <citetitle>The PostgreSQL Programmer's Guide</citetitle>.
1998-03-01 09:16:16 +01:00
</Para>
</ListItem>
</ItemizedList>
1998-12-18 17:20:28 +01:00
You might want to start up <Application>psql</Application>,
to try out the examples in this manual.
1998-03-01 09:16:16 +01:00
It can be activated for the <Database>mydb</Database>
database by typing the command:
<ProgramListing>
% psql mydb
</ProgramListing>
You will be greeted with the following message:
<ProgramListing>
2000-03-26 20:32:30 +02:00
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
1998-03-01 09:16:16 +01:00
mydb=>
</ProgramListing>
</Para>
<Para>
2000-03-26 20:32:30 +02:00
This prompt indicates that psql is listening
1998-03-01 09:16:16 +01:00
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
2000-05-02 22:02:03 +02:00
with the backslash character, "<literal>\</literal>". For example, you
1998-03-01 09:16:16 +01:00
can get help on the syntax of various
2000-03-26 20:32:30 +02:00
<ProductName>PostgreSQL</ProductName> <Acronym>SQL</Acronym> commands by typing:
1998-03-01 09:16:16 +01:00
<ProgramListing>
mydb=> \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>
mydb=> \g
</ProgramListing>
This tells the server to process the query. If you
2000-05-02 22:02:03 +02:00
terminate your query with a semicolon, the "<literal>\g</literal>" is not
1998-12-18 17:20:28 +01:00
necessary.
<Application>psql</Application> will automatically process semicolon terminated queries.
1998-03-01 09:16:16 +01:00
To read queries from a file, say myFile, instead of
entering them interactively, type:
<ProgramListing>
mydb=> \i fileName
</ProgramListing>
1999-10-04 17:18:54 +02:00
To get out of <Application>psql</Application> and return to Unix, type
1998-03-01 09:16:16 +01:00
<ProgramListing>
mydb=> \q
</ProgramListing>
and <Application>psql</Application> will quit and return you to your command
2000-03-26 20:32:30 +02:00
shell. (For more escape codes, type <Command>\?</Command> at the psql
1998-03-01 09:16:16 +01:00
prompt.)
White space (i.e., spaces, tabs and newlines) may be
used freely in <Acronym>SQL</Acronym> queries. Single-line comments are denoted by
2000-05-02 22:02:03 +02:00
"<literal>--</literal>". Everything after the dashes up to the end of the
1998-03-01 09:16:16 +01: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>".
1998-03-01 09:16:16 +01:00
</Para>
<Sect2>
<Title>Database Privileges</Title>
<Para>
1998-12-29 03:24:47 +01:00
</para>
1998-03-01 09:16:16 +01:00
</Sect2>
<Sect2>
<Title>Table Privileges</Title>
<Para>
TBD
</Para>
</Sect2>
</Sect1>
<Sect1>
<Title>Destroying a Database</Title>
<Para>
2000-03-26 20:32:30 +02:00
If you are the owner of the database
1999-10-04 17:18:54 +02:00
<Database>mydb</Database>, you can destroy it using the following Unix command:
1998-03-01 09:16:16 +01:00
<ProgramListing>
1999-12-07 23:41:44 +01:00
% dropdb mydb
1998-03-01 09:16:16 +01:00
</ProgramListing>
2000-03-26 20:32:30 +02:00
This action physically removes all of the Unix files
1998-03-01 09:16:16 +01:00
associated with the database and cannot be undone, so
2000-03-26 20:32:30 +02:00
this should only be done with a great deal of forethought.
1998-03-01 09:16:16 +01:00
</Para>
</Sect1>
</Chapter>
1999-05-04 04:24:26 +02:00
<!-- Keep this comment at the end of the file
Local variables:
2000-03-31 05:27:42 +02:00
mode:sgml
1999-05-04 04:24:26 +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-05-04 04:24:26 +02:00
sgml-local-ecat-files:nil
End:
-->