Newer
Older
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
PostgreSQL Installation Guide
by The PostgreSQL Development Team
Edited by Thomas Lockhart
PostgreSQL is copyright (C) 1998
by the Postgres Global Development Group.
Table of Contents
Summary
1. Introduction
2. Ports
Currently Supported Platforms
Unsupported Platforms
3. Installation
Requirements to Run Postgres
Installation Procedure
Playing with Postgres
The Next Step
Porting Notes
Ultrix4.x
Linux
Linux ELF
Linux a.out
BSD/OS
NeXT
4. Configuration Options
Parameters for Configuration (configure)
Parameters for Building (make)
Locale Support
What are the Benefits?
What are the Drawbacks?
Kerberos Authentication
Availability
Installation
Operation
5. Release Notes
Release 6.4
Migration to v6.4
Detailed Change List
List of Tables
2-1. Supported Platforms
2-2. Possibly Incompatible Platforms
4-1. Kerberos Parameter Examples
Summary
Postgres, developed originally in the UC Berkeley
Computer Science Department, pioneered many of the
object-relational concepts now becoming available in
some commercial databases. It provides SQL92/SQL3
language support, transaction integrity, and type
extensibility. PostgreSQL is a public-domain, open
source descendant of this original Berkeley code.
Chapter 1. Introduction
This installation procedure makes some assumptions
about the desired configuration and runtime
environment for your system. This may be adequate for
many installations, and is almost certainly adequate
for a first installation. But you may want to do an
initial installation up to the point of unpacking the
source tree and installing documentation, and then
print or browse the Administrator's Guide.
Chapter 2. Ports
This manual describes version 6.4 of Postgres. The
Postgres developer community has compiled and tested
Postgres on a number of platforms. Check the web site
for the latest information.
Currently Supported Platforms
At the time of publication, the following platforms
have been tested:
Table 2-1. Supported Platforms
OS Processor Version Reported Remarks
AIX 4.2.1 RS6000 v6.4 1998-10-27 (Andreas Zeugswetter)
BSDI x86 v6.4 1998-10-25 (Bruce Momjian
FreeBSD x86 v6.4 1998-10-26 (Tatsuo Ishii, Marc
2.2.x-3.x Fournier)
DGUX 5.4R4.11 m88k v6.3 1998-03-01 v6.4 probably OK. Needs
new maintainer. (Brian E
Gallew)
Digital Unix Alpha v6.4 1998-10-29 Minor patchable problems
4.0 (Pedro J. Lobo)
HPUX PA-RISC v6.4 1998-10-25 Both 9.0x and 10.20
(Tom Lane, Stan Brown)
IRIX 6.x MIPS v6.3 1998-03-01 5.x is different (Andrew
Martin)
linux 2.0.x Alpha v6.3.2 1998-04-16 Mostly successful. Needs
work for v6.4. (Ryan
Kirkpatrick)
linux 2.0.x x86 v6.4 1998-10-27 (Thomas Lockhart)
linux x86 v6.4 1998-10-25 (Oliver Elphick, Taral)
2.0.x/glibc2
linux 2.0.x Sparc v6.4 1998-10-25 (Tom Szybist)
linuxPPC PPC603e v6.4 1998-10-26 Powerbook 2400c (Tatsuo
2.1.24 Ishii)
mklinux DR3 PPC750 v6.4 1998-09-16 PowerMac 7600 (Tatsuo
Ishii)
NetBSD/i386 x86 v6.4 1998-10-25 (Brook Milligan)
1.3.2
NetBSD- NS32532 v6.4 1998-10-27 (small problems in
current date/time math
(Jon Buller)
NetBSD/sparc Sparc v6.4 1998-10-27 (Tom I Helbekkmo)
1.3H
NetBSD 1.3 VAX v6.3 1998-03-01 (Tom I Helbekkmo)
SCO UnixWare x86 v6.3 1998-03-01 aka UNIVEL (Billy G.
2.x Allie)
SCO UnixWare x86 v6.4 1998-10-04 (Billy G. Allie)
7
Solaris x86 v6.4 1998-10-28 (Marc Fournier)
Solaris Sparc v6.4 1998-10-28 (Tom Szybist, Frank
2.6-2.7 Ridderbusch)
SunOS 4.1.4 Sparc v6.3 1998-03-01 patches submitted (Tatsuo
Ishii)
SVR4 MIPS v6.4 1998-10-28 no 64-bit int support
(Frank Ridderbusch)
SVR4 4.4 m88k v6.2.1 1998-03-01 confirmed with patching
(Doug Winterburn)
Windows NT x86 v6.4 1998-10-08 Mostly working with the
Cygwin library. No DLLs
yet. (Horak Daniel)
Platforms listed for v6.3.x should also work with
v6.4, but we did not receive confirmation of such at
the time this list was compiled.
Note: For Windows NT, the server-side port of
Postgres has recently been accomplished. Check the
Askesis Postgres Home Page for up to date
information. You may also want to look for
possible patches on the Postgres web site.
Unsupported Platforms
There are a few platforms which have been attempted
and which have been reported to not work with the
standard distribution. Others listed here do not
provide sufficient library support for an attempt.
Table 2-2. Possibly Incompatible Platforms
OS Processor Version Reported Remarks
MacOS all v6.3 1998-03-01 not library compatible;
use ODBC/JDBC
NetBSD arm32 v6.3 1998-03-01 not yet working (Dave
Millen)
NetBSD m68k v6.3 1998-03-01 Amiga, HP300, Mac; not
yet working (Henry Hotz)
NextStep x86 v6.x 1998-03-01 client-only support;
v1.0.9 worked with
patches (David Wetzel)
Ultrix MIPS,VAX? v6.x 1998-03-01 no recent reports;
obsolete?
Windows x86 v6.3 1998-03-01 not library compatible;
client side maybe; use
ODBC/JDBC
Note that Windows ports of the frontend are
apparently possible using third-party Posix porting
tools and libraries.
Chapter 3. Installation
Complete installation instructions for Postgres v6.4.
Before installing Postgres, you may wish to visit
www.postgresql.org for up to date information,
patches, etc.
These installation instructions assume:
o Commands are Unix-compatible. See note below.
o Defaults are used except where noted.
o User postgres is the Postgres superuser.
o The source path is /usr/src/pgsql (other paths are possible).
o The runtime path is /usr/local/pgsql (other paths are possible).
Commands were tested on RedHat Linux version 4.2
using the tcsh shell. Except where noted, they will
probably work on most systems. Commands like ps and
tar may vary wildly between platforms on what options
you should use. Use common sense before typing in
these commands.
Our Makefiles require GNU make (called ?gmake? in this
document). They will not work with non-GNU make
programs. If you have GNU make installed under the
name ?make? instead of ?gmake?, then you will use the
command make instead. That's OK, but you need to have
the GNU form of make to succeed with an installation.
Requirements to Run Postgres
Up to date information on supported platforms is at
http://www.postgresql.org/docs/admin/install.htm. In
general, most Unix-compatible platforms with modern
libraries should be able to run Postgres.
Although the minimum required memory for running
Postgres is as little as 8MB, there are noticable
improvements in runtimes for the regression tests
when expanding memory up to 96MB on a relatively fast
dual-processor system running X-Windows. The rule is
you can never have too much memory.
Check that you have sufficient disk space. You will
need about 30 Mbytes for /usr/src/pgsql, about 5
Mbytes for /usr/local/pgsql (excluding your database)
and 1 Mbyte for an empty database. The database will
temporarily grow to about 20 Mbytes during the
regression tests. You will also need about 3 Mbytes
for the distribution tar file.
We therefore recommend that during installation and
testing you have well over 20 Mbytes free under
/usr/local and another 25 Mbytes free on the disk
partition containing your database. Once you delete
the source files, tar file and regression database,
you will need 2 Mbytes for /usr/local/pgsql, 1 Mbyte
for the empty database, plus about five times the
space you would require to store your database data
in a flat file.
To check for disk space, use
$ df -k
Installation Procedure
Procedure 3.1. Postgres Installation
For a fresh install or upgrading from previous
releases of Postgres:
1. Read any last minute information and platform
specific porting notes. There are some platform
specific notes at the end of this file for
Ultrix4.x, Linux, BSD/OS and NeXT. There are other
files in directory /usr/src/pgsql/doc, including
files FAQ-Irix and FAQ-Linux. Also look in
directory ftp://ftp.postgresql.org/pub. If there
is a file called INSTALL in this directory then
this file will contain the latest installation
information.
Please note that a "tested" platform in the list
given earlier simply means that someone went to
the effort at some point of making sure that a
Postgres distribution would compile and run on
this platform without modifying the code. Since
the current developers will not have access to all
of these platforms, some of them may not compile
cleanly and pass the regression tests in the
current release due to minor problems. Any such
known problems and their solutions will be posted
in ftp://ftp.postgresql.org/pub/INSTALL.
2. Create the Postgres superuser account (postgres is
commonly used) if it does not already exist.
The owner of the Postgres files can be any
unprivileged user account. It must not be root,
bin, or any other account with special access
rights, as that would create a security risk.
3. Log in to the Postgres superuser account. Most of
the remaining steps in the installation will
happen in this account.
4. Ftp file
ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz
from the Internet. Store it in your home directory.
5. Some platforms use flex. If your system uses flex
then make sure you have a good version. To check,
type
$ flex --version
If the flex command is not found then you probably
do not need it. If the version is 2.5.2 or 2.5.4
or greater then you are okay. If it is 2.5.3 or
before 2.5.2 then you will have to upgrade flex.
You may get it at
ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz.
If you need flex and don't have it or have the
wrong version, then you will be told so when you
attempt to compile the program. Feel free to skip
this step if you aren't sure you need it. If you
do need it then you will be told to
install/upgrade flex when you try to compile
Postgres.
You may want to do the entire flex installation
from the root account, though that is not
absolutely necessary. Assuming that you want the
installation to place files in the usual default
areas, type the following:
$ su -
$ cd /usr/local/src
ftp prep.ai.mit.edu
ftp> cd /pub/gnu/
ftp> binary
ftp> get flex-2.5.4.tar.gz
ftp> quit
$ gunzip -c flex-2.5.4.tar.gz | tar xvf -
$ cd flex-2.5.4
$ configure --prefix=/usr
$ gmake
$ gmake check
# You must be root when typing the next line:
$ gmake install
$ cd /usr/local/src
$ rm -rf flex-2.5.4
This will update files /usr/man/man1/flex.1,
/usr/bin/flex, /usr/lib/libfl.a,
/usr/include/FlexLexer.h and will add a link
/usr/bin/flex++ which points to flex.
6. If you are not upgrading an existing system then
skip to step 9. If you are upgrading an existing
system then back up your database. For alpha- and
beta-level releases, the database format is liable
to change, often every few weeks, with no notice
besides a quick comment in the HACKERS mailing
list. Full releases always require a dump/reload
from previous releases. It is therefore a bad idea
to skip this step.
Tip: Do not use the pg_dumpall script from v6.0 or
everything will be owned by the Postgres super
user.
To dump your fairly recent post-v6.0 database
installation, type
$ pg_dumpall -z > db.out
To use the latest pg_dumpall script on your
existing older database before upgrading Postgres,
pull the most recent version of pg_dumpall from
the new distribution:
$ cd
$ gunzip -c postgresql-v6.4.tar.gz \
| tar xvf - src/bin/pg_dump/pg_dumpall
$ chmod a+x src/bin/pg_dump/pg_dumpall
$ src/bin/pg_dump/pg_dumpall -z > db.out
$ rm -rf src
If you wish to preserve object id's (oids), then
use the -o option when running pg_dumpall.
However, unless you have a special reason for
doing this (such as using OIDs as keys in tables),
don't do it.
If the pg_dumpall command seems to take a long
time and you think it might have died, then, from
another terminal, type
$ ls -l db.out
several times to see if the size of the file is
growing.
Please note that if you are upgrading from a
version prior to Postgres95 v1.09 then you must
back up your database, install Postgres95 v1.09,
restore your database, then back it up again. You
should also read the release notes which should
cover any release-specific issues.
Caution
You must make sure that your database is not
updated in the middle of your backup. If
necessary, bring down postmaster, edit the
permissions in file
/usr/local/pgsql/data/pg_hba.conf to allow
only you on, then bring postmaster back up.
7. If you are upgrading an existing system then kill
the postmaster. Type
$ ps -ax | grep postmaster
This should list the process numbers for a number
of processes. Type the following line, with pid
replaced by the process id for process postmaster.
(Do not use the id for process "grep postmaster".)
Type
$ kill pid
to actually stop the process.
Tip: On systems which have Postgres started at
boot time, there is probably a startup file
which will accomplish the same thing. For
example, on my Linux system I can type
$ /etc/rc.d/init.d/postgres.init stop
to halt Postgres.
8. If you are upgrading an existing system then move
the old directories out of the way. If you are
short of disk space then you may have to back up
and delete the directories instead. If you do
this, save the old database in the
/usr/local/pgsql/data directory tree. At a
minimum, save file
/usr/local/pgsql/data/pg_hba.conf.
Type the following:
$ su -
$ cd /usr/src
$ mv pgsql pgsql_6_0
$ cd /usr/local
$ mv pgsql pgsql_6_0
$ exit
If you are not using /usr/local/pgsql/data as your
data directory (check to see if environment
variable PGDATA is set to something else) then you
will also want to move this directory in the same
manner.
9. Make new source and install directories. The
actual paths can be different for your
installation but you must be consistant throughout
this procedure.
Note: There are two places in this installation
procedure where you will have an opportunity to
specify installation locations for programs,
libraries, documentation, and other files.
Usually it is sufficient to specify these at the
make install stage of installation.
Type
$ su
$ cd /usr/src
$ mkdir pgsql
$ chown postgres:postgres pgsql
$ cd /usr/local
$ mkdir pgsql
$ chown postgres:postgres pgsql
$ exit
10. Unzip and untar the new source file. Type
$ cd /usr/src/pgsql
$ gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf -
11. Configure the source code for your system. It
is this step at which you can specify your actual
installation path for the build process (see the
--prefix option below). Type
$ cd /usr/src/pgsql/src
$ ./configure [ options ]
a. Among other chores, the configure script
selects a system-specific "template" file
from the files provided in the template
subdirectory. If it cannot guess which one to
use for your system, it will say so and exit.
In that case you'll need to figure out which
one to use and run configure again, this time
giving the --with-template=TEMPLATE option to
make the right file be chosen.
Please Report Problems: If your system is not
automatically recognized by configure and
you have to do this, please send email to
scrappy@hub.org with the output of the
program ./config.guess. Indicate what the
template file should be.
b. Choose configuration options. Check
Configuration Options for details. However,
for a plain-vanilla first installation with
no extra options like multi-byte character
support or locale collation support it may be
adequate to have chosen the installation
areas and to run configure without extra
options specified. The configure script
accepts many additional options that you can
use if you don't like the default
configuration. To see them all, type
./configure --help
Some of the more commonly used ones are:
--prefix=BASEDIR Selects a different base directory
The default is /usr/local/pgsql.
--with-template=TEMPLATE
Use template file TEMPLATE - the template
files are assumed to be in the directory
src/template, so look there for proper values.
--with-tcl Build interface libraries and programs requiring
Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
--with-perl Build the Perl interface library.
--with-odbc Build the ODBC driver package.
--enable-hba Enables Host Based Authentication (DEFAULT)
--disable-hba Disables Host Based Authentication
--enable-locale Enables USE_LOCALE
--enable-cassert Enables
ASSERT_CHECKING
--with-CC=compiler
Use a specific C compiler that the configure
script cannot find.
--with-CXX=compiler
--without-CXX
Use a specific C++ compiler that the configure
script cannot find, or exclude C++ compilation
altogether. (This only affects libpq++ at
present.)
c. Here is the configure script used on a Sparc Solaris 2.5 system with /opt/postgres
specified as the installation base directory:
$ ./configure --prefix=/opt/postgres \
--with-template=sparc_solaris-gcc
--with-pgport=5432 \
--enable-hba --disable-locale
Tip: Of course, you may type these three
lines all on the same line.
12. Install the man and HTML documentation. Type
$ cd /usr/src/pgsql/doc
$ gmake install
The documentation is also available in Postscript
format. Look for files ending with .ps.gz in the
same directory.
13. <removed>
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
14. Compile the program. Type
$ cd /usr/src/pgsql/src
$ gmake all >& make.log &
$ tail -f make.log
The last line displayed will hopefully be
All of PostgreSQL is successfully made. Ready to
install.
At this point, or earlier if you wish, type
control-C to get out of tail. (If you have
problems later on you may wish to examine file
make.log for warning and error messages.)
Note: You will probably find a number of warning
messages in make.log. Unless you have problems
later on, these messages may be safely ignored.
If the compiler fails with a message stating that
the flex command cannot be found then install flex
as described earlier. Next, change directory back
to this directory, type
$ make clean
then recompile again.
Compiler options, such as optimization and
debugging, may be specified on the command line
using the COPT variable. For example, typing
$ gmake COPT="-g" all >& make.log &
would invoke your compiler's -g option in all
steps of the build. See src/Makefile.global.in for
further details.
15. Install the program. Type
$ cd /usr/src/pgsql/src
$ gmake install >& make.install.log &
$ tail -f make.install.log
The last line displayed will be
gmake[1]: Leaving directory
`/usr/src/pgsql/src/man'
At this point, or earlier if you wish, type
control-C to get out of tail.
16. If necessary, tell your system how to find
the new shared libraries. You can do one of the
following, preferably the first:
a. As root, edit file /etc/ld.so.conf. Add a
line
/usr/local/pgsql/lib
to the file. Then run command /sbin/ldconfig.
b. In a bash shell, type
export
LD_LIBRARY_PATH=/usr/local/pgsql/lib
c. In a csh shell, type
setenv LD_LIBRARY_PATH
/usr/local/pgsql/lib
Please note that the above commands may vary
wildly for different operating systems. Check the
platform specific notes, such as those for
Ultrix4.x or and for non-ELF Linux.
If, when you create the database, you get the
message
pg_id: can't load library 'libpq.so'
then the above step was necessary. Simply do this
step, then try to create the database again.
17. If you used the --with-perl option to
configure, check the install log to see whether
the Perl module was actually installed. If you've
followed our advice to make the Postgres files be
owned by an unprivileged userid, then the Perl
module won't have been installed, for lack of
write privileges on the Perl library directories.
You can complete its installation, either now or
later, by becoming the user that does own the Perl
library (often root) (via su) and doing
$ cd /usr/src/pgsql/src/interfaces/perl5
$ gmake install
18. If it has not already been done, then prepare
account postgres for using Postgres. Any account
that will use Postgres must be similarly prepared.
There are several ways to influence the runtime
environment of the Postgres server. Refer to the
Administrator's Guide for more information.
Note: The following instructions are for a
bash/sh shell. Adapt accordingly for other
shells.
a. Add the following lines to your login
environment: shell, ~/.bash_profile:
PATH=$PATH:/usr/local/pgsql/bin
MANPATH=$MANPATH:/usr/local/pgsql/man
PGLIB=/usr/local/pgsql/lib
PGDATA=/usr/local/pgsql/data
export PATH MANPATH PGLIB PGDATA
b. Several regression tests could failed if the
user's locale collation scheme is different
from that of standard C locale.
If you configure and compile Postgres with
the --enable-locale option then set locale
environment to C (or unset all LC_*
variables) by putting these additional lines
to your login environment before starting
postmaster:
LC_COLLATE=C
LC_CTYPE=C
LC_COLLATE=C
export LC_COLLATE LC_CTYPE LC_COLLATE
c. Make sure that you have defined these
variables before continuing with the
remaining steps. The easiest way to do this
is to type:
$ source ~/.bash_profile
19. Create the database installation from your
Postgres superuser account (typically account
postgres). Do not do the following as root! This
would be a major security hole. Type
$ initdb
20. Set up permissions to access the database
system. Do this by editing file
/usr/local/pgsql/data/pg_hba.conf. The
instructions are included in the file. (If your
database is not located in the default location,
i.e. if PGDATA is set to point elsewhere, then the
location of this file will change accordingly.)
This file should be made read only again once you
are finished. If you are upgrading from v6.0 or
later you can copy file pg_hba.conf from your old
database on top of the one in your new database,
rather than redoing the file from scratch.
21. Briefly test that the backend will start and
run by running it from the command line.
a. Start the postmaster daemon running in the
background by typing
$ cd
$ postmaster -i
b. Create a database by typing
$ createdb
c. Connect to the new database:
$ psql
d. And run a sample query:
postgres=> SELECT datetime 'now';
e. Exit psql:
postgres=> \q
f. Remove the test database (unless you will
want to use it later for other tests):
$ destroydb
22. Run postmaster in the background from your
Postgres superuser account (typically account
postgres). Do not run postmaster from the root
account!
Usually, you will want to modify your computer so
that it will automatically start postmaster
whenever it boots. It is not required; the
Postgres server can be run successfully from
non-privileged accounts without root intervention.
Here are some suggestions on how to do this,
contributed by various users.
Whatever you do, postmaster must be run by the
Postgres superuser (postgres?) and not by root.
This is why all of the examples below start by
switching user (su) to postgres. These commands
also take into account the fact that environment
variables like PATH and PGDATA may not be set
properly. The examples are as follows. Use them
with extreme caution.
o If you are installing from a non-privileged
account and have no root access, then start the
postmaster and send it to the background:
$ cd
$ nohup postmaster > regress.log 2>&1 &
o Edit file rc.local on NetBSD or file rc2.d on
SPARC Solaris 2.5.1 to contain the following
single line:
su postgres -c "/usr/local/pgsql/bin/postmaster
-S -D /usr/local/pgsql/data"
o In FreeBSD 2.2-RELEASE edit
/usr/local/etc/rc.d/pgsql.sh to contain the
following lines and make it chmod 755 and chown
root:bin.
#!/bin/sh
[ -x /usr/local/pgsql/bin/postmaster ] && {
su -l pgsql -c 'exec
/usr/local/pgsql/bin/postmaster
-D/usr/local/pgsql/data
-S -o -F > /usr/local/pgsql/errlog' &
echo -n ' pgsql'
}
You may put the line breaks as shown above. The
shell is smart enough to keep parsing beyond
end-of-line if there is an expression unfinished.
The exec saves one layer of shell under the
postmaster process so the parent is init.
o In RedHat Linux add a file
/etc/rc.d/init.d/postgres.init which is based on
the example in contrib/linux/. Then make a
softlink to this file from
/etc/rc.d/rc5.d/S98postgres.init.
o In RedHat Linux edit file /etc/inittab to add the
following as a single line:
pg:2345:respawn:/bin/su - postgres -c
"/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
>> /usr/local/pgsql/server.log 2>&1 </dev/null"
(The author of this example says this example
will revive the postmaster if it dies, but he
doesn't know if there are other side effects.)
23. Run the regression tests. The file
/usr/src/pgsql/src/test/regress/README has
detailed instructions for running and interpreting
the regression tests. A short version follows
here:
a. Type
$ cd /usr/src/pgsql/src/test/regress
$ gmake clean
$ gmake all runtest
You do not need to type gmake clean if this
is the first time you are running the tests.
You should get on the screen (and also
written to file ./regress.out) a series of
statements stating which tests passed and
which tests failed. Please note that it can
be normal for some tests to "fail" on some
platforms. The script says a test has failed
if there is any difference at all between the
actual output of the test and the expected
output. Thus, tests may "fail" due to minor
differences in wording of error messages,
small differences in floating-point roundoff,
etc, between your system and the regression
test reference platform. "Failures" of this
type do not indicate a problem with Postgres.
The file ./regression.diffs contains the
textual differences between the actual test
output on your machine and the "expected"
output (which is simply what the reference
system produced). You should carefully
examine each difference listed to see whether
it appears to be a significant issue.
For example,
o For a i686/Linux-ELF platform, no tests
failed since this is the v6.4 regression
testing reference platform.
o For the SPARC/Linux-ELF platform, using the
970525 beta version of Postgres v6.2 the
following tests "failed": float8 and
geometry "failed" due to minor precision
differences in floating point numbers.
select_views produces massively different
output, but the differences are due to minor
floating point differences.
Even if a test result clearly indicates a
real failure, it may be a localized problem
that will not affect you. An example is that
the int8 test will fail, producing obviously
incorrect output, if your machine and C
compiler do not provide a 64-bit integer data
type (or if they do but configure didn't
discover it). This is not something to worry
about unless you need to store 64-bit
integers.
Conclusion? If you do see failures, try to
understand the nature of the differences and
then decide if those differences will affect
your intended use of Postgres. The regression
tests are a helpful tool, but they may
require some study to be useful.
After running the regression tests, type
$ destroydb regression
$ cd /usr/src/pgsql/src/test/regress
$ gmake clean
to recover the disk space used for the
tests. (You may want to save the
regression.diffs file in another place before
doing this.)
24. If you haven't already done so, this would be
a good time to modify your computer to do regular
maintainence. The following should be done at
regular intervals:
Procedure 3.2. Minimal Backup Procedure
1. Run the SQL command VACUUM. This will clean
up your database.
2. Back up your system. (You should probably
keep the last few backups on hand.) Preferably,
no one else should be using the system at the
time.
Ideally, the above tasks should be done by a shell
script that is run nightly or weekly by cron. Look
at the man page for crontab for a starting point
on how to do this. (If you do it, please e-mail us
a copy of your shell script. We would like to set
up our own systems to do this too.)
25. If you are upgrading an existing system then
reinstall your old database. Type
$ cd
$ psql -e template1 < db.out
If your pre-v6.2 database uses either path or
polygon geometric data types, then you will need
to upgrade any columns containing those types. To
do so, type (from within psql)
UPDATE FirstTable SET PathCol = UpgradePath(PathCol);
UPDATE SecondTable SET PathCol = UpgradePath(PathCol);
...
VACUUM;
UpgradePath() checks to see that a path value is
consistant with the old syntax, and will not
update a column which fails that examination.
UpgradePoly() cannot verify that a polygon is in
fact from an old syntax, but RevertPoly() is
provided to reverse the effects of a mis-applied
upgrade.
26. If you are a new user, you may wish to play
with Postgres as described below.
27. Clean up after yourself. Type
$ rm -rf /usr/src/pgsql_6_0
$ rm -rf /usr/local/pgsql_6_0
# Also delete old database directory tree if it is
not in
# /usr/local/pgsql_6_0/data
$ rm ~/postgresql-v6.2.1.tar.gz
28. You will probably want to print out the
documentation. If you have a Postscript printer,
or have your machine already set up to accept
Postscript files using a print filter, then to
print the User's Guide simply type
$ cd /usr/local/pgsql/doc
$ gunzip user.ps.tz | lpr
Here is how you might do it if you have
Ghostscript on your system and are writing to a
laserjet printer.
$ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
$ export
GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
$ gunzip user.ps.gz
$ gshp -sOUTPUTFILE=user.hp user.ps
$ gzip user.ps
$ lpr -l -s -r manpage.hp
29. The Postgres team wants to keep Postgres
working on all of the supported platforms. We
therefore ask you to let us know if you did or did
not get Postgres to work on you system. Please
send a mail message to pgsql-ports@postgresql.org
telling us the following:
o The version of Postgres (v6.4, 6.3.2, beta 981014, etc.).
o Your operating system (i.e. RedHat v5.1 Linux v2.0.34).
o Your hardware (SPARC, i486, etc.).
o Did you compile, install and run the regression
tests cleanly? If not, what source code did you
change (i.e. patches you applied, changes you
made, etc.), what tests failed, etc. It is normal
to get many warning when you compile. You do not
need to report these.
30. Now create, access and manipulate databases
as desired. Write client programs to access the
database server. In other words, enjoy!
Playing with Postgres
After Postgres is installed, a database system is
created, a postmaster daemon is running, and the
regression tests have passed, you'll want to see
Postgres do something. That's easy. Invoke the
interactive interface to Postgres, psql:
% psql template1
(psql has to open a particular database, but at this
point the only one that exists is the template1
database, which always exists. We will connect to it
only long enough to create another one and switch to
it.)
The response from psql is:
Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms
of POSTGRESQL
type \? for help on slash commands
type \q to quit
type \g or terminate with semicolon to execute
query
You are currently connected to the database:
template1
template1=>
Create the database foo:
template1=> create database foo;
CREATEDB
(Get in the habit of including those SQL semicolons.
Psql won't execute anything until it sees the
semicolon or a "\g" and the semicolon is required to
delimit multiple statements.)
Now connect to the new database:
template1=> \c foo
connecting to new database: foo
("slash" commands aren't SQL, so no semicolon. Use \?
to see all the slash commands.)
And create a table:
foo=> create table bar (i int4, c char(16));
CREATE
Then inspect the new table:
foo=> \d bar
Table = bar
+--------------+--------------+-------+
| Field | Type | Length|
+--------------+--------------+-------+
| i | int4 | 4 |
| c | (bp)char | 16 |
+--------------+--------------+-------+
And so on. You get the idea.
The Next Step
Questions? Bugs? Feedback? First, read the files in
directory /usr/src/pgsql/doc/. The FAQ in this
directory may be particularly useful.
If Postgres failed to compile on your computer then
fill out the form in file
/usr/src/pgsql/doc/bug.template and mail it to the
location indicated at the top of the form.
Check on the web site at http://www.postgresql.org
For more information on the various support mailing
lists.
Porting Notes
Note: Check for any platform-specific FAQs in the
doc/ directory of the source distribution. For
some ports, the notes below may be out of date.
Ultrix4.x
Note: There have been no recent reports of Ultrix
usage with Postgres.
You need to install the libdl-1.1 package since
Ultrix 4.x doesn't have a dynamic loader. It's
available in
s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.-
1.tar.Z
Linux
Linux ELF
The regression test reference machine is a
linux-2.0.30/libc-5.3.12/RedHat-4.2 installation
running on a dual processor i686. The linux-elf port
installs cleanly. See the Linux FAQ for more details.
Linux a.out
For non-ELF Linux, the dld library MUST be obtained
and installed on the system. It enables dynamic link
loading capability to the Postgres port. The dld
library can be obtained from the sunsite linux
distributions. The current name is dld-3.2.5. Jalon
Q. Zimmerman
BSD/OS
For BSD/OS 2.0 and 2.01, you will need to get the GNU
dld library.