430 lines
14 KiB
Plaintext
430 lines
14 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.12 2000/05/18 14:24:32 momjian 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 ("root")
|
|
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 "<literal>%</literal>" are commands that should be typed
|
|
at the Unix shell prompt. Examples that begin with the
|
|
character "<literal>*</literal>" 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
|
|
NOTICE: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, "<literal>\</literal>" 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 "<literal>\g</literal>" 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
|
|
"<literal>--</literal>". Everything after the dashes up to the end of the
|
|
line is ignored. Multiple-line comments, and comments within a line,
|
|
are denoted by "<literal>/* ... */</literal>".
|
|
</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:
|
|
-->
|