1 <!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.56 2001/09/16 16:11:09 petere Exp $ -->
3 <chapter id="installation">
4 <title><![%flattext-install-include[<productname>PostgreSQL</>]]>
5 Installation Instructions</title>
7 <indexterm zone="installation">
8 <primary>installation</primary>
11 <sect1 id="install-short">
12 <title>Short Version</title>
21 mkdir /usr/local/pgsql/data
22 chown postgres /usr/local/pgsql/data
24 /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
25 /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
26 /usr/local/pgsql/bin/createdb test
27 /usr/local/pgsql/bin/psql test
29 The long version is the rest of this
30 <![%flattext-install-include;[document.]]>
31 <![%flattext-install-ignore;[chapter.]]>
36 <sect1 id="install-requirements">
37 <title>Requirements</title>
40 In general, a modern Unix-compatible platform should be able to run
41 PostgreSQL. The platforms that had received explicit testing at the
42 time of release are listed in <xref linkend="supported-platforms">
43 below. In the <filename>doc</> subdirectory of the distribution
44 there are several platform-specific <acronym>FAQ</> documents you
45 might wish to consult if you are having trouble.
49 The following prerequisites exist for building <productname>PostgreSQL</>:
53 <primary>make</primary>
57 <acronym>GNU</> <application>make</> is required; other
58 <application>make</> programs will <emphasis>not</> work.
59 <acronym>GNU</> <application>make</> is often installed under
60 the name <filename>gmake</filename>; this document will always
61 refer to it by that name. (On <systemitem class="osname">GNU/Linux</> systems GNU make is the
62 default tool with the name <filename>make</>.) To test for
63 <acronym>GNU</acronym> <application>make</application> enter
65 <userinput>gmake --version</userinput>
67 If at all possible you should use version 3.76.1 or later.
73 You need an <acronym>ISO</>/<acronym>ANSI</> C compiler. Recent
74 versions of <productname>GCC</> are recommendable, but
75 <productname>PostgreSQL</> is known to build with a wide variety
76 of compilers from different vendors.
81 <para><application>gzip</></para>
86 <primary>readline</primary>
90 The <acronym>GNU</> <productname>Readline</> library for comfortable
91 line editing and command history retrieval will automatically be used
92 if found. You might wish to install it before proceeding, but it is not
93 required. (On <productname>NetBSD</productname>, the
94 <filename>libedit</filename> library is
95 <productname>readline</productname>-compatible and is used if
96 <filename>libreadline</filename> is not found.)
102 <primary>flex</primary>
105 <primary>bison</primary>
108 <primary>yacc</primary>
112 <application>Flex</> and <application>Bison</> are
113 <emphasis>not</> required when building from a released source
114 package because the output files are pre-generated. You will
115 need these programs only when building from a CVS tree or when
116 the actual scanner and parser definition files were changed. If
117 you need them, be sure to get <application>Flex</> 2.5.4 or
118 later and <application>Bison</> 1.28 or later. Other <application>yacc</>
119 programs can sometimes be used, but doing so requires extra
120 efforts and is not recommended. Other <application>lex</> programs will
127 <primary>installation</primary>
128 <secondary>on Windows</secondary>
131 To build on <productname>Windows NT</> or <productname>Windows
132 2000</> you need the <productname>Cygwin</> and
133 <productname>cygipc</> packages. See the file
134 <filename>doc/FAQ_MSWIN</> for details.
141 If you need to get a <acronym>GNU</acronym> package, you can find
142 it at your local <acronym>GNU</acronym> mirror site (see <ulink
143 url="http://www.gnu.org/order/ftp.html">http://www.gnu.org/order/ftp.html</>
144 for a list) or at <ulink
145 url="ftp://ftp.gnu.org/gnu/">ftp://ftp.gnu.org/gnu/</ulink>.
149 Also check that you have sufficient disk space. You will need about
150 30 MB for the source tree during compilation and about 5 MB for the
151 installation directory. An empty database takes about 1 MB, later
152 it takes about five times the amount of space that a flat text file
153 with the same data would take. If you are going to run the
154 regression tests you will temporarily need an extra 20 MB. Use the
155 <command>df</command> command to check for disk space.
159 <![%flattext-install-ignore;[
160 <sect1 id="install-getsource">
161 <title>Getting The Source</title>
164 The <productname>PostgreSQL</> &version; sources can by obtained from <ulink
165 url="ftp://ftp.postgresql.org/pub/postgresql-&version;.tar.gz"
166 >ftp://ftp.postgresql.org/pub/postgresql-&version;.tar.gz</ulink>.
167 Use a mirror if possible. Then unpack it:
169 <userinput>gunzip postgresql-&version;.tar.gz</userinput>
170 <userinput>tar xf postgresql-&version;.tar</userinput>
172 This will create a directory
173 <filename>postgresql-&version;</filename> with the <productname>PostgreSQL</> sources
174 in the current directory. Change into that directory for the rest
175 of the installation procedure.
180 <sect1 id="install-upgrading">
181 <title>If You Are Upgrading</title>
183 <indexterm zone="install-upgrading">
184 <primary>upgrading</primary>
188 The internal data storage format changes with new releases of
189 <productname>PostgreSQL</>. Therefore, if you are upgrading an
190 existing installation that does not have a version number
191 <quote>&majorversion;.x</quote>, you must back up and restore your
192 data as shown here. These instructions assume that your existing
193 installation is under the <filename>/usr/local/pgsql</> directory,
194 and that the data area is in <filename>/usr/local/pgsql/data</>.
195 Substitute your paths appropriately.
201 Make sure that your database is not updated during or after the
202 backup. This does not affect the integrity of the backup, but the
203 changed data would of course not be included. If necessary, edit
204 the permissions in the file
205 <filename>/usr/local/pgsql/data/pg_hba.conf</> (or equivalent) to
206 disallow access from everyone except you.
212 <primary>pg_dumpall</primary>
216 To dump your database installation, type:
218 <userinput>pg_dumpall > <replaceable>outputfile</></userinput>
220 If you need to preserve the OIDs (such as when using them as
221 foreign keys), then use the <option>-o</option> option when running
222 <command>pg_dumpall</>. <command>pg_dumpall</command> does not
223 save large objects. Check
224 <![%flattext-install-include[the <citetitle>Administrator's Guide</>]]>
225 <![%flattext-install-ignore[<xref linkend="backup-dump-caveats">]]>
226 if you need to do this.
230 Make sure that you use the <command>pg_dumpall</> command
231 from the version you are currently running. &version;'s
232 <command>pg_dumpall</> should not be used on older databases.
238 If you are installing the new version at the same location as the
239 old one then shut down the old server, at the latest before you
240 install the new files:
242 <userinput>kill -INT `cat /usr/local/pgsql/data/postmaster.pid`</>
244 Versions prior to 7.0 do not have this
245 <filename>postmaster.pid</> file. If you are using such a version
246 you must find out the process id of the server yourself, for
247 example by typing <userinput>ps ax | grep postmaster</>, and
248 supply it to the <command>kill</> command.
252 On systems that have <productname>PostgreSQL</> started at boot time, there is
253 probably a start-up file that will accomplish the same thing. For
254 example, on a <systemitem class="osname">Red Hat Linux</> system one might find that
256 <userinput>/etc/rc.d/init.d/postgresql stop</userinput>
264 If you are installing in the same place as the old version then
265 it is also a good idea to move the old installation out of the
266 way, in case you still need it later on. Use a command like this:
268 <userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>
275 After you have installed <productname>PostgreSQL</> &version;, create a new database
276 directory and start the new server. Remember that you must execute
277 these commands while logged in to the special database user account
278 (which you already have if you are upgrading).
280 <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
281 <userinput>/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data</>
283 Finally, restore your data with
285 <userinput>/usr/local/pgsql/bin/psql -d template1 -f <replaceable>outputfile</></userinput>
287 using the <emphasis>new</> <application>psql</>.
291 You can also install the new version in parallel with the old one
292 to decrease the downtime. These topics are discussed at length in
293 <![%flattext-install-include[the <citetitle>Administrator's Guide</>,]]>
294 <![%flattext-install-ignore[<xref linkend="migration">,]]>
295 which you are encouraged
301 <sect1 id="install-procedure">
302 <title>Installation Procedure</title>
306 <step id="configure">
307 <title>Configuration</>
309 <indexterm zone="configure">
310 <primary>configure</primary>
314 The first step of the installation procedure is to configure the
315 source tree for your system and choose the options you would like.
316 This is done by running the <filename>configure</> script. For a
317 default installation simply enter
319 <userinput>./configure</userinput>
321 This script will run a number of tests to guess values for various
322 system dependent variables and detect some quirks of your
323 operating system, and finally creates several files in the build
324 tree to record what it found.
328 The default configuration will build the server and utilities, as
329 well as all client applications and interfaces that only require a
330 C compiler. All files will be installed under
331 <filename>/usr/local/pgsql</> by default.
335 You can customize the build and installation process by supplying one
336 or more of the following command line options to
337 <filename>configure</filename>:
341 <term><option>--prefix=<replaceable>PREFIX</></option></term>
344 Install all files under the directory <replaceable>PREFIX</>
345 instead of <filename>/usr/local/pgsql</filename>. The actual
346 files will be installed into various subdirectories; no files
347 will ever be installed directly into the
348 <replaceable>PREFIX</> directory.
352 If you have special needs, you can also customize the
353 individual subdirectories with the following options.
359 <term><option>--exec-prefix=<replaceable>EXEC-PREFIX</></option></term>
362 You can install architecture-dependent files under a
363 different prefix, <replaceable>EXEC-PREFIX</>, than what
364 <replaceable>PREFIX</> was set to. This can be useful to
365 share architecture-independent files between hosts. If you
366 omit this, then <replaceable>EXEC-PREFIX</> is set equal to
367 <replaceable>PREFIX</> and both architecture dependent and
368 independent files will be installed under the same tree,
369 which is probably what you want.
375 <term><option>--bindir=<replaceable>DIRECTORY</></option></term>
378 Specifies the directory for executable programs. The default
379 is <filename><replaceable>EXEC-PREFIX</>/bin</>, which
380 normally means <filename>/usr/local/pgsql/bin</>.
386 <term><option>--datadir=<replaceable>DIRECTORY</></option></term>
389 Sets the directory for read-only data files used by the
390 installed programs. The default is
391 <filename><replaceable>PREFIX</>/share</>. Note that this has
392 nothing to do with where your database files will be placed.
398 <term><option>--sysconfdir=<replaceable>DIRECTORY</></option></term>
401 The directory for various configuration files,
402 <filename><replaceable>PREFIX</>/etc</> by default.
408 <term><option>--libdir=<replaceable>DIRECTORY</></option></term>
411 The location to install libraries and dynamically loadable
412 modules. The default is
413 <filename><replaceable>EXEC-PREFIX</>/lib</>.
419 <term><option>--includedir=<replaceable>DIRECTORY</></option></term>
422 The directory for installing C and C++ header files. The
423 default is <filename><replaceable>PREFIX</>/include</>.
429 <term><option>--docdir=<replaceable>DIRECTORY</></option></term>
432 Documentation files, except <quote>man</> pages, will be
433 installed into this directory. The default is
434 <filename><replaceable>PREFIX</>/doc</>.
440 <term><option>--mandir=<replaceable>DIRECTORY</></option></term>
443 The man pages that come with <productname>PostgreSQL</> will be installed under
444 this directory, in their respective
445 <filename>man<replaceable>x</></> subdirectories.
446 The default is <filename><replaceable>PREFIX</>/man</>.
454 Care has been taken to make it possible to install PostgreSQL
455 into shared installation locations (such as
456 <filename>/usr/local/include</filename>) without interfering
457 with the namespace of the rest of the system. First, the
458 string <quote><literal>/postgresql</literal></quote> is
459 automatically appended to <varname>datadir</varname>,
460 <varname>sysconfdir</varname>, and <varname>docdir</varname>,
461 unless the fully expanded directory name already contains the
462 string <quote><literal>postgres</></quote> or <quote><literal>pgsql</></quote>. For
463 example, if you choose <filename>/usr/local</filename> as
464 prefix, the documentation will be installed in
465 <filename>/usr/local/doc/postgresql</filename>, but if the
466 prefix is <filename>/opt/postgres</filename>, then it will be
467 in <filename>/opt/postgres/doc</filename>. Second, the
468 installation layout of the C and C++ header files has been
469 reorganized in the 7.2 release. The public header files of the
470 client interfaces are installed into
471 <varname>includedir</varname> and are namespace-clean. The
472 internal header files and the server header files are installed
473 into private directories under
474 <varname>includedir</varname>.
475 See the <citetitle>Programmer's Guide</citetitle> for
476 information how to get at the header files for each interface.
477 Finally, a private subdirectory will also be created, if appropriate,
478 under <varname>libdir</varname> for dynamically loadable modules.
486 <term><option>--with-includes=<replaceable>DIRECTORIES</></option></term>
489 <replaceable>DIRECTORIES</> is a colon-separated list of
490 directories that will be added to the list the compiler
491 searches for header files. If you have optional packages
492 (such as GNU <application>Readline</>) installed in a non-standard location
493 you have to use this option and probably the corresponding
494 <option>--with-libraries</> option.
497 Example: <literal>--with-includes=/opt/gnu/include:/usr/sup/include</>.
503 <term><option>--with-libraries=<replaceable>DIRECTORIES</></option></term>
506 <replaceable>DIRECTORIES</> is a colon-separated list of
507 directories to search for libraries. You will probably have
508 to use this option (and the corresponding
509 <option>--with-includes</> option) if you have packages
510 installed in non-standard locations.
513 Example: <literal>--with-libraries=/opt/gnu/lib:/usr/sup/lib</>.
519 <term><option>--enable-locale</option></term>
522 Enables locale support. There is a performance penalty
523 associated with locale support, but if you are not in an
524 English-speaking environment you will most likely need this.
530 <term><option>--enable-recode</option></term>
533 Enables single-byte character set recode support. See
534 <![%flattext-install-include[the <citetitle>Administrator's Guide</citetitle>]]>
535 <![%flattext-install-ignore[<xref linkend="recode">]]> about this feature.
541 <term><option>--enable-multibyte</option></term>
544 Allows the use of multibyte character encodings. This is
545 primarily for languages like Japanese, Korean, and Chinese.
547 <![%flattext-install-include[the <citetitle>Administrator's Guide</citetitle>]]>
548 <![%flattext-install-ignore[<xref linkend="multibyte">]]>
555 <term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term>
558 Enables Native Language Support (<acronym>NLS</acronym>), that is, the ability
559 to display a program's message in a language other than
560 English. <replaceable>LANGUAGES</replaceable> is a space
561 separated list of codes of the languages that you want
562 supported. (The intersection between your list and the set
563 of actually provided translations will be computed
564 automatically.) If you do not specify it, then all available
565 translations are installed.
569 The list of provided translations should be shown somewhere.
573 To use this option, you will need an implementation of the
574 <application>gettext</> API. Some operating systems have this built-in
575 (e.g., <systemitem class="osname">Linux</>, <systemitem class="osname">NetBSD</>, <systemitem class="osname">Solaris</>), for other systems you can download
576 an add-on package from here: <ulink
577 url="http://www.postgresql.org/~petere/gettext.html"
578 ><systemitem class="resource">http://www.postgresql.org/~petere/gettext.html</></ulink>. If
579 you are using the <application>gettext</> implementation in the GNU C library
580 then you will additionally need the <productname>GNU gettext</productname> package for
581 some utility programs. For any of the other implementations
582 you will not need it.
586 The download location should be moved.
593 <term><option>--with-pgport=<replaceable>NUMBER</></option></term>
596 Set <replaceable>NUMBER</> as the default port number for
597 server and clients. The default is 5432. The port can always
598 be changed later on, but if you specify it here then both
599 server and clients will have the same default compiled in,
600 which can be very convenient.
606 <term><option>--with-CXX</option></term>
609 Build the C++ interface library.
615 <term><option>--with-perl</option></term>
618 Build the Perl interface module. The Perl interface
619 will be installed at the usual place for Perl modules
620 (typically under <filename>/usr/lib/perl</filename>), so you
621 must have root access to perform the installation step (see
622 <xref linkend="install">). You need to have Perl 5 installed to
629 <term><option>--with-python</option></term>
632 Build the Python interface module. You need to have root
633 access to be able to install the Python module at its default
635 (<filename>/usr/lib/python<replaceable>x</>.<replaceable>y</></>).
636 To be able to use this option, you must have Python installed
637 and your system needs to support shared libraries. If you
638 instead want to build a new complete interpreter binary, you
639 will have to do it manually.
645 <term><option>--with-tcl</option></term>
648 Builds components that require Tcl/Tk, which are
649 <application>libpgtcl</>, <application>pgtclsh</>,
650 <application>pgtksh</application>, <application>PgAccess</>,
651 and <application>PL/Tcl</>. But see below about
652 <option>--without-tk</>.
658 <term><option>--without-tk</option></term>
661 If you specify <option>--with-tcl</> and this option, then
662 programs that require <productname>Tk</>
663 (<application>pgtksh</> and <application>PgAccess</>) will be
670 <term><option>--with-tclconfig=<replaceable>DIRECTORY</replaceable></option></term>
671 <term><option>--with-tkconfig=<replaceable>DIRECTORY</replaceable></option></term>
674 Tcl/Tk installs the files <filename>tclConfig.sh</filename> and
675 <filename>tkConfig.sh</filename> which contain certain
676 configuration information that is needed to build modules
677 interfacing to Tcl or Tk. These files are normally found
678 automatically at their well-known location, but if you want to
679 use a different version of Tcl or Tk you can specify the
680 directory where to find them.
686 <term><option>--enable-pltcl-unknown</option></term>
689 Enables enables PL/Tcl unknown support.
695 <term><option>--enable-pltcl-utf</option></term>
698 Enables enables PL/Tcl <function>Tcl_UtfToExternal</> and <function>Tcl_ExternalToUtf</>
699 conversion support. These functions needed for Tcl versions 8.1
700 and above for proper handling of 8-bit characters.
706 <term><option>--enable-odbc</option></term>
709 Build the ODBC driver package.
715 <term><option>--with-odbcinst=<replaceable>DIRECTORY</></option></term>
718 Specifies the directory where the ODBC driver will expect its
719 <filename>odbcinst.ini</> configuration file. The default is
720 <filename>/usr/local/pgsql/etc</filename> or whatever you
721 specified as <option>--sysconfdir</option>. A default file
722 will be installed there. If you intend to share the
723 <filename>odbcinst.ini</> file between several ODBC drivers
724 then you may want to use this option.
730 <term><option>--with-krb4=<replaceable>DIRECTORY</></option></term>
731 <term><option>--with-krb5=<replaceable>DIRECTORY</></option></term>
734 Build with support for Kerberos authentication. You can use
735 either Kerberos version 4 or 5, but not both. The
736 <replaceable>DIRECTORY</> argument specifies the root
737 directory of the Kerberos installation;
738 <filename>/usr/athena</> is assumed as default. If the
739 relevant headers files and libraries are not under a common
740 parent directory, then you must use the
741 <option>--with-includes</> and <option>--with-libraries</>
742 options in addition to this option. If, on the other hand,
743 the required files are in a location that is searched by
744 default (e.g., <filename>/usr/lib</>), then you can leave off
749 <filename>configure</> will check for the required header
750 files and libraries to make sure that your Kerberos
751 installation is sufficient before proceeding.
757 <term><option>--with-krb-srvnam=<replaceable>NAME</></option></term>
760 The name of the Kerberos service principal.
761 <literal>postgres</literal> is the default. There's probably no
762 reason to change this.
769 <primary>OpenSSL</primary>
770 <seealso>SSL</seealso>
773 <term><option>--with-openssl=<replaceable>DIRECTORY</></option></term>
776 Build with support for <acronym>SSL</> (encrypted) connections.
777 This requires the <productname>OpenSSL</> package to be installed.
778 The <replaceable>DIRECTORY</> argument specifies the
779 root directory of the <productname>OpenSSL</> installation; the
780 default is <filename>/usr/local/ssl</>.
784 <filename>configure</> will check for the required header
785 files and libraries to make sure that your <productname>OpenSSL</>
786 installation is sufficient before proceeding.
792 <term><option>--with-java</option></term>
795 Build the <acronym>JDBC</acronym> driver and associated Java
796 packages. This option requires
797 <application>Ant</application> to be installed (as well as a
798 <acronym>JDK</acronym>, of course). Refer to the
799 <acronym>JDBC</acronym> driver documentation in the
800 <citetitle>Programmer's Guide</citetitle> for more
807 <term><option>--enable-syslog</option></term>
810 Enables the <productname>PostgreSQL</> server to use the
811 <systemitem>syslog</> logging facility. (Using this option does not mean
812 that you must log with <systemitem>syslog</> or even that it will be done
813 by default, it simply makes it possible to turn this option
820 <term><option>--enable-debug</option></term>
823 Compiles all programs and libraries with debugging symbols.
824 This means that you can run the programs through a debugger
825 to analyze problems. This enlarges the size of the installed
826 executables considerably, and on non-GCC compilers it usually
827 also disables compiler optimization, causing slowdowns. However,
828 having the symbols available is extremely helpful for dealing
829 with any problems that may arise. Currently, this option is
830 considered of marginal value for production installations, but
831 you should have it on if you are doing development work or
832 running a beta version.
838 <term><option>--enable-cassert</option></term>
841 Enables <firstterm>assertion</> checks in the server, which test for
842 many <quote>can't happen</> conditions. This is invaluable for
843 code development purposes, but the tests slow things down a little.
844 Also, having the tests turned on won't necessarily enhance the
845 stability of your server! The assertion checks are not categorized
846 for severity, and so what might be a relatively harmless bug will
847 still lead to postmaster restarts if it triggers an assertion
848 failure. Currently, this option is not recommended for
849 production use, but you should have it on for development work
850 or when running a beta version.
858 If you prefer a C or C++ compiler different from the one
859 <filename>configure</filename> picks then you can set the
860 environment variables <envar>CC</> and <envar>CXX</envar>,
861 respectively, to the program of your choice. Similarly, you can
862 override the default compiler flags with the <envar>CFLAGS</envar>
863 and <envar>CXXFLAGS</envar> variables. For example:
865 <userinput>env CC=/opt/bin/gcc CFLAGS='-02 -pipe' ./configure</>
874 To start the build, type
876 <userinput>gmake</userinput>
878 (Remember to use <acronym>GNU</> <application>make</>.) The build
879 can take anywhere from 5 minutes to half an hour. The last line
882 All of PostgreSQL is successfully made. Ready to install.
888 <title>Regression Tests</title>
891 <primary>regression test</primary>
895 If you want to test the newly built server before you install it,
896 you can run the regression tests at this point. The regression
897 tests are a test suite to verify that <productname>PostgreSQL</>
898 runs on your machine in the way the developers expected it
901 <userinput>gmake check</userinput>
903 It is possible that some tests fail, due to differences in error
904 message wording or floating point results.
905 <![%flattext-install-include[The file
906 <filename>src/test/regress/README</> and the
907 <citetitle>Administrator's Guide</citetitle> contain]]>
908 <![%flattext-install-ignore[<xref linkend="regress"> contains]]>
909 detailed information about interpreting the test results. You can
910 repeat this test at any later time by issuing the same command.
915 <title>Installing The Files</title>
919 If you are upgrading an existing system and are going to install
920 the new files over the old ones then you should have backed up
921 your data and shut down the old server by now, as explained in
922 <xref linkend="install-upgrading"> above.
927 To install <productname>PostgreSQL</> enter
929 <userinput>gmake install</userinput>
931 This will install files into the directories that were specified
932 in <xref linkend="configure">. Make sure that you have appropriate
933 permissions to write into that area. Normally you need to do this
934 step as root. Alternatively, you could create the target
935 directories in advance and arrange for appropriate permissions to
940 If you built the Perl or Python interfaces and you were not the
941 root user when you executed the above command then that part of
942 the installation probably failed. In that case you should become
943 the root user and then do
945 <userinput>gmake -C src/interfaces/perl5 install</userinput>
946 <userinput>gmake -C src/interfaces/python install</userinput>
948 Due to a quirk in the Perl build environment the first command
949 will actually rebuild the complete interface and then install it.
950 This is not harmful, just unusual. If you do not have superuser
951 access you are on your own: you can still take the required files
952 and place them in other directories where Perl or Python can find
953 them, but how to do that is left as an exercise.
957 The standard install installs only the header files needed for client
958 application development. If you plan to do any server-side program
959 development (such as custom functions or data types written in C),
960 then you may want to install the entire <productname>PostgreSQL</>
961 include tree into your target include directory. To do that, enter
963 <userinput>gmake install-all-headers</userinput>
965 This adds a megabyte or two to the install footprint, and is only
966 useful if you don't plan to keep the whole source tree around for
967 reference. (If you do, you can just use the source's include
968 directory when building server-side software.)
972 <title>Client-only installation</title>
974 If you want to install only the client applications and
975 interface libraries, then you can use these commands:
977 <userinput>gmake -C src/bin install</>
978 <userinput>gmake -C src/interfaces install</>
979 <userinput>gmake -C doc install</>
985 To undo the installation use the command <command>gmake
986 uninstall</>. However, this will not remove the Perl and Python
987 interfaces and it will not remove any directories.
993 After the installation you can make room by removing the built
994 files from the source tree with the <command>gmake clean</>
995 command. This will preserve the choices made by the configure
996 program, so that you can rebuild everything with <command>gmake</>
997 later on. To reset the source tree to the state in which it was
998 distributed, use <command>gmake distclean</>. If you are going to
999 build for several platforms from the same source tree you must do
1000 this and re-configure for each build.
1005 <sect1 id="install-post">
1006 <title>Post-Installation Setup</title>
1009 <title>Shared Libraries</title>
1012 <primary>shared libraries</primary>
1016 On some systems that have shared libraries (which most systems do)
1017 you need to tell your system how to find the newly installed
1018 shared libraries. The systems on which this is
1019 <emphasis>not</emphasis> necessary include <systemitem
1020 class="osname">BSD/OS</>, <systemitem class="osname">FreeBSD</>,
1021 <systemitem class="osname">HP-UX</>, <systemitem
1022 class="osname">IRIX</>, <systemitem class="osname">Linux</>,
1023 <systemitem class="osname">NetBSD</>, <systemitem
1024 class="osname">OpenBSD</>, <systemitem class="osname">Tru64
1025 UNIX</> (formerly <systemitem class="osname">Digital UNIX</>), and
1026 <systemitem class="osname">Solaris</>.
1030 The method to set the shared library search path varies between
1031 platforms, but the most widely usable method is to set the
1032 environment variable <envar>LD_LIBRARY_PATH</> like so: In Bourne
1033 shells (<command>sh</>, <command>ksh</>, <command>bash</>, <command>zsh</>)
1035 LD_LIBRARY_PATH=/usr/local/pgsql/lib
1036 export LD_LIBRARY_PATH
1038 or in <command>csh</> or <command>tcsh</>
1040 setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
1042 Replace <literal>/usr/local/pgsql/lib</> with whatever you set
1043 <option><literal>--libdir</></> to in <xref linkend="configure">.
1044 You should put these commands into a shell start-up file such as
1045 <filename>/etc/profile</> or <filename>~/.bash_profile</>. Some
1046 good information about the caveats associated with the method can
1048 url="http://www.visi.com/~barr/ldpath.html">http://www.visi.com/~barr/ldpath.html</ulink>.
1052 On some systems it might be preferable to set the environment
1053 variable <envar>LD_RUN_PATH</envar> <emphasis>before</emphasis>
1059 On Linux systems the following is the preferred method, but you
1060 must have root access. Edit the file <filename>/etc/ld.so.conf</>
1063 <filename>/usr/local/pgsql/lib</>
1065 Then run command <command>/sbin/ldconfig</>.
1069 If in doubt, refer to the manual pages of your system (perhaps
1070 <command>ld.so</command> or <command>rld</command>). If you later
1071 on get a message like
1073 psql: error in loading shared libraries
1074 libpq.so.2.1: cannot open shared object file: No such file or directory
1076 then this step was necessary. Simply take care of it then.
1081 <title>Environment Variables</title>
1084 <primary><envar>PATH</envar></primary>
1088 If you installed into <filename>/usr/local/pgsql</> or some other
1089 location that is not searched for programs by default, you need to
1090 add <filename>/usr/local/pgsql/bin</> (or what you set
1091 <option><literal>--bindir</></> to in <xref linkend="configure">)
1092 into your <envar>PATH</>. To do this, add the following to your
1093 shell start-up file, such as <filename>~/.bash_profile</> (or
1094 <filename>/etc/profile</>, if you want it to affect every user):
1096 PATH=$PATH:/usr/local/pgsql/bin
1098 If you are using <command>csh</> or <command>tcsh</>, then use this command:
1100 set path = ( /usr/local/pgsql/bin $path )
1106 <primary><envar>MANPATH</envar></primary>
1107 <seealso>man pages</seealso>
1109 To enable your system to find the <application>man</>
1110 documentation, you need to add a line like the following to a
1111 shell start-up file:
1113 MANPATH=$MANPATH:/usr/local/pgsql/man
1118 The environment variables <envar>PGHOST</> and <envar>PGPORT</>
1119 specify to client applications the host and port of the database
1120 server, overriding the compiled-in defaults. If you are going to
1121 run client applications remotely then it is convenient if every
1122 user that plans to use the database sets <envar>PGHOST</>, but it
1123 is not required and the settings can be communicated via command
1124 line options to most client programs.
1130 <![%flattext-install-include;[
1131 <sect1 id="install-getting-started">
1132 <title>Getting Started</title>
1135 The following is a quick summary of how to get <productname>PostgreSQL</> up and
1136 running once installed. The <citetitle>Administrator's Guide</>
1137 contains more information.
1143 Create a user account for the <productname>PostgreSQL</>
1144 server. This is the user the server will run as. For production
1145 use you should create a separate, unprivileged account
1146 (<quote>postgres</> is commonly used). If you do not have root
1147 access or just want to play around, your own user account is
1148 enough, but running the server as root is a security risk and
1151 <userinput>adduser postgres</>
1158 Create a database installation with the <command>initdb</>
1159 command. To run <command>initdb</> you must be logged in to your
1160 <productname>PostgreSQL</> server account. It will not work as
1163 root# <userinput>mkdir /usr/local/pgsql/data</>
1164 root# <userinput>chown postgres /usr/local/pgsql/data</>
1165 root# <userinput>su - postgres</>
1166 postgres$ <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
1171 The <option>-D</> option specifies the location where the data
1172 will be stored. You can use any path you want, it does not have
1173 to be under the installation directory. Just make sure that the
1174 server account can write to the directory (or create it, if it
1175 doesn't already exist) before starting <command>initdb</>, as
1182 The previous step should have told you how to start up the
1183 database server. Do so now. The command should look something
1186 /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
1188 This will start the server in the foreground. To put the server
1189 in the background use something like
1191 nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
1192 </dev/null >>server.log 2>&1 </dev/null &
1197 To stop a server running in the background you can type
1199 kill `cat /usr/local/pgsql/data/postmaster.pid`
1204 In order to allow TCP/IP connections (rather than only Unix
1205 domain socket ones) you need to pass the <option>-i</> option to
1206 <filename>postmaster</>.
1214 <userinput>createdb testdb</>
1218 <userinput>psql testdb</>
1220 to connect to that database. At the prompt you can enter SQL
1221 commands and start experimenting.
1227 <sect1 id="install-whatnow">
1228 <title>What Now?</title>
1234 The <citetitle>Tutorial</> should be your first reading if you
1235 are completely new to <acronym>SQL</> databases. It should have
1237 <filename>/usr/local/pgsql/doc/html/tutorial.html</> unless you
1238 changed the installation directories.
1244 If you are familiar with database concepts then you want to
1245 proceed with the <citetitle>Administrator's Guide</citetitle>,
1246 which contains information about how to set up the database
1247 server, database users, and authentication. It can be found at
1248 <filename>/usr/local/pgsql/doc/html/admin.html</>.
1254 Usually, you will want to modify your computer so that it will
1255 automatically start the database server whenever it boots. Some
1256 suggestions for this are in the <citetitle>Administrator's
1263 Run the regression tests against the installed server (using the
1264 sequential test method). If you didn't run the tests before
1265 installation, you should definitely do it now. This is also
1266 explained in the <citetitle>Administrator's Guide</citetitle>.
1273 <!-- do we still ship this? -->
1276 The documentation is also available in Postscript format. If you
1277 have a Postscript printer, or have your machine already set up to
1278 accept Postscript files using a print filter, then to print, for
1279 example the <citetitle>User's Guide</> simply type
1281 cd /usr/local/pgsql/doc
1282 gunzip -c user.ps.gz | lpr
1284 Here is how you might do it if you have <productname>Ghostscript</>
1285 installed on your system and are writing to a Laserjet printer.
1287 gunzip -c user.ps.gz \
1288 | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \
1291 Printer setups can vary wildly from system to system. If in doubt,
1292 consult your manuals or your local expert.
1300 <sect1 id="supported-platforms">
1301 <title>Supported Platforms</title>
1304 <productname>PostgreSQL</> has been verified by the developer
1305 community to work on the platforms listed below. A supported
1306 platform generally means that <productname>PostgreSQL</> builds and
1307 installs according to these instructions and that the regression
1313 If you are having problems with the installation on a supported
1314 platform, please write to <email>pgsql-bugs@postgresql.org</email>
1315 or <email>pgsql-ports@postgresql.org</email>, not to the people
1324 <entry><acronym>OS</acronym></entry>
1325 <entry>Processor</entry>
1326 <entry>Version</entry>
1327 <entry>Reported</entry>
1328 <entry>Remarks</entry>
1333 <entry><systemitem class="osname">AIX 4.3.3</></entry>
1334 <entry><systemitem>RS6000</></entry>
1336 <entry>2001-03-21, Gilles Darold (<email>gilles@darold.net</email>)</entry>
1337 <entry>see also <filename>doc/FAQ_AIX</filename></entry>
1340 <entry><systemitem class="osname">BeOS 5.0.4</></entry>
1341 <entry><systemitem>x86</></entry>
1343 <entry>2001-02-26, Cyril Velter (<email>cyril.velter@libertysurf.fr</email>)</entry>
1344 <entry>requires new BONE networking stack</entry>
1347 <entry><systemitem class="osname">BSD/OS 4.01</></entry>
1348 <entry><systemitem>x86</></entry>
1350 <entry>2001-03-20, Bruce Momjian (<email>pgman@candle.pha.pa.us</email>)</entry>
1354 <entry><systemitem class="osname">FreeBSD 4.3</></entry>
1355 <entry><systemitem>x86</></entry>
1357 <entry>2001-03-19, Vince Vielhaber (<email>vev@hub.org</email>)</entry>
1361 <entry><systemitem class="osname">HP-UX</></entry>
1362 <entry><systemitem>PA-RISC</></entry>
1364 <entry>2001-03-19, 10.20 Tom Lane (<email>tgl@sss.pgh.pa.us</email>),
1365 2001-03-22, 11.00, 11i Giles Lean (<email>giles@nemeton.com.au</email>)</entry>
1366 <entry>32- and 64-bit on 11.00; see also <filename>doc/FAQ_HPUX</filename></entry>
1369 <entry><systemitem class="osname">IRIX 6.5.11</></entry>
1370 <entry><systemitem>MIPS</></entry>
1372 <entry>2001-03-22, Robert Bruccoleri (<email>bruc@acm.org</email>)</entry>
1373 <entry>32-bit compilation model</entry>
1376 <entry><systemitem class="osname">Linux 2.2.x</></entry>
1377 <entry><systemitem>Alpha</></entry>
1379 <entry>2001-01-23, Ryan Kirkpatrick (<email>pgsql@rkirkpat.net</email>)</entry>
1383 <entry><systemitem class="osname">Linux 2.2.x</></entry>
1384 <entry><systemitem>armv4l</></entry>
1386 <entry>2001-02-22, Mark Knox (<email>segfault@hardline.org</email>)</entry>
1390 <entry><systemitem class="osname">Linux 2.0.x</></entry>
1391 <entry><systemitem>MIPS</></entry>
1393 <entry>2001-03-30, Dominic Eidson (<email>sauron@the-infinite.org</email>)</entry>
1394 <entry><productname>Cobalt Qube</></entry>
1397 <entry><systemitem class="osname">Linux 2.2.18</></entry>
1398 <entry><systemitem>PPC74xx</></entry>
1400 <entry>2001-03-19, Tom Lane (<email>tgl@sss.pgh.pa.us</email>)</entry>
1401 <entry>Apple G3</entry>
1404 <entry><systemitem class="osname">Linux</></entry>
1405 <entry><systemitem>S/390</></entry>
1407 <entry>2000-11-17, Neale Ferguson (<email>Neale.Ferguson@softwareAG-usa.com</email>)</entry>
1411 <entry><systemitem class="osname">Linux 2.2.15</></entry>
1412 <entry><systemitem>Sparc</></entry>
1414 <entry>2001-01-30, Ryan Kirkpatrick (<email>pgsql@rkirkpat.net</email>)</entry>
1418 <entry><systemitem class="osname">Linux</></entry>
1419 <entry><systemitem>x86</></entry>
1421 <entry>2001-03-19, Thomas Lockhart (<email>thomas@fourpalms.org</email>)</entry>
1422 <entry>2.0.x, 2.2.x, 2.4.2</entry>
1425 <entry><systemitem class="osname">MacOS X</></entry>
1426 <entry><systemitem>PPC</></entry>
1428 <entry>2000-12-11, Peter Bierman (<email>bierman@apple.com</email>),
1429 2000-12-11, Daniel Luke (<email>dluke@geeklair.net</email>)</entry>
1430 <entry>Darwin (only) Beta-2 or higher</entry>
1433 <entry><systemitem class="osname">NetBSD 1.5</></entry>
1434 <entry><systemitem>Alpha</></entry>
1436 <entry>2001-03-22, Giles Lean (<email>giles@nemeton.com.au</email>)</entry>
1440 <entry><systemitem class="osname">NetBSD 1.5E</></entry>
1441 <entry><systemitem>arm32</></entry>
1443 <entry>2001-03-21, Patrick Welche (<email>prlw1@cam.ac.uk</email>)</entry>
1447 <entry><systemitem class="osname">NetBSD</></entry>
1448 <entry><systemitem>m68k</></entry>
1450 <entry>2000-04-10, Henry B. Hotz (<email>hotz@jpl.nasa.gov</email>)</entry>
1451 <entry>Mac 8xx</entry>
1454 <entry><systemitem class="osname">NetBSD</></entry>
1455 <entry><systemitem>PPC</></entry>
1457 <entry>2001-04-05, Henry B. Hotz (<email>hotz@jpl.nasa.gov</email>)</entry>
1458 <entry>Mac G4</entry>
1461 <entry><systemitem class="osname">NetBSD</></entry>
1462 <entry><systemitem>Sparc</></entry>
1464 <entry>2000-04-05, Matthew Green (<email>mrg@eterna.com.au</email>)</entry>
1465 <entry>32- and 64-bit builds</entry>
1468 <entry><systemitem class="osname">NetBSD 1.5</></entry>
1469 <entry><systemitem>VAX</></entry>
1471 <entry>2001-03-30, Tom I. Helbekkmo (<email>tih@kpnQwest.no</email>)</entry>
1475 <entry><systemitem class="osname">NetBSD 1.5</></entry>
1476 <entry><systemitem>x86</></entry>
1478 <entry>2001-03-23, Giles Lean (<email>giles@nemeton.com.au</email>)</entry>
1482 <entry><systemitem class="osname">OpenBSD 2.8</></entry>
1483 <entry><systemitem>Sparc</></entry>
1485 <entry>2001-03-23, Brandon Palmer (<email>bpalmer@crimelabs.net</email>)</entry>
1489 <entry><systemitem class="osname">OpenBSD 2.8</></entry>
1490 <entry><systemitem>x86</></entry>
1492 <entry>2001-03-21, Brandon Palmer (<email>bpalmer@crimelabs.net</email>)</entry>
1496 <entry><systemitem class="osname">SCO UnixWare 7.1.1</></entry>
1497 <entry><systemitem>x86</></entry>
1499 <entry>2001-03-19, Larry Rosenman (<email>ler@lerctr.org</email>)</entry>
1500 <entry><productname>UDK FS</productname> compiler; see also <filename>doc/FAQ_SCO</filename></entry>
1503 <entry><systemitem class="osname">Solaris 2.7-8</></entry>
1504 <entry><systemitem>Sparc</></entry>
1506 <entry>2001-03-22, Marc Fournier (<email>scrappy@hub.org</email>),
1507 2001-03-25, Justin Clift (<email>justin@postgresql.org</email>)</entry>
1508 <entry>see also <filename>doc/FAQ_Solaris</filename></entry>
1511 <entry><systemitem class="osname">Solaris 2.8</></entry>
1512 <entry><systemitem>x86</></entry>
1514 <entry>2001-03-27, Mathijs Brands (<email>mathijs@ilse.nl</email>)</entry>
1515 <entry>see also <filename>doc/FAQ_Solaris</filename></entry>
1518 <entry><systemitem class="osname">SunOS 4.1.4</></entry>
1519 <entry><systemitem>Sparc</></entry>
1521 <entry>2001-03-23, Tatsuo Ishii (<email>t-ishii@sra.co.jp</email>)</entry>
1525 <entry><systemitem class="osname">Tru64 UNIX</></entry>
1526 <entry><systemitem>Alpha</></entry>
1528 <entry>2001-03-26, Adriaan Joubert (<email>a.joubert@albourne.com</email>)</entry>
1529 <entry>4.0-5.0, <command>cc</> and <command>gcc</></entry>
1532 <entry><systemitem class="osname">Windows NT/2000</> with <application>Cygwin</></entry>
1533 <entry><systemitem>x86</></entry>
1535 <entry>2001-03-16, Jason Tishler (<email>Jason.Tishler@dothill.com</email>)</entry>
1536 <entry>with <application>Cygwin</application> tool set, see <filename>doc/FAQ_MSWIN</filename></entry>
1543 <title>Unsupported Platforms</title>
1545 The following platforms have not been verified to work. Platforms
1546 listed for version 6.3.x and later should also work with
1547 &version;, but we did not receive explicit confirmation of such at
1548 the time this list was compiled. We include these here to let you
1549 know that these platforms <emphasis>could</> be supported if given
1558 <entry><acronym>OS</acronym></entry>
1559 <entry>Processor</entry>
1560 <entry>Version</entry>
1561 <entry>Reported</entry>
1562 <entry>Remarks</entry>
1568 <entry><systemitem class="osname">DGUX 5.4R4.11</></entry>
1569 <entry><systemitem>m88k</></entry>
1571 <entry>1998-03-01, Brian E Gallew (<email>geek+@cmu.edu</email>)</entry>
1572 <entry>6.4 probably OK</entry>
1575 <entry><systemitem class="osname">MkLinux DR1</></entry>
1576 <entry><systemitem>PPC750</></entry>
1578 <entry>2001-04-03, Tatsuo Ishii (<email>t-ishii@sra.co.jp</email>)</entry>
1579 <entry>7.1 needs OS update?</entry>
1582 <entry><systemitem class="osname">NextStep</></entry>
1583 <entry><systemitem>x86</></entry>
1585 <entry>1998-03-01, David Wetzel (<email>dave@turbocat.de</email>)</entry>
1586 <entry>bit rot suspected</entry>
1589 <entry><systemitem class="osname">QNX 4.25</></entry>
1590 <entry><systemitem>x86</></entry>
1592 <entry>2000-04-01, Dr. Andreas Kardos (<email>kardos@repas-aeg.de</email>)</entry>
1593 <entry>Spinlock code needs work. See also <filename>doc/FAQ_QNX4</filename>.</entry>
1596 <entry><systemitem class="osname">SCO OpenServer 5</></entry>
1597 <entry><systemitem>x86</></entry>
1599 <entry>1999-05-25, Andrew Merrill (<email>andrew@compclass.com</>)</entry>
1600 <entry>7.1 should work, but no reports; see also <filename>doc/FAQ_SCO</filename></entry>
1603 <entry><systemitem class="osname">System V R4</></entry>
1604 <entry><systemitem>m88k</></entry>
1605 <entry>6.2.1</entry>
1606 <entry>1998-03-01, Doug Winterburn (<email>dlw@seavme.xroads.com</email>)</entry>
1607 <entry>needs new <acronym>TAS</acronym> spinlock code</entry>
1610 <entry><systemitem class="osname">System V R4</></entry>
1611 <entry><systemitem>MIPS</></entry>
1613 <entry>1998-10-28, Frank Ridderbusch (<email>ridderbusch.pad@sni.de</email>)</entry>
1614 <entry>no 64-bit integer</entry>
1617 <entry><systemitem class="osname">Ultrix</></entry>
1618 <entry><systemitem>MIPS</></entry>
1620 <entry>2001-03-26</entry>
1621 <entry><acronym>TAS</acronym> spinlock code not detected</entry>
1624 <entry><systemitem class="osname">Ultrix</></entry>
1625 <entry><systemitem>VAX</></entry>
1627 <entry>1998-03-01</entry>
1628 <entry>No recent reports. Obsolete?</entry>
1631 <entry><systemitem class="osname">Windows 9x, ME, NT, 2000</> (native)</entry>
1632 <entry><systemitem>x86</></entry>
1634 <entry>2001-03-26, Magnus Hagander (<email>mha@sollentuna.net</email>)</entry>
1636 client-side libraries (<application>libpq</> and <application>psql</>) or ODBC/JDBC, no server-side;
1637 <![%flattext-install-include[see Administrator's Guide]]>
1638 <![%flattext-install-ignore[see <xref linkend="install-win32">]]>