1<?xml version="1.0"?>
2<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3<!--
4This file contains the stand-alone installation instructions that end up in
5the INSTALL file.  This document stitches together parts of the installation
6instructions in the main documentation with some material that only appears
7in the stand-alone version.
8-->
9<article id="installation">
10 <title><productname>PostgreSQL</productname> Installation from Source Code</title>
11
12 <!-- This text replaces the introductory text of installation.sgml -->
13 <para>
14  This document describes the installation of
15  <productname>PostgreSQL</productname> using this source code distribution.
16 </para>
17
18 <para>
19  If you are building <productname>PostgreSQL</productname> for Microsoft
20  Windows, read this document if you intend to build with MinGW or Cygwin;
21  but if you intend to build with Microsoft's <productname>Visual
22  C++</productname>, see the main documentation instead.
23 </para>
24
25 <xi:include href="postgres.sgml" xpointer="install-short" xmlns:xi="http://www.w3.org/2001/XInclude"/>
26 <xi:include href="postgres.sgml" xpointer="install-requirements" xmlns:xi="http://www.w3.org/2001/XInclude"/>
27 <xi:include href="postgres.sgml" xpointer="install-procedure" xmlns:xi="http://www.w3.org/2001/XInclude"/>
28 <xi:include href="postgres.sgml" xpointer="install-post" xmlns:xi="http://www.w3.org/2001/XInclude"/>
29
30 <sect1 id="install-getting-started">
31  <title>Getting Started</title>
32
33  <para>
34   The following is a quick summary of how to get <productname>PostgreSQL</productname> up and
35   running once installed. The main documentation contains more information.
36  </para>
37
38  <procedure>
39   <step>
40    <para>
41     Create a user account for the <productname>PostgreSQL</productname>
42     server. This is the user the server will run as. For production
43     use you should create a separate, unprivileged account
44     (<quote>postgres</quote> is commonly used). If you do not have root
45     access or just want to play around, your own user account is
46     enough, but running the server as root is a security risk and
47     will not work.
48<screen><userinput>adduser postgres</userinput></screen>
49    </para>
50   </step>
51
52   <step>
53    <para>
54     Create a database installation with the <command>initdb</command>
55     command. To run <command>initdb</command> you must be logged in to your
56     <productname>PostgreSQL</productname> server account. It will not work as
57     root.
58<screen>root# <userinput>mkdir /usr/local/pgsql/data</userinput>
59root# <userinput>chown postgres /usr/local/pgsql/data</userinput>
60root# <userinput>su - postgres</userinput>
61postgres$ <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</userinput></screen>
62    </para>
63
64    <para>
65     The <option>-D</option> option specifies the location where the data
66     will be stored. You can use any path you want, it does not have
67     to be under the installation directory. Just make sure that the
68     server account can write to the directory (or create it, if it
69     doesn't already exist) before starting <command>initdb</command>, as
70     illustrated here.
71    </para>
72   </step>
73
74   <step>
75    <para>
76     At this point, if you did not use the <command>initdb</command> <literal>-A</literal>
77     option, you might want to modify <filename>pg_hba.conf</filename> to control
78     local access to the server before you start it.  The default is to
79     trust all local users.
80    </para>
81   </step>
82
83   <step>
84    <para>
85     The previous <command>initdb</command> step should have told you how to
86     start up the database server. Do so now. The command should look
87     something like:
88<programlisting>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data start</programlisting>
89    </para>
90
91    <para>
92     To stop a server running in the background you can type:
93<programlisting>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data stop</programlisting>
94    </para>
95   </step>
96
97   <step>
98    <para>
99     Create a database:
100<screen><userinput>/usr/local/pgsql/bin/createdb testdb</userinput></screen>
101     Then enter:
102<screen><userinput>/usr/local/pgsql/bin/psql testdb</userinput></screen>
103     to connect to that database. At the prompt you can enter SQL
104     commands and start experimenting.
105    </para>
106   </step>
107  </procedure>
108 </sect1>
109
110 <sect1 id="install-whatnow">
111  <title>What Now?</title>
112
113  <para>
114   <itemizedlist>
115    <listitem>
116     <para>
117      The <productname>PostgreSQL</productname> distribution contains a
118      comprehensive documentation set, which you should read sometime.
119      After installation, the documentation can be accessed by
120      pointing your browser to
121      <filename>/usr/local/pgsql/doc/html/index.html</filename>, unless you
122      changed the installation directories.
123     </para>
124
125     <para>
126      The first few chapters of the main documentation are the Tutorial,
127      which should be your first reading if you are completely new to
128      <acronym>SQL</acronym> databases.  If you are familiar with database
129      concepts then you want to proceed with part on server
130      administration, which contains information about how to set up
131      the database server, database users, and authentication.
132     </para>
133    </listitem>
134
135    <listitem>
136     <para>
137      Usually, you will want to modify your computer so that it will
138      automatically start the database server whenever it boots. Some
139      suggestions for this are in the documentation.
140     </para>
141    </listitem>
142
143    <listitem>
144     <para>
145      Run the regression tests against the installed server (using
146      <command>make installcheck</command>). If you didn't run the
147      tests before installation, you should definitely do it now. This
148      is also explained in the documentation.
149     </para>
150    </listitem>
151
152    <listitem>
153     <para>
154      By default, <productname>PostgreSQL</productname> is configured to run on
155      minimal hardware.  This allows it to start up with almost any
156      hardware configuration. The default configuration is, however,
157      not designed for optimum performance. To achieve optimum
158      performance, several server parameters must be adjusted, the two
159      most common being <varname>shared_buffers</varname> and
160      <varname>work_mem</varname>.
161      Other parameters mentioned in the documentation also affect
162      performance.
163     </para>
164    </listitem>
165   </itemizedlist>
166  </para>
167 </sect1>
168
169 <xi:include href="postgres.sgml" xpointer="supported-platforms" xmlns:xi="http://www.w3.org/2001/XInclude"/>
170 <xi:include href="postgres.sgml" xpointer="installation-platform-notes" xmlns:xi="http://www.w3.org/2001/XInclude"/>
171</article>
172