1998-07-29 08:35:19 +02:00
|
|
|
<Chapter Id="start">
|
1998-03-01 09:16:16 +01:00
|
|
|
<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
|
1998-10-18 00:02:21 +02:00
|
|
|
the character <Quote>%</Quote> are commands that should be typed
|
1998-03-01 09:16:16 +01:00
|
|
|
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>
|
1999-05-04 04:57:13 +02:00
|
|
|
% PATH=/usr/local/pgsql/bin:$PATH
|
1998-03-01 09:16:16 +01:00
|
|
|
% 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>
|
|
|
|
As of <ProductName>Postgres</ProductName> v6.3, 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.
|
|
|
|
</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 (1) the <Application>postmaster</Application> is not running,
|
|
|
|
or (2) 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>
|
|
|
|
</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 Mark="bullet" Spacing="compact">
|
|
|
|
<ListItem>
|
|
|
|
<Para>
|
1998-10-21 07:33:41 +02:00
|
|
|
running the <ProductName>Postgres</ProductName> terminal monitor programs
|
|
|
|
(e.g. <Application>psql</Application>) which allows you to interactively
|
1998-03-01 09:16:16 +01:00
|
|
|
enter, edit, and execute <Acronym>SQL</Acronym> commands.
|
|
|
|
</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
|
1999-01-07 04:05:01 +01:00
|
|
|
in <citetitle>The PostgreSQL Programmer's Guide</citetitle>.
|
1998-03-01 09:16:16 +01:00
|
|
|
</Para>
|
|
|
|
</ListItem>
|
|
|
|
</ItemizedList>
|
|
|
|
|
1998-10-21 07:33:41 +02: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>
|
|
|
|
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>
|
|
|
|
|
|
|
|
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
|
1999-01-07 04:05:01 +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>
|
|
|
|
|
|
|
|
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>
|
|
|
|
% 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>
|
|
|
|
</Sect2>
|
|
|
|
</Sect1>
|
|
|
|
|
|
|
|
</Chapter>
|
1999-01-07 04:05:01 +01:00
|
|
|
|
|
|
|
<!-- 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:
|
|
|
|
-->
|