database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-08-31 17:02:12 +03:00
Code Activity

New blood and fresh air for tutorial

Browse Source
This commit is contained in:
Peter Eisentraut
2001-09-02 23:27:50 +00:00
parent 5608f13028
commit 60ce9e9279
9 changed files with 1352 additions and 1141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

699
doc/src/sgml/start.sgml
View File

@@ -1,414 +1,405 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.16 2001/07/15 13:45:03 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.17 2001/09/02 23:27:49 petere Exp $
-->
<chapter id="start">
<chapter id="tutorial-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 id="start-env">
<title>Setting Up Your Environment</title>
<sect1 id="tutorial-install">
<title>Installation</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.
Before you can use <productname>PostgreSQL</productname> you need
to install it, of course. It is possible that
<productname>PostgreSQL</productname> is already installed at your
site, either because it was included in your operating system
distribution or because the system administrator already installed
it. If that is the case, you should obtain information from the
operating system documentation or your system administrator about
how to access <productname>PostgreSQL</productname>.
</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.
If you are not sure whether <productname>PostgreSQL</productname>
is already available or whether you can use it for your
experimentation then you can install it yourself. Doing so is not
hard and it can be a good exercise.
<productname>PostgreSQL</productname> can be installed by any
unprivileged user, no superuser (<systemitem>root</systemitem>)
access is required.
</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.
If you are installing <productname>PostgreSQL</productname>
yourself, then refer to the <citetitle>Administrator's
Guide</citetitle> for instructions on installation, and return to
this guide when the installation is complete. Be sure to follow
closely the section about setting up the appropriate environment
variables.
</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 <envar>PGHOST</envar> environment variable to the name of the
database server machine. The environment variable
<envar>PGPORT</envar> 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 database, you should consult your
site administrator or, if that is you, the documentation to make
sure that your environment is properly set up. If you did not
understand the preceding paragraph then read the next section.
</para>
</sect1>
<sect1 id="start-psql">
<title>Starting the Interactive Monitor (psql)</title>
<sect1 id="tutorial-arch">
<title>Architectural Fundamentals</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.
Before we proceed, you should understand the basic
<productname>PostgreSQL</productname> system architecture.
Understanding how the parts of
<productname>PostgreSQL</productname> interact will make the next
chapter somewhat clearer.
</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>
In database jargon, <productname>PostgreSQL</productname> uses a
client/server model. A <productname>PostgreSQL</productname>
session consists of the following cooperating processes
(programs):
<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
psql: could not connect to server: Connection refused
Is the server running locally and accepting
connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
</programlisting>
or
<programlisting>
% psql -h localhost template1
psql: could not connect to server: Connection refused
Is the server running on host localhost and accepting
TCP/IP connections on port 5432?
</programlisting>
it is usually because
<itemizedlist mark="bullet" spacing="compact">
<itemizedlist>
<listitem>
<para>
the <application>postmaster</application> is not running,
or
A server process, which manages the database files, accepts
connections to the database from client applications, and
performs actions on the database on behalf of the clients. The
database server program is called
<filename>postmaster</filename>.
<indexterm><primary>postmaster</primary></indexterm>
</para>
</listitem>
<listitem>
<para>
you are attempting to connect to the wrong server host.
The user's client (frontend) application that wants to perform
database operations. Client applications can be very diverse
in nature: They could be a text-oriented tool, a graphical
application, a web server that accesses the database to
display web pages, or a specialized database maintenance tool.
Some client applications are supplied with the
<productname>PostgreSQL</productname> distribution, most are
developed by users.
</para>
</listitem>
</itemizedlist>
</para>
<para>
If you get the following error message:
As is typical of client/server applications, the client and the
server can be on different hosts. In that case they communicate
over a TCP/IP network connection. You should keep this in mind,
because the files that can be accessed on a client machine might
not be accessible (or might only be accessed using a different
file name) on the database server machine.
</para>
<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>
The <productname>PostgreSQL</productname> server can handle
multiple concurrent connections from clients. For that purpose it
starts (<quote>forks</quote>) a new process for each connection.
From that point on, the client and the new server process
communicate without intervention by the original
<filename>postmaster</filename> process. Thus, the
<filename>postmaster</filename> is always running, waiting for
client connections, whereas client and associated server processes
come and go. (All of this is of course invisible to the user. We
only mention it here for completeness.)
</para>
</sect1>
<sect1 id="start-manage-db">
<title>Managing a Database</title>
<sect1 id="tutorial-createdb">
<title>Creating a Database</title>
<indexterm zone="tutorial-createdb">
<primary>database</primary>
<secondary>creating</secondary>
</indexterm>
<indexterm zone="tutorial-createdb">
<primary>createdb</primary>
</indexterm>
<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.
The first test to see whether you can access the database server
is to try to create a database. A running
<productname>PostgreSQL</productname> server can manage many
databases. Typically, a separate database is used for each
project or for each user.
</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.
Possibly, your site administrator has already created a database
for your use. He should have told you what the name of your
database is. In this case you can omit this step and skip ahead
to the next section.
</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.
To create a new database, in this example named
<quote>mydb</quote>, you use the following command:
<screen>
<prompt>$</prompt> <userinput>createdb mydb</userinput>
</screen>
This should produce as response:
<screen>
CREATE DATABASE
</screen>
Is so, this step was successful and you can skip over the
remainder of this section.
</para>
<sect2>
<title>Creating a Database</title>
<para>
If you see a message similar to
<screen>
createdb: command not found
</screen>
then PostgreSQL was not installed properly. Either it was not
installed at all or the search path was not set correctly. Try
calling the command with an absolute path instead:
<screen>
<prompt>$</prompt> <userinput>/usr/local/pgsql/bin/createdb</userinput>
</screen>
The path at your site might be different. Contact your site
administrator or check back in the installation instructions to
correct the situation.
</para>
<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>
Another response could be this:
<screen>
psql: could not connect to server: Connection refused
Is the server running locally and accepting
connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
createdb: database creation failed
</screen>
This means that the server was not started, or it was not started
where <command>createdb</command> expected it. Again, check the
installation instructions or consult the administrator.
</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>
If you do not have the privileges required to create a database,
you will see the following:
<screen>
ERROR: CREATE DATABASE: permission denied
createdb: database creation failed
</screen>
Not every user has authorization to create new databases. If
<productname>PostgreSQL</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. If you installed <productname>PostgreSQL</productname>
yourself then you should log in for the purposes of this tutorial
under the user account that you started the server as.
<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>
<footnote>
<para>
As an explanation for why this works:
<productname>PostgreSQL</productname> user names are separate
from operating system user accounts. If you connect to a
database, you can choose what
<productname>PostgreSQL</productname> user name to connect as;
if you don't, it will default to the same name as your current
operating system account. As it happens, there will always be a
<productname>PostgreSQL</productname> user account that has the
same name as the operating system user that started the server,
and it also happens that that user always has permission to
create databases. Instead of logging in as that user you can
also specify the <option>-U</option> option everywhere to select
a <productname>PostgreSQL</productname> user name to connect as.
</para>
</footnote>
</para>
<sect2>
<title>Accessing a Database</title>
<para>
You can also create databases with other names.
<productname>PostgreSQL</productname> allows you to create any
number of databases at a given site. Database names must have an
alphabetic first character and are limited to 32 characters in
length. A convenient choice is to create a database with the same
name as your current user name. Many tools assume that database
name as the default, so it can save you some typing. To create
that database, simply type
<screen>
<prompt>$</prompt> <userinput>createdb</userinput>
</screen>
</para>
<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>
<para>
If you don't want to use your database anymore you can remove it.
For example, if you are the owner (creator) of the database
<quote>mydb</quote>, you can destroy it using the following
command:
<screen>
<prompt>$</prompt> <userinput>dropdb mydb</userinput>
</screen>
(In this case, the database name does not default to the user
account name. You always need to specify it.) This action
physically removes all files associated with the database and
cannot be undone, so this should only be done with a great deal of
forethought.
</para>
</sect1>
<sect1 id="tutorial-accessdb">
<title>Accessing a Database</title>
<indexterm zone="tutorial-accessdb">
<primary>psql</primary>
</indexterm>
<para>
Once you have created a database, you can access it by:
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<para>
Running the <productname>PostgreSQL</productname> interactive
terminal program, called <quote>psql</quote>, which allows you
to interactively enter, edit, and execute
<acronym>SQL</acronym> commands.
</para>
</listitem>
<listitem>
<para>
Using an existing graphical frontend tool like
<application>PgAccess</application> or
<application>ApplixWare</application> (via
<acronym>ODBC</acronym>) to create and manipulate a database.
These possibilities are not covered in this tutorial.
</para>
</listitem>
<listitem>
<para>
Writing a custom application, using one of the several
available language bindings. These possibilities are discussed
further in <citetitle>The PostgreSQL Programmer's
Guide</citetitle>.
</para>
</listitem>
</itemizedlist>
You probably want to start up <command>psql</command>, to try out
the examples in this tutorial. It can be activated for the
<quote>mydb</quote> database by typing the command:
<screen>
<prompt>$</prompt> <userinput>psql mydb</userinput>
</screen>
If you leave off the database name then it will default to your
user account name. You already discovered this scheme in the
previous section.
</para>
<para>
In <command>psql</command>, you will be greeted with the following
message:
<screen>
Welcome to psql, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help on internal slash commands
\g or terminate with semicolon to execute query
\q to quit
mydb=&gt;
</screen>
<indexterm><primary>superuser</primary></indexterm>
The last line could also be
<screen>
mydb=#
</screen>
That would mean you are a database superuser, which is most likely
the case if you installed <productname>PostgreSQL</productname>
yourself. Being a superuser means that you are not subject to
access controls. For the purpose of this tutorial this is not of
importance.
</para>
<para>
If you have encountered problems starting <command>psql</command>
then go back to the previous section. The diagnostics of
<command>psql</command> and <command>createdb</command> are
similar, and if the latter worked the former should work as well.
</para>
<para>
The last line printed out by <command>psql</command> is the
prompt, and it indicates that <command>psql</command> is listening
to you and that you can type <acronym>SQL</acronym> queries into a
workspace maintained by <command>psql</command>. Try out these
commands:
<indexterm><primary>version</primary></indexterm>
<screen>
<prompt>mydb=&gt;</prompt> <userinput>SELECT version();</userinput>
version
----------------------------------------------------------------
PostgreSQL 7.2devel on i586-pc-linux-gnu, compiled by GCC 2.96
(1 row)
<prompt>mydb=&gt;</prompt> <userinput>SELECT current_date;</userinput>
date
------------
2001-08-31
(1 row)
<prompt>mydb=&gt;</prompt> <userinput>SELECT 2 + 2;</userinput>
?column?
----------
4
(1 row)
</screen>
</para>
<para>
The <command>psql</command> program has a number of internal
commands that are not SQL commands. They begin the backslash
character, <quote><literal>\</literal></quote>. Some of these
commands were already listed in the welcome message. For example,
you can get help on the syntax of various
<productname>PostgreSQL</productname> <acronym>SQL</acronym>
commands by typing:
<screen>
<prompt>mydb=&gt;</prompt> <userinput>\h</userinput>
</screen>
</para>
<para>
To get out of <command>psql</command>, type
<screen>
<prompt>mydb=&gt;</prompt> <userinput>\q</userinput>
</screen>
and <command>psql</command> will quit and return you to your
command shell. (For more internal commands, type
<literal>\?</literal> at the <command>psql</command> prompt.) The
full capabilities of <command>psql</command> are documented in the
<citetitle>Reference Manual</citetitle>. If PostgreSQL is
installed correctly you can also type <literal>man psql</literal>
at the operating system shell prompt to see the documentation. In
this tutorial we will not use these features explicitly, but you
can use them yourself when you see it fit.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file