mirror of
https://github.com/postgres/postgres.git
synced 2025-05-28 05:21:27 +03:00
425 lines
15 KiB
Plaintext
425 lines
15 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.32 2003/09/12 22:17:24 tgl Exp $
|
|
-->
|
|
|
|
<chapter id="tutorial-start">
|
|
<title>Getting Started</title>
|
|
|
|
<sect1 id="tutorial-install">
|
|
<title>Installation</title>
|
|
|
|
<para>
|
|
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>
|
|
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 you are installing <productname>PostgreSQL</productname>
|
|
yourself, then refer to <xref linkend="installation">
|
|
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="tutorial-arch">
|
|
<title>Architectural Fundamentals</title>
|
|
|
|
<para>
|
|
Before we proceed, you should understand the basic
|
|
<productname>PostgreSQL</productname> system architecture.
|
|
Understanding how the parts of
|
|
<productname>PostgreSQL</productname> interact will make this
|
|
chapter somewhat clearer.
|
|
</para>
|
|
|
|
<para>
|
|
In database jargon, <productname>PostgreSQL</productname> uses a
|
|
client/server model. A <productname>PostgreSQL</productname>
|
|
session consists of the following cooperating processes
|
|
(programs):
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
The user's client (frontend) application that wants to perform
|
|
database operations. Client applications can be very diverse
|
|
in nature: a client 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>
|
|
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 accessible using a different
|
|
file name) on the database server machine.
|
|
</para>
|
|
|
|
<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="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>
|
|
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>
|
|
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>
|
|
To create a new database, in this example named
|
|
<literal>mydb</literal>, you use the following command:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>createdb mydb</userinput>
|
|
</screen>
|
|
This should produce as response:
|
|
<screen>
|
|
CREATE DATABASE
|
|
</screen>
|
|
If so, this step was successful and you can skip over the
|
|
remainder of this section.
|
|
</para>
|
|
|
|
<para>
|
|
If you see a message similar to
|
|
<screen>
|
|
createdb: command not found
|
|
</screen>
|
|
then <productname>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 mydb</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>
|
|
Another response could be this:
|
|
<screen>
|
|
createdb: could not connect to database template1: could not connect to server:
|
|
No such file or directory
|
|
Is the server running locally and accepting
|
|
connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
|
|
</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:
|
|
<screen>
|
|
createdb: database creation failed: ERROR: permission denied to create database
|
|
</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.
|
|
|
|
<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>
|
|
|
|
<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 63 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>
|
|
If you do not want to use your database anymore you can remove it.
|
|
For example, if you are the owner (creator) of the database
|
|
<literal>mydb</literal>, you can destroy it using the following
|
|
command:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>dropdb mydb</userinput>
|
|
</screen>
|
|
(For this command, 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>
|
|
|
|
<para>
|
|
More about <command>createdb</command> and <command>dropdb</command> may
|
|
be found in <xref linkend="APP-CREATEDB"> and <xref linkend="APP-DROPDB">
|
|
respectively.
|
|
</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 <application><firstterm>psql</></application>, 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 an office suite with
|
|
<acronym>ODBC</acronym> support 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 <xref linkend="client-interfaces">.
|
|
</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
|
|
<literal>mydb</literal> 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 &version;, 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=>
|
|
</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
|
|
work space maintained by <command>psql</command>. Try out these
|
|
commands:
|
|
<indexterm><primary>version</primary></indexterm>
|
|
<screen>
|
|
<prompt>mydb=></prompt> <userinput>SELECT version();</userinput>
|
|
version
|
|
----------------------------------------------------------------
|
|
PostgreSQL &version; on i586-pc-linux-gnu, compiled by GCC 2.96
|
|
(1 row)
|
|
|
|
<prompt>mydb=></prompt> <userinput>SELECT current_date;</userinput>
|
|
date
|
|
------------
|
|
2002-08-31
|
|
(1 row)
|
|
|
|
<prompt>mydb=></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 with the backslash
|
|
character, <quote><literal>\</literal></quote>. Some of these
|
|
commands were 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=></prompt> <userinput>\h</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To get out of <command>psql</command>, type
|
|
<screen>
|
|
<prompt>mydb=></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
|
|
<xref linkend="app-psql">. If <productname>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 fit.
|
|
</para>
|
|
|
|
</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:
|
|
-->
|