mirror of
https://github.com/postgres/postgres.git
synced 2025-05-06 19:59:18 +03:00
3c49c6facb
Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
411 lines
15 KiB
Plaintext
411 lines
15 KiB
Plaintext
<!-- doc/src/sgml/start.sgml -->
|
|
|
|
<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 might 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> might 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 database actions on behalf of the clients. The
|
|
database server program is called
|
|
<filename>postgres</filename>.
|
|
<indexterm><primary>postgres</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. To achieve this 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>postgres</filename> process. Thus, the
|
|
master server process 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. In that 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>
|
|
If this produces no response then 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</productname> was not installed properly. Either it was not
|
|
installed at all or your shell's search path was not set to include it.
|
|
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 the installation instructions to
|
|
correct the situation.
|
|
</para>
|
|
|
|
<para>
|
|
Another response could be this:
|
|
<screen>
|
|
createdb: could not connect to database postgres: 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>
|
|
Another response could be this:
|
|
<screen>
|
|
createdb: could not connect to database postgres: FATAL: role "joe" does not exist
|
|
</screen>
|
|
where your own login name is mentioned. This will happen if the
|
|
administrator has not created a <productname>PostgreSQL</productname> user account
|
|
for you. (<productname>PostgreSQL</productname> user accounts are distinct from
|
|
operating system user accounts.) If you are the administrator, see
|
|
<xref linkend="user-manag"/> for help creating accounts. You will need to
|
|
become the operating system user under which <productname>PostgreSQL</productname>
|
|
was installed (usually <literal>postgres</literal>) to create the first user
|
|
account. It could also be that you were assigned a
|
|
<productname>PostgreSQL</productname> user name that is different from your
|
|
operating system user name; in that case you need to use the <option>-U</option>
|
|
switch or set the <envar>PGUSER</envar> environment variable to specify your
|
|
<productname>PostgreSQL</productname> user name.
|
|
</para>
|
|
|
|
<para>
|
|
If you have a user account but it does 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. When 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 bytes 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> can
|
|
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</firstterm></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>pgAdmin</application> or an office suite with
|
|
<acronym>ODBC</acronym> or <acronym>JDBC</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
|
|
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 do not supply the database name then it will default to your
|
|
user account name. You already discovered this scheme in the
|
|
previous section using <command>createdb</command>.
|
|
</para>
|
|
|
|
<para>
|
|
In <command>psql</command>, you will be greeted with the following
|
|
message:
|
|
<screen>
|
|
psql (&version;)
|
|
Type "help" for help.
|
|
|
|
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 the <productname>PostgreSQL</productname> instance
|
|
yourself. Being a superuser means that you are not subject to
|
|
access controls. For the purposes of this tutorial that is not
|
|
important.
|
|
</para>
|
|
|
|
<para>
|
|
If you encounter problems starting <command>psql</command>
|
|
then go back to the previous section. The diagnostics of
|
|
<command>createdb</command> and <command>psql</command> are
|
|
similar, and if the former worked the latter 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 x86_64-pc-linux-gnu, compiled by gcc (Debian 4.9.2-10) 4.9.2, 64-bit
|
|
(1 row)
|
|
|
|
<prompt>mydb=></prompt> <userinput>SELECT current_date;</userinput>
|
|
date
|
|
------------
|
|
2016-01-07
|
|
(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>.
|
|
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"/>. In this tutorial we will not use these
|
|
features explicitly, but you can use them yourself when it is helpful.
|
|
</para>
|
|
|
|
</sect1>
|
|
</chapter>
|