<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - GETTING STARTED</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="architec.html">[ Previous ]</A>
<A HREF="query.html">[ Next ]</A>
</font>
<HR>
<H1>3. GETTING STARTED WITH POSTGRES</H1>
<HR>
This section discusses how to start POSTGRES and set up
your own environment so that you can use frontend
applications. We assume POSTGRES has already been
successfully installed. (Refer to the installation notes
for how to install POSTGRES.)
<p>
Some of the steps listed in this section will apply to
all POSTGRES users, and some will apply primarily to
the site database administrator. This site administrator
is the person who installed the software, created
the database directories and started the <B>postmaster</B>
process. This person does not have to be the UNIX
superuser, "root," or the computer system administrator.
In this section, items for end users are labelled
"User" and items intended for the site administrator
are labelled "Admin."
Throughout this manual, any examples that begin with
the character ``%'' are commands that should be typed
at the UNIX shell prompt. Examples that begin with the
character ``*'' are commands in the POSTGRES query
language, POSTGRES <B>SQL</B>.
<H2><A NAME="setting-up-your-environment">3.1. Admin/User: Setting Up Your Environment</A></H2>
<IMG SRC="figure02.gif" ALT="Figure 2. POSTGRES file layout.">
Figure 2. shows how the POSTGRES distribution is laid
out when installed in the default way. For simplicity,
we will assume that POSTGRES has been installed in the
directory /usr/local/postgres95. Therefore, wherever
you see the directory /usr/local/postgres95 you should
substitute the name of the directory where POSTGRES is
actually installed.
All POSTGRES commands are installed in the directory
/usr/local/postgres95/bin. Therefore, you should add
this directory to your shell command path. If you use
a variant of the Berkeley C shell, such as csh or tcsh,
you would add
<pre> % set path = ( /usr/local/postgres95/bin $path )
</pre>
in the .login file in your home directory. If you use
a variant of the Bourne shell, such as sh, ksh, or
bash, then you would add
<pre>
% PATH=/usr/local/postgres95/bin:$PATH
% export PATH
</pre>
to the .profile file in your home directory.
From now on, we will assume that you have added the
POSTGRES bin directory to your path. In addition, we
will make frequent reference to "setting a shell
variable" or "setting an environment variable" throughout
this document. If you did not fully understand the
last paragraph on modifying your search path, you
should consult the UNIX manual pages that describe your
shell before going any further.
<H2><A NAME="starting-the-postmaster">3.2. Admin: Starting the <B>Postmaster</A></B></H2>
It should be clear from the preceding discussion that
nothing can happen to a database unless the <B>postmaster</B>
process is running. As the site administrator, there
are a number of things you should remember before
starting the <B>postmaster</B>. These are discussed in the
section of this manual titled, "Administering POSTGRES."
However, if POSTGRES has been installed by following
the installation instructions exactly as written, the
following simple command is all you should
need to start the <B>postmaster</B>:
<pre> % postmaster &
</pre>
The <B>postmaster</B> occasionally prints out messages which
are often helpful during troubleshooting. If you wish
to view debugging messages from the <B>postmaster</B>, you can
start it with the -d option and redirect the output to
the log file:
<pre> % postmaster -d >& pm.log &
</pre>
If you do not wish to see these messages, you can type
<pre> % postmaster -S
</pre>
and the <B>postmaster</B> will be "S"ilent. Notice that there
is no ampersand ("&") at the end of the last example.
<H2><A NAME="adding-and-deleting-users">3.3. Admin: Adding and Deleting Users</A></H2>
The createuser command enables specific users to access
POSTGRES. The destroyuser command removes users and
prevents them from accessing POSTGRES. Note that these
commands only affect users with respect to POSTGRES;
they have no effect administration of users that the
operating system manages.
<H2><A NAME="starting-applications">3.4. User: Starting Applications</A></H2>
Assuming that your site administrator has properly
started the <B>postmaster</B> process and authorized you to
use the database, you (as a user) may begin to start up
applications. As previously mentioned, you should add
/usr/local/postgres95/bin to your shell search path.
In most cases, this is all you should have to do in
terms of preparation.<A HREF="#1">1</A>
If you get the following error message from a POSTGRES
command (such as <B>psql</B> or createdb):
<pre> connectDB() failed: Is the postmaster running at 'localhost' on port '4322'?
</pre>
it is usually because (1) the <B>postmaster</B> is not running, or (2) you are attempting to connect to the wrong
server host.
If you get the following error message:
<pre> FATAL 1:Feb 17 23:19:55:process userid (2360) !=
database owner (268)
</pre>
it means that the site administrator started the <B>postmaster</B> as the wrong user. Tell him to restart it as
the POSTGRES superuser.
<H2><A NAME="managing-a-database">3.5. User: Managing a Database</A></H2>
Now that POSTGRES is up and running we can create some
databases to experiment with. Here, we describe the
basic commands for managing a database.
<H3><A NAME="creating-a-database">3.5.1. Creating a Database</A></H3>
Let's say you want to create a database named mydb.
You can do this with the following command:
<pre> % createdb mydb
</pre>
POSTGRES 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 POSTGRES 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.
<H3><A NAME="accessing-a-database">3.5.2. Accessing a Database</A></H3>
Once you have constructed a database, you can access it
by:
<UL>
<LI>running the POSTGRES terminal monitor programs (
monitor or <B>psql</B>) which allows you to interactively
enter, edit, and execute <B>SQL</B> commands.
<LI>writing a C program using the LIBPQ subroutine
library. This allows you to submit <B>SQL</B> commands
from C and get answers and status messages back to
your program. This interface is discussed further
in section ??.
</UL>
You might want to start up <B>psql</B>, to try out the examples in this manual. It can be activated for the mydb
database by typing the command:
<pre> % psql mydb
</pre>
You will be greeted with the following message:
<pre> Welcome to the POSTGRES95 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=>
</pre> This prompt indicates that the terminal monitor is listening to you and that you can type <B>SQL</B> queries into a
workspace maintained by the terminal monitor.
The <B>psql</B> program responds to escape codes that begin
with the backslash character, "\". For example, you
can get help on the syntax of various POSTGRES <B>SQL</B> commands by typing:
<pre> mydb=> \h
</pre>
Once you have finished entering your queries into the
workspace, you can pass the contents of the workspace
to the POSTGRES server by typing:
<pre> mydb=> \g
</pre>
This tells the server to process the query. If you
terminate your query with a semicolon, the \g is not
necessary. <B>psql</B> will automatically process semicolon terminated queries.
To read queries from a file, say myFile, instead of
entering them interactively, type:
<pre> mydb=> \i fileName
</pre>
To get out of <B>psql</B> and return to UNIX, type
<pre> mydb=> \q
</pre>
and <B>psql</B> will quit and return you to your command
shell. (For more escape codes, type \h at the monitor
prompt.)
White space (i.e., spaces, tabs and newlines) may be
used freely in <B>SQL</B> queries. Comments are denoted by
<b>--</b>. Everything after the dashes up to the end of the
line is ignored.
<H3><A NAME="detroying-a-database">3.5.3. Destroying a Database</A></H3>
If you are the database administrator for the database
mydb, you can destroy it using the following UNIX command:
<pre> % destroydb mydb
</pre>
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 fore-thought.
<p>
<HR>
<A NAME="1"><B>1.</B></A> If your site administrator has not set things up in the
default way, you may have some more work to do. For example, if the database server machine is a remote machine, you
will need to set the <B>PGHOST</B> environment variable to the name
of the database server machine. The environment variable
<B>PGPORT</B> may also have to be set. The bottom line is this: if
you try to start an application program and it complains
that it cannot connect to the <B>postmaster</B>, you should immediately consult your site administrator to make sure that your
environment is properly set up.
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="architec.html">[ Previous ]</A>
<A HREF="query.html">[ Next ]</A>
</font>
</BODY>
</HTML>