mirror of
https://github.com/postgres/postgres.git
synced 2025-10-31 10:30:33 +03:00
183bbd1b6d
Now that the dust has more or less settled on 52a10224e and follow-ons,
make sure the examples in the documentation are up-to-date.
410 lines
15 KiB
Plaintext
410 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
|
|
supervisor 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: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory
|
|
Is the server running locally and accepting connections on that socket?
|
|
</screen>
|
|
This means that the server was not started, or it is not listening
|
|
where <command>createdb</command> expects to contact it. Again, check the
|
|
installation instructions or consult the administrator.
|
|
</para>
|
|
|
|
<para>
|
|
Another response could be this:
|
|
<screen>
|
|
createdb: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: 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: error: 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
|
|
-------------------------------------------------------------------&zwsp;-----------------------
|
|
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>
|