mirror of
https://github.com/postgres/postgres.git
synced 2025-12-22 17:42:17 +03:00
SGML source for new documentation.
This commit is contained in:
Thomas G. Lockhart
315
doc/src/sgml/start.sgml
Normal file
315
doc/src/sgml/start.sgml
Normal file
@@ -0,0 +1,315 @@
|
||||
<Chapter>
|
||||
<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>&percnt</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>
|
||||
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>
|
||||
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>
|
||||
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 <XRef LinkEnd="PROGRAMMERS-GUIDE">.
|
||||
</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>
|
||||
|
||||
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>
|
||||
% 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>
|
||||
Reference in New Issue
Block a user