<!--
- This file currently contains several small chapters.
- Each chapter should be split off into a separate source file...
- - thomas 1998-02-24
-->
<Chapter Id="postmaster">
<Title>Starting <Application>postmaster</Application></Title>
<Para>
Nothing can happen to a database unless the
<Application>postmaster</Application>
process is running. As the site administrator, there
are a number of things you should remember before
starting the <Application>postmaster</Application>.
These are discussed in the installation and configuration sections
of this manual.
However, if <ProductName>Postgres</ProductName> has been installed by following
the installation instructions exactly as written, the
following simple command is all you should
need to start the <Application>postmaster</Application>:
<ProgramListing>
% postmaster
</ProgramListing>
The <Application>postmaster</Application> occasionally prints out
messages which
are often helpful during troubleshooting. If you wish
to view debugging messages from the <Application>postmaster</Application>,
you can
start it with the -d option and redirect the output to
the log file:
<ProgramListing>
% postmaster -d >& pm.log &
</ProgramListing>
If you do not wish to see these messages, you can type
<ProgramListing>
% postmaster -S
</ProgramListing>
and the <Application>postmaster</Application> will be "S"ilent.
Notice that there
is no ampersand ("&") at the end of the last example.
</Para>
</Chapter>
<Chapter Id="newuser">
<Title>Adding and Deleting Users</Title>
<Para>
<Application>createuser</Application> enables specific users to access
<ProductName>Postgres</ProductName>.
<Application>destroyuser</Application> removes users and
prevents them from accessing <ProductName>Postgres</ProductName>.
Note that these
commands only affect users with respect to
<ProductName>Postgres</ProductName>;
they have no effect on users other privileges or status with regards
to the underlying
operating system.
</Para>
</Chapter>
<Chapter Id="disk">
<Title>Disk Management</Title>
<Para>
</Para>
<Sect1>
<Title>Alternate 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>
Either an absolute path name or an environment variable
may be specified as a location. Note that for security and integrity reasons,
all paths and environment variables so specified have some
additional path fields appended.
<Note>
<Para>
The environment variable style of specification
is to be preferred since it allows the site administrator more flexibility in
managing disk storage.
</Para>
</Note>
<Para>
Remember that database creation is actually performed by the database backend.
Therefore, any environment variable specifying an alternate location must have
been defined before the backend was started. To define an alternate location
PGDATA2 pointing to <filename>/home/postgres/data</filename>, type
<ProgramListing>
% setenv PGDATA2 /home/postgres/data
</ProgramListing>
<Para>
Usually, you will want to define this variable in the
<ProductName>Postgres</ProductName> superuser's
<filename>.profile</filename>
or
<filename>.cshrc</filename>
initialization file to ensure that it is defined upon system startup.
<Para>
To create a data storage area in <filename>/home/postgres/data</filename>, ensure
that <filename>/home/postgres</filename> already exists and is writable.
From the command line, type
<ProgramListing>
% initlocation $PGDATA2
Creating Postgres database system directory /home/postgres/data
Creating Postgres database system directory /home/postgres/data/base
</ProgramListing>
<Para>
To test the new location, create a database <Database>test</Database> by typing
<ProgramListing>
% createdb -D PGDATA2 test
% destroydb test
</ProgramListing>
</Sect1>
</Chapter>
<Chapter Id="trouble">
<Title>Troubleshooting</Title>
<Para>
Assuming that your site administrator has properly
started the <Application>postmaster</Application> process
and authorized you to
use the database, you (as a user) may begin to start up
applications. As previously mentioned, you should add
<filename>/usr/local/pgsql/bin</filename> to your shell search path.
In most cases, this is all you should have to do in
terms of preparation.
<Para>
If you get the following error message from a
<ProductName>Postgres</ProductName>
command (such as <Application>psql</Application> or
<Application>createdb</Application>):
<ProgramListing>
connectDB() failed: Is the postmaster running at 'localhost' on port '5432'?
</ProgramListing>
it is usually because either the <Application>postmaster</Application> is not running,
or you are attempting to connect to the wrong server host.
If you get the following error message:
<ProgramListing>
FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
</ProgramListing>
it means that the site administrator started the <Application>postmaster</Application>
as the wrong user. Tell him to restart it as
the <ProductName>Postgres</ProductName> superuser.
</Para>
</Chapter>
<Chapter Id="manage-ag">
<Title>Managing a Database</Title>
<Para>
Now that <ProductName>Postgres</ProductName> is up and running we can create
some databases to experiment with. Here, we describe the
basic commands for managing a database.
</Para>
<Sect1>
<Title>Creating a Database</Title>
<Para>
Let's say you want to create a database named mydb.
You can do this with the following command:
<ProgramListing>
% createdb mydb
</ProgramListing>
<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 16 characters in length.
Not every user has authorization to become a database
administrator. If <ProductName>Postgres</ProductName>
refuses to create databases
for you, then the site administrator needs to grant you
permission to create databases. Consult your site
administrator if this occurs.
</Para>
</Sect1>
<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>
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 mydb
database by typing the command:
<ProgramListing>
% psql mydb
</ProgramListing>
You will be greeted with the following message:
<ProgramListing>
Welcome to the Postgres interactive sql monitor:
type \? for help on slash commands
type \q to quit
type \g or terminate with semicolon to execute query
You are currently connected to the database: mydb
mydb=>
</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, "\". For example, you
can get help on the syntax of various
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> commands by typing:
<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
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, say myFile, instead of
entering them interactively, type:
<ProgramListing>
mydb=> \i fileName
</ProgramListing>
To get out of <Application>psql</Application> and return to UNIX, type
<ProgramListing>
mydb=> \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
<Quote>--</Quote>. Everything after the dashes up to the end of the
line is ignored. Multiple-line comments, and comments within a line,
are denoted by <Quote>/* ... */</Quote>
</Para>
</Sect1>
<Sect1>
<Title>Destroying a Database</Title>
<Para>
If you are the database administrator for the database
mydb, you can destroy it using the following UNIX command:
<ProgramListing>
% destroydb mydb
</ProgramListing>
This action physically removes all of the UNIX files
associated with the database and cannot be undone, so
this should only be done with a great deal of forethought.
</Para>
</Sect1>
</Chapter>