3
<chapter id="installation">
4
<title><![%standalone-include[<productname>PostgreSQL</>]]>
5
Installation from Source Code</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
15
distribution. (If you are installing a pre-packaged distribution,
16
such as an RPM or Debian package, ignore this
17
<![%standalone-include;[document]]>
18
<![%standalone-ignore;[chapter]]>
19
and read the packager's instructions instead.)
22
<sect1 id="install-short">
23
<title>Short Version</title>
32
mkdir /usr/local/pgsql/data
33
chown postgres /usr/local/pgsql/data
35
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
36
/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data >logfile 2>&1 &
37
/usr/local/pgsql/bin/createdb test
38
/usr/local/pgsql/bin/psql test
40
The long version is the rest of this
41
<![%standalone-include;[document.]]>
42
<![%standalone-ignore;[chapter.]]>
47
<sect1 id="install-requirements">
48
<title>Requirements</title>
51
In general, a modern Unix-compatible platform should be able to run
52
<productname>PostgreSQL</>.
53
The platforms that had received specific testing at the
54
time of release are listed in <xref linkend="supported-platforms">
55
below. In the <filename>doc</> subdirectory of the distribution
56
there are several platform-specific <acronym>FAQ</> documents you
57
might wish to consult if you are having trouble.
61
The following software packages are required for building
62
<productname>PostgreSQL</>:
68
<primary>make</primary>
71
<acronym>GNU</> <application>make</> is required; other
72
<application>make</> programs will <emphasis>not</> work.
73
<acronym>GNU</> <application>make</> is often installed under
74
the name <filename>gmake</filename>; this document will always
75
refer to it by that name. (On some systems
76
<acronym>GNU</acronym> <application>make</> is the default tool with the name
77
<filename>make</>.) To test for <acronym>GNU</acronym>
78
<application>make</application> enter
80
<userinput>gmake --version</userinput>
82
It is recommended to use version 3.76.1 or later.
88
You need an <acronym>ISO</>/<acronym>ANSI</> C compiler. Recent
89
versions of <productname>GCC</> are recommendable, but
90
<productname>PostgreSQL</> is known to build with a wide variety
91
of compilers from different vendors.
97
<application>tar</> is required to unpack the source
98
distribution in the first place, in addition to either
99
<application>gzip</> or <application>bzip2</>. In
100
addition, <application>gzip</> is required to install the
108
<primary>readline</primary>
111
<primary>libedit</primary>
114
The <acronym>GNU</> <productname>Readline</> library is used by
115
default. It allows <application>psql</application> (the
116
PostgreSQL command line SQL interpreter) to remember each
117
command you type, and allows you to use arrow keys to recall and
118
edit previous commands. This is very helpful and is strongly
119
recommended. If you don't want to use it then you must specify
120
the <option>--without-readline</option> option for
121
<filename>configure</>. As an alternative, you can often use the
122
BSD-licensed <filename>libedit</filename> library, originally
123
developed on <productname>NetBSD</productname>. The
124
<filename>libedit</filename> library is
125
GNU <productname>Readline</productname>-compatible and is used if
126
<filename>libreadline</filename> is not found, or if
127
<option>--with-libedit-preferred</option> is used as an
128
option to <filename>configure</>. If you are using a package-based
129
Linux distribution, be aware that you need both the
130
<literal>readline</> and <literal>readline-devel</> packages, if
131
those are separate in your distribution.
138
<primary>zlib</primary>
141
The <productname>zlib</productname> compression library will be
142
used by default. If you don't want to use it then you must
143
specify the <option>--without-zlib</option> option for
144
<filename>configure</filename>. Using this option disables
145
support for compressed archives in <application>pg_dump</> and
146
<application>pg_restore</>.
153
The following packages are optional. They are not required in the
154
default configuration, but they are needed when certain build
155
options are enabled, as explained below.
160
To build the server programming language
161
<application>PL/Perl</application> you need a full
162
<productname>Perl</productname> installation, including the
163
<filename>libperl</filename> library and the header files.
164
Since <application>PL/Perl</application> will be a shared
165
library, the <indexterm><primary>libperl</primary></indexterm>
166
<filename>libperl</filename> library must be a shared library
167
also on most platforms. This appears to be the default in
168
recent <productname>Perl</productname> versions, but it was not
169
in earlier versions, and in any case it is the choice of whomever
170
installed Perl at your site.
174
If you don't have the shared library but you need one, a message
175
like this will appear during the build to point out this fact:
177
*** Cannot build PL/Perl because libperl is not a shared library.
178
*** You might have to rebuild your Perl installation. Refer to
179
*** the documentation for details.
181
(If you don't follow the on-screen output you will merely notice
182
that the <application>PL/Perl</application> library object,
183
<filename>plperl.so</filename> or similar, will not be
184
installed.) If you see this, you will have to rebuild and
185
install <productname>Perl</productname> manually to be able to
186
build <application>PL/Perl</application>. During the
187
configuration process for <productname>Perl</productname>,
188
request a shared library.
194
To build the <application>PL/Python</> server programming
195
language, you need a <productname>Python</productname>
196
installation with the header files and the <application>distutils</application> module.
197
The <application>distutils</application> module is included by default with
198
<productname>Python</productname> 1.6 and later; users of
199
earlier versions of <productname>Python</productname> will need
204
Since <application>PL/Python</application> will be a shared
205
library, the <indexterm><primary>libpython</primary></indexterm>
206
<filename>libpython</filename> library must be a shared library
207
also on most platforms. This is not the case in a default
208
<productname>Python</productname> installation. If after
209
building and installing you have a file called
210
<filename>plpython.so</filename> (possibly a different
211
extension), then everything went well. Otherwise you should
212
have seen a notice like this flying by:
214
*** Cannot build PL/Python because libpython is not a shared library.
215
*** You might have to rebuild your Python installation. Refer to
216
*** the documentation for details.
218
That means you have to rebuild (part of) your
219
<productname>Python</productname> installation to supply this
224
If you have problems, run <productname>Python</> 2.3 or later's
225
configure using the <literal>--enable-shared</> flag. On some
226
operating systems you don't have to build a shared library, but
227
you will have to convince the <productname>PostgreSQL</> build
228
system of this. Consult the <filename>Makefile</filename> in
229
the <filename>src/pl/plpython</filename> directory for details.
235
If you want to build the <application>PL/Tcl</application>
236
procedural language, you of course need a <productname>Tcl</>
237
installation. If you are using a pre-8.4 release of
238
<productname>Tcl</>, ensure that it was built without multithreading
245
To enable Native Language Support (<acronym>NLS</acronym>), that
246
is, the ability to display a program's messages in a language
247
other than English, you need an implementation of the
248
<application>Gettext</> <acronym>API</acronym>. Some operating
249
systems have this built-in (e.g., <systemitem
250
class="osname">Linux</>, <systemitem class="osname">NetBSD</>,
251
<systemitem class="osname">Solaris</>), for other systems you
252
can download an add-on package from <ulink
253
url="http://developer.postgresql.org/~petere/bsd-gettext/"></ulink>.
254
If you are using the <application>Gettext</> implementation in
255
the <acronym>GNU</acronym> C library then you will additionally
256
need the <productname>GNU Gettext</productname> package for some
257
utility programs. For any of the other implementations you will
264
<application>Kerberos</>, <productname>OpenSSL</>,
265
<productname>OpenLDAP</>, and/or
266
<application>PAM</>, if you want to support authentication or
267
encryption using these services.
274
If you are building from a <acronym>CVS</acronym> tree instead of
275
using a released source package, or if you want to do development,
276
you also need the following packages:
282
<primary>flex</primary>
285
<primary>lex</primary>
288
<primary>bison</primary>
291
<primary>yacc</primary>
294
GNU <application>Flex</> and <application>Bison</>
295
are needed to build a CVS checkout or if you changed the actual
296
scanner and parser definition files. If you need them, be sure
297
to get <application>Flex</> 2.5.4 or later and
298
<application>Bison</> 1.875 or later. Other <application>lex</>
299
and <application>yacc</> programs cannot be used.
306
If you need to get a <acronym>GNU</acronym> package, you can find
307
it at your local <acronym>GNU</acronym> mirror site (see <ulink
308
url="http://www.gnu.org/order/ftp.html"></>
309
for a list) or at <ulink
310
url="ftp://ftp.gnu.org/gnu/"></ulink>.
314
Also check that you have sufficient disk space. You will need about
315
65 MB for the source tree during compilation and about 15 MB for
316
the installation directory. An empty database cluster takes about
317
25 MB, databases take about five times the amount of space that a
318
flat text file with the same data would take. If you are going to
319
run the regression tests you will temporarily need up to an extra
320
90 MB. Use the <command>df</command> command to check free disk
325
<![%standalone-ignore;[
326
<sect1 id="install-getsource">
327
<title>Getting The Source</title>
330
The <productname>PostgreSQL</> &version; sources can be obtained by
331
anonymous FTP from <ulink
332
url="ftp://ftp.postgresql.org/pub/source/v&version;/postgresql-&version;.tar.gz"></ulink>.
333
Other download options can be found on our website:
334
<ulink url="http://www.postgresql.org/download/"></ulink>. After you
335
have obtained the file, unpack it:
337
<userinput>gunzip postgresql-&version;.tar.gz</userinput>
338
<userinput>tar xf postgresql-&version;.tar</userinput>
340
This will create a directory
341
<filename>postgresql-&version;</filename> under the current directory
342
with the <productname>PostgreSQL</> sources.
343
Change into that directory for the rest
344
of the installation procedure.
349
<sect1 id="install-upgrading">
350
<title>Upgrading</title>
352
<indexterm zone="install-upgrading">
353
<primary>upgrading</primary>
357
These instructions assume that your existing installation is under the
358
<filename>/usr/local/pgsql</> directory, and that the data area is in
359
<filename>/usr/local/pgsql/data</>. Substitute your paths
364
The internal data storage format typically changes in every major
365
release of <productname>PostgreSQL</>. Therefore, if you are upgrading
366
an existing installation that does not have a version number of
367
<quote>&majorversion;.x</quote>, you must back up and restore your
368
data. If you are upgrading from <productname>PostgreSQL</>
369
<quote>&majorversion;.x</quote>, the new version can use your current
370
data files so you should skip the backup and restore steps below because
371
they are unnecessary.
377
If making a backup, make sure that your database is not being updated.
378
This does not affect the integrity of the backup, but the changed
379
data would of course not be included. If necessary, edit the
380
permissions in the file <filename>/usr/local/pgsql/data/pg_hba.conf</>
381
(or equivalent) to disallow access from everyone except you.
386
<primary>pg_dumpall</primary>
387
<secondary>use during upgrade</secondary>
390
To back up your database installation, type:
392
<userinput>pg_dumpall > <replaceable>outputfile</></userinput>
394
If you need to preserve OIDs (such as when using them as
395
foreign keys), then use the <option>-o</option> option when running
396
<application>pg_dumpall</>.
400
To make the backup, you can use the <application>pg_dumpall</application>
401
command from the version you are currently running. For best
402
results, however, try to use the <application>pg_dumpall</application>
403
command from <productname>PostgreSQL</productname> &version;,
404
since this version contains bug fixes and improvements over older
405
versions. While this advice might seem idiosyncratic since you
406
haven't installed the new version yet, it is advisable to follow
407
it if you plan to install the new version in parallel with the
408
old version. In that case you can complete the installation
409
normally and transfer the data later. This will also decrease
416
Shut down the old server:
418
<userinput>pg_ctl stop</>
420
On systems that have <productname>PostgreSQL</> started at boot time,
421
there is probably a start-up file that will accomplish the same thing. For
422
example, on a <systemitem class="osname">Red Hat Linux</> system one
425
<userinput>/etc/rc.d/init.d/postgresql stop</userinput>
433
If restoring from backup, rename or delete the old installation
434
directory. It is a good idea to rename the directory, rather than
435
delete it, in case you have trouble and need to revert to it. Keep
436
in mind the directory might consume significant disk space. To rename
437
the directory, use a command like this:
439
<userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>
446
Install the new version of <productname>PostgreSQL</productname> as
447
outlined in <![%standalone-include[the next section.]]>
448
<![%standalone-ignore[<xref linkend="install-procedure">.]]>
454
Create a new database cluster if needed. Remember that you must
455
execute these commands while logged in to the special database user
456
account (which you already have if you are upgrading).
458
<userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
465
Restore your previous <filename>pg_hba.conf</> and any
466
<filename>postgresql.conf</> modifications.
472
Start the database server, again from the special database user
475
<userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</>
482
Finally, restore your data from backup with
484
<userinput>/usr/local/pgsql/bin/psql -d postgres -f <replaceable>outputfile</></userinput>
486
using the <emphasis>new</> <application>psql</>.
492
Further discussion appears in
493
<![%standalone-include[the documentation,]]>
494
<![%standalone-ignore[<xref linkend="migration">,]]>
495
including instructions on how the previous installation can continue
496
running while the new installation is installed.
501
<sect1 id="install-procedure">
502
<title>Installation Procedure</title>
506
<step id="configure">
507
<title>Configuration</>
509
<indexterm zone="configure">
510
<primary>configure</primary>
514
The first step of the installation procedure is to configure the
515
source tree for your system and choose the options you would like.
516
This is done by running the <filename>configure</> script. For a
517
default installation simply enter
519
<userinput>./configure</userinput>
521
This script will run a number of tests to guess values for various
522
system dependent variables and detect some quirks of your
523
operating system, and finally will create several files in the
524
build tree to record what it found. (You can also run
525
<filename>configure</filename> in a directory outside the source
526
tree if you want to keep the build directory separate.)
530
The default configuration will build the server and utilities, as
531
well as all client applications and interfaces that require only a
532
C compiler. All files will be installed under
533
<filename>/usr/local/pgsql</> by default.
537
You can customize the build and installation process by supplying one
538
or more of the following command line options to
539
<filename>configure</filename>:
543
<term><option>--prefix=<replaceable>PREFIX</></option></term>
546
Install all files under the directory <replaceable>PREFIX</>
547
instead of <filename>/usr/local/pgsql</filename>. The actual
548
files will be installed into various subdirectories; no files
549
will ever be installed directly into the
550
<replaceable>PREFIX</> directory.
554
If you have special needs, you can also customize the
555
individual subdirectories with the following options. However,
556
if you leave these with their defaults, the installation will be
557
relocatable, meaning you can move the directory after
558
installation. (The <literal>man</> and <literal>doc</>
559
locations are not affected by this.)
563
For relocatable installs, you might want to use
564
<filename>configure</filename>'s <literal>--disable-rpath</>
565
option. Also, you will need to tell the operating system how
566
to find the shared libraries.
572
<term><option>--exec-prefix=<replaceable>EXEC-PREFIX</></option></term>
575
You can install architecture-dependent files under a
576
different prefix, <replaceable>EXEC-PREFIX</>, than what
577
<replaceable>PREFIX</> was set to. This can be useful to
578
share architecture-independent files between hosts. If you
579
omit this, then <replaceable>EXEC-PREFIX</> is set equal to
580
<replaceable>PREFIX</> and both architecture-dependent and
581
independent files will be installed under the same tree,
582
which is probably what you want.
588
<term><option>--bindir=<replaceable>DIRECTORY</></option></term>
591
Specifies the directory for executable programs. The default
592
is <filename><replaceable>EXEC-PREFIX</>/bin</>, which
593
normally means <filename>/usr/local/pgsql/bin</>.
599
<term><option>--sysconfdir=<replaceable>DIRECTORY</></option></term>
602
Sets the directory for various configuration files,
603
<filename><replaceable>PREFIX</>/etc</> by default.
609
<term><option>--libdir=<replaceable>DIRECTORY</></option></term>
612
Sets the location to install libraries and dynamically loadable
613
modules. The default is
614
<filename><replaceable>EXEC-PREFIX</>/lib</>.
620
<term><option>--includedir=<replaceable>DIRECTORY</></option></term>
623
Sets the directory for installing C and C++ header files. The
624
default is <filename><replaceable>PREFIX</>/include</>.
630
<term><option>--datarootdir=<replaceable>DIRECTORY</></option></term>
633
Sets the root directory for various types of read-only data
634
files. This only sets the default for some of the following
635
options. The default is
636
<filename><replaceable>PREFIX</>/share</>.
642
<term><option>--datadir=<replaceable>DIRECTORY</></option></term>
645
Sets the directory for read-only data files used by the
646
installed programs. The default is
647
<filename><replaceable>DATAROOTDIR</></>. Note that this has
648
nothing to do with where your database files will be placed.
654
<term><option>--localedir=<replaceable>DIRECTORY</></option></term>
657
Sets the directory for installing locale data, in particular
658
message translation catalog files. The default is
659
<filename><replaceable>DATAROOTDIR</>/locale</>.
665
<term><option>--mandir=<replaceable>DIRECTORY</></option></term>
668
The man pages that come with <productname>PostgreSQL</> will be installed under
669
this directory, in their respective
670
<filename>man<replaceable>x</></> subdirectories.
671
The default is <filename><replaceable>DATAROOTDIR</>/man</>.
677
<term><option>--docdir=<replaceable>DIRECTORY</></option></term>
680
Sets the root directory for installing documentation files,
681
except <quote>man</> pages. This only sets the default for
682
the following options. The default value for this option is
683
<filename><replaceable>DATAROOTDIR</>/doc/postgresql</>.
689
<term><option>--htmldir=<replaceable>DIRECTORY</></option></term>
692
The HTML-formatted documentation for
693
<productname>PostgreSQL</productname> will be installed under
694
this directory. The default is
695
<filename><replaceable>DATAROOTDIR</></>.
703
Care has been taken to make it possible to install
704
<productname>PostgreSQL</> into shared installation locations
705
(such as <filename>/usr/local/include</filename>) without
706
interfering with the namespace of the rest of the system. First,
707
the string <quote><literal>/postgresql</literal></quote> is
708
automatically appended to <varname>datadir</varname>,
709
<varname>sysconfdir</varname>, and <varname>docdir</varname>,
710
unless the fully expanded directory name already contains the
711
string <quote><literal>postgres</></quote> or
712
<quote><literal>pgsql</></quote>. For example, if you choose
713
<filename>/usr/local</filename> as prefix, the documentation will
714
be installed in <filename>/usr/local/doc/postgresql</filename>,
715
but if the prefix is <filename>/opt/postgres</filename>, then it
716
will be in <filename>/opt/postgres/doc</filename>. The public C
717
header files of the client interfaces are installed into
718
<varname>includedir</varname> and are namespace-clean. The
719
internal header files and the server header files are installed
720
into private directories under <varname>includedir</varname>. See
721
the documentation of each interface for information about how to
722
get at the its header files. Finally, a private subdirectory will
723
also be created, if appropriate, under <varname>libdir</varname>
724
for dynamically loadable modules.
732
<term><option>--with-includes=<replaceable>DIRECTORIES</></option></term>
735
<replaceable>DIRECTORIES</> is a colon-separated list of
736
directories that will be added to the list the compiler
737
searches for header files. If you have optional packages
738
(such as GNU <application>Readline</>) installed in a non-standard
740
you have to use this option and probably also the corresponding
741
<option>--with-libraries</> option.
744
Example: <literal>--with-includes=/opt/gnu/include:/usr/sup/include</>.
750
<term><option>--with-libraries=<replaceable>DIRECTORIES</></option></term>
753
<replaceable>DIRECTORIES</> is a colon-separated list of
754
directories to search for libraries. You will probably have
755
to use this option (and the corresponding
756
<option>--with-includes</> option) if you have packages
757
installed in non-standard locations.
760
Example: <literal>--with-libraries=/opt/gnu/lib:/usr/sup/lib</>.
766
<term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term>
769
Enables Native Language Support (<acronym>NLS</acronym>),
770
that is, the ability to display a program's messages in a
771
language other than English.
772
<replaceable>LANGUAGES</replaceable> is a space-separated
773
list of codes of the languages that you want supported, for
774
example <literal>--enable-nls='de fr'</>. (The intersection
775
between your list and the set of actually provided
776
translations will be computed automatically.) If you do not
777
specify a list, then all available translations are
782
To use this option, you will need an implementation of the
783
<application>Gettext</> API; see above.
789
<term><option>--with-pgport=<replaceable>NUMBER</></option></term>
792
Set <replaceable>NUMBER</> as the default port number for
793
server and clients. The default is 5432. The port can always
794
be changed later on, but if you specify it here then both
795
server and clients will have the same default compiled in,
796
which can be very convenient. Usually the only good reason
797
to select a non-default value is if you intend to run multiple
798
<productname>PostgreSQL</> servers on the same machine.
804
<term><option>--with-perl</option></term>
807
Build the <application>PL/Perl</> server-side language.
813
<term><option>--with-python</option></term>
816
Build the <application>PL/Python</> server-side language.
822
<term><option>--with-tcl</option></term>
825
Build the <application>PL/Tcl</> server-side language.
831
<term><option>--with-tclconfig=<replaceable>DIRECTORY</replaceable></option></term>
834
Tcl installs the file <filename>tclConfig.sh</filename>, which
835
contains configuration information needed to build modules
836
interfacing to Tcl. This file is normally found automatically
837
at a well-known location, but if you want to use a different
838
version of Tcl you can specify the directory in which to look
845
<term><option>--with-gssapi</option></term>
848
Build with support for GSSAPI authentication. On many
849
systems, the GSSAPI (usually a part of the Kerberos installation)
850
system is not installed in a location
851
that is searched by default (e.g., <filename>/usr/include</>,
852
<filename>/usr/lib</>), so you must use the options
853
<option>--with-includes</> and <option>--with-libraries</> in
854
addition to this option. <filename>configure</> will check
855
for the required header files and libraries to make sure that
856
your GSSAPI installation is sufficient before proceeding.
862
<term><option>--with-krb5</option></term>
865
Build with support for Kerberos 5 authentication. On many
866
systems, the Kerberos system is not installed in a location
867
that is searched by default (e.g., <filename>/usr/include</>,
868
<filename>/usr/lib</>), so you must use the options
869
<option>--with-includes</> and <option>--with-libraries</> in
870
addition to this option. <filename>configure</> will check
871
for the required header files and libraries to make sure that
872
your Kerberos installation is sufficient before proceeding.
878
<term><option>--with-krb-srvnam=<replaceable>NAME</></option></term>
881
The default name of the Kerberos service principal (also used
883
<literal>postgres</literal> is the default. There's usually no
884
reason to change this unless you have a Windows environment,
885
in which case it must be set to uppercase
886
<literal>POSTGRES</literal>.
893
<primary>OpenSSL</primary>
894
<seealso>SSL</seealso>
897
<term><option>--with-openssl</option></term>
900
Build with support for <acronym>SSL</> (encrypted)
901
connections. This requires the <productname>OpenSSL</>
902
package to be installed. <filename>configure</> will check
903
for the required header files and libraries to make sure that
904
your <productname>OpenSSL</> installation is sufficient
911
<term><option>--with-pam</option></term>
914
Build with <acronym>PAM</><indexterm><primary>PAM</></>
915
(Pluggable Authentication Modules) support.
921
<term><option>--with-ldap</option></term>
924
Build with <acronym>LDAP</><indexterm><primary>LDAP</></>
925
support for authentication and connection parameter lookup (see
926
<![%standalone-include[the documentation about client authentication
927
and libpq]]><![%standalone-ignore[<xref linkend="libpq-ldap"> and
928
<xref linkend="auth-ldap">]]> for more information). On Unix,
929
this requires the <productname>OpenLDAP</> package to be
930
installed. <filename>configure</> will check for the required
931
header files and libraries to make sure that your
932
<productname>OpenLDAP</> installation is sufficient before
933
proceeding. On Windows, the default <productname>WinLDAP</>
940
<term><option>--without-readline</option></term>
943
Prevents use of the <application>Readline</> library
944
(and <application>libedit</> as well). This option disables
945
command-line editing and history in
946
<application>psql</application>, so it is not recommended.
952
<term><option>--with-libedit-preferred</option></term>
955
Favors the use of the BSD-licensed <application>libedit</> library
956
rather than GPL-licensed <application>Readline</>. This option
957
is significant only if you have both libraries installed; the
958
default in that case is to use <application>Readline</>.
964
<term><option>--with-bonjour</option></term>
967
Build with Bonjour support. This requires Bonjour support
968
in your operating system. Recommended on Mac OS X.
974
<term><option>--with-ossp-uuid</option></term>
977
Use the <ulink url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID
978
library</ulink> when building <filename>contrib/uuid-ossp</>.
979
The library provides functions to generate
980
UUIDs.<indexterm><primary>UUID</primary></indexterm>
986
<term><option>--with-libxml</option></term>
989
Build with libxml (enables SQL/XML support). Libxml version 2.6.23 or
990
later is required for this feature.
994
Libxml installs a program <command>xml2-config</command> that
995
can be used to detect the required compiler and linker
996
options. PostgreSQL will use it automatically if found. To
997
specify a libxml installation at an unusual location, you can
998
either set the environment variable
999
<envar>XML2_CONFIG</envar> to point to the
1000
<command>xml2-config</command> program belonging to the
1001
installation, or use the options
1002
<option>--with-includes</option> and
1003
<option>--with-libraries</option>.
1009
<term><option>--with-libxslt</option></term>
1012
Use libxslt when building <filename>contrib/xml2</>.
1013
<filename>contrib/xml2</> relies on this library to perform
1014
XSL transformations of XML.
1020
<term><option>--disable-integer-datetimes</option></term>
1023
Disable support for 64-bit integer storage for timestamps and
1024
intervals, and store datetime values as floating-point
1025
numbers instead. Floating-point datetime storage was the
1026
default in <productname>PostgreSQL</productname> releases
1027
prior to 8.4, but it is now deprecated, because it does not
1028
support microsecond precision for the full range of
1029
<type>timestamp</type> values. However, integer-based
1030
datetime storage requires a 64-bit integer type. Therefore,
1031
this option can be used when no such type is available, or
1032
for compatibility with applications written for prior
1033
versions of <productname>PostgreSQL</productname>. See
1034
<![%standalone-include[the documentation about datetime datatypes]]>
1035
<![%standalone-ignore[<xref linkend="datatype-datetime">]]>
1036
for more information.
1042
<term><option>--disable-float4-byval</option></term>
1045
Disable passing float4 values <quote>by value</>, causing them
1046
to be passed <quote>by reference</> instead. This option costs
1047
performance, but may be needed for compatibility with old
1048
user-defined functions that are written in C and use the
1049
<quote>version 0</> calling convention. A better long-term
1050
solution is to update any such functions to use the
1051
<quote>version 1</> calling convention.
1057
<term><option>--disable-float8-byval</option></term>
1060
Disable passing float8 values <quote>by value</>, causing them
1061
to be passed <quote>by reference</> instead. This option costs
1062
performance, but may be needed for compatibility with old
1063
user-defined functions that are written in C and use the
1064
<quote>version 0</> calling convention. A better long-term
1065
solution is to update any such functions to use the
1066
<quote>version 1</> calling convention.
1067
Note that this option affects not only float8, but also int8 and some
1068
related types such as timestamp.
1069
On 32-bit platforms, <option>--disable-float8-byval</> is the default
1070
and it is not allowed to select <option>--enable-float8-byval</>.
1076
<term><option>--with-segsize=<replaceable>SEGSIZE</replaceable></option></term>
1079
Set the <firstterm>segment size</>, in gigabytes. Large tables are
1080
divided into multiple operating-system files, each of size equal
1081
to the segment size. This avoids problems with file size limits
1082
that exist on many platforms. The default segment size, 1 gigabyte,
1083
is safe on all supported platforms. If your operating system has
1084
<quote>largefile</> support (which most do, nowadays), you can use
1085
a larger segment size. This can be helpful to reduce the number of
1086
file descriptors consumed when working with very large tables.
1087
But be careful not to select a value larger than is supported
1088
by your platform and the filesystem(s) you intend to use. Other
1089
tools you might wish to use, such as <application>tar</>, could
1090
also set limits on the usable file size.
1091
It is recommended, though not absolutely required, that this value
1093
Note that changing this value requires an initdb.
1099
<term><option>--with-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
1102
Set the <firstterm>block size</>, in kilobytes. This is the unit
1103
of storage and I/O within tables. The default, 8 kilobytes,
1104
is suitable for most situations; but other values may be useful
1106
The value must be a power of 2 between 1 and 32 (kilobytes).
1107
Note that changing this value requires an initdb.
1113
<term><option>--with-wal-segsize=<replaceable>SEGSIZE</replaceable></option></term>
1116
Set the <firstterm>WAL segment size</>, in megabytes. This is
1117
the size of each individual file in the WAL log. It may be useful
1118
to adjust this size to control the granularity of WAL log shipping.
1119
The default size is 16 megabytes.
1120
The value must be a power of 2 between 1 and 64 (megabytes).
1121
Note that changing this value requires an initdb.
1127
<term><option>--with-wal-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
1130
Set the <firstterm>WAL block size</>, in kilobytes. This is the unit
1131
of storage and I/O within the WAL log. The default, 8 kilobytes,
1132
is suitable for most situations; but other values may be useful
1134
The value must be a power of 2 between 1 and 64 (kilobytes).
1135
Note that changing this value requires an initdb.
1141
<term><option>--disable-spinlocks</option></term>
1144
Allow the build to succeed even if <productname>PostgreSQL</>
1145
has no CPU spinlock support for the platform. The lack of
1146
spinlock support will result in poor performance; therefore,
1147
this option should only be used if the build aborts and
1148
informs you that the platform lacks spinlock support. If this
1149
option is required to build <productname>PostgreSQL</> on
1150
your platform, please report the problem to the
1151
<productname>PostgreSQL</> developers.
1157
<term><option>--enable-thread-safety</option></term>
1160
Make the client libraries thread-safe. This allows
1161
concurrent threads in <application>libpq</application> and
1162
<application>ECPG</application> programs to safely control
1163
their private connection handles. This option requires adequate
1164
threading support in your operating system.
1170
<term><option>--with-system-tzdata=<replaceable>DIRECTORY</replaceable></option></term>
1172
<primary>time zone data</primary>
1176
<productname>PostgreSQL</> includes its own time zone database,
1177
which it requires for date and time operations. This time zone
1178
database is in fact compatible with the <quote>zoneinfo</> time zone
1179
database provided by many operating systems such as FreeBSD,
1180
Linux, and Solaris, so it would be redundant to install it again.
1181
When this option is used, the system-supplied time zone database
1182
in <replaceable>DIRECTORY</replaceable> is used instead of the one
1183
included in the PostgreSQL source distribution.
1184
<replaceable>DIRECTORY</replaceable> must be specified as an
1185
absolute path. <filename>/usr/share/zoneinfo</filename> is a
1186
likely directory on some operating systems. Note that the
1187
installation routine will not detect mismatching or erroneous time
1188
zone data. If you use this option, you are advised to run the
1189
regression tests to verify that the time zone data you have
1190
pointed to works correctly with <productname>PostgreSQL</>.
1194
This option is mainly aimed at binary package distributors
1195
who know their target operating system well. The main
1196
advantage of using this option is that the PostgreSQL package
1197
won't need to be upgraded whenever any of the many local
1198
daylight-saving time rules change. Another advantage is that
1199
PostgreSQL can be cross-compiled<indexterm><primary>cross
1200
compilation</primary></indexterm> more straightforwardly if the
1201
time zone database files do not need to be built during the
1208
<term><option>--without-zlib</option></term>
1212
<primary>zlib</primary>
1214
Prevents use of the <application>Zlib</> library. This disables
1215
support for compressed archives in <application>pg_dump</application>
1216
and <application>pg_restore</application>.
1217
This option is only intended for those rare systems where this
1218
library is not available.
1224
<term><option>--enable-debug</option></term>
1227
Compiles all programs and libraries with debugging symbols.
1228
This means that you can run the programs through a debugger
1229
to analyze problems. This enlarges the size of the installed
1230
executables considerably, and on non-GCC compilers it usually
1231
also disables compiler optimization, causing slowdowns. However,
1232
having the symbols available is extremely helpful for dealing
1233
with any problems that might arise. Currently, this option is
1234
recommended for production installations only if you use GCC.
1235
But you should always have it on if you are doing development work
1236
or running a beta version.
1242
<term><option>--enable-coverage</option></term>
1245
If using GCC, all programs and libraries are compiled with
1246
code coverage testing instrumentation. When run, they
1247
generate files in the build directory with code coverage
1249
<![%standalone-ignore[See <xref linkend="regress-coverage">
1250
for more information.]]> This option is for use only with GCC
1251
and when doing development work.
1257
<term><option>--enable-profiling</option></term>
1260
If using GCC, all programs and libraries are compiled so they
1261
can be profiled. On backend exit, a subdirectory will be created
1262
that contains the <filename>gmon.out</> file for use in profiling.
1263
This option is for use only with GCC and when doing development work.
1269
<term><option>--enable-cassert</option></term>
1272
Enables <firstterm>assertion</> checks in the server, which test for
1273
many <quote>cannot happen</> conditions. This is invaluable for
1274
code development purposes, but the tests can slow down the
1275
server significantly.
1276
Also, having the tests turned on won't necessarily enhance the
1277
stability of your server! The assertion checks are not categorized
1278
for severity, and so what might be a relatively harmless bug will
1279
still lead to server restarts if it triggers an assertion
1280
failure. This option is not recommended for production use, but
1281
you should have it on for development work or when running a beta
1288
<term><option>--enable-depend</option></term>
1291
Enables automatic dependency tracking. With this option, the
1292
makefiles are set up so that all affected object files will
1293
be rebuilt when any header file is changed. This is useful
1294
if you are doing development work, but is just wasted overhead
1295
if you intend only to compile once and install. At present,
1296
this option will work only if you use GCC.
1302
<term><option>--enable-dtrace</option></term>
1306
<primary>DTrace</primary>
1308
Compiles <productname>PostgreSQL</productname> with support for the
1309
dynamic tracing tool DTrace.
1310
<![%standalone-ignore[See <xref linkend="dynamic-trace">
1311
for more information.]]>
1315
To point to the <command>dtrace</command> program, the
1316
environment variable <envar>DTRACE</envar> can be set. This
1317
will often be necessary because <command>dtrace</command> is
1318
typically installed under <filename>/usr/sbin</filename>,
1319
which might not be in the path.
1323
Extra command-line options for the <command>dtrace</command> program
1324
can be specified in the environment variable
1325
<envar>DTRACEFLAGS</envar>. On Solaris,
1326
to include DTrace support in a 64-bit binary, you must specify
1327
<literal>DTRACEFLAGS="-64"</> to configure. For example,
1328
using the GCC compiler:
1330
./configure CC='gcc -m64' --enable-dtrace DTRACEFLAGS='-64' ...
1332
Using Sun's compiler:
1334
./configure CC='/opt/SUNWspro/bin/cc -xtarget=native64' --enable-dtrace DTRACEFLAGS='-64' ...
1344
If you prefer a C compiler different from the one
1345
<filename>configure</filename> picks, you can set the
1346
environment variable <envar>CC</> to the program of your choice.
1347
By default, <filename>configure</filename> will pick
1348
<filename>gcc</filename> if available, else the platform's
1349
default (usually <filename>cc</>). Similarly, you can override the
1350
default compiler flags if needed with the <envar>CFLAGS</envar> variable.
1354
You can specify environment variables on the
1355
<filename>configure</filename> command line, for example:
1357
<userinput>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</>
1362
Here is a list of the significant variables that can be set in
1367
<term><envar>BISON</envar></term>
1376
<term><envar>CC</envar></term>
1385
<term><envar>CFLAGS</envar></term>
1388
options to pass to the C compiler
1394
<term><envar>CPP</envar></term>
1403
<term><envar>CPPFLAGS</envar></term>
1406
options to pass to the C preprocessor
1412
<term><envar>DTRACE</envar></term>
1415
location of the <command>dtrace</command> program
1421
<term><envar>DTRACEFLAGS</envar></term>
1424
options to pass to the <command>dtrace</command> program
1430
<term><envar>FLEX</envar></term>
1439
<term><envar>LDFLAGS</envar></term>
1442
options to pass to the link editor
1448
<term><envar>LDFLAGS_SL</envar></term>
1451
linker options for shared library linking
1457
<term><envar>MSGFMT</envar></term>
1460
<command>msgfmt</command> program for native language support
1466
<term><envar>PERL</envar></term>
1469
Full path to the Perl interpreter. This will be used to
1470
determine the dependencies for building PL/Perl.
1476
<term><envar>PYTHON</envar></term>
1479
Full path to the Python interpreter. This will be used to
1480
determine the dependencies for building PL/Python.
1486
<term><envar>TCLSH</envar></term>
1489
Full path to the Tcl interpreter. This will be used to
1490
determine the dependencies for building PL/Tcl, and it will
1491
be substituted into Tcl scripts.
1497
<term><envar>XML2_CONFIG</envar></term>
1500
<command>xml2-config</command> program used to locate the
1501
libxml installation.
1510
<title>Build</title>
1513
To start the build, type
1515
<userinput>gmake</userinput>
1517
(Remember to use <acronym>GNU</> <application>make</>.) The build
1518
will take a few minutes depending on your
1519
hardware. The last line displayed should be
1521
All of PostgreSQL is successfully made. Ready to install.
1527
<title>Regression Tests</title>
1530
<primary>regression test</primary>
1534
If you want to test the newly built server before you install it,
1535
you can run the regression tests at this point. The regression
1536
tests are a test suite to verify that <productname>PostgreSQL</>
1537
runs on your machine in the way the developers expected it
1540
<userinput>gmake check</userinput>
1542
(This won't work as root; do it as an unprivileged user.)
1543
<![%standalone-include[The file
1544
<filename>src/test/regress/README</> and the
1545
documentation contain]]>
1546
<![%standalone-ignore[<xref linkend="regress"> contains]]>
1547
detailed information about interpreting the test results. You can
1548
repeat this test at any later time by issuing the same command.
1553
<title>Installing The Files</title>
1557
If you are upgrading an existing system and are going to install
1558
the new files over the old ones, be sure to back up
1559
your data and shut down the old server before proceeding, as explained in
1560
<xref linkend="install-upgrading"> above.
1565
To install <productname>PostgreSQL</> enter
1567
<userinput>gmake install</userinput>
1569
This will install files into the directories that were specified
1570
in <xref linkend="configure">. Make sure that you have appropriate
1571
permissions to write into that area. Normally you need to do this
1572
step as root. Alternatively, you could create the target
1573
directories in advance and arrange for appropriate permissions to
1578
You can use <literal>gmake install-strip</literal> instead of
1579
<literal>gmake install</literal> to strip the executable files and
1580
libraries as they are installed. This will save some space. If
1581
you built with debugging support, stripping will effectively
1582
remove the debugging support, so it should only be done if
1583
debugging is no longer needed. <literal>install-strip</literal>
1584
tries to do a reasonable job saving space, but it does not have
1585
perfect knowledge of how to strip every unneeded byte from an
1586
executable file, so if you want to save all the disk space you
1587
possibly can, you will have to do manual work.
1591
The standard installation provides all the header files needed for client
1592
application development as well as for server-side program
1593
development, such as custom functions or data types written in C.
1594
(Prior to <productname>PostgreSQL</> 8.0, a separate <literal>gmake
1595
install-all-headers</> command was needed for the latter, but this
1596
step has been folded into the standard install.)
1600
<title>Client-only installation:</title>
1602
If you want to install only the client applications and
1603
interface libraries, then you can use these commands:
1605
<userinput>gmake -C src/bin install</>
1606
<userinput>gmake -C src/include install</>
1607
<userinput>gmake -C src/interfaces install</>
1608
<userinput>gmake -C doc install</>
1610
<filename>src/bin</> has a few binaries for server-only use,
1618
<title>Registering <application>eventlog</> on <systemitem
1619
class="osname">Windows</>:</title>
1621
To register a <systemitem class="osname">Windows</> <application>eventlog</>
1622
library with the operating system, issue this command after installation:
1624
<userinput>regsvr32 <replaceable>pgsql_library_directory</>/pgevent.dll</>
1626
This creates registry entries used by the event viewer.
1631
<title>Uninstallation:</title>
1633
To undo the installation use the command <command>gmake
1634
uninstall</>. However, this will not remove any created directories.
1639
<title>Cleaning:</title>
1642
After the installation you can make room by removing the built
1643
files from the source tree with the command <command>gmake
1644
clean</>. This will preserve the files made by the <command>configure</command>
1645
program, so that you can rebuild everything with <command>gmake</>
1646
later on. To reset the source tree to the state in which it was
1647
distributed, use <command>gmake distclean</>. If you are going to
1648
build for several platforms within the same source tree you must do
1649
this and re-configure for each build. (Alternatively, use
1650
a separate build tree for each platform, so that the source tree
1651
remains unmodified.)
1656
If you perform a build and then discover that your <command>configure</>
1657
options were wrong, or if you change anything that <command>configure</>
1658
investigates (for example, software upgrades), then it's a good
1659
idea to do <command>gmake distclean</> before reconfiguring and
1660
rebuilding. Without this, your changes in configuration choices
1661
might not propagate everywhere they need to.
1665
<sect1 id="install-post">
1666
<title>Post-Installation Setup</title>
1669
<title>Shared Libraries</title>
1672
<primary>shared library</primary>
1676
On some systems that have shared libraries (which most systems do)
1677
you need to tell your system how to find the newly installed
1678
shared libraries. The systems on which this is
1679
<emphasis>not</emphasis> necessary include <systemitem
1680
class="osname">BSD/OS</>, <systemitem class="osname">FreeBSD</>,
1681
<systemitem class="osname">HP-UX</>, <systemitem
1682
class="osname">IRIX</>, <systemitem class="osname">Linux</>,
1683
<systemitem class="osname">NetBSD</>, <systemitem
1684
class="osname">OpenBSD</>, <systemitem class="osname">Tru64
1685
UNIX</> (formerly <systemitem class="osname">Digital UNIX</>), and
1686
<systemitem class="osname">Solaris</>.
1690
The method to set the shared library search path varies between
1691
platforms, but the most widely usable method is to set the
1692
environment variable <envar>LD_LIBRARY_PATH</> like so: In Bourne
1693
shells (<command>sh</>, <command>ksh</>, <command>bash</>, <command>zsh</>):
1695
LD_LIBRARY_PATH=/usr/local/pgsql/lib
1696
export LD_LIBRARY_PATH
1698
or in <command>csh</> or <command>tcsh</>:
1700
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
1702
Replace <literal>/usr/local/pgsql/lib</> with whatever you set
1703
<option><literal>--libdir</></> to in <xref linkend="configure">.
1704
You should put these commands into a shell start-up file such as
1705
<filename>/etc/profile</> or <filename>~/.bash_profile</>. Some
1706
good information about the caveats associated with this method can
1708
url="http://www.visi.com/~barr/ldpath.html"></ulink>.
1712
On some systems it might be preferable to set the environment
1713
variable <envar>LD_RUN_PATH</envar> <emphasis>before</emphasis>
1718
On <systemitem class="osname">Cygwin</systemitem>, put the library
1719
directory in the <envar>PATH</envar> or move the
1720
<filename>.dll</filename> files into the <filename>bin</filename>
1725
If in doubt, refer to the manual pages of your system (perhaps
1726
<command>ld.so</command> or <command>rld</command>). If you later
1727
on get a message like
1729
psql: error in loading shared libraries
1730
libpq.so.2.1: cannot open shared object file: No such file or directory
1732
then this step was necessary. Simply take care of it then.
1737
<primary>ldconfig</primary>
1739
If you are on <systemitem class="osname">BSD/OS</>, <systemitem
1740
class="osname">Linux</>, or <systemitem class="osname">SunOS 4</>
1741
and you have root access you can run:
1743
/sbin/ldconfig /usr/local/pgsql/lib
1745
(or equivalent directory) after installation to enable the
1746
run-time linker to find the shared libraries faster. Refer to the
1747
manual page of <command>ldconfig</> for more information. On
1748
<systemitem class="osname">FreeBSD</>, <systemitem
1749
class="osname">NetBSD</>, and <systemitem
1750
class="osname">OpenBSD</> the command is:
1752
/sbin/ldconfig -m /usr/local/pgsql/lib
1754
instead. Other systems are not known to have an equivalent
1760
<title>Environment Variables</title>
1763
<primary><envar>PATH</envar></primary>
1767
If you installed into <filename>/usr/local/pgsql</> or some other
1768
location that is not searched for programs by default, you should
1769
add <filename>/usr/local/pgsql/bin</> (or whatever you set
1770
<option><literal>--bindir</></> to in <xref linkend="configure">)
1771
into your <envar>PATH</>. Strictly speaking, this is not
1772
necessary, but it will make the use of <productname>PostgreSQL</>
1773
much more convenient.
1777
To do this, add the following to your shell start-up file, such as
1778
<filename>~/.bash_profile</> (or <filename>/etc/profile</>, if you
1779
want it to affect every user):
1781
PATH=/usr/local/pgsql/bin:$PATH
1784
If you are using <command>csh</> or <command>tcsh</>, then use this command:
1786
set path = ( /usr/local/pgsql/bin $path )
1792
<primary><envar>MANPATH</envar></primary>
1794
To enable your system to find the <application>man</>
1795
documentation, you need to add lines like the following to a
1796
shell start-up file unless you installed into a location that is
1797
searched by default:
1799
MANPATH=/usr/local/pgsql/man:$MANPATH
1805
The environment variables <envar>PGHOST</> and <envar>PGPORT</>
1806
specify to client applications the host and port of the database
1807
server, overriding the compiled-in defaults. If you are going to
1808
run client applications remotely then it is convenient if every
1809
user that plans to use the database sets <envar>PGHOST</>. This
1810
is not required, however: the settings can be communicated via command
1811
line options to most client programs.
1817
<![%standalone-include;[
1818
<sect1 id="install-getting-started">
1819
<title>Getting Started</title>
1822
The following is a quick summary of how to get <productname>PostgreSQL</> up and
1823
running once installed. The main documentation contains more information.
1829
Create a user account for the <productname>PostgreSQL</>
1830
server. This is the user the server will run as. For production
1831
use you should create a separate, unprivileged account
1832
(<quote>postgres</> is commonly used). If you do not have root
1833
access or just want to play around, your own user account is
1834
enough, but running the server as root is a security risk and
1837
<userinput>adduser postgres</>
1844
Create a database installation with the <command>initdb</>
1845
command. To run <command>initdb</> you must be logged in to your
1846
<productname>PostgreSQL</> server account. It will not work as
1849
root# <userinput>mkdir /usr/local/pgsql/data</>
1850
root# <userinput>chown postgres /usr/local/pgsql/data</>
1851
root# <userinput>su - postgres</>
1852
postgres$ <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
1857
The <option>-D</> option specifies the location where the data
1858
will be stored. You can use any path you want, it does not have
1859
to be under the installation directory. Just make sure that the
1860
server account can write to the directory (or create it, if it
1861
doesn't already exist) before starting <command>initdb</>, as
1868
At this point, if you did not use the <command>initdb</> <literal>-A</>
1869
option, you might want to modify <filename>pg_hba.conf</> to control
1870
local access to the server before you start it. The default is to
1871
trust all local users.
1877
The previous <command>initdb</> step should have told you how to
1878
start up the database server. Do so now. The command should look
1881
/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
1883
This will start the server in the foreground. To put the server
1884
in the background use something like:
1886
nohup /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data \
1887
</dev/null >>server.log 2>&1 </dev/null &
1892
To stop a server running in the background you can type:
1894
kill `cat /usr/local/pgsql/data/postmaster.pid`
1903
<userinput>createdb testdb</>
1907
<userinput>psql testdb</>
1909
to connect to that database. At the prompt you can enter SQL
1910
commands and start experimenting.
1916
<sect1 id="install-whatnow">
1917
<title>What Now?</title>
1923
The <productname>PostgreSQL</> distribution contains a
1924
comprehensive documentation set, which you should read sometime.
1925
After installation, the documentation can be accessed by
1926
pointing your browser to
1927
<filename>/usr/local/pgsql/doc/html/index.html</>, unless you
1928
changed the installation directories.
1932
The first few chapters of the main documentation are the Tutorial,
1933
which should be your first reading if you are completely new to
1934
<acronym>SQL</> databases. If you are familiar with database
1935
concepts then you want to proceed with part on server
1936
administration, which contains information about how to set up
1937
the database server, database users, and authentication.
1943
Usually, you will want to modify your computer so that it will
1944
automatically start the database server whenever it boots. Some
1945
suggestions for this are in the documentation.
1951
Run the regression tests against the installed server (using
1952
<command>gmake installcheck</command>). If you didn't run the
1953
tests before installation, you should definitely do it now. This
1954
is also explained in the documentation.
1960
By default, <productname>PostgreSQL</> is configured to run on
1961
minimal hardware. This allows it to start up with almost any
1962
hardware configuration. The default configuration is, however,
1963
not designed for optimum performance. To achieve optimum
1964
performance, several server parameters must be adjusted, the two
1965
most common being <varname>shared_buffers</varname> and
1966
<varname>work_mem</varname>.
1967
Other parameters mentioned in the documentation also affect
1977
<sect1 id="supported-platforms">
1978
<title>Supported Platforms</title>
1981
A platform (that is, a CPU architecture and operating system combination)
1982
is considered supported by the <productname>PostgreSQL</> development
1983
community if the code contains provisions to work on that platform and
1984
it has recently been verified to build and pass its regression tests
1985
on that platform. Currently, most testing of platform compatibility
1986
is done automatically by test machines in the
1987
<ulink url="http://buildfarm.postgresql.org/">PostgreSQL Build Farm</ulink>.
1988
If you are interested in using <productname>PostgreSQL</> on a platform
1989
that is not represented in the build farm, but on which the code works
1990
or can be made to work, you are strongly encouraged to set up a build
1991
farm member machine so that continued compatibility can be assured.
1995
In general, <productname>PostgreSQL</> can be expected to work on
1996
these CPU architectures: x86, x86_64, IA64, PowerPC,
1997
PowerPC 64, S/390, S/390x, Sparc, Sparc 64, Alpha, ARM, MIPS, MIPSEL, M68K,
1998
and PA-RISC. Code support exists for M32R, NS32K, and VAX, but these
1999
architectures are not known to have been tested recently. It is often
2000
possible to build on an unsupported CPU type by configuring with
2001
<option>--disable-spinlocks</option>, but performance will be poor.
2005
<productname>PostgreSQL</> can be expected to work on these operating
2006
systems: Linux (all recent distributions), Windows (Win2000 SP4 and later),
2007
FreeBSD, OpenBSD, NetBSD, Mac OS X, AIX, HP/UX, IRIX, Solaris, Tru64 Unix,
2008
and UnixWare. Other Unix-like systems may also work but are not currently
2009
being tested. In most cases, all CPU architectures supported by
2010
a given operating system will work. Look in
2011
the <xref linkend="installation-platform-notes"> below to see if
2012
there is information
2013
specific to your operating system, particularly if using an older system.
2017
If you have installation problems on a platform that is known
2018
to be supported according to recent build farm results, please report
2019
it to <email>pgsql-bugs@postgresql.org</email>. If you are interested
2020
in porting <productname>PostgreSQL</> to a new platform,
2021
<email>pgsql-hackers@postgresql.org</email> is the appropriate place
2026
<sect1 id="installation-platform-notes">
2027
<title>Platform-Specific Notes</title>
2030
This section documents additional platform-specific issues
2031
regarding the installation and setup of PostgreSQL. Be sure to
2032
read the installation instructions, and in
2033
particular <xref linkend="install-requirements"> as well. Also,
2034
check <![%standalone-include[the
2035
file <filename>src/test/regress/README</> and the documentation]]>
2036
<![%standalone-ignore[<xref linkend="regress">]]> regarding the
2037
interpretation of regression test results.
2041
Platforms that are not covered here have no known platform-specific
2042
installation issues.
2045
<sect2 id="installation-notes-aix">
2048
<indexterm zone="installation-notes-aix">
2049
<primary>AIX</primary>
2050
<secondary>installation on</secondary>
2054
PostgreSQL on AIX works, but getting it installed properly can be
2055
challenging. Both AIX version 4.3 and 5.3 are supported in
2056
theory. You can use GCC or the native IBM compiler xlc. In
2057
general, using recent versions of AIX and PostgreSQL helps. Check
2058
the build farm for up to date information about which versions of
2059
AIX are known to work.
2063
Use the following <command>configure</command> flags in addition
2064
to your own if you have Readline or libz
2065
there: <literal>--with-includes=/usr/local/include
2066
--with-libraries=/usr/local/lib</literal>.
2070
If you don't have a PowerPC or use GCC you might see rounding
2071
differences in the geometry regression test. There will probably
2072
be warnings about 0.0/0.0 division and duplicate symbols which you
2077
Some of the AIX tools may be <quote>a little different</quote>
2078
from what you may be accustomed to on other platforms. If you are
2079
looking for a version of <command>ldd</command>, useful for
2080
determining what object code depends on what libraries, the
2081
following URLs may help you:
2082
<ulink url="http://www.faqs.org/faqs/aix-faq/part4/section-22.html"></ulink>,
2083
<ulink url="http://www.han.de/~jum/aix/ldd.c"></ulink>.
2087
<title>AIX 4.3.2</title>
2090
On AIX 4.3.2, you need <filename>libm.a</filename> that is in the
2091
fileset bos.adt.libm. Try the following command:
2093
$ lslpp -l bos.adt.libm
2099
<title>GCC issues</title>
2102
On AIX 5.3, there have been some problems getting PostgreSQL to
2103
compile and run using GCC.
2107
You will want to use a version of GCC subsequent to 3.3.2,
2108
particularly if you use a prepackaged version. We had good
2109
success with 4.0.1. Problems with earlier versions seem to have
2110
more to do with the way IBM packaged GCC than with actual issues
2111
with GCC, so that if you compile GCC yourself, you might well
2112
have success with an earlier version of GCC.
2117
<title>Unix-domain sockets broken</title>
2120
AIX 5.3 has a problem
2121
where <structname>sockadr_storage</structname> is not defined to
2122
be large enough. In version 5.3, IBM increased the size of
2123
<structname>sockaddr_un</structname>, the address structure for
2124
Unix-domain sockets, but did not correspondingly increase the
2125
size of <structname>sockadr_storage</structname>. The result of
2126
this is that attempts to use Unix-domain sockets with PostgreSQL
2127
lead to libpq overflowing the data structure. TCP/IP connections
2128
work OK, but not Unix-domain sockets, which prevents the
2129
regression tests from working.
2133
The problem was reported to IBM, and is recorded as bug report
2134
PMR29657. If you upgrade to maintenance level 5300-03, that will
2135
include this fix. Use the command <literal>oslevel -r</literal>
2136
to determine what maintenance level you are at. An immediate
2137
resolution is to alter <symbol>_SS_MAXSIZE</symbol> to = 1025 in
2138
<filename>/usr/include/sys/socket.h</filename>.
2143
<title>Memory Management</title>
2144
<!-- http://archives.postgresql.org/message-id/603bgqmpl9.fsf@dba2.int.libertyrms.com -->
2147
AIX can be somewhat peculiar with regards to the way it does
2148
memory management. You can have a server with many multiples of
2149
gigabytes of RAM free, but still get out of memory or address
2150
space errors when running applications. One example
2151
is <command>createlang</command> failing with unusual errors.
2152
For example, running as the owner of the PostgreSQL installation:
2154
-bash-3.00$ createlang plpgsql template1
2155
createlang: language installation failed: ERROR: could not load library "/opt/dbs/pgsql748/lib/plpgsql.so": A memory address is not in the address space for the process.
2157
Running as a non-owner in the group posessing the PostgreSQL
2160
-bash-3.00$ createlang plpgsql template1
2161
createlang: language installation failed: ERROR: could not load library "/opt/dbs/pgsql748/lib/plpgsql.so": Bad address
2163
Another example is out of memory errors in the PostgreSQL server
2164
logs, with every memory allocation near or greater than 256 MB
2169
The overall cause of all these problems is the default bittedness
2170
and memory model used by the server process. By default, all
2171
binaries built on AIX are 32-bit. This does not depend upon
2172
hardware type or kernel in use. These 32-bit processes are
2173
limited to 4 GB of memory laid out in 256 MB segments using one
2174
of a few models. The default allows for less than 256 MB in the
2175
heap as it shares a single segment with the stack.
2179
In the case of the <command>createlang</command> example, above,
2180
check your umask and the permissions of the binaries in your
2181
PostgreSQL installation. The binaries involved in that example
2182
were 32-bit and installed as mode 750 instead of 755. Due to the
2183
permissions being set in this fashion, only the owner or a member
2184
of the possessing group can load the library. Since it isn't
2185
world-readable, the loader places the object into the process'
2186
heap instead of the shared library segments where it would
2187
otherwise be placed.
2191
The <quote>ideal</quote> solution for this is to use a 64-bit
2192
build of PostgreSQL, but that is not always practical, because
2193
systems with 32-bit processors can build, but not run, 64-bit
2198
If a 32-bit binary is desired, set <symbol>LDR_CNTRL</symbol> to
2199
<literal>MAXDATA=0x<replaceable>n</replaceable>0000000</literal>,
2200
where 1 <= n <= 8, before starting the PostgreSQL server,
2201
and try different values and <filename>postgresql.conf</filename>
2202
settings to find a configuration that works satisfactorily. This
2203
use of <symbol>LDR_CNTRL</symbol> tells AIX that you want the
2204
server to have <symbol>MAXDATA</symbol> bytes set aside for the
2205
heap, allocated in 256 MB segments. When you find a workable
2207
<command>ldedit</command> can be used to modify the binaries so
2208
that they default to using the desired heap size. PostgreSQL can
2209
also be rebuilt, passing <literal>configure
2210
LDFLAGS="-Wl,-bmaxdata:0x<replaceable>n</replaceable>0000000"</literal>
2211
to achieve the same effect.
2215
For a 64-bit build, set <envar>OBJECT_MODE</envar> to 64 and
2216
pass <literal>CC="gcc -maix64"</literal>
2217
and <literal>LDFLAGS="-Wl,-bbigtoc"</literal>
2218
to <command>configure</command>. (Options for
2219
<command>xlc</command> might differ.) If you omit the export of
2220
<envar>OBJECT_MODE</envar>, your build may fail with linker errors. When
2221
<envar>OBJECT_MODE</envar> is set, it tells AIX's build utilities
2222
such as <command>ar</>, <command>as</>, and <command>ld</> what
2223
type of objects to default to handling.
2227
By default, overcommit of paging space can happen. While we have
2228
not seen this occur, AIX will kill processes when it runs out of
2229
memory and the overcommit is accessed. The closest to this that
2230
we have seen is fork failing because the system decided that
2231
there was not enough memory for another process. Like many other
2232
parts of AIX, the paging space allocation method and
2233
out-of-memory kill is configurable on a system- or process-wide
2234
basis if this becomes a problem.
2238
<title>References and resources</title>
2241
<biblioset relation="article">
2242
<title><ulink url="http://publib.boulder.ibm.com/infocenter/pseries/topic/com.ibm.aix.doc/aixprggd/genprogc/lrg_prg_support.htm">Large Program Support</ulink></title>
2244
<biblioset relation="book">
2245
<title>AIX Documentation: General Programming Concepts: Writing and Debugging Programs</title>
2250
<biblioset relation="article">
2251
<title><ulink url="http://publib.boulder.ibm.com/infocenter/pseries/topic/com.ibm.aix.doc/aixprggd/genprogc/address_space.htm">Program Address Space Overview</ulink></title>
2253
<biblioset relation="book">
2254
<title>AIX Documentation: General Programming Concepts: Writing and Debugging Programs</title>
2259
<biblioset relation="article">
2260
<title><ulink url="http://publib.boulder.ibm.com/infocenter/pseries/v5r3/topic/com.ibm.aix.doc/aixbman/prftungd/resmgmt2.htm">Performance Overview of the Virtual Memory Manager (VMM)</ulink></title>
2262
<biblioset relation="book">
2263
<title>AIX Documentation: Performance Management Guide</title>
2268
<biblioset relation="article">
2269
<title><ulink url="http://publib.boulder.ibm.com/infocenter/pseries/v5r3/topic/com.ibm.aix.doc/aixbman/prftungd/memperf7.htm">Page Space Allocation</ulink></title>
2271
<biblioset relation="book">
2272
<title>AIX Documentation: Performance Management Guide</title>
2277
<biblioset relation="article">
2278
<title><ulink url="http://publib.boulder.ibm.com/infocenter/pseries/v5r3/topic/com.ibm.aix.doc/aixbman/prftungd/memperf6.htm">Paging-space thresholds tuning</ulink></title>
2280
<biblioset relation="book">
2281
<title>AIX Documentation: Performance Management Guide</title>
2286
<title><ulink url=" http://www.redbooks.ibm.com/abstracts/sg245674.html?Open">Developing and Porting C and C++ Applications on AIX</ulink></title>
2288
<publishername>IBM Redbook</publishername>
2295
<title>Statistics Collector Issues</title>
2296
<!-- http://archives.postgresql.org/message-id/6064jt6cfm.fsf_-_@dba2.int.libertyrms.com -->
2299
When implementing PostgreSQL version 8.1 on AIX 5.3, we
2300
periodically ran into problems where the statistics collector
2301
would <quote>mysteriously</quote> not come up successfully. This
2302
appears to be the result of unexpected behaviour in the IPv6
2303
implementation. It looks like PostgreSQL and IPv6 do not play
2304
very well together at this time on AIX.
2308
Any of the following actions <quote>fix</quote> the problem.
2312
Delete the IPv6 address for localhost:
2315
# ifconfig lo0 inet6 ::1/0 delete
2322
Remove IPv6 from net services. The
2323
file <filename>/etc/netsvc.conf</filename> on AIX is roughly
2324
equivalent to <filename>/etc/nsswitch.conf</filename> on
2325
Solaris/Linux. The default, on AIX, is thus:
2333
to deactivate searching for IPv6 addresses.
2341
<sect2 id="installation-notes-cygwin">
2342
<title>Cygwin</title>
2344
<indexterm zone="installation-notes-cygwin">
2345
<primary>Cyginw</primary>
2346
<secondary>installation on</secondary>
2350
PostgreSQL can be built using Cygwin, a Linux-like environment for
2351
Windows, but that method is inferior to the native Windows build
2352
<![%standalone-ignore[(see <xref linkend="install-win32">)]]> and
2353
is no longer recommended.
2357
When building from source, proceed according to the normal
2358
installation procedure (i.e., <literal>./configure;
2359
make</literal>; etc.), noting the following-Cygwin specific
2365
Set your path to use the Cygwin bin directory before the
2366
Windows utilities. This will help prevent problems with
2373
The GNU make command is called "make" not "gmake".
2379
The <command>adduser</command> command is not supported; use
2380
the appropriate user management application on Windows NT,
2381
2000, or XP. Otherwise, skip this step.
2387
The <command>su</command> command is not supported; use ssh to
2388
simulate su on Windows NT, 2000, or XP. Otherwise, skip this
2395
OpenSSL is not supported.
2401
Start <command>cygserver</command> for shared memory support.
2402
To do this, enter the command <literal>/usr/sbin/cygserver
2403
&</literal>. This program needs to be running anytime you
2404
start the PostgreSQL server or initialize a database cluster
2405
(<command>initdb</command>). The
2406
default <command>cygserver</command> configuration may need to
2407
be changed (e.g., increase <symbol>SEMMNS</symbol>) to prevent
2408
PostgreSQL from failing due to a lack of system resources.
2414
The parallel regression tests (<literal>make check</literal>)
2415
can generate spurious regression test failures due to
2416
overflowing the <function>listen()</function> backlog queue
2417
which causes connection refused errors or hangs. You can limit
2418
the number of connections using the make
2419
variable <varname>MAX_CONNECTIONS</varname> thus:
2421
make MAX_CONNECTIONS=5 check
2423
(On some systems you can have up to about 10 simultaneous
2431
It is possible to install <command>cygserver</command> and the
2432
PostgreSQL server as Windows NT services. For information on how
2433
to do this, please refer to the <filename>README</filename>
2434
document included with the PostgreSQL binary package on Cygwin.
2435
It is installed in the
2436
directory <filename>/usr/share/doc/Cygwin</filename>.
2440
<sect2 id="installation-notes-hpux">
2441
<title>HP-UX</title>
2443
<indexterm zone="installation-notes-hpux">
2444
<primary>HP-UX</primary>
2445
<secondary>installation on</secondary>
2449
PostgreSQL 7.3+ should work on Series 700/800 PA-RISC machines
2450
running HP-UX 10.X or 11.X, given appropriate system patch levels
2451
and build tools. At least one developer routinely tests on HP-UX
2452
10.20, and we have reports of successful installations on HP-UX
2457
Aside from the PostgreSQL source distribution, you will need GNU
2458
make (HP's make will not do), and either GCC or HP's full ANSI C
2459
compiler. If you intend to build from CVS sources rather than a
2460
distribution tarball, you will also need Flex (GNU lex) and Bison
2461
(GNU yacc). We also recommend making sure you are fairly
2462
up-to-date on HP patches. At a minimum, if you are building 64
2463
bit binaries on on HP-UX 11.11 you may need PHSS_30966 (11.11) or a
2464
successor patch otherwise <command>initdb</command> may hang:
2466
PHSS_30966 s700_800 ld(1) and linker tools cumulative patch
2469
On general principles you should be current on libc and ld/dld
2470
patches, as well as compiler patches if you are using HP's C
2471
compiler. See HP's support sites such
2472
as <ulink url="http://itrc.hp.com"></ulink> and
2473
<ulink url="ftp://us-ffs.external.hp.com/"></ulink> for free
2474
copies of their latest patches.
2478
If you are building on a PA-RISC 2.0 machine and want to have
2479
64-bit binaries using GCC, you must use GCC 64-bit version. GCC
2480
binaries for HP-UX PA-RISC and Itanium are available from
2481
<ulink url="http://www.hp.com/go/gcc"></ulink>. Don't forget to
2482
get and install binutils at the same time.
2486
If you are building on a PA-RISC 2.0 machine and want the compiled
2487
binaries to run on PA-RISC 1.1 machines you will need to specify
2488
<option>+DAportable</option> in <envar>CFLAGS</envar>.
2492
If you are building on a HP-UX Itanium machine, you will need the
2493
latest HP ANSI C compiler with its dependent patch or successor
2496
PHSS_30848 s700_800 HP C Compiler (A.05.57)
2497
PHSS_30849 s700_800 u2comp/be/plugin library Patch
2502
If you have both HP's C compiler and GCC's, then you might want to
2503
explicitly select the compiler to use when you
2504
run <command>configure</command>:
2508
for HP's C compiler, or
2512
for GCC. If you omit this setting, then configure will
2513
pick <command>gcc</command> if it has a choice.
2517
The default install target location
2518
is <filename>/usr/local/pgsql</filename>, which you might want to
2519
change to something under <filename>/opt</filename>. If so, use
2521
<option>--prefix</option> switch to <command>configure</command>.
2525
In the regression tests, there might be some low-order-digit
2526
differences in the geometry tests, which vary depending on which
2527
compiler and math library versions you use. Any other error is
2528
cause for suspicion.
2532
<sect2 id="installation-notes-irix">
2535
<indexterm zone="installation-notes-irix">
2536
<primary>IRIX</primary>
2537
<secondary>installation on</secondary>
2541
PostgreSQL has been reported to run successfully on MIPS r8000,
2542
r10000 (both ip25 and ip27) and r12000(ip35) processors, running
2543
IRIX 6.5.5m, 6.5.12, 6.5.13, and 6.5.26 with MIPSPro compilers
2544
version 7.30, 7.3.1.2m, 7.3, and 7.4.4m.
2548
You will need the MIPSPro full ANSI C compiler. There are
2549
problems trying to build with GCC. It is a known GCC bug (not
2550
fixed as of version 3.0) related to using functions that return
2551
certain kinds of structures. This bug affects functions like
2552
<function>inet_ntoa</>, <function>inet_lnaof</>, <function>inet_netof</>, <function>inet_makeaddr</>,
2553
and <function>semctl</>. It is supposed to be fixed by forcing
2554
code to link those functions with libgcc, but this has not been
2559
It is known that version 7.4.1m of the MIPSPro compiler generates
2560
incorrect code. The symptom is <quote>invalid primary checkpoint
2561
record</quote> when trying to start the database.) Version 7.4.4m
2562
is OK; the status of intermediate versions is uncertain.
2566
There may be a compilation problem like the following:
2568
cc-1020 cc: ERROR File = pqcomm.c, Line = 427
2569
The identifier "TCP_NODELAY" is undefined.
2571
if (setsockopt(port->sock, IPPROTO_TCP, TCP_NODELAY,
2573
Some versions include TCP definitions
2574
in <filename>sys/xti.h</filename>, so it is necessary to
2575
add <literal>#include <sys/xti.h></literal>
2576
in <filename>src/backend/libpq/pqcomm.c</> and in
2577
<filename>src/interfaces/libpq/fe-connect.c</>. If you encounter
2578
this, please let us know so we can develop a proper fix.
2582
In the regression tests, there might be some low-order-digit
2583
differences in the geometry tests, depending on which FPU are you
2584
using. Any other error is cause for suspicion.
2588
<sect2 id="installation-notes-mingw">
2589
<title>MinGW/Native Windows</title>
2591
<indexterm zone="installation-notes-mingw">
2592
<primary>MinGW</primary>
2593
<secondary>installation on</secondary>
2597
PostgreSQL for Windows can be built using MinGW, a Unix-like build
2598
environment for Microsoft operating systems, or using
2599
Microsoft's <productname>Visual C++</productname> compiler suite.
2600
The MinGW build variant uses the normal build system described in
2601
this chapter; the Visual C++ build works completely differently
2602
and is described in <![%standalone-include[the
2603
documentation]]><![%standalone-ignore[<xref linkend="install-win32">]]>.
2604
There is also a precompiled binary installer which you can find at
2605
from <ulink url="http://pgfoundry.org/projects/pginstaller"></ulink>.
2606
It is a fully native build and uses no additional software like
2607
MinGW. The ready-made installer files are available on the main
2608
PostgreSQL FTP servers in the <filename>binary/win32</filename>
2613
The native Win32 port requires a 32-bit NT-based Microsoft
2614
operating system, like Windows NT 4, Windows 2000/2003, or Windows
2615
XP. (NT 4 is no longer supported.) Earlier operating systems do
2616
not have sufficient infrastructure (but Cygwin may be used on
2617
those). MinGW, the Unix-like build tools, and MSYS, a collection
2618
of Unix tools required to run shell scripts
2619
like <command>configure</command>, can be downloaded
2620
from <ulink url="http://www.mingw.org/"></ulink>. Neither is
2621
required to run the resulting binaries; they are needed only for
2622
creating the binaries.
2626
After you have everything installed, it is suggested that you
2627
run <application>psql</application>
2628
under <command>CMD.EXE</command>, as the MSYS console has
2633
<sect2 id="installation-notes-sco">
2634
<title>SCO OpenServer and SCO UnixWare</title>
2636
<indexterm zone="installation-notes-sco">
2637
<primary>SCO</primary>
2638
<secondary>installation on</secondary>
2641
<indexterm zone="installation-notes-sco">
2642
<primary>UnixWare</primary>
2643
<secondary>installation on</secondary>
2647
PostgreSQL can be built on SCO UnixWare 7 and SCO OpenServer 5.
2648
On OpenServer, you can use either the OpenServer Development Kit
2649
or the Universal Development Kit. However, some tweaking may be
2650
needed, as described below.
2654
<title>Skunkware</title>
2657
You should locate your copy of the SCO Skunkware CD. The
2658
Skunkware CD is included with UnixWare 7 and current versions of
2659
OpenServer 5. Skunkware includes ready-to-install versions of
2660
many popular programs that are available on the Internet. For
2661
example, gzip, gunzip, GNU Make, Flex, and Bison are all
2662
included. For UnixWare 7.1, this CD is now labeled "Open License
2663
Software Supplement". If you do not have this CD, the software
2664
on it is available via anonymous FTP
2665
from <ulink url="ftp://ftp.sco.com/skunkware"></ulink>.
2669
Skunkware has different versions for UnixWare and OpenServer.
2670
Make sure you install the correct version for your operating
2671
system, except as noted below.
2675
On UnixWare 7.1.3 and beyond, the GCC compiler is included on the
2676
UDK CD as is GNU Make.
2681
<title>GNU Make</title>
2684
You need to use the GNU Make program, which is on the Skunkware
2685
CD. By default, it installs
2686
as <filename>/usr/local/bin/make</filename>. To avoid confusion
2687
with the SCO <filename>make</filename> program, you may want to rename GNU <filename>make</filename> to
2688
<filename>gmake</filename>.
2692
As of UnixWare 7.1.3 and above, the GNU Make program is is the
2693
OSTK portion of the UDK CD, and is
2694
in <filename>/usr/gnu/bin/gmake</filename>.
2699
<title>Readline</title>
2702
The Readline library is on the Skunkware CD. But it is not
2703
included on the UnixWare 7.1 Skunkware CD. If you have the
2704
UnixWare 7.0.0 or 7.0.1 Skunkware CDs, you can install it from
2706
try <ulink url="ftp://ftp.sco.com/skunkware"></ulink>.
2710
By default, Readline installs into <filename>/usr/local/lib</> and
2711
<filename>/usr/local/include</>. However, the
2712
PostgreSQL <command>configure</command> program will not find it
2713
there without help. If you installed Readline, then use the
2714
following options to <command>configure</command>:
2716
./configure --with-libraries=/usr/local/lib --with-includes=/usr/local/include
2722
<title>Using the UDK on OpenServer</title>
2725
If you are using the new Universal Development Kit (UDK) compiler
2726
on OpenServer, you need to specify the locations of the UDK
2729
./configure --with-libraries=/udk/usr/lib --with-includes=/udk/usr/include
2731
Putting these together with the Readline options from above:
2733
./configure --with-libraries="/udk/usr/lib /usr/local/lib" --with-includes="/udk/usr/include /usr/local/include"
2739
<title>Reading the PostgreSQL man pages</title>
2742
By default, the PostgreSQL man pages are installed into
2743
<filename>/usr/local/pgsql/man</filename>. By default, UnixWare
2744
does not look there for man pages. To be able to read them you
2746
<varname>MANPATH</varname> variable
2747
in <filename>/etc/default/man</filename>, for example:
2749
MANPATH=/usr/lib/scohelp/%L/man:/usr/dt/man:/usr/man:/usr/share/man:scohelp:/usr/local/man:/usr/local/pgsql/man
2754
On OpenServer, some extra research needs to be invested to make
2755
the man pages usable, because the man system is a bit different
2756
from other platforms. Currently, PostgreSQL will not install
2762
<title>C99 Issues with the 7.1.1b Feature Supplement</title>
2765
For compilers earlier than the one released with OpenUNIX 8.0.0
2766
(UnixWare 7.1.2), including the 7.1.1b Feature Supplement, you
2767
may need to specify <option>-Xb</option>
2768
in <varname>CFLAGS</varname> or the <varname>CC</varname>
2769
environment variable. The indication of this is an error in
2770
compiling <filename>tuplesort.c</filename> referencing inline
2771
functions. Apparently there was a change in the 7.1.2(8.0.0)
2772
compiler and beyond.
2777
<title><option>--enable-thread-safety</option> and UnixWare</title>
2780
If you use the <command>configure</command>
2781
option <option>--enable-thread-safety</option>,
2782
you <emphasis>must</emphasis> use <option>-Kpthread</option>
2783
on <emphasis>all</emphasis> libpq-using programs. libpq
2784
uses <function>pthread_*</function> calls, which are only
2786
<option>-Kpthread</>/<option>-Kthread</> flag.
2791
<sect2 id="installation-notes-solaris">
2792
<title>Solaris</title>
2794
<indexterm zone="installation-notes-solaris">
2795
<primary>Solaris</primary>
2796
<secondary>installation on</secondary>
2800
PostgreSQL is well-supported on Solaris. The more up to date your
2801
operating system, the fewer issues you will experience; details
2806
Note that PostgreSQL is bundled with Solaris 10 (from update 2).
2807
Official packages are also available on
2808
<ulink url="http://pgfoundry.org/projects/solarispackages/"></ulink>.
2809
Packages for older Solaris versions (8, 9) you can be obtained
2810
from <ulink url="http://www.sunfreeware.com/"></ulink> or
2811
<ulink url="http://www.blastwave.org/"></ulink>.
2815
<title>Required tools</title>
2818
You can build with either GCC or Sun's compiler suite. For
2819
better code optimization, Sun's compiler is strongly recommended
2820
on the SPARC architecture. We have heard reports of problems
2821
when using GCC 2.95.1; gcc 2.95.3 or later is recommended. If
2822
you are using Sun's compiler, be careful not to select
2823
<filename>/usr/ucb/cc</filename>;
2824
use <filename>/opt/SUNWspro/bin/cc</filename>.
2828
You can download Sun Studio
2829
from <ulink url="http://developers.sun.com/sunstudio/downloads/"></ulink>.
2830
Many of GNU tools are integrated into Solaris 10, or they are
2831
present on the Solaris companion CD. If you like packages for
2832
older version of Solaris, you can find these tools
2833
at <ulink url="http://www.sunfreeware.com"></ulink>
2834
or <ulink url="http://www.blastwave.org"></ulink>. If you prefer
2836
at <ulink url="http://www.gnu.org/order/ftp.html"></ulink>.
2841
<title>Problems with OpenSSL</title>
2844
When you build PostgreSQL with OpenSSL support you might get
2845
compilation errors in the following files:
2847
<listitem><para><filename>src/backend/libpq/crypt.c</filename></para></listitem>
2848
<listitem><para><filename>src/backend/libpq/password.c</filename></para></listitem>
2849
<listitem><para><filename>src/interfaces/libpq/fe-auth.c</filename></para></listitem>
2850
<listitem><para><filename>src/interfaces/libpq/fe-connect.c</filename></para></listitem>
2853
This is because of a namespace conflict between the standard
2854
<filename>/usr/include/crypt.h</filename> header and the header
2855
files provided by OpenSSL.
2859
Upgrading your OpenSSL installation to version 0.9.6a fixes this
2860
problem. Solaris 9 and above has a newer version of OpenSSL.
2865
<title>configure complains about a failed test program</title>
2868
If <command>configure</command> complains about a failed test
2869
program, this is probably a case of the run-time linker being
2870
unable to find some library, probably libz, libreadline or some
2871
other non-standard library such as libssl. To point it to the
2872
right location, set the <envar>LDFLAGS</envar> environment
2873
variable on the <command>configure</command> command line, e.g.,
2875
configure ... LDFLAGS="-R /usr/sfw/lib:/opt/sfw/lib:/usr/local/lib"
2878
the <citerefentry><refentrytitle>ld</><manvolnum>1</></citerefentry>
2879
man page for more information.
2884
<title>64-bit build sometimes crashes</title>
2887
On Solaris 7 and older, the 64-bit version of libc has a buggy
2888
<function>vsnprintf</function> routine, which leads to erratic
2889
core dumps in PostgreSQL. The simplest known workaround is to
2890
force PostgreSQL to use its own version of vsnprintf rather than
2891
the library copy. To do this, after you
2892
run <command>configure</command> edit a file produced by
2893
<command>configure</command>:
2894
In <filename>src/Makefile.global</filename>, change the line
2900
LIBOBJS = snprintf.o
2902
(There might be other files already listed in this variable.
2903
Order does not matter.) Then build as usual.
2908
<title>Compiling for optimal performance</title>
2911
On the SPARC architecture, Sun Studio is strongly recommended for
2912
compilation. Try using the <option>-xO5</option> optimization
2913
flag to generate significantly faster binaries. Do not use any
2914
flags that modify behavior of floating-point operations
2915
and <varname>errno</varname> processing (e.g.,
2916
<option>-fast</option>). These flags could raise some
2917
nonstandard PostgreSQL behavior for example in the date/time
2922
If you do not have a reason to use 64-bit binaries on SPARC,
2923
prefer the 32-bit version. The 64-bit operations are slower and
2924
64-bit binaries are slower than the 32-bit variants. And on
2925
other hand, 32-bit code on the AMD64 CPU family is not native,
2926
and that is why 32-bit code is significant slower on this CPU
2931
Some tricks for tuning PostgreSQL and Solaris for performance can
2933
at <ulink url="http://www.sun.com/servers/coolthreads/tnb/applications_postgresql.jsp"></ulink>.
2934
This article is primary focused on T2000 platform, but many of
2935
the recommendations are also useful on other hardware with
2941
<title>Using DTrace for tracing PostgreSQL</title>
2944
Yes, using DTrace is possible. See <![%standalone-include[the
2946
<![%standalone-ignore[<xref linkend="dynamic-trace">]]> for further
2947
information. You can also find more information in this
2948
article: <ulink url="http://blogs.sun.com/robertlor/entry/user_level_dtrace_probes_in"></ulink>.
2952
If you see the linking of the postgres executable abort with an
2955
Undefined first referenced
2957
AbortTransaction utils/probes.o
2958
CommitTransaction utils/probes.o
2959
ld: fatal: Symbol referencing errors. No output written to postgres
2960
collect2: ld returned 1 exit status
2961
gmake: *** [postgres] Error 1
2963
your DTrace installation is too old to handle probes in static
2964
functions. You need Solaris 10u4 or newer.
added
removed
doc/src/sgml/installation.sgml
