1 PostgreSQL Installation Instructions
8 Post-Installation Setup
20 /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
21 /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
22 /usr/local/pgsql/bin/createdb test
23 /usr/local/pgsql/bin/psql test
25 The long version is the rest of this document.
27 ------------------------------------------------------------------------
31 In general, a modern Unix-compatible platform should be able to run
32 PostgreSQL. The platforms that had received explicit testing at the time of
33 release are listed in the section called Supported Platforms below. In the
34 doc subdirectory of the distribution there are several platform-specific FAQ
35 documents you might wish to consult if you are having trouble.
37 The following prerequisites exist for building PostgreSQL:
39 * GNU make is required; other make programs will not work. GNU make is
40 often installed under the name gmake; this document will always refer
41 to it by that name. (On GNU/Linux systems GNU make is the default tool
42 with the name make.) To test for GNU make enter
46 If at all possible you should use version 3.76.1 or later.
48 * You need an ISO/ANSI C compiler. Recent versions of GCC are
49 recommendable, but PostgreSQL is known to build with a wide variety of
50 compilers from different vendors.
54 * The GNU Readline library for comfortable line editing and command
55 history retrieval will automatically be used if found. You might wish
56 to install it before proceeding, but it is not required.
58 * Flex and Bison are not required when building from a released source
59 package because the output files are pre-generated. You will need these
60 programs only when building from a CVS tree or when the actual scanner
61 and parser definition files were changed. If you need them, be sure to
62 get Flex 2.5.4 or later and Bison 1.28 or later. Other yacc programs
63 can sometimes be used, but doing so requires extra efforts and is not
64 recommended. Other lex programs will definitely not work.
66 * To build on Windows NT or Windows 2000 you need the Cygwin and cygipc
67 packages. See the file doc/FAQ_MSWIN for details.
69 If you need to get a GNU package, you can find it at your local GNU mirror
70 site (see http://www.gnu.org/order/ftp.html for a list) or at
71 ftp://ftp.gnu.org/gnu/.
73 Also check that you have sufficient disk space. You will need about 30 MB
74 for the source tree during compilation and about 5 MB for the installation
75 directory. An empty database takes about 1 MB, later it takes about five
76 times the amount of space that a flat text file with the same data would
77 take. If you are going to run the regression tests you will temporarily need
78 an extra 20 MB. Use the df command to check for disk space.
80 ------------------------------------------------------------------------
84 The internal data storage format changes with new releases of PostgreSQL.
85 Therefore, if you are upgrading an existing installation that does not have
86 a version number "7.1.x", you must back up and restore your data as shown
87 here. These instructions assume that your existing installation is under the
88 /usr/local/pgsql directory, and that the data area is in
89 /usr/local/pgsql/data. Substitute your paths appropriately.
91 1. Make sure that your database is not updated during or after the backup.
92 This does not affect the integrity of the backup, but the changed data
93 would of course not be included. If necessary, edit the permissions in
94 the file /usr/local/pgsql/data/pg_hba.conf (or equivalent) to disallow
95 access from everyone except you.
97 2. To dump your database installation, type:
99 pg_dumpall > outputfile
101 If you need to preserve the OIDs (such as when using them as foreign
102 keys), then use the -o option when running pg_dumpall.
104 Make sure that you use the pg_dumpall command from the version you are
105 currently running. 7.1devel's pg_dumpall should not be used on older
108 3. If you are installing the new version at the same location as the old
109 one then shut down the old server, at the latest before you install the
112 kill -INT `cat /usr/local/pgsql/data/postmaster.pid`
114 Versions prior to 7.0 do not have this postmaster.pid file. If you are
115 using such a version you must find out the process id of the server
116 yourself, for example by typing ps ax | grep postmaster, and supply it
119 On systems which have PostgreSQL started at boot time, there is
120 probably a start-up file that will accomplish the same thing. For
121 example, on a Red Hat Linux system one might find that
123 /etc/rc.d/init.d/postgresql stop
127 4. If you are installing in the same place as the old version then it is
128 also a good idea to move the old installation out of the way, in case
129 you still need it later on. Use a command like this:
131 mv /usr/local/pgsql /usr/local/pgsql.old
133 After you have installed PostgreSQL 7.1devel, create a new database
134 directory and start the new server. Remember that you must execute these
135 commands while logged in to the special database user account (which you
136 already have if you are upgrading).
138 /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
139 /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
141 Finally, restore your data with
143 /usr/local/pgsql/bin/psql -d template1 -f outputfile
147 You can also install the new version in parallel with the old one to
148 decrease the downtime. These topics are discussed at length in the
149 Administrator's Guide, which you are encouraged to read in any case.
151 ------------------------------------------------------------------------
153 Installation Procedure
157 The first step of the installation procedure is to configure the source
158 tree for your system and choose the options you would like. This is
159 done by running the configure script. For a default installation simply
164 This script will run a number of tests to guess values for various
165 system dependent variables and detect some quirks of your operating
166 system, and finally creates several files in the build tree to record
169 The default configuration will build the server and utilities, as well
170 as all client applications and interfaces that only require a C
171 compiler. All files will be installed under /usr/local/pgsql by
174 You can customize the build and installation process by supplying one
175 or more of the following command line options to configure:
179 Install all files under the directory PREFIX instead of
180 /usr/local/pgsql. The actual files will be installed into various
181 subdirectories; no files will ever be installed directly into the
184 If you have special needs, you can also customize the individual
185 subdirectories with the following options.
187 --exec-prefix=EXEC-PREFIX
189 You can install architecture-dependent files under a different
190 prefix, EXEC-PREFIX, than what PREFIX was set to. This can be
191 useful to share architecture-independent files between hosts. If
192 you omit this, then EXEC-PREFIX is set equal to PREFIX and both
193 architecture dependent and independent files will be installed
194 under the same tree, which is probably what you want.
198 Specifies the directory for executable programs. The default is
199 EXEC-PREFIX/bin, which normally means /usr/local/pgsql/bin.
203 Sets the directory for read-only data files used by the installed
204 programs. The default is PREFIX/share. Note that this has nothing
205 to do with where your database files will be placed.
207 --sysconfdir=DIRECTORY
209 The directory for various configuration files, PREFIX/etc by
214 The location to install libraries and dynamically loadable
215 modules. The default is EXEC-PREFIX/lib.
217 --includedir=DIRECTORY
219 The directory for installing C and C++ header files. The default
224 Documentation files, except "man" pages, will be installed into
225 this directory. The default is PREFIX/doc.
229 The man pages that come with PostgreSQL will be installed under
230 this directory, in their respective manx subdirectories. The
231 default is PREFIX/man.
233 Note: To reduce the pollution of shared installation
234 locations (such as /usr/local/include), the string
235 "/postgresql" is automatically appended to datadir,
236 sysconfdir, includedir, and docdir, unless the fully expanded
237 directory name already contains the string "postgres" or
238 "pgsql". For example, if you choose /usr/local as prefix, the
239 C header files will be installed in
240 /usr/local/include/postgresql, but if the prefix is
241 /opt/postgres, then they will be in /opt/postgres/include.
243 --with-includes=DIRECTORIES
245 DIRECTORIES is a colon-separated list of directories that will be
246 added to the list the compiler searches for header files. If you
247 have optional packages (such as GNU Readline) installed in a
248 non-standard location you have to use this option and probably the
249 corresponding --with-libraries option.
251 Example: --with-includes=/opt/gnu/include:/usr/sup/include.
253 --with-libraries=DIRECTORIES
255 DIRECTORIES is a colon-separated list of directories to search for
256 libraries. You will probably have to use this option (and the
257 corresponding --with-includes option) if you have packages
258 installed in non-standard locations.
260 Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.
264 Enables locale support. There is a performance penalty associated
265 with locale support, but if you are not in an English-speaking
266 environment you will most likely need this.
270 Enables single-byte character set recode support. See the
271 Administrator's Guide about this feature.
275 Allows the use of multibyte character encodings. This is primarily
276 for languages like Japanese, Korean, and Chinese. Read the
277 Administrator's Guide for details.
281 Set NUMBER as the default port number for server and clients. The
282 default is 5432. The port can always be changed later on, but if
283 you specify it here then both server and clients will have the
284 same default compiled in, which can be very convenient.
288 Build the C++ interface library.
292 Build the Perl interface module. The Perl interface will be
293 installed at the usual place for Perl modules (typically under
294 /usr/lib/perl), so you must have root access to perform the
295 installation step (see step 4). You need to have Perl 5 installed
300 Build the Python interface module. You need to have root access to
301 be able to install the Python module at its default place
302 (/usr/lib/pythonx.y). To be able to use this option, you must have
303 Python installed and your system needs to support shared
304 libraries. If you instead want to build a new complete interpreter
305 binary, you will have to do it manually.
309 Builds components that require Tcl/Tk, which are libpgtcl,
310 pgtclsh, pgtksh, pgaccess, and PL/Tcl. But see below about
315 If you specify --with-tcl and this option, then programs that
316 require Tk (i.e., pgtksh and pgaccess) will be excluded.
318 --with-tclconfig=DIRECTORY, --with-tkconfig=DIRECTORY
320 Tcl/Tk installs the files tclConfig.sh and tkConfig.sh which
321 contain certain configuration information that is needed to build
322 modules interfacing to Tcl or Tk. These files are normally found
323 automatically at their well-known location, but if you want to use
324 a different version of Tcl or Tk you can specify the directory
329 Build the ODBC driver package.
331 --with-odbcinst=DIRECTORY
333 Specifies the directory where the ODBC driver will expect its
334 odbcinst.ini configuration file. The default is
335 /usr/local/pgsql/etc or whatever you specified as --sysconfdir. A
336 default file will be installed there. If you intend to share the
337 odbcinst.ini file between several ODBC drivers then you may want
340 --with-krb4=DIRECTORY, --with-krb5=DIRECTORY
342 Build with support for Kerberos authentication. You can use either
343 Kerberos version 4 or 5, but not both. The DIRECTORY argument
344 specifies the root directory of the Kerberos installation;
345 /usr/athena is assumed as default. If the relevant headers files
346 and libraries are not under a common parent directory, then you
347 must use the --with-includes and --with-libraries options in
348 addition to this option. If, on the other hand, the required files
349 are in a location that is searched by default (e.g., /usr/lib),
350 then you can leave off the argument.
352 configure will check for the required header files and libraries
353 to make sure that your Kerberos installation is sufficient before
356 --with-krb-srvnam=NAME
358 The name of the Kerberos service principal. "postgres" is the
359 default. There's probably no reason to change this.
361 --with-openssl=DIRECTORY
363 Build with support for SSL (encrypted) connections. This requires
364 the OpenSSL package to be installed. The DIRECTORY argument
365 specifies the root directory of the OpenSSL installation; the
366 default is /usr/local/ssl.
368 configure will check for the required header files and libraries
369 to make sure that your OpenSSL installation is sufficient before
374 Enables the PostgreSQL server to use the syslog logging facility.
375 (Using this option does not mean that you must log with syslog or
376 even that it will be done by default, it simply makes it possible
377 to turn this option on at run time.)
381 Compiles all programs and libraries with debugging symbols. This
382 means that you can run the programs through a debugger to analyze
383 problems. This option is not recommended for production use.
385 If you prefer a C or C++ compiler different from the one configure
386 picks then you can set the environment variables CC and CXX,
387 respectively, to the program of your choice. Similarly, you can
388 override the default compiler flags with the CFLAGS and CXXFLAGS
389 variables. For example:
391 env CC=/opt/bin/gcc CFLAGS='-02 -pipe' ./configure
395 To start the build, type
399 (Remember to use GNU make.) The build can take anywhere from 5 minutes
400 to half an hour. The last line displayed should be
402 All of PostgreSQL is successfully made. Ready to install.
406 If you want to test the newly built server before you install it, you
407 can run the regression tests at this point. The regression tests are a
408 test suite to verify that PostgreSQL runs on your machine in the way
409 the developers expected it to. Type
413 It is possible that some tests fail, due to differences in error
414 message wording or floating point results. The file
415 src/test/regress/README and the Administrator's Guide contain detailed
416 information about interpreting the test results. You can repeat this
417 test at any later time by issuing the same command.
419 4. Installing The Files
421 Note: If you are upgrading an existing system and are going
422 to install the new files over the old ones then you should
423 have backed up your data and shut down the old server by now,
424 as explained in the section called If You Are Upgrading
427 To install PostgreSQL enter
431 This will install files into the directories that were specified in
432 step 1. Make sure that you have appropriate permissions to write into
433 that area. Normally you need to do this step as root. Alternatively,
434 you could create the target directories in advance and arrange for
435 appropriate permissions to be granted.
437 If you built the Perl or Python interfaces and you were not the root
438 user when you executed the above command then that part of the
439 installation probably failed. In that case you should become the root
442 gmake -C src/interfaces/perl5 install
443 gmake -C src/interfaces/python install
445 Due to a quirk in the Perl build environment the first command will
446 actually rebuild the complete interface and then install it. This is
447 not harmful, just unusual. If you do not have superuser access you are
448 on your own: you can still take the required files and place them in
449 other directories where Perl or Python can find them, but how to do
450 that is left as an exercise.
452 Client-only installation. If you want to install only the client
453 applications and interfaces, then you can use these commands:
455 gmake -C src/bin install
456 gmake -C src/interfaces install
459 To undo the installation use the command gmake uninstall. However, this
460 will not remove the Perl and Python interfaces and it will not remove
463 After the installation you can make room by removing the built files from
464 the source tree with the gmake clean command. This will preserve the choices
465 made by the configure program, so that you can rebuild everything with gmake
466 later on. To reset the source tree to the state in which it was distributed,
467 use gmake distclean. If you are going to build for several platforms from
468 the same source tree you must do this and re-configure for each build.
470 ------------------------------------------------------------------------
472 Post-Installation Setup
476 On some systems that have shared libraries (which most systems do) you need
477 to tell your system how to find the newly installed shared libraries. The
478 systems on which this is not necessary include FreeBSD, HP/UX, Irix, Linux,
479 NetBSD, OpenBSD, OSF/1 (Digital Unix, Tru64 UNIX), and Solaris.
481 The method to set the shared library search path varies between platforms,
482 but the most widely usable method is to set the environment variable
483 LD_LIBRARY_PATH like so: In Bourne shells (sh, ksh, bash, zsh)
485 LD_LIBRARY_PATH=/usr/local/pgsql/lib
486 export LD_LIBRARY_PATH
490 setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
492 Replace /usr/local/pgsql/lib with whatever you set --libdir to in step 1.
493 You should put these commands into a shell start-up file such as
494 /etc/profile or ~/.bash_profile. Some good information about the caveats
495 associated with the method can be found at
496 http://www.visi.com/~barr/ldpath.html.
498 On some systems it might be preferable to set the environment variable
499 LD_RUN_PATH before building.
501 If in doubt, refer to the manual pages of your system (perhaps ld.so or
502 rld). If you later on get a message like
504 psql: error in loading shared libraries
505 libpq.so.2.1: cannot open shared object file: No such file or directory
507 then this step was necessary. Simply take care of it then.
509 ------------------------------------------------------------------------
511 Environment Variables
513 If you installed into /usr/local/pgsql or some other location that is not
514 searched for programs by default, you need to add /usr/local/pgsql/bin (or
515 what you set --bindir to in step 1) into your PATH. To do this, add the
516 following to your shell start-up file, such as ~/.bash_profile (or
517 /etc/profile, if you want it to affect every user):
519 PATH=$PATH:/usr/local/pgsql/bin
521 If you are using csh or tcsh, then use this command:
523 set path = ( /usr/local/pgsql/bin path )
525 To enable your system to find the man documentation, you need to add a line
526 like the following to a shell start-up file:
528 MANPATH=$MANPATH:/usr/local/pgsql/man
530 The environment variables PGHOST and PGPORT specify to client applications
531 the host and port of the database server, overriding the compiled-in
532 defaults. If you are going to run client applications remotely then it is
533 convenient if every user that plans to use the database sets PGHOST, but it
534 is not required and the settings can be communicated via command line
535 options to most client programs.
537 ------------------------------------------------------------------------
541 The following is a quick summary of how to get PostgreSQL up and running
542 once installed. The Administrator's Guide contains more information.
544 1. Create a user account for the PostgreSQL server. This is the user the
545 server will run as. For production use you should create a separate,
546 unprivileged account ("postgres" is commonly used). If you do not have
547 root access or just want to play around, your own user account is
548 enough, but running the server as root is a security risk and will not
553 2. Create a database installation with the initdb command. To run initdb
554 you must be logged in to your PostgreSQL server account. It will not
557 root# mkdir /usr/local/pgsql/data
558 root# chown postgres /usr/local/pgsql/data
560 postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
562 The -D option specifies the location where the data will be stored. You
563 can use any path you want, it does not have to be under the
564 installation directory. Just make sure that the server account can
565 write to the directory (or create it, if it doesn't already exist)
566 before starting initdb, as illustrated here.
568 3. The previous step should have told you how to start up the database
569 server. Do so now. The command should look something like
571 /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
573 This will start the server in the foreground. To put the server in the
574 background use something like
576 nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
577 </dev/null >>server.log 2>&1 </dev/null &
579 To stop a server running in the background you can type
581 kill `cat /usr/local/pgsql/data/postmaster.pid`
583 In order to allow TCP/IP connections (rather than only Unix domain
584 socket ones) you need to pass the -i option to postmaster.
586 4. Create a database:
594 to connect to that database. At the prompt you can enter SQL commands
595 and start experimenting.
597 ------------------------------------------------------------------------
601 * The Tutorial should be your first reading if you are completely new to
602 SQL databases. It should have been installed at
603 /usr/local/pgsql/doc/html/tutorial.htm unless you changed the
604 installation directories.
606 * If you are familiar with database concepts then you want to proceed
607 with the Administrator's Guide, which contains information about how to
608 set up the database server, database users, and authentication. It can
609 be found at /usr/local/pgsql/doc/html/admin.htm.
611 * Usually, you will want to modify your computer so that it will
612 automatically start the database server whenever it boots. Some
613 suggestions for this are in the Administrator's Guide.
615 * Run the regression tests against the installed server (using the
616 sequential test method). If you didn't run the tests before
617 installation, you should definitely do it now. This is also explained
618 in the Administrator's Guide.
620 ------------------------------------------------------------------------
624 PostgreSQL has been verified by the developer community to work on the
625 platforms listed below. A supported platform generally means that PostgreSQL
626 builds and installs according to these instructions and that the regression
629 Note: If you are having problems with the installation on a
630 supported platform, please write to <pgsql-bugs@postgresql.org> or
631 <pgsql-ports@postgresql.org>, not to the people listed here.
633 OS Processor Version Reported Remarks
634 AIX 4.3.2 RS6000 7.0 2000-04-05, Andread Zeugswetter See also
635 (<Andreas.Zeugswetter@telecom.at>) doc/FAQ_AIX
636 BSDI 4.01 x86 7.0 2000-04-04, Bruce Momjian
637 (<pgman@candle.pha.pa.us>)
638 Compaq Tru64 Alpha 7.0 2000-04-11, Andrew McMurry
639 5.0 (<andrew.mcmurry@astro.uio.no>)
640 FreeBSD 4.0 x86 7.0 2000-04-04, Marc Fournier
642 HPUX 9.0x andPA-RISC 7.0 2000-04-12, Tom Lane See also
643 10.20 (<tgl@sss.pgh.pa.us>) doc/FAQ_HPUX
644 IRIX 6.5.6f MIPS 6.5.3 2000-02-18, Kevin Wheatley MIPSPro
645 (<hxpro@cinesite.co.uk>) 7.3.1.1m N32
647 Linux 2.0.x Alpha 7.0 2000-04-05, Ryan Kirkpatrick with published
648 (<pgsql@rkirkpat.net>) patches
649 Linux 2.2.x armv4l 7.0 2000-04-17, Mark Knox Regression
650 (<segfault@hardline.org>) test needs
652 Linux 2.2.x x86 7.0 2000-03-26, Lamar Owen
653 (<lamar.owen@wgcr.org>)
654 Linux 2.0.x MIPS 7.0 2000-04-13, Tatsuo Ishii Cobalt Qube
655 (<t-ishii@sra.co.jp>)
656 Linux 2.2.5 Sparc 7.0 2000-04-02, Tom Szybist
657 (<szybist@boxhill.com>)
658 LinuxPPC R4 PPC603e 7.0 2000-04-13, Tatsuo Ishii
659 (<t-ishii@sra.co.jp>)
660 mklinux PPC750 7.0 2000-04-13, Tatsuo Ishii
661 (<t-ishii@sra.co.jp>)
662 NetBSD 1.4 arm32 7.0 2000-04-08, Patrick Welche
663 (<prlw1@newn.cam.ac.uk>)
664 NetBSD 1.4U x86 7.0 2000-03-26, Patrick Welche
665 (<prlw1@newn.cam.ac.uk>)
666 NetBSD m68k 7.0 2000-04-10, Henry B. Hotz Mac 8xx
667 (<hotz@jpl.nasa.gov>)
668 NetBSD Sparc 7.0 2000-04-13, Tom I. Helbekkmo
670 QNX 4.25 x86 7.0 2000-04-01, Dr. Andreas Kardos See also
671 (<kardos@repas-aeg.de>) doc/FAQ_QNX4
672 SCO x86 6.5 1999-05-25, Andrew Merrill See also
673 OpenServer 5 (<andrew@compclass.com>) doc/FAQ_SCO
674 SCO UnixWare x86 7.0 2000-04-18, Billy G. Allie See also
675 7 (<Bill.Allie@mug.org>) doc/FAQ_SCO
676 Solaris x86 7.0 2000-04-12, Marc Fournier
678 Solaris Sparc 7.0 2000-04-12, Peter Eisentraut
679 2.5.1-2.7 (<peter_e@gmx.net>), Marc Fournier
681 SunOS 4.1.4 Sparc 7.0 2000-04-13, Tatsuo Ishii
682 (<t-ishii@sra.co.jp>)
683 Windows/Win32x86 7.0 2000-04-02, Magnus Hagander Client-side
684 (<mha@sollentuna.net>) libraries or
687 WinNT/Cygwin x86 7.0 2000-03-30, Daniel Horak with
688 (<horak@sit.plzen-city.cz>) RedHat/Cygnus
691 Unsupported Platforms. The following platforms have not been verified to
692 work. Platforms listed for version 6.3.x and later should also work with
693 7.1devel, but we did not receive explicit confirmation of such at the time
694 this list was compiled. We include these here to let you know that these
695 platforms could be supported if given some attention.
697 OS Processor Version Reported Remarks
698 BeOS x86 7.0 2000-05-01, Adam Haberlach Client-side
699 (<adam@newsnipple.com>) coming soon?
700 DGUX m88k 6.3 1998-03-01, Brian E Gallew 6.4 probably
701 5.4R4.11 (<geek+@cmu.edu>) OK. Needs new
703 NetBSD 1.3VAX 6.3 1998-03-01, Tom I Helbekkmo 7.0 should
704 (<tih@kpnQwest.no>) work.
705 System V m88k 6.2.1 1998-03-01, Doug Winterburn Needs new TAS
706 R4 4.4 (<dlw@seavme.xroads.com>) spinlock code
707 System V MIPS 6.4 1998-10-28, Frank Ridderbusch No 64-bit
708 R4 (<ridderbusch.pad@sni.de>) integer
709 Ultrix MIPS, VAX 6.x 1998-03-01 No recent
712 MacOS all 6.x 1998-03-01 Not library
715 NextStep x86 6.x 1998-03-01, David Wetzel Client-only
716 (<dave@turbocat.de>) support