1 <!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.201 2004/05/18 21:46:25 momjian Exp $ -->
3 <chapter id="installation">
4 <title><![%standalone-include[<productname>PostgreSQL</>]]>
5 Installation Instructions</title>
7 <indexterm zone="installation">
8 <primary>installation</primary>
12 This <![%standalone-include;[document]]>
13 <![%standalone-ignore;[chapter]]> describes the installation of
14 <productname>PostgreSQL</productname> from the source code
18 <sect1 id="install-short">
19 <title>Short Version</title>
28 mkdir /usr/local/pgsql/data
29 chown postgres /usr/local/pgsql/data
31 /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
32 /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
33 /usr/local/pgsql/bin/createdb test
34 /usr/local/pgsql/bin/psql test
36 The long version is the rest of this
37 <![%standalone-include;[document.]]>
38 <![%standalone-ignore;[chapter.]]>
43 <sect1 id="install-requirements">
44 <title>Requirements</title>
47 In general, a modern Unix-compatible platform should be able to run
48 <productname>PostgreSQL</>.
49 The platforms that had received specific testing at the
50 time of release are listed in <xref linkend="supported-platforms">
51 below. In the <filename>doc</> subdirectory of the distribution
52 there are several platform-specific <acronym>FAQ</> documents you
53 might wish to consult if you are having trouble.
57 The following software packages are required for building
58 <productname>PostgreSQL</>:
64 <primary>make</primary>
67 <acronym>GNU</> <application>make</> is required; other
68 <application>make</> programs will <emphasis>not</> work.
69 <acronym>GNU</> <application>make</> is often installed under
70 the name <filename>gmake</filename>; this document will always
71 refer to it by that name. (On some systems
72 <acronym>GNU</acronym> <application>make</> is the default tool with the name
73 <filename>make</>.) To test for <acronym>GNU</acronym>
74 <application>make</application> enter
76 <userinput>gmake --version</userinput>
78 It is recommended to use version 3.76.1 or later.
84 You need an <acronym>ISO</>/<acronym>ANSI</> C compiler. Recent
85 versions of <productname>GCC</> are recommendable, but
86 <productname>PostgreSQL</> is known to build with a wide variety
87 of compilers from different vendors.
93 <application>gzip</> is needed to unpack the distribution in the
94 first place.<![%standalone-include;[ If you are reading this, you probably already got
102 <primary>readline</primary>
105 The <acronym>GNU</> <productname>Readline</> library (for
106 comfortable line editing and command history retrieval) will be
107 used by default. If you don't want to use it then you must
108 specify the <option>--without-readline</option> option for
109 <filename>configure</>. (On <productname>NetBSD</productname>,
110 the <filename>libedit</filename> library is
111 <productname>Readline</productname>-compatible and is used if
112 <filename>libreadline</filename> is not found.)
119 <primary>installation</primary>
120 <secondary>on Windows</secondary>
123 To build on <productname>Windows NT</> or <productname>Windows
124 2000</> you need the <productname>Cygwin</> and
125 <productname>cygipc</> packages. See the file
126 <filename>doc/FAQ_MSWIN</> for details.
133 The following packages are optional. They are not required in the
134 default configuration, but they are needed when certain build
135 options are enabled, as explained below.
140 To build the server programming language PL/Perl you need a full
141 <productname>Perl</productname> installation, including the
142 <filename>libperl</filename> library and the header files.
143 Since PL/Perl will be a shared library, the
144 <indexterm><primary>libperl</primary></indexterm>
145 <filename>libperl</filename> library must be a shared library
146 also on most platforms. This appears to be the default in
147 recent Perl versions, but it was not in earlier versions, and in
148 general it is the choice of whomever installed Perl at your
153 If you don't have the shared library but you need one, a message
154 like this will appear during the build to point out this fact:
156 *** Cannot build PL/Perl because libperl is not a shared library.
157 *** You might have to rebuild your Perl installation. Refer to
158 *** the documentation for details.
160 (If you don't follow the on-screen output you will merely notice
161 that the PL/Perl library object, <filename>plperl.so</filename>
162 or similar, will not be installed.) If you see this, you will
163 have to rebuild and install <productname>Perl</productname>
164 manually to be able to build PL/Perl. During the configuration
165 process for <productname>Perl</productname>, request a shared
172 To build the PL/Python server programming language, you need a
173 Python installation, including the header files. Since
174 PL/Python will be a shared library, the
175 <indexterm><primary>libpython</primary></indexterm>
176 <filename>libpython</filename> library must be a shared library
177 also on most platforms. This is not the case in a default
182 If after building and installing you have a file called
183 <filename>plpython.so</filename> (possibly a different
184 extension), then everything went well. Otherwise you should
185 have seen a notice like this flying by:
187 *** Cannot build PL/Python because libpython is not a shared library.
188 *** You might have to rebuild your Python installation. Refer to
189 *** the documentation for details.
191 That means you have to rebuild (part of) your Python
192 installation to supply this shared library.
196 If you have problems, run Python 2.3 or later's configure using the
197 <literal>--enable-shared</> flag. On some operating systems you
198 don't have to build a shared library, but you will have
199 to convince the <productname>PostgreSQL</> build system of this.
200 Consult the <filename>Makefile</filename> in the
201 <filename>src/pl/plpython</filename> directory for details.
207 If you want to build Tcl or Tk components (clients and the
208 PL/Tcl language) you of course need a Tcl installation.
214 To enable Native Language Support (<acronym>NLS</acronym>), that
215 is, the ability to display a program's messages in a language
216 other than English, you need an implementation of the
217 <application>Gettext</> <acronym>API</acronym>. Some operating
218 systems have this built-in (e.g., <systemitem
219 class="osname">Linux</>, <systemitem class="osname">NetBSD</>,
220 <systemitem class="osname">Solaris</>), for other systems you
221 can download an add-on package from here: <ulink
222 url="http://developer.postgresql.org/~petere/bsd-gettext/" ></ulink>.
223 If you are using the <application>Gettext</> implementation in
224 the <acronym>GNU</acronym> C library then you will additionally
225 need the <productname>GNU Gettext</productname> package for some
226 utility programs. For any of the other implementations you will
233 <application>Kerberos</>, <productname>OpenSSL</>, or <application>PAM</>,
234 if you want to support authentication using these services.
241 If you are building from a <acronym>CVS</acronym> tree instead of
242 using a released source package, or if you want to do development,
243 you also need the following packages:
249 <primary>flex</primary>
252 <primary>bison</primary>
255 <primary>yacc</primary>
258 <application>Flex</> and <application>Bison</>
259 are needed to build a CVS checkout or if you changed the actual
260 scanner and parser definition files. If you need them, be sure
261 to get <application>Flex</> 2.5.4 or later and
262 <application>Bison</> 1.875 or later. Other <application>yacc</>
263 programs can sometimes be used, but doing so requires extra
264 effort and is not recommended. Other <application>lex</>
265 programs will definitely not work.
272 If you need to get a <acronym>GNU</acronym> package, you can find
273 it at your local <acronym>GNU</acronym> mirror site (see <ulink
274 url="http://www.gnu.org/order/ftp.html"></>
275 for a list) or at <ulink
276 url="ftp://ftp.gnu.org/gnu/"></ulink>.
280 Also check that you have sufficient disk space. You will need about
281 65 MB for the source tree during compilation and about 15 MB for
282 the installation directory. An empty database cluster takes about
283 25 MB, databases take about five times the amount of space that a
284 flat text file with the same data would take. If you are going to
285 run the regression tests you will temporarily need up to an extra
286 90 MB. Use the <command>df</command> command to check for disk
291 <![%standalone-ignore;[
292 <sect1 id="install-getsource">
293 <title>Getting The Source</title>
296 The <productname>PostgreSQL</> &version; sources can be obtained by
297 anonymous FTP from <ulink
298 url="ftp://ftp.postgresql.org/pub/source/v&version;/postgresql-&version;.tar.gz"></ulink>.
299 Use a mirror if possible. After you have obtained the file, unpack it:
301 <userinput>gunzip postgresql-&version;.tar.gz</userinput>
302 <userinput>tar xf postgresql-&version;.tar</userinput>
304 This will create a directory
305 <filename>postgresql-&version;</filename> under the current directory
306 with the <productname>PostgreSQL</> sources.
307 Change into that directory for the rest
308 of the installation procedure.
313 <sect1 id="install-upgrading">
314 <title>If You Are Upgrading</title>
316 <indexterm zone="install-upgrading">
317 <primary>upgrading</primary>
321 The internal data storage format changes with new releases of
322 <productname>PostgreSQL</>. Therefore, if you are upgrading an
323 existing installation that does not have a version number
324 <quote>&majorversion;.x</quote>, you must back up and restore your
325 data as shown here. These instructions assume that your existing
326 installation is under the <filename>/usr/local/pgsql</> directory,
327 and that the data area is in <filename>/usr/local/pgsql/data</>.
328 Substitute your paths appropriately.
334 Make sure that your database is not updated during or after the
335 backup. This does not affect the integrity of the backup, but the
336 changed data would of course not be included. If necessary, edit
337 the permissions in the file
338 <filename>/usr/local/pgsql/data/pg_hba.conf</> (or equivalent) to
339 disallow access from everyone except you.
346 <primary>pg_dumpall</primary>
347 <secondary>use during upgrade</secondary>
350 To back up your database installation, type:
352 <userinput>pg_dumpall > <replaceable>outputfile</></userinput>
354 If you need to preserve OIDs (such as when using them as
355 foreign keys), then use the <option>-o</option> option when running
356 <application>pg_dumpall</>.
360 <application>pg_dumpall</application> does not
361 save large objects. Check
362 <![%standalone-include[the documentation]]>
363 <![%standalone-ignore[<xref linkend="backup-dump-caveats">]]>
364 if you need to do this.
368 To make the backup, you can use the <application>pg_dumpall</application>
369 command from the version you are currently running. For best
370 results, however, try to use the <application>pg_dumpall</application>
371 command from <productname>PostgreSQL</productname> &version;,
372 since this version contains bug fixes and improvements over older
373 versions. While this advice might seem idiosyncratic since you
374 haven't installed the new version yet, it is advisable to follow
375 it if you plan to install the new version in parallel with the
376 old version. In that case you can complete the installation
377 normally and transfer the data later. This will also decrease
384 If you are installing the new version at the same location as the
385 old one then shut down the old server, at the latest before you
386 install the new files:
388 <userinput>kill -INT `cat /usr/local/pgsql/data/postmaster.pid | sed 1q`</>
390 Versions prior to 7.0 do not have this
391 <filename>postmaster.pid</> file. If you are using such a version
392 you must find out the process ID of the server yourself, for
393 example by typing <userinput>ps ax | grep postmaster</>, and
394 supply it to the <command>kill</> command.
398 On systems that have <productname>PostgreSQL</> started at boot time, there is
399 probably a start-up file that will accomplish the same thing. For
400 example, on a <systemitem class="osname">Red Hat Linux</> system one might find that
402 <userinput>/etc/rc.d/init.d/postgresql stop</userinput>
404 works. Another possibility is <userinput>pg_ctl stop</>.
410 If you are installing in the same place as the old version then
411 it is also a good idea to move the old installation out of the
412 way, in case you have trouble and need to revert to it.
413 Use a command like this:
415 <userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>
422 After you have installed <productname>PostgreSQL</> &version;, create a new database
423 directory and start the new server. Remember that you must execute
424 these commands while logged in to the special database user account
425 (which you already have if you are upgrading).
427 <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
428 <userinput>/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data</>
430 Finally, restore your data with
432 <userinput>/usr/local/pgsql/bin/psql -d template1 -f <replaceable>outputfile</></userinput>
434 using the <emphasis>new</> <application>psql</>.
438 These topics are discussed at length in <![%standalone-include[the
439 documentation,]]> <![%standalone-ignore[<xref
440 linkend="migration">,]]> which you are encouraged to read in any
446 <sect1 id="install-procedure">
447 <title>Installation Procedure</title>
451 <step id="configure">
452 <title>Configuration</>
454 <indexterm zone="configure">
455 <primary>configure</primary>
459 The first step of the installation procedure is to configure the
460 source tree for your system and choose the options you would like.
461 This is done by running the <filename>configure</> script. For a
462 default installation simply enter
464 <userinput>./configure</userinput>
466 This script will run a number of tests to guess values for various
467 system dependent variables and detect some quirks of your
468 operating system, and finally will create several files in the
469 build tree to record what it found. (You can also run
470 <filename>configure</filename> in a directory outside the source
471 tree if you want to keep the build directory separate.)
475 The default configuration will build the server and utilities, as
476 well as all client applications and interfaces that require only a
477 C compiler. All files will be installed under
478 <filename>/usr/local/pgsql</> by default.
482 You can customize the build and installation process by supplying one
483 or more of the following command line options to
484 <filename>configure</filename>:
488 <term><option>--prefix=<replaceable>PREFIX</></option></term>
491 Install all files under the directory <replaceable>PREFIX</>
492 instead of <filename>/usr/local/pgsql</filename>. The actual
493 files will be installed into various subdirectories; no files
494 will ever be installed directly into the
495 <replaceable>PREFIX</> directory.
499 If you have special needs, you can also customize the
500 individual subdirectories with the following options. However,
501 if you leave these with their defaults, the installation will be
502 relocatable, meaning you can move the directory after
503 installation. (The <literal>man</> and <literal>doc</>
504 locations are not affected by this.)
508 For relocatable installs, you might want to use
509 <filename>configure</filename>'s <literal>--disable-rpath</>
510 option. Also, you will need to tell the operating system how
511 to find the shared libraries.
516 <term><option>--exec-prefix=<replaceable>EXEC-PREFIX</></option></term>
519 You can install architecture-dependent files under a
520 different prefix, <replaceable>EXEC-PREFIX</>, than what
521 <replaceable>PREFIX</> was set to. This can be useful to
522 share architecture-independent files between hosts. If you
523 omit this, then <replaceable>EXEC-PREFIX</> is set equal to
524 <replaceable>PREFIX</> and both architecture-dependent and
525 independent files will be installed under the same tree,
526 which is probably what you want.
532 <term><option>--bindir=<replaceable>DIRECTORY</></option></term>
535 Specifies the directory for executable programs. The default
536 is <filename><replaceable>EXEC-PREFIX</>/bin</>, which
537 normally means <filename>/usr/local/pgsql/bin</>.
543 <term><option>--datadir=<replaceable>DIRECTORY</></option></term>
546 Sets the directory for read-only data files used by the
547 installed programs. The default is
548 <filename><replaceable>PREFIX</>/share</>. Note that this has
549 nothing to do with where your database files will be placed.
555 <term><option>--sysconfdir=<replaceable>DIRECTORY</></option></term>
558 The directory for various configuration files,
559 <filename><replaceable>PREFIX</>/etc</> by default.
565 <term><option>--libdir=<replaceable>DIRECTORY</></option></term>
568 The location to install libraries and dynamically loadable
569 modules. The default is
570 <filename><replaceable>EXEC-PREFIX</>/lib</>.
576 <term><option>--includedir=<replaceable>DIRECTORY</></option></term>
579 The directory for installing C and C++ header files. The
580 default is <filename><replaceable>PREFIX</>/include</>.
586 <term><option>--mandir=<replaceable>DIRECTORY</></option></term>
589 The man pages that come with <productname>PostgreSQL</> will be installed under
590 this directory, in their respective
591 <filename>man<replaceable>x</></> subdirectories.
592 The default is <filename><replaceable>PREFIX</>/man</>.
598 <term><option>--with-docdir=<replaceable>DIRECTORY</></option></term>
599 <term><option>--without-docdir</option></term>
602 Documentation files, except <quote>man</> pages, will be
603 installed into this directory. The default is
604 <filename><replaceable>PREFIX</>/doc</>. If the option
605 <option>--without-docdir</option> is specified, the
606 documentation will not be installed by <command>make
607 install</command>. This is intended for packaging scripts
608 that have special methods for installing documentation.
616 Care has been taken to make it possible to install
617 <productname>PostgreSQL</> into shared installation locations
618 (such as <filename>/usr/local/include</filename>) without
619 interfering with the namespace of the rest of the system. First,
620 the string <quote><literal>/postgresql</literal></quote> is
621 automatically appended to <varname>datadir</varname>,
622 <varname>sysconfdir</varname>, and <varname>docdir</varname>,
623 unless the fully expanded directory name already contains the
624 string <quote><literal>postgres</></quote> or
625 <quote><literal>pgsql</></quote>. For example, if you choose
626 <filename>/usr/local</filename> as prefix, the documentation will
627 be installed in <filename>/usr/local/doc/postgresql</filename>,
628 but if the prefix is <filename>/opt/postgres</filename>, then it
629 will be in <filename>/opt/postgres/doc</filename>. The public C
630 header files of the client interfaces are installed into
631 <varname>includedir</varname> and are namespace-clean. The
632 internal header files and the server header files are installed
633 into private directories under <varname>includedir</varname>. See
634 the documentation of each interface for information about how to
635 get at the its header files. Finally, a private subdirectory will
636 also be created, if appropriate, under <varname>libdir</varname>
637 for dynamically loadable modules.
645 <term><option>--with-includes=<replaceable>DIRECTORIES</></option></term>
648 <replaceable>DIRECTORIES</> is a colon-separated list of
649 directories that will be added to the list the compiler
650 searches for header files. If you have optional packages
651 (such as GNU <application>Readline</>) installed in a non-standard
653 you have to use this option and probably also the corresponding
654 <option>--with-libraries</> option.
657 Example: <literal>--with-includes=/opt/gnu/include:/usr/sup/include</>.
663 <term><option>--with-libraries=<replaceable>DIRECTORIES</></option></term>
666 <replaceable>DIRECTORIES</> is a colon-separated list of
667 directories to search for libraries. You will probably have
668 to use this option (and the corresponding
669 <option>--with-includes</> option) if you have packages
670 installed in non-standard locations.
673 Example: <literal>--with-libraries=/opt/gnu/lib:/usr/sup/lib</>.
679 <term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term>
682 Enables Native Language Support (<acronym>NLS</acronym>),
683 that is, the ability to display a program's messages in a
684 language other than English.
685 <replaceable>LANGUAGES</replaceable> is a space separated
686 list of codes of the languages that you want supported, for
687 example <literal>--enable-nls='de fr'</>. (The intersection
688 between your list and the set of actually provided
689 translations will be computed automatically.) If you do not
690 specify a list, then all available translations are
695 To use this option, you will need an implementation of the
696 <application>Gettext</> API; see above.
702 <term><option>--with-pgport=<replaceable>NUMBER</></option></term>
705 Set <replaceable>NUMBER</> as the default port number for
706 server and clients. The default is 5432. The port can always
707 be changed later on, but if you specify it here then both
708 server and clients will have the same default compiled in,
709 which can be very convenient. Usually the only good reason
710 to select a non-default value is if you intend to run multiple
711 <productname>PostgreSQL</> servers on the same machine.
717 <term><option>--with-perl</option></term>
720 Build the PL/Perl server-side language.
726 <term><option>--with-python</option></term>
729 Build the PL/Python server-side language.
735 <term><option>--with-tcl</option></term>
738 Build <application>PL/Tcl</>, which requires Tcl/Tk
739 <option>--without-tk</>.
745 <term><option>--without-tk</option></term>
748 If you specify <option>--with-tcl</> and this option, then
749 the program that requires <productname>Tk</>
750 (<application>pgtksh</>) will be
757 <term><option>--with-tclconfig=<replaceable>DIRECTORY</replaceable></option></term>
758 <term><option>--with-tkconfig=<replaceable>DIRECTORY</replaceable></option></term>
761 Tcl/Tk installs the files <filename>tclConfig.sh</filename> and
762 <filename>tkConfig.sh</filename>, which contain
763 configuration information needed to build modules
764 interfacing to Tcl or Tk. These files are normally found
765 automatically at their well-known locations, but if you want to
766 use a different version of Tcl or Tk you can specify the
767 directory in which to find them.
773 <term><option>--with-krb4</option></term>
774 <term><option>--with-krb5</option></term>
777 Build with support for Kerberos authentication. You can use
778 either Kerberos version 4 or 5, but not both. On many
779 systems, the Kerberos system is not installed in a location
780 that is searched by default (e.g., <filename>/usr/include</>,
781 <filename>/usr/lib</>), so you must use the options
782 <option>--with-includes</> and <option>--with-libraries</> in
783 addition to this option. <filename>configure</> will check
784 for the required header files and libraries to make sure that
785 your Kerberos installation is sufficient before proceeding.
791 <term><option>--with-krb-srvnam=<replaceable>NAME</></option></term>
794 The name of the Kerberos service principal.
795 <literal>postgres</literal> is the default. There's probably no
796 reason to change this.
803 <primary>OpenSSL</primary>
804 <seealso>SSL</seealso>
807 <term><option>--with-openssl</option></term>
810 Build with support for <acronym>SSL</> (encrypted)
811 connections. This requires the <productname>OpenSSL</>
812 package to be installed. <filename>configure</> will check
813 for the required header files and libraries to make sure that
814 your <productname>OpenSSL</> installation is sufficient
821 <term><option>--with-pam</option></term>
824 Build with <acronym>PAM</><indexterm><primary>PAM</></>
825 (Pluggable Authentication Modules) support.
831 <term><option>--without-readline</option></term>
834 Prevents the use of the <application>Readline</> library. This disables
835 command-line editing and history in
836 <application>psql</application>, so it is not recommended.
842 <term><option>--with-rendezvous</option></term>
845 Build with Rendezvous support.
851 <term><option>--disable-spinlocks</option></term>
854 Allow the build to succeed even if <productname>PostgreSQL</>
855 has no CPU spinlock support for the platform. The lack of
856 spinlock support will result in poor performance; therefore,
857 this option should only be used if the build aborts and
858 informs you that the platform lacks spinlock support. If this
859 option is required to build <productname>PostgreSQL</> on
860 your platform, please report the problem to the
861 <productname>PostgreSQL</> developers.
867 <term><option>--enable-thread-safety</option></term>
870 Make the client libraries thread-safe. This allows
871 concurrent threads in <application>libpq</application> and
872 <application>ECPG</application> programs to safely control
873 their private connection handles.
879 <term><option>--without-zlib</option></term>
882 Prevents the use of the <application>Zlib</> library. This disables
883 compression support in <application>pg_dump</application>.
884 This option is only intended for those rare systems where this
885 library is not available.
891 <term><option>--enable-debug</option></term>
894 Compiles all programs and libraries with debugging symbols.
895 This means that you can run the programs through a debugger
896 to analyze problems. This enlarges the size of the installed
897 executables considerably, and on non-GCC compilers it usually
898 also disables compiler optimization, causing slowdowns. However,
899 having the symbols available is extremely helpful for dealing
900 with any problems that may arise. Currently, this option is
901 recommended for production installations only if you use GCC.
902 But you should always have it on if you are doing development work
903 or running a beta version.
909 <term><option>--enable-cassert</option></term>
912 Enables <firstterm>assertion</> checks in the server, which test for
913 many <quote>can't happen</> conditions. This is invaluable for
914 code development purposes, but the tests slow things down a little.
915 Also, having the tests turned on won't necessarily enhance the
916 stability of your server! The assertion checks are not categorized
917 for severity, and so what might be a relatively harmless bug will
918 still lead to server restarts if it triggers an assertion
919 failure. Currently, this option is not recommended for
920 production use, but you should have it on for development work
921 or when running a beta version.
927 <term><option>--enable-depend</option></term>
930 Enables automatic dependency tracking. With this option, the
931 makefiles are set up so that all affected object files will
932 be rebuilt when any header file is changed. This is useful
933 if you are doing development work, but is just wasted overhead
934 if you intend only to compile once and install. At present,
935 this option will work only if you use GCC.
944 If you prefer a C compiler different from the one
945 <filename>configure</filename> picks then you can set the
946 environment variable <envar>CC</> to the program of your choice.
947 By default, <filename>configure</filename> will pick
948 <filename>gcc</filename> unless this is inappropriate for the
949 platform. Similarly, you can override the default compiler flags
950 with the <envar>CFLAGS</envar> variable.
954 You can specify environment variables on the
955 <filename>configure</filename> command line, for example:
957 <userinput>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</>
966 To start the build, type
968 <userinput>gmake</userinput>
970 (Remember to use <acronym>GNU</> <application>make</>.) The build
971 may take anywhere from 5 minutes to half an hour depending on your
972 hardware. The last line displayed should be
974 All of PostgreSQL is successfully made. Ready to install.
980 <title>Regression Tests</title>
983 <primary>regression test</primary>
987 If you want to test the newly built server before you install it,
988 you can run the regression tests at this point. The regression
989 tests are a test suite to verify that <productname>PostgreSQL</>
990 runs on your machine in the way the developers expected it
993 <userinput>gmake check</userinput>
995 (This won't work as root; do it as an unprivileged user.)
996 <![%standalone-include[The file
997 <filename>src/test/regress/README</> and the
998 documentation contain]]>
999 <![%standalone-ignore[<xref linkend="regress"> contains]]>
1000 detailed information about interpreting the test results. You can
1001 repeat this test at any later time by issuing the same command.
1006 <title>Installing The Files</title>
1010 If you are upgrading an existing system and are going to install
1011 the new files over the old ones, then you should have backed up
1012 your data and shut down the old server by now, as explained in
1013 <xref linkend="install-upgrading"> above.
1018 To install <productname>PostgreSQL</> enter
1020 <userinput>gmake install</userinput>
1022 This will install files into the directories that were specified
1023 in <xref linkend="configure">. Make sure that you have appropriate
1024 permissions to write into that area. Normally you need to do this
1025 step as root. Alternatively, you could create the target
1026 directories in advance and arrange for appropriate permissions to
1031 You can use <literal>gmake install-strip</literal> instead of
1032 <literal>gmake install</literal> to strip the executable files and
1033 libraries as they are installed. This will save some space. If
1034 you built with debugging support, stripping will effectively
1035 remove the debugging support, so it should only be done if
1036 debugging is no longer needed. <literal>install-strip</literal>
1037 tries to do a reasonable job saving space, but it does not have
1038 perfect knowledge of how to strip every unneeded byte from an
1039 executable file, so if you want to save all the disk space you
1040 possibly can, you will have to do manual work.
1044 The standard installation provides only the header files needed for client
1045 application development. If you plan to do any server-side program
1046 development (such as custom functions or data types written in C),
1047 then you may want to install the entire <productname>PostgreSQL</>
1048 include tree into your target include directory. To do that, enter
1050 <userinput>gmake install-all-headers</userinput>
1052 This adds a megabyte or two to the installation footprint, and is only
1053 useful if you don't plan to keep the whole source tree around for
1054 reference. (If you do, you can just use the source's include
1055 directory when building server-side software.)
1059 <title>Client-only installation:</title>
1061 If you want to install only the client applications and
1062 interface libraries, then you can use these commands:
1064 <userinput>gmake -C src/bin install</>
1065 <userinput>gmake -C src/include install</>
1066 <userinput>gmake -C src/interfaces install</>
1067 <userinput>gmake -C doc install</>
1075 <title>Uninstallation:</title>
1077 To undo the installation use the command <command>gmake
1078 uninstall</>. However, this will not remove any created directories.
1083 <title>Cleaning:</title>
1086 After the installation you can make room by removing the built
1087 files from the source tree with the command <command>gmake
1088 clean</>. This will preserve the files made by the <command>configure</command>
1089 program, so that you can rebuild everything with <command>gmake</>
1090 later on. To reset the source tree to the state in which it was
1091 distributed, use <command>gmake distclean</>. If you are going to
1092 build for several platforms from the same source tree you must do
1093 this and re-configure for each build.
1098 If you perform a build and then discover that your <command>configure</>
1099 options were wrong, or if you change anything that <command>configure</>
1100 investigates (for example, software upgrades), then it's a good
1101 idea to do <command>gmake distclean</> before reconfiguring and
1102 rebuilding. Without this, your changes in configuration choices
1103 may not propagate everywhere they need to.
1107 <sect1 id="install-post">
1108 <title>Post-Installation Setup</title>
1111 <title>Shared Libraries</title>
1114 <primary>shared library</primary>
1118 On some systems that have shared libraries (which most systems do)
1119 you need to tell your system how to find the newly installed
1120 shared libraries. The systems on which this is
1121 <emphasis>not</emphasis> necessary include <systemitem
1122 class="osname">BSD/OS</>, <systemitem class="osname">FreeBSD</>,
1123 <systemitem class="osname">HP-UX</>, <systemitem
1124 class="osname">IRIX</>, <systemitem class="osname">Linux</>,
1125 <systemitem class="osname">NetBSD</>, <systemitem
1126 class="osname">OpenBSD</>, <systemitem class="osname">Tru64
1127 UNIX</> (formerly <systemitem class="osname">Digital UNIX</>), and
1128 <systemitem class="osname">Solaris</>.
1132 The method to set the shared library search path varies between
1133 platforms, but the most widely usable method is to set the
1134 environment variable <envar>LD_LIBRARY_PATH</> like so: In Bourne
1135 shells (<command>sh</>, <command>ksh</>, <command>bash</>, <command>zsh</>)
1137 LD_LIBRARY_PATH=/usr/local/pgsql/lib
1138 export LD_LIBRARY_PATH
1140 or in <command>csh</> or <command>tcsh</>
1142 setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
1144 Replace <literal>/usr/local/pgsql/lib</> with whatever you set
1145 <option><literal>--libdir</></> to in <xref linkend="configure">.
1146 You should put these commands into a shell start-up file such as
1147 <filename>/etc/profile</> or <filename>~/.bash_profile</>. Some
1148 good information about the caveats associated with this method can
1150 url="http://www.visi.com/~barr/ldpath.html"></ulink>.
1154 On some systems it might be preferable to set the environment
1155 variable <envar>LD_RUN_PATH</envar> <emphasis>before</emphasis>
1160 On <systemitem class="osname">Cygwin</systemitem>, put the library
1161 directory in the <envar>PATH</envar> or move the
1162 <filename>.dll</filename> files into the <filename>bin</filename>
1167 If in doubt, refer to the manual pages of your system (perhaps
1168 <command>ld.so</command> or <command>rld</command>). If you later
1169 on get a message like
1171 psql: error in loading shared libraries
1172 libpq.so.2.1: cannot open shared object file: No such file or directory
1174 then this step was necessary. Simply take care of it then.
1179 <primary>ldconfig</primary>
1181 If you are on <systemitem class="osname">BSD/OS</>, <systemitem
1182 class="osname">Linux</>, or <systemitem class="osname">SunOS 4</>
1183 and you have root access you can run
1185 /sbin/ldconfig /usr/local/pgsql/lib
1187 (or equivalent directory) after installation to enable the
1188 run-time linker to find the shared libraries faster. Refer to the
1189 manual page of <command>ldconfig</> for more information. On
1190 <systemitem class="osname">FreeBSD</>, <systemitem
1191 class="osname">NetBSD</>, and <systemitem
1192 class="osname">OpenBSD</> the command is
1194 /sbin/ldconfig -m /usr/local/pgsql/lib
1196 instead. Other systems are not known to have an equivalent
1202 <title>Environment Variables</title>
1205 <primary><envar>PATH</envar></primary>
1209 If you installed into <filename>/usr/local/pgsql</> or some other
1210 location that is not searched for programs by default, you should
1211 add <filename>/usr/local/pgsql/bin</> (or whatever you set
1212 <option><literal>--bindir</></> to in <xref linkend="configure">)
1213 into your <envar>PATH</>. Strictly speaking, this is not
1214 necessary, but it will make the use of <productname>PostgreSQL</>
1215 much more convenient.
1219 To do this, add the following to your shell start-up file, such as
1220 <filename>~/.bash_profile</> (or <filename>/etc/profile</>, if you
1221 want it to affect every user):
1223 PATH=/usr/local/pgsql/bin:$PATH
1226 If you are using <command>csh</> or <command>tcsh</>, then use this command:
1228 set path = ( /usr/local/pgsql/bin $path )
1234 <primary><envar>MANPATH</envar></primary>
1236 To enable your system to find the <application>man</>
1237 documentation, you need to add lines like the following to a
1238 shell start-up file unless you installed into a location that is
1239 searched by default.
1241 MANPATH=/usr/local/pgsql/man:$MANPATH
1247 The environment variables <envar>PGHOST</> and <envar>PGPORT</>
1248 specify to client applications the host and port of the database
1249 server, overriding the compiled-in defaults. If you are going to
1250 run client applications remotely then it is convenient if every
1251 user that plans to use the database sets <envar>PGHOST</>. This
1252 is not required, however: the settings can be communicated via command
1253 line options to most client programs.
1259 <![%standalone-include;[
1260 <sect1 id="install-getting-started">
1261 <title>Getting Started</title>
1264 The following is a quick summary of how to get <productname>PostgreSQL</> up and
1265 running once installed. The main documentation contains more information.
1271 Create a user account for the <productname>PostgreSQL</>
1272 server. This is the user the server will run as. For production
1273 use you should create a separate, unprivileged account
1274 (<quote>postgres</> is commonly used). If you do not have root
1275 access or just want to play around, your own user account is
1276 enough, but running the server as root is a security risk and
1279 <userinput>adduser postgres</>
1286 Create a database installation with the <command>initdb</>
1287 command. To run <command>initdb</> you must be logged in to your
1288 <productname>PostgreSQL</> server account. It will not work as
1291 root# <userinput>mkdir /usr/local/pgsql/data</>
1292 root# <userinput>chown postgres /usr/local/pgsql/data</>
1293 root# <userinput>su - postgres</>
1294 postgres$ <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
1299 The <option>-D</> option specifies the location where the data
1300 will be stored. You can use any path you want, it does not have
1301 to be under the installation directory. Just make sure that the
1302 server account can write to the directory (or create it, if it
1303 doesn't already exist) before starting <command>initdb</>, as
1310 The previous step should have told you how to start up the
1311 database server. Do so now. The command should look something
1314 /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
1316 This will start the server in the foreground. To put the server
1317 in the background use something like
1319 nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
1320 </dev/null >>server.log 2>&1 </dev/null &
1325 To stop a server running in the background you can type
1327 kill `cat /usr/local/pgsql/data/postmaster.pid`
1332 In order to allow TCP/IP connections (rather than only Unix
1333 domain socket ones) you need to pass the <option>-i</> option to
1334 <filename>postmaster</>.
1342 <userinput>createdb testdb</>
1346 <userinput>psql testdb</>
1348 to connect to that database. At the prompt you can enter SQL
1349 commands and start experimenting.
1355 <sect1 id="install-whatnow">
1356 <title>What Now?</title>
1362 The <productname>PostgreSQL</> distribution contains a
1363 comprehensive documentation set, which you should read sometime.
1364 After installation, the documentation can be accessed by
1365 pointing your browser to
1366 <filename>/usr/local/pgsql/doc/html/index.html</>, unless you
1367 changed the installation directories.
1371 The first few chapters of the main documentation are the Tutorial,
1372 which should be your first reading if you are completely new to
1373 <acronym>SQL</> databases. If you are familiar with database
1374 concepts then you want to proceed with part on server
1375 administration, which contains information about how to set up
1376 the database server, database users, and authentication.
1382 Usually, you will want to modify your computer so that it will
1383 automatically start the database server whenever it boots. Some
1384 suggestions for this are in the documentation.
1390 Run the regression tests against the installed server (using
1391 <command>gmake installcheck</command>). If you didn't run the
1392 tests before installation, you should definitely do it now. This
1393 is also explained in the documentation.
1399 By default, <productname>PostgreSQL</> is configured to run on
1400 minimal hardware. This allows it to start up with almost any
1401 hardware configuration. The default configuration is, however,
1402 not designed for optimum performance. To achieve optimum
1403 performance, several server parameters must be adjusted, the two
1404 most common being <varname>shared_buffers</varname> and
1405 <varname>work_mem</varname>.
1406 Other parameters mentioned in the documentation also affect
1416 <sect1 id="supported-platforms">
1417 <title>Supported Platforms</title>
1420 <productname>PostgreSQL</> has been verified by the developer
1421 community to work on the platforms listed below. A supported
1422 platform generally means that <productname>PostgreSQL</> builds and
1423 installs according to these instructions and that the regression
1429 If you are having problems with the installation on a supported
1430 platform, please write to <email>pgsql-bugs@postgresql.org</email>
1431 or <email>pgsql-ports@postgresql.org</email>, not to the people
1440 <entry><acronym>OS</acronym></entry>
1441 <entry>Processor</entry>
1442 <entry>Version</entry>
1443 <entry>Reported</entry>
1444 <entry>Remarks</entry>
1449 <entry><systemitem class="osname">AIX</></entry>
1450 <entry><systemitem>RS6000</></entry>
1453 Hans-Jürgen Schönig (<email>hs@cybertec.at</email>)</entry>
1454 <entry>see also <filename>doc/FAQ_AIX</filename></entry>
1457 <entry><systemitem class="osname">BSD/OS</></entry>
1458 <entry><systemitem>x86</></entry>
1461 Bruce Momjian (<email>pgman@candle.pha.pa.us</email>)</entry>
1465 <entry><systemitem class="osname">FreeBSD</></entry>
1466 <entry><systemitem>Alpha</></entry>
1469 Peter Eisentraut (<email>peter_e@gmx.net</email>)</entry>
1473 <entry><systemitem class="osname">FreeBSD</></entry>
1474 <entry><systemitem>x86</></entry>
1477 Peter Eisentraut (<email>peter_e@gmx.net</email>)</entry>
1481 <entry><systemitem class="osname">HP-UX</></entry>
1482 <entry><systemitem>PA-RISC</></entry>
1485 2003-10-31, 10.20, Tom Lane (<email>tgl@sss.pgh.pa.us</email>);
1486 2003-11-04, 11.00, Peter Eisentraut (<email>peter_e@gmx.net</email>)
1488 <entry><command>gcc</> and <command>cc</>; see also <filename>doc/FAQ_HPUX</filename></entry>
1491 <entry><systemitem class="osname">IRIX</></entry>
1492 <entry><systemitem>MIPS</></entry>
1495 Robert E. Bruccoleri (<email>bruc@stone.congenomics.com</email>)</entry>
1496 <entry>6.5.20, <command>cc</command> only</entry>
1499 <entry><systemitem class="osname">Linux</></entry>
1500 <entry><systemitem>Alpha</></entry>
1503 Noèl Köthe (<email>noel@debian.org</email>)</entry>
1507 <entry><systemitem class="osname">Linux</></entry>
1508 <entry><systemitem>arm41</></entry>
1511 Noèl Köthe (<email>noel@debian.org</email>)</entry>
1515 <entry><systemitem class="osname">Linux</></entry>
1516 <entry><systemitem>Itanium</></entry>
1519 Noèl Köthe (<email>noel@debian.org</email>)</entry>
1523 <entry><systemitem class="osname">Linux</></entry>
1524 <entry><systemitem>m68k</></entry>
1527 Noèl Köthe (<email>noel@debian.org</email>)</entry>
1531 <entry><systemitem class="osname">Linux</></entry>
1532 <entry><systemitem>MIPS</></entry>
1535 Noèl Köthe (<email>noel@debian.org</email>)</entry>
1539 <entry><systemitem class="osname">Linux</></entry>
1540 <entry><systemitem>Opteron</></entry>
1543 Jani Averbach (<email>jaa@cc.jyu.fi</email>)</entry>
1547 <entry><systemitem class="osname">Linux</></entry>
1548 <entry><systemitem>PPC</></entry>
1551 Noèl Köthe (<email>noel@debian.org</email>)</entry>
1555 <entry><systemitem class="osname">Linux</></entry>
1556 <entry><systemitem>S/390</></entry>
1559 Noèl Köthe (<email>noel@debian.org</email>)</entry>
1563 <entry><systemitem class="osname">Linux</></entry>
1564 <entry><systemitem>Sparc</></entry>
1567 Peter Eisentraut (<email>peter_e@gmx.net</email>)</entry>
1568 <entry>2.4, 32-bit</entry>
1571 <entry><systemitem class="osname">Linux</></entry>
1572 <entry><systemitem>x86</></entry>
1575 Peter Eisentraut (<email>peter_e@gmx.net</email>)</entry>
1579 <entry><systemitem class="osname">Mac OS X</></entry>
1580 <entry><systemitem>PPC</></entry>
1583 10.2.8, Adam Witney (<email>awitney@sghms.ac.uk</email>),
1584 10.3, Marko Karppinen (<email>marko@karppinen.fi</email>)</entry>
1588 <entry><systemitem class="osname">NetBSD</></entry>
1589 <entry><systemitem>arm32</></entry>
1592 Patrick Welche (<email>prlw1@newn.cam.ac.uk</email>)</entry>
1593 <entry>1.6ZE/acorn32</entry>
1596 <entry><systemitem class="osname">NetBSD</></entry>
1597 <entry><systemitem>Sparc</></entry>
1598 <entry>7.4.1</entry>
1600 Peter Eisentraut (<email>peter_e@gmx.net</email>)</entry>
1601 <entry>1.6.1, 32-bit</entry>
1604 <entry><systemitem class="osname">NetBSD</></entry>
1605 <entry><systemitem>x86</></entry>
1608 Peter Eisentraut (<email>peter_e@gmx.net</email>)</entry>
1612 <entry><systemitem class="osname">OpenBSD</></entry>
1613 <entry><systemitem>Sparc</></entry>
1616 Peter Eisentraut (<email>peter_e@gmx.net</email>)</entry>
1620 <entry><systemitem class="osname">OpenBSD</></entry>
1621 <entry><systemitem>x86</></entry>
1624 Peter Eisentraut (<email>peter_e@gmx.net</email>)</entry>
1628 <entry><systemitem class="osname">Solaris</></entry>
1629 <entry><systemitem>Sparc</></entry>
1632 Christopher Browne (<email>cbbrowne@libertyrms.info</email>)</entry>
1633 <entry>2.8; see also <filename>doc/FAQ_Solaris</filename></entry>
1636 <entry><systemitem class="osname">Solaris</></entry>
1637 <entry><systemitem>x86</></entry>
1640 Kurt Roeckx (<email>Q@ping.be</email>)</entry>
1641 <entry>2.6; see also <filename>doc/FAQ_Solaris</filename></entry>
1644 <entry><systemitem class="osname">Tru64 UNIX</></entry>
1645 <entry><systemitem>Alpha</></entry>
1647 <entry>2003-10-25, 5.1b, Peter Eisentraut (<email>peter_e@gmx.net</email>);
1648 2003-10-29, 4.0g, Alessio Bragadini (<email>alessio@albourne.com</email>)</entry>
1652 <entry><systemitem class="osname">UnixWare</></entry>
1653 <entry><systemitem>x86</></entry>
1655 <entry>2003-11-03, Larry Rosenman (<email>ler@lerctr.org</email>)</entry>
1656 <entry>7.1.3; join test may fail, see also <filename>doc/FAQ_SCO</filename></entry>
1659 <entry><systemitem class="osname">Windows with <application>Cygwin</application></></entry>
1660 <entry><systemitem>x86</></entry>
1663 Peter Eisentraut (<email>peter_e@gmx.net</email>)</entry>
1664 <entry>see <filename>doc/FAQ_MSWIN</filename></entry>
1667 <entry><systemitem class="osname">Windows</></entry>
1668 <entry><systemitem>x86</></entry>
1671 Dave Page (<email>dpage@vale-housing.co.uk</email>)</entry>
1673 native is client-side only,
1674 <![%standalone-include[see documentation]]>
1675 <![%standalone-ignore[see <xref linkend="install-win32">]]>
1683 <title>Unsupported Platforms:</title>
1685 The following platforms are either known not to work, or they used
1686 to work in a previous release and we did not receive explicit
1687 confirmation of a successful test with version &majorversion; at
1688 the time this list was compiled. We include these here to let you
1689 know that these platforms <emphasis>could</> be supported if given
1698 <entry><acronym>OS</acronym></entry>
1699 <entry>Processor</entry>
1700 <entry>Version</entry>
1701 <entry>Reported</entry>
1702 <entry>Remarks</entry>
1708 <entry><systemitem class="osname">BeOS</></entry>
1709 <entry><systemitem>x86</></entry>
1712 Cyril Velter (<email>cyril.velter@libertysurf.fr</email>)</entry>
1713 <entry>needs updates to semaphore code</entry>
1716 <entry><systemitem class="osname">Linux</></entry>
1717 <entry><systemitem>PlayStation 2</></entry>
1720 Peter Eisentraut (<email>peter_e@gmx.net</email>)</entry>
1722 needs new <filename>config.guess</filename>,
1723 <option>--disable-spinlocks</option>
1727 <entry><systemitem class="osname">Linux</></entry>
1728 <entry><systemitem>PA-RISC</></entry>
1731 Noèl Köthe (<email>noel@debian.org</email>)</entry>
1732 <entry>needs <option>--disable-spinlocks</option>, otherwise OK</entry>
1735 <entry><systemitem class="osname">NetBSD</></entry>
1736 <entry><systemitem>Alpha</></entry>
1739 Thomas Thai (<email>tom@minnesota.com</email>)</entry>
1743 <entry><systemitem class="osname">NetBSD</></entry>
1744 <entry><systemitem>MIPS</></entry>
1745 <entry>7.2.1</entry>
1747 Warwick Hunter (<email>whunter@agile.tv</email>)</entry>
1748 <entry>1.5.3</entry>
1751 <entry><systemitem class="osname">NetBSD</></entry>
1752 <entry><systemitem>PPC</></entry>
1755 Bill Studenmund (<email>wrstuden@netbsd.org</email>)</entry>
1759 <entry><systemitem class="osname">NetBSD</></entry>
1760 <entry><systemitem>VAX</></entry>
1763 Tom I. Helbekkmo (<email>tih@kpnQwest.no</email>)</entry>
1767 <entry><systemitem class="osname">QNX 4 RTOS</></entry>
1768 <entry><systemitem>x86</></entry>
1771 Bernd Tegge (<email>tegge@repas-aeg.de</email>)
1773 <entry>needs updates to semaphore code;
1774 see also <filename>doc/FAQ_QNX4</filename></entry>
1777 <entry><systemitem class="osname">QNX RTOS v6</></entry>
1778 <entry><systemitem>x86</></entry>
1780 <entry>2001-11-20, Igor Kovalenko (<email>Igor.Kovalenko@motorola.com</email>)</entry>
1781 <entry>patches available in archives, but too late for 7.2</entry>
1784 <entry><systemitem class="osname">SCO OpenServer</></entry>
1785 <entry><systemitem>x86</></entry>
1786 <entry>7.3.1</entry>
1788 Shibashish Satpathy (<email>shib@postmark.net</>)</entry>
1789 <entry>5.0.4, <command>gcc</>; see also <filename>doc/FAQ_SCO</filename></entry>
1792 <entry><systemitem class="osname">SunOS 4</></entry>
1793 <entry><systemitem>Sparc</></entry>
1795 <entry>2001-12-04, Tatsuo Ishii (<email>t-ishii@sra.co.jp</email>)</entry>
1805 <!-- Keep this comment at the end of the file
1810 sgml-minimize-attributes:nil
1811 sgml-always-quote-attributes:t
1813 sgml-indent-tabs-mode:nil
1815 sgml-parent-document:nil
1816 sgml-default-dtd-file:"./reference.ced"
1817 sgml-exposed-tags:nil
1818 sgml-local-catalogs:("/usr/share/sgml/catalog")
1819 sgml-local-ecat-files:nil