1 POSTGRESQL INSTALLATION INSTRUCTIONS
2 Copyright (c) 1997 Regents of the University of California
4 This is file /usr/src/pgsql/INSTALL. It contains notes on how to install
5 PostgreSQL v6.2. Up to date information on PostgreSQL may be found at
6 http://www.postgresql.org.
8 PostgreSQL is an RDBMS database server. It is not completely ANSI SQL
9 compliant, but with each release it gets closer.
11 PostgreSQL, formerly called Postgres95, is a derivative of Postgres 4.2
12 (the last release of the UC Berkeley research project). For copyright
13 terms for PostgreSQL, please see the file named COPYRIGHT. This version
14 was developed by a team of developers on the postgres developers mailing
15 list. Version 1 (through 1.01) was developed by Jolly Chen and Andrew
18 The installation notes below assume the following (except where noted):
19 - Commands are Unix-compatible. See note below.
20 - Defaults are used except where noted.
21 - User postgres is the postgres superuser.
22 - The source path is /usr/src/pgsql (other paths are possible).
23 - The runtime path is /usr/local/pgsql (other paths are possible).
25 Commands were tested on RedHat Linux version 4.0 using the bash shell.
26 Except where noted, they will probably work on most systems. Commands
27 like ps and tar vary wildly on what options you should use on each
28 platform. USE COMMON SENSE before typing in these commands.
30 Our Makefiles require GNU make (called gmake in this document) and
31 also assume that "install" accepts BSD options. The INSTALL
32 variable in the Makefiles is set to the BSD-compatible version of
33 install. On some systems, you will have to find a BSD-compatible
34 install command (eg. bsdinst, which comes with the MIT X Window System
38 REQUIREMENTS TO RUN POSTGRESQL
39 ------------------------------
41 PostgreSQL has been tested on the following platforms:
43 aix IBM on AIX 3.2.5 or 4.x
44 alpha DEC Alpha AXP on Digital Unix 2.0, 3.2, 4.0
45 BSD44_derived OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
46 bsdi BSD/OS 2.0, 2.01, 2.1, 3.0
48 hpux HP PA-RISC on HP-UX 9.0, 10
49 i386_solaris i386 Solaris
50 irix5 SGI MIPS on IRIX 5.3
51 linux Intel x86 on Linux 2.0 and Linux ELF
54 (For non-ELF Linux, see LINUX_ELF below).
56 sparc_solaris SUN SPARC on Solaris 2.4, 2.5, 2.5.1
57 sunos4 SUN SPARC on SunOS 4.1.3
58 svr4 Intel x86 on Intel SVR4 and MIPS
59 ultrix4 DEC MIPS on Ultrix 4.4
61 PostgreSQL has known problems/bugs on the following platforms:
63 nextstep Motorola MC68K or Intel x86 on NeXTSTEP 3.2
65 PostgreSQL is also known to work on a number of other platforms that the
66 authors have not personally tested.
68 You should have at least 8 MB of memory and at least 45 MB of disk space
69 to hold the source, binaries, and user databases. After installation
70 you may reduce this to about 3 Mbytes plus space for user databases.
72 To those doing a fresh install or upgrading from previous releases of
74 ----------------------------------------------
76 1) Read any last minute information and platform specific porting
77 notes. There are some platform specific notes at the end of this
78 file for Ultrix4.x, Linux, BSD/OS and NeXT. There are other
79 files in directory /usr/src/pgsql/doc, including files FAQ-Irix
80 and FAQ-Linux. Also look in directory ftp://ftp.postgresql.org/pub.
81 If there is a file called INSTALL in this directory then this
82 file will contain the latest installation information.
84 Please note that a "tested" platform in the list given earlier
85 simply means that someone went to the effort at some point of making
86 sure that a PostgreSQL distribution would compile and run on this
87 platform without modifying the code. Since the current developers
88 will not have access to all of these platforms, some of them may not
89 compile cleanly and pass the regression tests in the current
90 release due to minor problems. Any such known problems and their
91 solutions will be posted in ftp://ftp.postgresql.org/pub/INSTALL.
93 2) Create account postgres if it does not already exist.
95 3) Log into account postgres.
97 3a) Check that you have sufficient disk space. You will need about
98 17 Mbytes for /usr/src/pgsql, about 2 Mbytes for /usr/local/pgsql
99 (excluding your database) and 1 Mbyte for an empty database.
100 The database will temporarily grow to about 20 Mbytes during the
101 regression tests. You will also need about 3 Mbytes for the
102 distribution tar file.
104 We therefore recommend that during installation and testing you
105 have well over 20 Mbytes free under /usr/local and another 25 Mbytes
106 free on the disk partition containing your database. Once you
107 delete the source files, tar file and regression database, you
108 will need 2 Mbytes for /usr/local/pgsql, 1 Mbyte for the empty
109 database, plus about five times the space you would require to
110 store your database data in a flat file.
112 To check for disk space, use command "df -k".
114 4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.2.tar.gz from the
115 internet. Store it in your home directory.
117 5) Some platforms use flex. If your system uses flex then make sure
118 you have a good version. Type
121 If the flex command is not found then you probably do not need it.
122 If the version is 2.5.2 or 2.5.4 or greater then you are okay. If it
123 is 2.5.3 or before 2.5.2 then you will have to upgrade flex. You may
124 get it at ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz.
126 If you need flex and don't have it or have the wrong version, then
127 you will be told so when you attempt to compile the program. Feel
128 free to skip this step if you aren't sure you need it. If you do
129 need it then you will be told to install/upgrade flex when you try to
132 To install it, type the following:
134 gunzip -c flex-2.5.4.tar.gz | tar xvf -
136 configure --prefix=/usr
139 # You must be root when typing the next line.
144 This will update files /usr/man/man1/flex.1, /usr/bin/flex,
145 /usr/lib/libfl.a, /usr/include/FlexLexer.h and will add link
146 /usr/bin/flex++ which points to flex.
148 6) If you are upgrading an existing system then back up your database.
149 The database format is liable to change every few weeks with no
150 notice besides a quick comment in the HACKERS mailing list. It is
151 therefore a bad idea to skip this step. Also, do not use the
152 pg_dumpall script from v6.0 or everything will be owned by the
153 postgres super user. Type (with the gunzip line and the following
154 line typed as one line):
156 gunzip -c postgresql-v6.2.tar.gz |
157 tar xvf - src/bin/pg_dump/pg_dumpall
158 chmod a+x src/bin/pg_dump/pg_dumpall
159 src/bin/pg_dump/pg_dumpall > db.out
161 If you wish to preserve object id's (oids), then use the -o
162 option when running pg_dumpall. However, unless you have a
163 special reason for doing this, don't do it.
165 If the pg_dumpall command seems to take a long time and you think
166 it might have died, then, from another terminal, use "ls -l db.out"
167 several times to see if the size of the file is growing.
169 Please note that if you are upgrading from a version prior to
170 Postgres95 v1.09 then you must back up your database, install
171 Postgres95 v1.09, restore your database, then back it up again.
172 You should also read files /usr/src/pgsql/migration/*.
174 You must make sure that your database is not updated in the middle of
175 your backup. If necessary, bring down postmaster, edit the permissions
176 in file /usr/local/pgsql/data/pg_hba.conf to allow only you on, then
177 bring postmaster back up.
179 7) If you are upgrading an existing system then kill the postmaster. Type
180 ps -ax | grep postmaster
181 This should list the process numbers for a number of processes. Type
182 the following line, with "???" replaced by the process id for process
183 "postmaster". (Do not use the id for process "grep postmaster".) Type
185 with "???" modified as indicated.
187 8) If you are upgrading an existing system then move the old directories
188 out of the way. If you are short of disk space then you may have to
189 back up and delete the directories instead. If you do this, save the
190 old database in the /usr/local/pgsql/data directory tree. At a
191 minimum, save file /usr/local/pgsql/data/pg_hba.conf.
201 If you are not using /usr/local/pgsql/data as your data directory
202 (check to see if environment variable PGDATA is set to something
203 else) then you will also want to move this directory in the same
206 9) Make new source and install directories. The actual paths can be
207 different for your installation; be consistant with your configuration
213 chown postgres:postgres pgsql
216 chown postgres:postgres pgsql
219 10) Unzip and untar the new source file. Type
221 gunzip -c ~/postgresql-v6.2.tar.gz | tar xvf -
223 11) Configure the source code for your system. It is this step at which
224 you can specify your actual source path and installation paths for
225 the build process (see the --prefix option below). Type
226 cd /usr/src/pgsql/src
229 The configure program will list the template files available and
230 ask you to choose one. A lot of times, an appropriate template
231 file is chosen for you, and you can just press Enter to accept the
232 default. If the default is not appropriate, then type in the
233 appropriate template file and press Enter. (If you do this, then
234 send email to scrappy@hub.org stating the output of the program
235 './config.guess' and what the template file should be.)
237 Once you have entered the template file, you will be asked a
238 number of questions about your particular configuration. These
239 can be skipped by adding parameters to the configure command above.
240 The following parameters can be tagged onto the end of the configure
243 --prefix=BASEDIR Selects a different base directory for the
244 installation of the PostgreSQL configuration.
245 The default is /usr/local/pgsql.
247 --enable-hba Enables Host Based Authentication
249 --disable-hba Disables Host Based Authentication
251 --enable-locale Enables USE_LOCALE
253 --disable-locale Disables USE_LOCALE
255 --enable-cassert Enables ASSERT_CHECKING
257 --disable-cassert Disables ASSERT_CHECKING
259 The default for ASSERT_CHECKING is normally
260 enabled for development versions and
261 disabled for release versions of PostgreSQL.
263 --with-template=TEMPLATE
264 Use template file TEMPLATE - the template
265 files are assumed to be in the directory
266 src/template, so look there for proper values.
267 (If the configure script cannot find the
268 specified template file, it will ask you for
271 --with-pgport=PORT Sets the port that the postmaster process
272 listens for incoming connections on. The
273 default for this is port 5432.
275 As an example, here is the configure script I use on a Sparc
276 Solaris 2.5 system with /opt/postgres being the install base.
278 % ./configure --prefix=/opt/postgres
279 --with-template=sparc_solaris-gcc --with-pgport=5432
280 --enable-hba --disable-locale
282 Of course, in a real shell, you would type these three lines all
285 12) Compile the program. Type
286 cd /usr/src/pgsql/src
287 gmake all >& make.log &
290 The last line displayed will hopefully be "All of PostgreSQL is
291 successfully made. Ready to install." At this point, or earlier
292 if you wish, type control-C to get out of tail. (If you have
293 problems later on you may wish to examine file make.log for
294 warning and error messages.)
296 If your computer does not have gmake (GNU make) then try running
297 make instead throughout the rest of these notes.
299 Please note that you will probably find a number of warning
300 messages in make.log. Unless you have problems later on, these
301 messages may be safely ignored.
303 If the compiler fails with an error stating that the flex command
304 cannot be found then install flex as described earlier. Next,
305 change directory back to this directory, type "make clean", then
308 13) Install the program. Type
309 cd /usr/src/pgsql/src
310 gmake install >& make.install.log &
311 tail -f make.install.log
313 The last line displayed will be "gmake[1]: Leaving directory
314 `/usr/src/pgsql/src/man'". At this point, or earlier if you wish,
315 type control-C to get out of tail.
317 14) If necessary, tell UNIX how to find your shared libraries. If you
318 are using Linux-ELF do ONE of the following, preferably the first:
320 a) As root, edit file /etc/ld.so.conf. Add line
322 to the file. Then run command /sbin/ldconfig.
324 b) In a bash shell, type
325 export LD_LIBRARY_PATH=/usr/local/pgsql/lib
327 c) In a csh shell, type
328 setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
330 Please note that the above commands may vary wildly for different
331 operating systems. Check the platform specific notes, such as
332 those for Ultrix4.x or and for non-ELF Linux.
334 If, when you create the database, you get the message "pg_id: can't
335 load library 'libpq.so'" then the above step was necessary. Simply
336 do this step, then try to create the database again.
338 15) If it has not already been done, then prepare account postgres
339 for using PostgreSQL. Any account that will use PostgreSQL must
340 be similarily prepared. (The following instructions are for a
341 bash shell. Adapt accordingly for other shells.)
343 Add the following lines to your login shell, ~/.bash_profile:
344 PATH=$PATH:/usr/local/pgsql/bin
345 MANPATH=$MANPATH:/usr/local/pgsql/man
346 PGLIB=/usr/local/pgsql/lib
347 PGDATA=/usr/local/pgsql/data
348 export PATH MANPATH PGLIB PGDATA
350 Make sure that you have defined these variables before continuing
351 with the remaining steps. The easiest way to do this is to type:
352 source ~/.bash_profile
354 16) Create the database. DO NOT DO THE FOLLOWING AS ROOT! This would
355 be a major security hole. Type
358 17) Set up permissions to access the database system. Do this by editing
359 file /usr/local/pgsql/data/pg_hba.conf. The instructions are
360 included in the file. (If your database is not located in the
361 default location, i.e. if PGDATA is set to point elsewhere, then the
362 location of this file will change accordingly.) This file should be
363 made read only again once you are finsihed.
365 If you are upgrading from v6.0 you can copy file pg_hba.conf from
366 your old database on top of the one in your new database, rather than
367 redoing this from scratch.
369 18) If you wish to skip the regression tests then skip to step 21.
370 However, we think skipping the tests is a BAD idea!
372 The file /usr/src/pgsql/src/test/regress/README has detailed
373 instructions for running and interpreting the regression tests.
374 A short version follows here:
376 Start the postmaster in preparation for the regression tests. First,
377 set the timezone for Berkeley, California. On some systems you may do
378 this by setting environment variable TZ. I.e., using bash, type
381 Now start the postmaster daemon running in the background by typing
383 nohup postmaster > regress.log 2>&1 &
385 Run postmaster from your postgres super user account (typically
386 account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
388 19) Run the regression tests. Type
390 cd /usr/src/pgsql/src/test/regress
394 You do not need to type "gmake clean" if this is the first time you
395 are running the tests.
397 You should get on the screen (and also written to file ./regress.out)
398 a series of statements stating which tests passed and which tests
399 failed. Please note that it can be normal for some of the tests to
400 "fail". For the failed tests, use diff to compare the files in
401 directories ./results and ./expected. If float8 failed, type
403 cd /usr/src/pgsql/src/test/regress
404 diff -w expected/float8.out results
406 "Failed" tests may have failed due to slightly different error messages,
407 output formatting, failure to set the timezone correctly for your
408 platform, etc. "Failures" of this type do not indicate a problem with
411 Here is an example from a i686/Linux-ELF platform (this is the platform
412 on which most of the regression tests were generated). No tests failed
413 since this is the v6.2 regression reference platform.
415 Here is an example from the SPARC/Linux-ELF platform. Using the
416 970525 beta version of PostgreSQL v6.2 the following tests "failed".
417 float8 and geometry "failed" due to minor precision differences in
418 floating point numbers. select_views produces massively different output,
419 but the differences are due to minor floating point differences.
421 Conclusion? If you do see failures, try to understand the nature of
422 the differences and then decide if those differences will affect your
423 intended use of PostgreSQL. However, keep in mind that this is likely
424 to be the most solid release of PostgreSQL to date, incorporating many
425 bug fixes from v6.0, and that previous versions of PostgreSQL have been
426 in use successfully for some time now.
428 After running the tests, type
430 cd /usr/src/pgsql/src/test/regress
433 20) Stop the postmaster as described in step 7. Then restore the
434 timezone to it's normal setting. If you changed the timezone by
435 modifying environment variable TZ then one way to do this is to
436 log out of, then back into, account postgres.
438 21) Start the postmaster daemon running. Type
440 nohup postmaster > server.log 2>&1 &
441 Run postmaster from your postgres super user account (typically
442 account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
444 22) If you haven't already done so, this would be a good time to modify
445 your computer so that it will automatically start postmaster whenever
446 you boot your computer.
448 Here are some suggestions on how to do this, contributed by various
451 Whatever you do, postmaster must be run by user postgres, AND NOT BY
452 ROOT. This is why all of the examples below start by switching user
453 (su) to postgres. These commands also take into account the fact
454 that environment variables like PATH and PGDATA may not be set properly.
456 The examples are as follows. Use them with extreme caution.
458 a) Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
459 2.5.1 to contain the following single line:
460 su postgres -c "/usr/local/pgsql/bin/postmaster -S -D
461 /usr/local/pgsql/data"
463 b) In RedHat v4.0 Linux edit file /etc/inittab to contain the
464 following single line:
465 pg:2345:respawn:/bin/su - postgres -c
466 "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
467 >> /usr/local/pgsql/server.log 2>&1" /dev/null
468 (The author of this example says this example will revive the
469 postmaster if it dies, but he doesn't know if there are other side
472 c) In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
473 contain the following lines and make it chmod 755 and chown
476 [ -x /usr/local/pgsql/bin/postmaster ] && {
477 su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
478 -D/usr/local/pgsql/data
479 -S -o -F > /usr/local/pgsql/errlog' &
482 You may put the line breaks as shown above. The shell is smart
483 enough to keep parsing beyond end-of-line if there is an
484 expression unfinished. The exec saves one layer of shell under
485 the postmaster process so the parent is init. Note: Unlike the
486 other examples, this one has been tested.
488 d) In RedHat v4.0 Linux create file /etc/rc.d/init.d/postgres.init to
489 contain the following single line:
490 su -c "cd ~postgres; nohup /usr/local/pgsql/bin/postmaster
491 -D /usr/local/pgsql/data > server.log 2>&1 &" postgres
492 Next, type the following:
494 ln -s ../init.d/postgres.init S1000postgres
495 Change "1000" to a number of your choice to indicate the
496 loading order of the various programs pointed to in directory
497 /etc/rc3.d. (Note that this example has not been tested yet.)
499 22a) If you haven't already done so, this would be a good time to modify
500 your computer to do regular maintainence. The following should be
501 done at regular intervals:
503 a) Run the SQL command vacuum. This will clean up your database.
504 b) Back up your system. (You should probably keep the last few
505 backups on hand.) Ideally, no one else should be using the
508 Ideally, the above tasks should be done by a shell script that is
509 run nightly or weekly by cron. Look at the man page for crontab
510 for a starting point on how to do this. (If you do it, please
511 e-mail us a copy of your shell script. We would like to set up
512 our own systems to do this too.)
514 23) If you are upgrading an existing system then install your old database.
517 psql -e template1 < db.out
519 If your old database uses either path or polygon geometric data types,
520 then you will need to upgrade any columns containing those types. To
521 do so, type (from within psql)
522 update YourTable set PathCol = UpgradePath(PathCol);
523 update YourTable set PolyCol = UpgradePoly(PolyCol);
527 UpgradePath() checks to see that a path value is consistant with the
528 old syntax, and will not update a column which fails that examination.
529 UpgradePoly() cannot verify that a polygon is in fact from an old
530 syntax, but RevertPoly() is provided to reverse the effects of a
533 24) If you are a new user, you may wish to play with postgres as described
536 25) Clean up after yourself. Type
537 rm -rf /usr/src/pgsql_6_0
538 rm -rf /usr/local/pgsql_6_0
539 # Also delete old database directory tree if it is not in
540 # /usr/local/pgsql_6_0/data
541 rm ~/postgresql-v6.2.tar.gz
543 26) You will probably want to print out the documentation. Here is how
544 you might do it if you have Ghostscript on your system and are
545 writing to a laserjet printer.
546 alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
547 export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
548 # Print out the man pages.
549 man -a -t /usr/local/pgsql/man/*/* > manpage.ps
550 gshp -sOUTPUTFILE=manpage.hp manpage.ps
552 lpr -l -s -r manpage.hp
553 # Print out the Postgres95 User Manual, version 1.0,
555 cd /usr/src/pgsql/doc
556 gshp -sOUTPUTFILE=userguide.hp userguide.ps
557 lpr -l -s -r userguide.hp
559 If you are a developer, you will probably want to also print out
560 the Postgres Implemention Guide, version 1.0, October 1, 1995.
561 This is a WWW document located at
562 http://www.postgresql.org/docs/impguide.
564 27) The Postgres team wants to keep PostgreSQL working on all of the
565 supported platforms. We therefore ask you to let us know if you did
566 or did not get PostgreSQL to work on you system. Please send a
567 mail message to pgsql-ports@postgresql.org telling us the following:
568 - The version of PostgreSQL (v6.2, 6.1.1, beta 970703, etc.).
569 - Your operating system (i.e. RedHat v4.0 Linux v2.0.26).
570 - Your hardware (SPARC, i486, etc.).
571 - Did you compile, install and run the regression tests cleanly?
572 If not, what source code did you change (i.e. patches you
573 applied, changes you made, etc.), what tests failed, etc.
574 It is normal to get many warning when you compile. You do
575 not need to report these.
577 28) Now create, access and manipulate databases as desired. Write client
578 programs to access the database server. In other words, ENJOY!
581 PLAYING WITH POSTGRESQL
582 -----------------------
584 After PostgreSQL is installed, a database system is created, a postmaster
585 daemon is running, and the regression tests have passed, you'll want to
586 see PostgreSQL do something. That's easy. Invoke the interactive interface
587 to PostgreSQL, psql, and start typing SQL:
591 (psql has to open a particular database, but at this point the only one
592 that exists is the template1 database, which always exists. We will connect
593 to it only long enough to create another one and switch to it).
595 The response from psql is:
597 type \? for help on slash commands
599 type \g or terminate with semicolon to execute query
600 You are currently connected to the database: template1
604 Create the database foo:
606 template1=> CREATE DATABASE FOO;
609 (Get in the habit of including those SQL semicolons. Psql won't execute
610 anything until it sees the semicolon or a "\g" and the semicolon is required
611 to delimit multiple statements.)
614 closing connection to database: template1
615 connecting to new database: foo
617 (\ commands aren't SQL, so no semicolon. Use \? to see all the \ commands.)
619 foo=> CREATE TABLE bar (column1 int4, column2 char16);
629 QUESTIONS? BUGS? FEEDBACK?
630 ----------------------------
632 First, read the files in directory /usr/src/pgsql/doc. The FAQ in
633 this directory may be particularly useful.
635 If PostgreSQL failed to compile on your computer then fill out the form
636 in file /usr/src/pgsql/doc/bug.template and mail it to the location
637 indicated at the top of the form.
639 Mail questions to pgsql-questions@postgresql.org. For more information
640 on the various mailing lists, see http://www.postgresql.org under mailing
644 ----------------------------------------------------------------------
646 Porting Notes (these notes may be out of date):
650 You need to install the libdl-1.1 package since Ultrix 4.x doesn't
651 have a dynamic loader. It's available in
652 s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
655 The linux-elf port installs cleanly. If you are using an
656 i486 processor or higher, you can edit template/linux-elf
657 to include "-m486" as a compiler option. configure does not
658 detect that sigsetjmp() is available, but you can edit
659 include/config.h after running configure and before running
660 make to include "#define HAVE_SIGSETJMP 1". Note that I have
661 not seen any difference in PostgreSQL behavior either way.
663 <Thomas.Lockhart@jpl.nasa.gov> 97/05/17)
665 For non-ELF Linux, the dld library MUST be obtained and installed on
666 the system. It enables dynamic link loading capability to the postgres
667 port. The dld library can be obtained from the sunsite linux
668 distributions. The current name is dld-3.2.5.
670 <sneaker@powergrid.electriciti.com> 5/11/95)
673 For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library.
676 The NeXT port was supplied by Tom R. Hageman <tom@basil.icce.rug.nl>.
677 It requires a SysV IPC emulation library and header files for
678 shared libary and semaphore stuff. Tom just happens to sell such
679 a product so contact him for information. He has also indicated that
680 binary releases of PostgreSQL for NEXTSTEP will be made available to
681 the general public. Contact Info@RnA.nl for information.