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.3. 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 Yu.
17 The installation notes below assume the following (except where noted):
18 - Commands are Unix-compatible. See note below.
19 - Defaults are used except where noted.
20 - User postgres is the Postgres superuser.
21 - The source path is /usr/src/pgsql (other paths are possible).
22 - The runtime path is /usr/local/pgsql (other paths are possible).
24 Commands were tested on RedHat Linux version 4.0 using the bash shell.
25 Except where noted, they will probably work on most systems. Commands
26 like ps and tar vary wildly on what options you should use on each
27 platform. USE COMMON SENSE before typing in these commands.
29 Our Makefiles require GNU make (called gmake in this document) and
30 also assume that "install" accepts BSD options. The INSTALL
31 variable in the Makefiles is set to the BSD-compatible version of
32 install. On some systems, you will have to find a BSD-compatible
33 install command (eg. bsdinst, which comes with the MIT X Window System
37 REQUIREMENTS TO RUN POSTGRESQL
38 ------------------------------
40 PostgreSQL has been tested on the following platforms:
42 aix IBM on AIX 3.2.5 or 4.x
43 alpha DEC Alpha AXP on Digital Unix 2.0, 3.2, 4.0
44 BSD44_derived OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
45 bsdi BSD/OS 2.0, 2.01, 2.1, 3.0
47 hpux HP PA-RISC on HP-UX 9.0, 10
48 i386_solaris i386 Solaris
49 irix5 SGI MIPS on IRIX 5.3
50 linux Intel x86 on Linux 2.0 and Linux ELF
53 (For non-ELF Linux, see LINUX_ELF below).
55 sparc_solaris SUN SPARC on Solaris 2.4, 2.5, 2.5.1
56 sunos4 SUN SPARC on SunOS 4.1.3
57 svr4 Intel x86 on Intel SVR4 and MIPS
58 ultrix4 DEC MIPS on Ultrix 4.4
60 PostgreSQL has known problems/bugs on the following platforms:
62 nextstep Motorola MC68K or Intel x86 on NeXTSTEP 3.2
64 PostgreSQL is also known to work on a number of other platforms that the
65 authors have not personally tested.
67 You should have at least 8 MB of memory and at least 45 MB of disk space
68 to hold the source, binaries, and user databases. After installation
69 you may reduce this to about 3 Mbytes plus space for user databases.
71 To those doing a fresh install or upgrading from previous releases of
73 ----------------------------------------------
75 1) Read any last minute information and platform specific porting
76 notes. There are some platform specific notes at the end of this
77 file for Ultrix4.x, Linux, BSD/OS and NeXT. There are other
78 files in directory /usr/src/pgsql/doc, including files FAQ-Irix
79 and FAQ-Linux. Also look in directory ftp://ftp.postgresql.org/pub.
80 If there is a file called INSTALL in this directory then this
81 file will contain the latest installation information.
83 Please note that a "tested" platform in the list given earlier
84 simply means that someone went to the effort at some point of making
85 sure that a PostgreSQL distribution would compile and run on this
86 platform without modifying the code. Since the current developers
87 will not have access to all of these platforms, some of them may not
88 compile cleanly and pass the regression tests in the current
89 release due to minor problems. Any such known problems and their
90 solutions will be posted in ftp://ftp.postgresql.org/pub/INSTALL.
92 2) Create account postgres if it does not already exist.
94 3) Log into account postgres.
96 3a) Check that you have sufficient disk space. You will need about
97 17 Mbytes for /usr/src/pgsql, about 2 Mbytes for /usr/local/pgsql
98 (excluding your database) and 1 Mbyte for an empty database.
99 The database will temporarily grow to about 20 Mbytes during the
100 regression tests. You will also need about 3 Mbytes for the
101 distribution tar file.
103 We therefore recommend that during installation and testing you
104 have well over 20 Mbytes free under /usr/local and another 25 Mbytes
105 free on the disk partition containing your database. Once you
106 delete the source files, tar file and regression database, you
107 will need 2 Mbytes for /usr/local/pgsql, 1 Mbyte for the empty
108 database, plus about five times the space you would require to
109 store your database data in a flat file.
111 To check for disk space, use command "df -k".
113 4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.3.tar.gz from the
114 Internet. Store it in your home directory.
116 5) Some platforms use flex. If your system uses flex then make sure
117 you have a good version. Type
120 If the flex command is not found then you probably do not need it.
121 If the version is 2.5.2 or 2.5.4 or greater then you are okay. If it
122 is 2.5.3 or before 2.5.2 then you will have to upgrade flex. You may
123 get it at ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz.
125 If you need flex and don't have it or have the wrong version, then
126 you will be told so when you attempt to compile the program. Feel
127 free to skip this step if you aren't sure you need it. If you do
128 need it then you will be told to install/upgrade flex when you try to
131 To install it, type the following:
133 gunzip -c flex-2.5.4.tar.gz | tar xvf -
135 configure --prefix=/usr
138 # You must be root when typing the next line.
143 This will update files /usr/man/man1/flex.1, /usr/bin/flex,
144 /usr/lib/libfl.a, /usr/include/FlexLexer.h and will add link
145 /usr/bin/flex++ which points to flex.
147 6) If you are upgrading an existing system then back up your database.
148 For alpha- and beta-level releases, the database format is liable
149 to change often every few weeks with no notice besides a quick comment
150 in the HACKERS mailing list. Full releases always require a dump/reload
151 from previous releases. It is therefore a bad idea to skip this
152 step. Type (with the gunzip line and the following line typed as one
155 gunzip -c postgresql-v6.3.tar.gz |
156 tar xvf - src/bin/pg_dump/pg_dumpall
157 chmod a+x src/bin/pg_dump/pg_dumpall
158 src/bin/pg_dump/pg_dumpall > db.out
160 If you wish to preserve object id's (oids), then use the -o
161 option when running pg_dumpall. However, unless you have a
162 special reason for doing this, don't do it.
164 If the pg_dumpall command seems to take a long time and you think
165 it might have died, then, from another terminal, use "ls -l db.out"
166 several times to see if the size of the file is growing.
168 Please note that if you are upgrading from a version prior to
169 Postgres95 v1.09 then you must back up your database, install
170 Postgres95 v1.09, restore your database, then back it up again.
171 You should also read files /usr/src/pgsql/migration/*.
173 You must make sure that your database is not updated in the middle of
174 your backup. If necessary, bring down postmaster, edit the permissions
175 in file /usr/local/pgsql/data/pg_hba.conf to allow only you on, then
176 bring postmaster back up.
178 7) If you are upgrading an existing system then kill the postmaster. Type
179 ps -ax | grep postmaster
180 This should list the process numbers for a number of processes. Type
181 the following line, with "???" replaced by the process id for process
182 "postmaster". (Do not use the id for process "grep postmaster".) Type
184 with "???" modified as indicated.
186 8) If you are upgrading an existing system then move the old directories
187 out of the way. If you are short of disk space then you may have to
188 back up and delete the directories instead. If you do this, save the
189 old database in the /usr/local/pgsql/data directory tree. At a
190 minimum, save file /usr/local/pgsql/data/pg_hba.conf.
200 If you are not using /usr/local/pgsql/data as your data directory
201 (check to see if environment variable PGDATA is set to something
202 else) then you will also want to move this directory in the same
205 9) Make new source and install directories. The actual paths can be
206 different for your installation; be consistant with your configuration
212 chown postgres:postgres pgsql
215 chown postgres:postgres pgsql
218 10) Unzip and untar the new source file. Type
220 gunzip -c ~/postgresql-v6.3.tar.gz | tar xvf -
222 11) Configure the source code for your system. It is this step at which
223 you can specify your actual source path and installation paths for
224 the build process (see the --prefix option below). Type
225 cd /usr/src/pgsql/src
228 The configure program will list the template files available and
229 ask you to choose one. A lot of times, an appropriate template
230 file is chosen for you, and you can just press Enter to accept the
231 default. If the default is not appropriate, then type in the
232 appropriate template file and press Enter. (If you do this, then
233 send email to scrappy@hub.org stating the output of the program
234 './config.guess' and what the template file should be.)
236 Once you have entered the template file, you will be asked a
237 number of questions about your particular configuration. These
238 can be skipped by adding parameters to the configure command above.
239 The following parameters can be tagged onto the end of the configure
242 --prefix=BASEDIR Selects a different base directory for the
243 installation of the PostgreSQL configuration.
244 The default is /usr/local/pgsql.
246 --enable-hba Enables Host Based Authentication (DEFAULT)
248 --disable-hba Disables Host Based Authentication
250 --enable-locale Enables USE_LOCALE
252 --disable-locale Disables USE_LOCALE (DEFAULT)
254 --enable-cassert Enables ASSERT_CHECKING
256 --disable-cassert Disables ASSERT_CHECKING (DEFAULT)
258 --with-template=TEMPLATE
259 Use template file TEMPLATE - the template
260 files are assumed to be in the directory
261 src/template, so look there for proper values.
262 (If the configure script cannot find the
263 specified template file, it will ask you for
266 --with-pgport=PORT Sets the port that the postmaster process
267 listens for incoming connections on. The
268 default for this is port 5432.
270 As an example, here is the configure script I use on a Sparc
271 Solaris 2.5 system with /opt/postgres being the install base.
273 % ./configure --prefix=/opt/postgres
274 --with-template=sparc_solaris-gcc --with-pgport=5432
275 --enable-hba --disable-locale
277 Of course, in a real shell, you would type these three lines all
280 12) Compile the program. Type
281 cd /usr/src/pgsql/src
282 gmake all >& make.log &
285 The last line displayed will hopefully be "All of PostgreSQL is
286 successfully made. Ready to install." At this point, or earlier
287 if you wish, type control-C to get out of tail. (If you have
288 problems later on you may wish to examine file make.log for
289 warning and error messages.)
291 If your computer does not have gmake (GNU make) then try running
292 make instead throughout the rest of these notes.
294 Please note that you will probably find a number of warning
295 messages in make.log. Unless you have problems later on, these
296 messages may be safely ignored.
298 If the compiler fails with an error stating that the flex command
299 cannot be found then install flex as described earlier. Next,
300 change directory back to this directory, type "make clean", then
303 13) Install the program. Type
304 cd /usr/src/pgsql/src
305 gmake install >& make.install.log &
306 tail -f make.install.log
308 The last line displayed will be "gmake[1]: Leaving directory
309 `/usr/src/pgsql/src/man'". At this point, or earlier if you wish,
310 type control-C to get out of tail.
312 14) If necessary, tell UNIX how to find your shared libraries. If you
313 are using Linux-ELF do ONE of the following, preferably the first:
315 a) As root, edit file /etc/ld.so.conf. Add line
317 to the file. Then run command /sbin/ldconfig.
319 b) In a bash shell, type
320 export LD_LIBRARY_PATH=/usr/local/pgsql/lib
322 c) In a csh shell, type
323 setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
325 Please note that the above commands may vary wildly for different
326 operating systems. Check the platform specific notes, such as
327 those for Ultrix4.x or and for non-ELF Linux.
329 If, when you create the database, you get the message "pg_id: can't
330 load library 'libpq.so'" then the above step was necessary. Simply
331 do this step, then try to create the database again.
333 15) If it has not already been done, then prepare account postgres
334 for using PostgreSQL. Any account that will use PostgreSQL must
335 be similarily prepared. (The following instructions are for a
336 bash shell. Adapt accordingly for other shells.)
338 Add the following lines to your login shell, ~/.bash_profile:
339 PATH=$PATH:/usr/local/pgsql/bin
340 MANPATH=$MANPATH:/usr/local/pgsql/man
341 PGLIB=/usr/local/pgsql/lib
342 PGDATA=/usr/local/pgsql/data
343 export PATH MANPATH PGLIB PGDATA
345 Make sure that you have defined these variables before continuing
346 with the remaining steps. The easiest way to do this is to type:
347 source ~/.bash_profile
349 16) Create the database. DO NOT DO THE FOLLOWING AS ROOT! This would
350 be a major security hole. Type
353 17) Set up permissions to access the database system. Do this by editing
354 file /usr/local/pgsql/data/pg_hba.conf. The instructions are
355 included in the file. (If your database is not located in the
356 default location, i.e. if PGDATA is set to point elsewhere, then the
357 location of this file will change accordingly.) This file should be
358 made read only again once you are finsihed.
360 If you are upgrading, you can NOT copy file pg_hba.conf from your
361 old database on top of the one in your new database. You will
362 have to re-do your changes.
365 18) If you wish to skip the regression tests then skip to step 21.
366 However, we think skipping the tests is a BAD idea!
368 The file /usr/src/pgsql/src/test/regress/README has detailed
369 instructions for running and interpreting the regression tests.
370 A short version follows here:
372 Start the postmaster in preparation for the regression tests. First,
373 set the timezone for Berkeley, California. On some systems you may do
374 this by setting environment variable TZ. I.e., using bash, type
377 Now start the postmaster daemon running in the background by typing
379 nohup postmaster > regress.log 2>&1 &
381 Run postmaster from your Postgres super user account (typically
382 account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
384 19) Run the regression tests. Type
386 cd /usr/src/pgsql/src/test/regress
390 You do not need to type "gmake clean" if this is the first time you
391 are running the tests.
393 You should get on the screen (and also written to file ./regress.out)
394 a series of statements stating which tests passed and which tests
395 failed. Please note that it can be normal for some of the tests to
396 "fail". For the failed tests, use diff to compare the files in
397 directories ./results and ./expected. If float8 failed, type
399 cd /usr/src/pgsql/src/test/regress
400 diff -w expected/float8.out results
402 "Failed" tests may have failed due to slightly different error messages,
403 output formatting, failure to set the timezone correctly for your
404 platform, etc. "Failures" of this type do not indicate a problem with
407 For a i686/Linux-ELF platform, no tests failed since this is the
408 v6.3 regression testing reference platform.
410 For the SPARC/Linux-ELF platform, using the 970525 beta version of
411 PostgreSQL v6.2 the following tests "failed":
412 float8 and geometry "failed" due to minor precision differences in
413 floating point numbers. select_views produces massively different output,
414 but the differences are due to minor floating point differences.
416 Conclusion? If you do see failures, try to understand the nature of
417 the differences and then decide if those differences will affect your
418 intended use of PostgreSQL. However, keep in mind that this is likely
419 to be the most solid release of PostgreSQL to date, incorporating many
420 bug fixes from v6.2.1, and that previous versions of PostgreSQL have been
421 in use successfully for some time now.
423 After running the tests, type
425 cd /usr/src/pgsql/src/test/regress
428 20) Stop the postmaster as described in step 7. Then restore the
429 timezone to it's normal setting. If you changed the timezone by
430 modifying environment variable TZ then one way to do this is to
431 log out of, then back into, account postgres.
433 21) Start the postmaster daemon running. Type
435 nohup postmaster > server.log 2>&1 &
436 Run postmaster from your Postgres super user account (typically
437 account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
439 22) If you haven't already done so, this would be a good time to modify
440 your computer so that it will automatically start postmaster whenever
441 you boot your computer.
443 Here are some suggestions on how to do this, contributed by various
446 Whatever you do, postmaster must be run by user postgres AND NOT BY
447 ROOT. This is why all of the examples below start by switching user
448 (su) to postgres. These commands also take into account the fact
449 that environment variables like PATH and PGDATA may not be set properly.
451 The examples are as follows. Use them with extreme caution.
453 a) Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
454 2.5.1 to contain the following single line:
455 su postgres -c "/usr/local/pgsql/bin/postmaster -S -D
456 /usr/local/pgsql/data"
458 b) In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
459 contain the following lines and make it chmod 755 and chown
462 [ -x /usr/local/pgsql/bin/postmaster ] && {
463 su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
464 -D/usr/local/pgsql/data
465 -S -o -F > /usr/local/pgsql/errlog' &
468 You may put the line breaks as shown above. The shell is smart
469 enough to keep parsing beyond end-of-line if there is an
470 expression unfinished. The exec saves one layer of shell under
471 the postmaster process so the parent is init. Note: Unlike most
472 other examples, this one has been tested.
474 c) In RedHat v4.0 Linux edit file /etc/inittab to contain the
475 following single line:
476 pg:2345:respawn:/bin/su - postgres -c
477 "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
478 >> /usr/local/pgsql/server.log 2>&1" /dev/null
479 (The author of this example says this example will revive the
480 postmaster if it dies, but he doesn't know if there are other side
483 d) The contrib/linux area of the PostgreSQL distribution has an example
484 init.d script compatible with and tested using recent RedHat packages.
486 22a) If you haven't already done so, this would be a good time to modify
487 your computer to do regular maintainence. The following should be
488 done at regular intervals:
490 a) Run the SQL command vacuum. This will clean up your database.
491 b) Back up your system. (You should probably keep the last few
492 backups on hand.) Ideally, no one else should be using the
495 Ideally, the above tasks should be done by a shell script that is
496 run nightly or weekly by cron. Look at the man page for crontab
497 for a starting point on how to do this. (If you do it, please
498 e-mail us a copy of your shell script. We would like to set up
499 our own systems to do this too.)
501 23) If you are upgrading an existing system then install your old database.
504 psql -e template1 < db.out
506 If your pre-v6.2 database uses either path or polygon geometric data types,
507 then you will need to upgrade any columns containing those types. To
508 do so, type (from within psql)
509 update YourTable set PathCol = UpgradePath(PathCol);
510 update YourTable set PolyCol = UpgradePoly(PolyCol);
514 UpgradePath() checks to see that a path value is consistant with the
515 old syntax, and will not update a column which fails that examination.
516 UpgradePoly() cannot verify that a polygon is in fact from an old
517 syntax, but RevertPoly() is provided to reverse the effects of a
520 24) If you are a new user, you may wish to play with Postgres as described
523 25) Clean up after yourself. Type
524 rm -rf /usr/src/pgsql_6_0
525 rm -rf /usr/local/pgsql_6_0
526 # Also delete old database directory tree if it is not in
527 # /usr/local/pgsql_6_0/data
528 rm ~/postgresql-v6.3.tar.gz
530 26) You will probably want to print out the documentation. Here is how
531 you might do it if you have Ghostscript on your system and are
532 writing to a laserjet printer.
533 alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
534 export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
535 # Print out the man pages.
536 man -a -t /usr/local/pgsql/man/*/* > manpage.ps
537 gshp -sOUTPUTFILE=manpage.hp manpage.ps
539 lpr -l -s -r manpage.hp
540 # Print out the Postgres95 User Manual, version 1.0,
542 cd /usr/src/pgsql/doc
543 gshp -sOUTPUTFILE=userguide.hp userguide.ps
544 lpr -l -s -r userguide.hp
546 If you are a developer, you will probably want to also print out
547 the Postgres Implemention Guide, version 1.0, October 1, 1995.
548 This is a WWW document located at
549 http://www.postgresql.org/docs/impguide.
551 27) The Postgres team wants to keep PostgreSQL working on all of the
552 supported platforms. We therefore ask you to let us know if you did
553 or did not get PostgreSQL to work on you system. Please send a
554 mail message to pgsql-ports@postgresql.org telling us the following:
555 - The version of PostgreSQL (v6.3, 6.2.1, beta 970703, etc.).
556 - Your operating system (i.e. RedHat v4.0 Linux v2.0.26).
557 - Your hardware (SPARC, i486, etc.).
558 - Did you compile, install and run the regression tests cleanly?
559 If not, what source code did you change (i.e. patches you
560 applied, changes you made, etc.), what tests failed, etc.
561 It is normal to get many warning when you compile. You do
562 not need to report these.
564 28) Now create, access and manipulate databases as desired. Write client
565 programs to access the database server. In other words, ENJOY!
568 PLAYING WITH POSTGRESQL
569 -----------------------
571 After PostgreSQL is installed, a database system is created, a postmaster
572 daemon is running, and the regression tests have passed, you'll want to
573 see PostgreSQL do something. That's easy. Invoke the interactive interface
574 to PostgreSQL, psql, and start typing SQL:
578 (psql has to open a particular database, but at this point the only one
579 that exists is the template1 database, which always exists. We will connect
580 to it only long enough to create another one and switch to it).
582 The response from psql is:
584 type \? for help on slash commands
586 type \g or terminate with semicolon to execute query
587 You are currently connected to the database: template1
591 Create the database foo:
593 template1=> CREATE DATABASE FOO;
596 (Get in the habit of including those SQL semicolons. Psql won't execute
597 anything until it sees the semicolon or a "\g" and the semicolon is required
598 to delimit multiple statements.)
601 closing connection to database: template1
602 connecting to new database: foo
604 (\ commands aren't SQL, so no semicolon. Use \? to see all the \ commands.)
606 foo=> CREATE TABLE bar (column1 int4, column2 char16);
616 QUESTIONS? BUGS? FEEDBACK?
617 ----------------------------
619 First, read the files in directory /usr/src/pgsql/doc. The FAQ in
620 this directory may be particularly useful.
622 If PostgreSQL failed to compile on your computer then fill out the form
623 in file /usr/src/pgsql/doc/bug.template and mail it to the location
624 indicated at the top of the form.
626 Mail questions to pgsql-questions@postgresql.org. For more information
627 on the various mailing lists, see http://www.postgresql.org under mailing
631 ----------------------------------------------------------------------
633 Porting Notes (these notes may be out of date):
637 You need to install the libdl-1.1 package since Ultrix 4.x doesn't
638 have a dynamic loader. It's available in
639 s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
642 A linux-2.0.30/libc-5.3.12/RedHat-4.2 running on a dual processor
643 i686 is the regression testing reference machine.
644 The linux-elf port installs cleanly. If you are using an
645 i486 processor or higher, you can edit template/linux-elf
646 to include "-m486" as a compiler option. configure does not
647 detect that sigsetjmp() is available, but you can edit
648 include/config.h after running configure and before running
649 make to include "#define HAVE_SIGSETJMP 1". Note that I have
650 not seen any difference in PostgreSQL behavior either way.
652 <lockhart@alumni.caltech.edu> 97/10/14)
654 For non-ELF Linux, the dld library MUST be obtained and installed on
655 the system. It enables dynamic link loading capability to the Postgres
656 port. The dld library can be obtained from the sunsite linux
657 distributions. The current name is dld-3.2.5.
659 <sneaker@powergrid.electriciti.com> 5/11/95)
662 For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library.
665 The NeXT port was supplied by Tom R. Hageman <tom@basil.icce.rug.nl>.
666 It requires a SysV IPC emulation library and header files for
667 shared libary and semaphore stuff. Tom just happens to sell such
668 a product so contact him for information. He has also indicated that
669 binary releases of PostgreSQL for NEXTSTEP will be made available to
670 the general public. Contact Info@RnA.nl for information.