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 Compiler. You need a Standard ("ANSI") C compiler. Recent versions of GCC
38 are recommendable, but PostgreSQL is known to build with a wide variety of
39 compilers from different vendors.
41 Make. Building PostgreSQL requires GNU make; it will not work with other
42 make programs. GNU make is often installed under the name gmake. This
43 document will always refer to it by that name. (On GNU/Linux systems GNU
44 make is the default tool with the name make.) To test for GNU make enter
48 If at all possible you should try to use version 3.76.1 or later. If you
49 need to get GNU make, you can find it at your local GNU mirror site (see
50 http://www.gnu.org/order/ftp.html) or at ftp://ftp.gnu.org/gnu/make.
52 Resources. Check that you have sufficient disk space. You will need about 30
53 MB for the source tree during compilation and about 5 MB for the
54 installation directory. An empty database takes about 1 MB, later it takes
55 about five times the amount of space that a flat text file with the same
56 data would take. If you are going to run the regression tests you will
57 temporarily need an extra 20 MB. Use the df command to check for disk space.
59 ------------------------------------------------------------------------
63 The internal data storage format changes with new releases of PostgreSQL.
64 Therefore, if you are upgrading an existing installation that does not have
65 a version number "7.1.x", you must back up and restore your data as shown
66 here. These instructions assume that your existing installation is under the
67 /usr/local/pgsql directory, and that the data area is in
68 /usr/local/pgsql/data. Substitute your paths appropriately.
70 1. Make sure that your database is not updated during or after the backup.
71 This does not affect the integrity of the backup, but the changed data
72 would of course not be included. If necessary, edit the permissions in
73 the file /usr/local/pgsql/data/pg_hba.conf (or equivalent) to disallow
74 access from everyone except you.
76 2. To dump your database installation, type:
78 pg_dumpall > outputfile
80 If you need to preserve the oids (such as when using them as foreign
81 keys), then use the -o option when running pg_dumpall.
83 Make sure that you use the pg_dumpall command from the version you are
84 currently running. 7.1's pg_dumpall should not be used on older
87 3. If you are installing the new version at the same location as the old
88 one then shut down the old server, at the latest before you install the
91 kill -INT `cat /usr/local/pgsql/data/postmaster.pid`
93 Versions prior to 7.0 do not have this postmaster.pid file. If you are
94 using such a version you must find out the process id of the server
95 yourself, for example by typing ps ax | grep postmaster, and supply it
98 On systems which have PostgreSQL started at boot time, there is
99 probably a startup file that will accomplish the same thing. For
100 example, on a Redhat Linux system one might find that
102 /etc/rc.d/init.d/postgres.init stop
106 4. If you are installing in the same place as the old version then it is
107 also a good idea to move the old installation out of the way, in case
108 you still need it later on. Use a command like this:
110 mv /usr/local/pgsql /usr/local/pgsql.old
112 After you have installed PostgreSQL 7.1, create a new database directory and
113 start the new server. Remember that you must execute these commands while
114 logged in to the special database user account (which you already have if
117 /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/bin
118 /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/bin
120 Finally, restore your data with
122 /usr/local/pgsql/bin/psql -d template1 -f outputfile
126 You can also install the new version in parallel with the old one to
127 decrease the downtime. These topic are discussed at length in the
128 Administrator's Guide, which you are encouraged to read in any case. The
129 pg_upgrade utility can also often be used.
131 ------------------------------------------------------------------------
133 Installation Procedure
137 The first step of the installation procedure to configure the source
138 tree for your system and choose the options you would like. This is
139 done by running the configure script. For a default installation,
144 This script will run a number of tests to guess values for various
145 system dependent variables and detect some quirks of your operating
146 system, and finally creates several files in the build tree to record
149 The default configuration will build the server and utilities, as well
150 as all client applications and interfaces that only require a C
151 compiler. All files will be installed under /usr/local/pgsql by
154 You can customize the build and installation process by giving one or
155 more of the following command line options to configure:
159 Install all files under the directory PREFIX instead of
160 /usr/local/pgsql. The actual files will be installed into various
161 subdirectories; no files will ever be installed directly into the
164 If you have special needs, you can also customize the individual
165 subdirectories with the following options.
167 --exec-prefix=EXEC-PREFIX
169 You can install architecture-dependent files under a different
170 prefix, EXEC-PREFIX, than what PREFIX was set to. This can be
171 useful to share architecture-independent files between hosts. If
172 you omit this, then EXEC-PREFIX is set equal to PREFIX and both
173 architecture dependent and independent files will be installed
174 under the same tree, which is probably what you want.
178 Specifies the directory for executable programs. The default is
179 EXEC-PREFIX/bin, which normally means /usr/local/pgsql/bin.
183 Sets the directory for read-only data files used by the installed
184 programs. The default is PREFIX/share. Note that this has nothing
185 to do with where your database files will be placed.
187 --sysconfdir=DIRECTORY
189 The directory for various configuration files, PREFIX/etc by
194 The location to install libraries and dynamically loadable
195 modules. The default is EXEC-PREFIX/lib.
197 --includedir=DIRECTORY
199 The directory for installing C and C++ header files. The default
204 Documentation files, except "man" pages, will be installed into
205 this directory. The default is PREFIX/doc.
209 The man pages that come with PostgreSQL will be installed under
210 this directory, in their respective manx subdirectories.
213 --with-includes=DIRECTORIES
215 DIRECTORIES is a colon-separated list of directories that will be
216 added to the list the compiler searches for header files. If you
217 have optional packages (such as GNU Readline) installed in a
218 non-standard location you have to use this option and probably the
219 corresponding --with-libraries option.
221 Example: --with-includes=/opt/gnu/include:/usr/sup/include.
223 --with-libraries=DIRECTORIES
225 DIRECTORIES is a colon-separated list of directories to search for
226 libraries. You will probably have to use this option (and the
227 corresponding --with-includes option) if you have packages
228 installed in non-standard locations.
230 Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.
234 Enables locale support. There is a performance penalty associated
235 with locale support, but if you are not in an English-speaking
236 environment you will most likely need this.
240 Enables character set recode support. See doc/README.Charsets for
241 details on this feature.
245 Allows the use of multibyte character encodings. This is primarily
246 for languages like Japanese, Korean, and Chinese. Read
247 doc/README.mb for details.
251 Set NUMBER as the default port number for server and clients. The
252 default is 5432. The port can always be changed later on, but if
253 you specify it here then both server and clients will have the
254 same default compiled in, which can be very convenient.
258 Build the C++ interface library. configure will automatically pick
259 the C++ compiler that goes with the C compiler you are using. It
260 is not recommended or supported to use C and C++ compilers of
261 different origin in the same build.
265 Build the Perl interface module. The Perl interface will be
266 installed at the usual place for Perl modules (typically under
267 /usr/lib/perl), so you must have root access to perform the
268 installation step (see step 4). You need to have Perl 5 installed
273 Build the Python interface module. You need to have root access to
274 be able to install the Python module at its default place
275 (/usr/lib/pythonx.y). To be able to use this option, you must have
276 Python installed and your system needs to support shared
277 libraries. If you instead want to build a new complete interpreter
278 binary, you will have to do it manually.
282 Builds components that require Tcl, which are libpgtcl, pgtclsh,
287 Use the X Window System. If you specified --with-tcl then this
288 will enable the build of modules requiring Tcl/Tk, that is, pgtksh
291 --with-tclconfig=DIRECTORY, --with-tkconfig=DIRECTORY
293 Tcl/Tk installs the files tclConfig.sh and tkConfig.sh which
294 contain certain configuration information that is needed to build
295 modules interfacing to Tcl or Tk. These files are normally found
296 automatically at their well-known location, but if you want to use
297 a different version of Tcl or Tk you can specify the directory
302 Build the ODBC driver package.
304 --with-odbcinst=DIRECTORY
306 Specifies the directory where the ODBC driver will expect its
307 odbcinst.ini configuration file. The default is
308 /usr/local/pgsql/etc or whatever you specified as --sysconfdir. A
309 default file will be installed there.
311 --with-krb4=DIRECTORY, --with-krb5=DIRECTORY
313 Build with suppport for Kerberos authentication. You can use
314 either Kerberos version 4 or 5, but not both. The DIRECTORY
315 argument specifies the root directory of the Kerberos
316 installation; /usr/athena is assumed as default. If the relevant
317 headers files and libraries are not under a common parent
318 directory, then you must use the --with-includes and
319 --with-libraries options in addition to this option. If, on the
320 other hand, the required files are in a location that is searched
321 by default (e.g., /usr/lib), then you can leave off the argument.
323 configure will check for the required header files and libraries
324 to make sure that your Kerberos installation is sufficient before
327 --with-krb-srvnam=NAME
329 The name of the Kerberos service principal. "postgres" is the
330 default. There's probably no reason to change this.
332 --with-krb-srvtab=FILE
334 Specifies the location of the Kerberos server shared key file
335 ("srvtab"). If you are using Kerberos 4, this defaults to
336 /etc/srvtab, with Kerberos 5 to
337 FILE:/usr/local/pgsql/etc/krb5.keytab, or equivalent, depending on
338 what you set --sysconfdir to above.
342 Enables the PostgreSQL server to use the syslog logging facility.
343 (Using this option does not mean that you have to log with syslog
344 or even that it will be done by default, it simply makes it
345 possible to turn this option on at run time.)
349 Compiles all programs and libraries with debugging symbols. This
350 means that you can run the programs through a debugger to analyze
351 problems. This option is not recommended for production use.
353 Environment variables. You can set the CC environment variable to
354 choose the C compiler to use. If you don't then configure will look for
357 CC=/opt/bin/gcc ./configure
361 To start the build, type
365 (Remember to use GNU make.) The build can take anywhere from 5 minutes
366 to half an hour. The last line displayed should be
368 All of PostgreSQL is successfully made. Ready to install.
372 If you want to test the newly built server before you install it, you
373 can run the regression tests at this point. The regression tests are a
374 test suite to verify that PostgreSQL runs on your machine in the way
375 the developers expected it to. Type
377 gmake -C src/test/regress all runcheck
379 It is possible that some tests fail, due to differences in error
380 message wording or floating point results. The file
381 src/test/regress/README and the Administrator's Guide contain detailed
382 information about interpreting the test results. You can repeat this
383 test at any later time by issuing the same command.
385 4. Installing The Files
387 Note: If you are upgrading an existing system and are going
388 to install the new files over the old ones then you should
389 have backed up your data and shut down the old server by now,
390 as explained in the section called If You Are Upgrading
393 To install PostgreSQL enter
397 This will install files into the directories that were specified in
398 step 1. Make sure that you have appropriate permissions to write into
399 that area. Normally you need to do this step as root. Alternatively,
400 you could create the target directories in advance and arrange for
401 appropriate permissions to be granted.
403 If you built the Perl or Python interfaces and you were not the root
404 user when you executed the above command then that part of the
405 installation probably failed. In that case you should become the root
408 gmake -C src/interfaces/perl5 install
409 gmake -C src/interfaces/python install
411 Due to a quirk in the Perl build environment the first command will
412 actually rebuild the complete interface and then install it. This is
413 not harmful, just unusual. If you do not have superuser access you are
414 on your own: you can still take the required files and place them in
415 other directories where Perl or Python can find them, but how to do
416 that is left as an exercise.
418 Client-only installation. If you want to install only the client
419 applications and interfaces, then you can use these commands:
421 gmake -C src/bin install
422 gmake -C src/interfaces install
425 To undo the installation use the command gmake uninstall. However, this
426 will not remove the Perl and Python interfaces and it will not remove
429 Cleanup. After the installation you can make room by removing the built
430 files from the source tree with the gmake clean command. This will preserve
431 the choices made by the configure program, so that you can rebuild
432 everything with gmake later on. To reset the source tree to the state in
433 which it was distributed, use gmake distclean. If you are going to build for
434 several platforms from the same source tree you must do this and
435 re-configure for each build.
437 ------------------------------------------------------------------------
439 Post-Installation Setup
443 On most systems that have shared libraries (which most systems do) you need
444 to tell your system how to find the newly installed shared libraries. How to
445 do this varies between platforms, but the most widely usable method is to
446 set the environment variable LD_LIBRARY_PATH like so: In Bourne shells (sh,
449 LD_LIBRARY_PATH=/usr/local/pgsql/lib
450 export LD_LIBRARY_PATH
454 setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
456 Replace /usr/local/pgsql/lib with whatever you set --libdir to in step 1.
457 You should put these commands into a shell startup file such as /etc/profile
460 On Linux systems the following is the preferred method, but you must have
461 root access. Edit the file /etc/ld.so.conf to add a line
465 Then run command /sbin/ldconfig.
467 If in doubt, refer to the manual pages of your system. If you later on get a
470 psql: error in loading shared libraries
471 libpq.so.2.1: cannot open shared object file: No such file or directory
473 then this step was necessary. Simply take care of it then.
475 ------------------------------------------------------------------------
477 Environment Variables
479 If you installed into /usr/local/pgsql or some other location that is not
480 searched for programs by default, you need to add /usr/local/pgsql/bin (or
481 what you set --bindir to in step 1) into your PATH. To do this, add the
482 following to your shell startup file, such as ~/.bash_profile (or
483 /etc/profile, if you want it to affect every user):
485 PATH=$PATH:/usr/local/pgsql/bin
487 If you are using csh or tcsh, then use this command:
489 set path = ( /usr/local/pgsql/bin path )
491 To enable your system to find the man documentation, you need to add a line
492 like the following to a shell startup file:
494 MANPATH=$MANPATH:/usr/local/pgsql/man
496 The environment variables PGHOST and PGPORT specify to client applications
497 the host and port of the database server, overriding the compiled-in
498 defaults. If you are going to run client applications remotely then it is
499 convenient if every user that plans to use the database sets PGHOST, but it
500 is not required and the settings can be communicated via command line
501 options to most client programs.
503 ------------------------------------------------------------------------
507 The following is a quick summary of how to get PostgreSQL up and running
508 once installed. The Administrator's Guide contains more information.
510 1. Create the PostgreSQL server account. This is the user the server will
511 run as. For production use you should create a separate, unprivileged
512 account ("postgres" is commonly used). If you do not have root access
513 or just want to play around, your own user account is enough, but
514 running the server as root is a security risk and therefore not
519 2. Create a database installation with the initdb command. To run initdb
520 you must be logged in to your PostgreSQL server account. It will not
523 root# mkdir /usr/local/pgsql/data
524 root# chown postgres /usr/local/pgsql/data
526 postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
528 The -D option specifies the location where the data will be stored. You
529 can use any path you want, it does not have to be under the
530 installation directory. Just make sure that the server account can
531 write to the directory (or create it, if it doesn't already exist)
532 before starting initdb, as illustrated here.
534 3. The previous step should have told you how to start up the database
535 server. Do so now. The command should look something like
537 /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
539 This will start the server in the foreground. To put the server in the
540 background use something like
542 nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
543 </dev/null >>server.log 2>&1 </dev/null &
545 To stop a server running in the background you can type
547 kill `cat /usr/local/psgql/data/postmaster.pid`
549 In order to allow TCP/IP connections (rather than only Unix domain
550 socket ones) you need to pass the -i option to postmaster.
552 4. Create a database:
560 to connect to that database. At the prompt you can enter SQL commands
561 and start experimenting.
563 ------------------------------------------------------------------------
567 * The Tutorial should be your first reading if you are completely new to
568 SQL databases. It should have been installed at
569 /usr/local/pgsql/doc/tutorial/index.html unless you changed the
570 installation directories.
572 * If you are familiar with database concepts then you want to proceed
573 with the Administrator's Guide, which contains information about how to
574 set up the database server, database users, and authentication. It can
575 be found at /usr/local/pgsql/doc/admin/index.html.
577 * Usually, you will want to modify your computer so that it will
578 automatically start the database server whenever it boots. Some
579 suggestions for this are in the Administrator's Guide.
581 * Run the regression tests against the installed server (using the
582 sequential test method). If you didn't run the tests before
583 installation, you should definitely do it now. This is also explained
584 in the Administrator's Guide.
586 ------------------------------------------------------------------------
590 At the time of release, PostgreSQL 7.1 has been verified by the developer
591 community to work on the following platforms. A supported platform generally
592 means that PostgreSQL builds and installs according to these instructions
593 and that the regression tests pass, except for minor differences.
595 Note: If you are having problems with the installation on a
596 supported platform, please write to <pgsql-bugs@postgresql.org> or
597 <pgsql-ports@postgresql.org>, not to the people listed here.
599 OS Processor Version Reported Remarks
600 AIX 4.3.2 RS6000 7.0 2000-04-05, Andread Zeugswetter See also
601 (<Andreas.Zeugswetter@telecom.at>) doc/FAQ_AIX
602 BSDI 4.01 x86 7.0 2000-04-04, Bruce Momjian
603 (<pgman@candle.pha.pa.us>)
604 Compaq Tru64 Alpha 7.0 2000-04-11, Andrew McMurry
605 5.0 (<andrew.mcmurry@astro.uio.no>)
606 FreeBSD 4.0 x86 7.0 2000-04-04, Marc Fournier
608 HPUX 9.0x andPA-RISC 7.0 2000-04-12, Tom Lane
609 10.20 (<tgl@sss.pgh.pa.us>)
610 IRIX 6.5.6f MIPS 6.5.3 2000-02-18, Kevin Wheatley MIPSPro
611 (<hxpro@cinesite.co.uk>) 7.3.1.1m N32
613 Linux 2.0.x Alpha 7.0 2000-04-05, Ryan Kirkpatrick with published
614 (<pgsql@rkirkpat.net>) patches
615 Linux 2.2.x armv4l 7.0 2000-04-17, Mark Knox Regression
616 (<segfault@hardline.org>) test needs
618 Linux 2.2.x x86 7.0 2000-03-26, Lamar Owen
619 (<lamar.owen@wgcr.org>)
620 Linux 2.0.x MIPS 7.0 2000-04-13, Tatsuo Ishii Cobalt Qube
621 (<t-ishii@sra.co.jp>)
622 Linux 2.2.5 Sparc 7.0 2000-04-02, Tom Szybist
623 (<szybist@boxhill.com>)
624 LinuxPPC R4 PPC603e 7.0 2000-04-13, Tatsuo Ishii
625 (<t-ishii@sra.co.jp>)
626 mklinux PPC750 7.0 2000-04-13, Tatsuo Ishii
627 (<t-ishii@sra.co.jp>)
628 NetBSD 1.4 arm32 7.0 2000-04-08, Patrick Welche
629 (<prlw1@newn.cam.ac.uk>)
630 NetBSD 1.4U x86 7.0 2000-03-26, Patrick Welche
631 (<prlw1@newn.cam.ac.uk>)
632 NetBSD m68k 7.0 2000-04-10, Henry B. Hotz Mac 8xx
633 (<hotz@jpl.nasa.gov>)
634 NetBSD Sparc 7.0 2000-04-13, Tom I. Helbekkmo
636 QNX 4.25 x86 7.0 2000-04-01, Dr. Andreas Kardos
637 (<kardos@repas-aeg.de>)
638 SCO x86 6.5 1999-05-25, Andrew Merrill
639 OpenServer 5 (<andrew@compclass.com>)
640 SCO UnixWare x86 7.0 2000-04-18, Billy G. Allie See also
641 7 (<Bill.Allie@mug.org>) doc/FAQ_SCO
642 Solaris x86 7.0 2000-04-12, Marc Fournier
644 Solaris Sparc 7.0 2000-04-12, Peter Eisentraut
645 2.5.1-2.7 (<peter_e@gmx.net>), Marc Fournier
647 SunOS 4.1.4 Sparc 7.0 2000-04-13, Tatsuo Ishii
648 (<t-ishii@sra.co.jp>)
649 Windows/Win32x86 7.0 2000-04-02, Magnus Hagander Client-side
650 (<mha@sollentuna.net>) libraries or
653 WinNT/Cygwin x86 7.0 2000-03-30, Daniel Horak with
654 (<horak@sit.plzen-city.cz>) RedHat/Cygnus
657 Unsupported Platforms. The following platforms have not been verified to
658 work. Platforms listed for version 6.3.x and later should also work with
659 7.1, but we did not receive explicit confirmation of such at the time this
660 list was compiled. We include these here to let you know that these
661 platforms could be supported if given some attention.
663 OS Processor Version Reported Remarks
664 BeOS x86 7.0 2000-05-01, Adam Haberlach Client-side
665 (<adam@newsnipple.com>) coming soon?
666 DGUX m88k 6.3 1998-03-01, Brian E Gallew 6.4 probably
667 5.4R4.11 (<geek+@cmu.edu>) OK. Needs new
669 NetBSD 1.3VAX 6.3 1998-03-01, Tom I Helbekkmo 7.0 should
670 (<tih@kpnQwest.no>) work.
671 System V m88k 6.2.1 1998-03-01, Doug Winterburn Needs new TAS
672 R4 4.4 (<dlw@seavme.xroads.com>) spinlock code
673 System V MIPS 6.4 1998-10-28, Frank Ridderbusch No 64-bit
674 R4 (<ridderbusch.pad@sni.de>) integer
675 Ultrix MIPS, VAX 6.x 1998-03-01 No recent
678 MacOS all 6.x 1998-03-01 Not library
681 NextStep x86 6.x 1998-03-01, David Wetzel Client-only
682 (<dave@turbocat.de>) support