<!--
$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.10 2000/04/07 13:30:58 thomas Exp $
-->
<chapter id="start">
<title>Getting Started</title>
<abstract>
<para>
How to begin work with <productname>Postgres</productname> for a new user.
</para>
</abstract>
<para>
Some of the steps required to use <productname>Postgres</productname>
can be performed by any Postgres user, and some must be done by
the site database administrator. This site administrator
is the person who installed the software, created
the database directories and started the
<application>postmaster</application>
process. This person does not have to be the Unix
superuser (<quote>root</quote>)
or the computer system administrator; a person can install and use
<productname>Postgres</productname> without any special accounts or
privileges.
</para>
<para>
If you are installing <productname>Postgres</productname> yourself, then
refer to the Administrator's Guide for instructions on
installation, and return
to this guide when the installation is complete.
</para>
<para>
Throughout this manual, any examples that begin with
the character <quote>%</quote> are commands that should be typed
at the Unix shell prompt. Examples that begin with the
character <quote>*</quote> are commands in the Postgres query
language, Postgres <acronym>SQL</acronym>.
</para>
<sect1>
<title>Setting Up Your Environment</title>
<para>
This section discusses how to set up
your own environment so that you can use frontend
applications. We assume <productname>Postgres</productname> has
already been
successfully installed and started; refer to the Administrator's Guide
and the installation notes
for how to install Postgres.
</para>
<para>
<productname>Postgres</productname> is a client/server
application. As a user,
you only need access to the client portions of the installation
(an example
of a client application is the interactive monitor
<application>psql</application>).
For simplicity,
we will assume that <productname>Postgres</productname> has been
installed in the
directory <filename>/usr/local/pgsql</filename>. Therefore, wherever
you see the directory <filename>/usr/local/pgsql</filename> you should
substitute the name of the directory where
<productname>Postgres</productname> is
actually installed.
All <productname>Postgres</productname> commands are installed in
the directory
<filename>/usr/local/pgsql/bin</filename>. 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
<programlisting>
% set path = ( /usr/local/pgsql/bin path )
</programlisting>
in the <filename>.login</filename> file in your home directory.
If you use
a variant of the Bourne shell, such as sh, ksh, or
bash, then you would add
<programlisting>
% PATH=/usr/local/pgsql/bin:$PATH
% export PATH
</programlisting>
to the .profile file in your home directory.
From now on, we will assume that you have added the
<productname>Postgres</productname> bin directory to your path.
In addition, we
will make frequent reference to <quote>setting a shell
variable</quote> or <quote>setting an environment
variable</quote> 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.
</para>
<para>
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 <acronym>PGHOST</acronym> environment
variable to the name
of the database server machine. The environment variable
<acronym>PGPORT</acronym> 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 <application>postmaster</application>,
you should immediately consult your site administrator to make
sure that your
environment is properly set up.
</para>
</sect1>
<sect1>
<title>Starting the Interactive Monitor (psql)</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>
<para>
Two different styles of connections
are supported. The site administrator will have chosen to allow
TCP/IP network connections
or will have restricted database access to local (same-machine)
socket connections only.
These choices become significant if you encounter problems in
connecting to a database, since you will want to confirm that you
are choosing an allowed connection option.
</para>
<para>
If you get the following error message from a
<productname>Postgres</productname>
command (such as <application>psql</application> or
<application>createdb</application>):
<programlisting>
% psql template1
Connection to database 'postgres' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '5432'?
</programlisting>
or
<programlisting>
% psql -h localhost template1
Connection to database 'postgres' failed.
connectDB() failed: Is the postmaster running and accepting TCP/IP
(with -i) connections at 'localhost' on port '5432'?
</programlisting>
it is usually because
<itemizedlist mark="bullet" spacing="compact">
<listitem>
<para>
the <application>postmaster</application> is not running,
or
</para>
</listitem>
<listitem>
<para>
you are attempting to connect to the wrong server host.
</para>
</listitem>
</itemizedlist>
</para>
<para>
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>
</sect1>
<sect1>
<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>
<para>
Most <productname>Postgres</productname>
applications assume that the database name, if not specified, is
the same as the name on your computer
account.
</para>
<para>
If your database administrator has set up your account without
database creation privileges,
then she should have told you what the name of your database is. If
this is the case, then you
can skip the sections on creating and destroying databases.
</para>
<sect2>
<title>Creating a Database</title>
<para>
Let's say you want to create a database named
<database>mydb</database>.
You can do this with the following command:
<programlisting>
% createdb mydb
</programlisting>
</para>
<para>
If you do not have the privileges required to create a database,
you will see
the following:
<programlisting>
% createdb mydb
WARN:user "your username" is not allowed to create/destroy databases
createdb: database creation failed on mydb.
</programlisting>
</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.
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>
</sect2>
<sect2>
<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 programs
(e.g. <application>psql</application>) which allows you to
interactively
enter, edit, and execute <acronym>SQL</acronym> commands.
</para>
</listitem>
<listitem>
<para>
Using an existing native frontend tool like
<application>pgaccess</application> or
<application>ApplixWare</application> (via
<acronym>ODBC</acronym>) to create and manipulate a
database.
</para>
</listitem>
<listitem>
<para>
Using a language like perl or tcl which has a supported
interface for <productname>Postgres</productname>. Some of
these languages also have convenient and powerful GUI toolkits
which can help you construct custom
applications. <application>pgaccess</application>, mentioned
above, is one such application written in tk/tcl and can be
used as an example.
</para>
</listitem>
<listitem>
<para>
Writing a <acronym>C</acronym> program using
the LIBPQ subroutine
library. This allows you to submit
<acronym>SQL</acronym> commands
from <acronym>C</acronym> and get answers and
status messages back to
your program. This interface is discussed further
in <citetitle>The 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 <database>mydb</database>
database by typing the command:
<programlisting>
% psql mydb
</programlisting>
You will be greeted with the following message:
<programlisting>
Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL
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: template1
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, <quote>\</quote> For example, you
can get help on the syntax of various
<productname>Postgres</productname> <acronym>SQL</acronym>
commands by typing:
<programlisting>
mydb=> \h
</programlisting>
</para>
<para>
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 <quote>\g</quote> 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 <command>\h</command> 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>
</sect2>
<sect2>
<title>Destroying a Database</title>
<para>
If you are the database administrator for the database
<database>mydb</database>, you can destroy it using the
following Unix command:
<programlisting>
% dropdb 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>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:t
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
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->