2 -----------------------------------------------------------------------------
3 Version 4.0, for the PostgreSQL 7.2-1PGDG RPMset.
4 Lamar Owen <lamar.owen@wgcr.org>
5 ----------------------------------------------------------------------------
9 1.) Introduction, QuickStart, and credits
10 2.) PostgreSQL RPM packages and rationale
11 3.) Upgrading from an older version of PostgreSQL without losing data.
12 4.) Regression Testing
13 5.) Starting postmaster automatically on startup
14 6.) Grand Unified Configuration(GUC) File.
15 7.) Rebuilding the source RPM.
18 10.) Further Information Resource
21 -----------------------------------------------------------------------------
22 The postmaster '-i' option is NOT used by default in the initscript shipped
23 with these RPMs. Please do NOT modify the initscript to add the '-i' back
24 in -- it will get overwritten on the next package upgrade. Rather, see the
25 section below on the Grand Unified Configuration file, which includes the
26 recommended way to get '-i' functionality back.
29 -----------------------------------------------------------------------------
30 This document exists to explain the layout of the RPM's for PostgreSQL, to
31 explain how to migrate from an older version, and to explain WHY it can be
32 so difficult to upgrade PostgreSQL.
34 This document is written to be applicable to version 7.2 of PostgreSQL,
35 which is the current version of the RPM's as of this writing.
37 Official PostgreSQL Global Development Group RPM's will from version 7.1.2
38 on carry a 'PGDG' after the release number. Other RPMset's as distributed
39 with Linux distributions may have a different release number and initials.
41 It is preferable for the distribution-specific set to be the one used, as
42 the PGDG set is intentionally generic. So, if your distro has a set of RPMs,
43 use them in preference. If you want to stay up-to-date on the PostgreSQL
44 core itself, use the PGDG generic set -- but understand that it is a
47 These RPMs are designed to be LSB-compliant -- if you find this not to be the
48 case, please let me know by way of the pgsql-ports@postgresql.org mailing
52 -----------------------------------------------------------------------------
53 If this is an upgrade, please go to section 3, UPGRADING.
54 If this is a fresh installation, simply start the postmaster using:
55 /etc/rc.d/init.d/postgresql start (on RedHat and TurboLinux)
57 The file /var/lib/pgsql/.bash_profile is now packaged to help with the
58 setting of environment variables. You may edit this file, and it won't be
59 overwritten during an upgrade. However, enhancements and bugfixes may be added
60 to this file, so be sure to check .bash_profile.rpmnew after upgrading.
62 The user 'postgres' is created during installation of the server subpackage.
63 This user by default is UID and GID 26. The user has the default shell set to
64 bash, and the home directory set to /var/lib/pgsql. This user also has no
65 default password -- in order to be able to su to from a non-root account
66 or login as 'postgres' you will need to set a password using passwd.
69 -----------------------------------------------------------------------------
73 Trond Eivind Glomsrød
83 POSTGRESQL RPM PACKAGES AND RATIONALE.
84 -----------------------------------------------------------------------------
85 On RedHat Linux, prior to version 6.5, PostgreSQL was packaged in RPM form in
86 three (or four) packages:
88 postgresql: The server and documentation
89 postgresql-clients: The client libraries, the cli, and the tcl interface
90 postgresql-devel: Development libraries (for the client-side)
91 postgresql-data: A sample database -- not shipped with the 6.4 RPMS.
93 However, it was decided that a different split would be more appropriate for
94 users. The 7.0 splitup allows more flexibility in installation, as well as
95 making the new clients into their own packages. The new packages are:
97 postgresql: Some clients and libraries, and documentation
98 postgresql-server: Server executables and data files
99 postgresql-devel: Client-side development libraries
100 postgresql-tcl: TCL/TK client libraries and the pgaccess client
101 postgresql-perl: PERL client module
102 postgresql-python: The PygreSQL client library
103 postgresql-odbc: Linux ODBC client (not required to use ODBC from Win95)
104 postgresql-jdbc: JAR of the JDBC client
105 postgresql-test: The regression tests and associated files.
107 For version 7.0.x, another package is being shipped, and one package has been
109 postgresql-tk: Tk client and pgaccess.
110 postgresql-tcl: Tcl client and PL ONLY.
112 For version 7.1, more packages are being shipped:
113 postgresql-libs: client shared libraries.
114 postgresql-docs: extra documentation,such as the SGML doc sources.
115 postgresql-contrib: The contrib source tree, as well as selected binaries.
117 For SuSE Linux <= 7.0, the packages are named differently, but with the same
118 functionality. Here is a mapping:
120 ----- -----------------
122 pg_serv postgresql-server
123 pg_devel postgresql-devel
124 pg_tcl postgresql-tcl
125 pg_perl postgresql-perl
126 pg_pyth postgresql-python
127 pg_odbc postgresql-odbc
128 pg_jdbc postgresql-jdbc
129 pg_test postgresql-test
131 There are other changes to the SuSE packages to make them conform to the
132 SuSE packaging standards. SuSE Linux has been shipping their own packages.
134 While the repackaging will initially cause some confusion, it makes it
135 possible to set up a RedHat linux machine to be only a client -- the server
136 is no longer required. The clients were split out -- after all, a person who
137 needs the perl client may very well not need the tcl client, etc. And, the
138 regression tests were added to give some confidence of the suitability of
139 PostgreSQL, as well as the stability of the server machine. Additionally,
140 the regression tests can be used to help find hardware errors.
143 -----------------------------------------------------------------------------
144 In compliance with the Linux FHS, the PostgreSQL RPM's install files in a manner
145 not consistent with most of the PostgreSQL documentation. According to the
146 standard PostgreSQL documentation, PostgreSQL is installed under the directory
147 /usr/local/pgsql, with executables, source, and data existing in various
150 Different distributions have different ideas of some of these file locations.
151 In particular, the documentation directory can be /usr/doc, /usr/doc/packages,
152 /usr/share/doc, /usr/share/doc/packages, or some other similar path. The
153 RedHat 7 locations are listed below. On SuSE <7.1, substitute 'postgres' for
154 'postgresql' below, and 'pg_tk' for 'postgresql-tk' below.
156 However, the RPM's install the files like this:
157 Executables: /usr/bin
159 Documentation: /usr/share/doc/postgresql-x.y.z
160 Contrib: /usr/share/doc/postgresql-x.y.z/contrib
161 Source: not installed
162 Data: /var/lib/pgsql/data
163 Backup area: /var/lib/pgsql/backup
164 Templates: /usr/share/pgsql
165 Procedural Languages: /usr/lib/pgsql
166 TK client docs: /usr/share/doc/postgresql-tk-x.y.z
167 Development Headers: /usr/include/pgsql
168 Other shared data: /usr/share/pgsql
169 Regression tests: /usr/lib/pgsql/test/regress (in the -test package)
170 Documentation SGML: /usr/share/doc/postgresql-docs-x.y.z
172 The above list references the Red Hat 7.x structure. These locations may
173 change for other distributions. Use of 'rpm -ql' for each package is
174 recommended as the 'Official' location source.
176 While it may seem gratuitous to place these files in different locations, the
177 FHS requires it -- distributions should not ever touch /usr/local. It may
178 also seem like more work to keep track of where everything is -- but, that's
179 the beauty of RPM -- you don't have to keep track of the files, RPM does it
182 These RPM's are meant to be LSB-compliant. If you find errors in them that
183 cause thembe be non-compliant, please let me know.
186 -----------------------------------------------------------------------------
187 CAUTION: While a semi-automatic upgrade process has been implemented, it is
188 STRONGLY recommended that a full dump of your database (using pg_dumpall) is
189 performed BEFORE upgrading the RPMs! If you have already done the upgrade
190 with the RPM, and want to return to your previous version to do the dump,
191 find the old RPM's and use 'rpm -U --oldpackage' to downgrade.
193 I cannot overemphasize this precaution.
195 NOTE: moving your existing data from /var/lib/pgsql to /var/lib/pgsql/data is
196 not currently automatic -- you will need to do this yourself at this release!
197 This change occurred between 6.5.3 and 7.0, so upgrading from prior to 7.0 to
198 7.0 or later might be difficult.
200 NOTE: This program is not included in the packages distributed with
201 Red Hat Linux. The releasenotes specifies a dump before a system
204 The single biggest problem with upgrading PostgreSQL RPM's has been the lack
205 of a reasonably automated upgrade process. PostgreSQL has the property of
206 the binary on-disk database format changing between major versions (like
207 between 6.3 and 6.4). However, a change from 6.5 to 6.5.3 does not change
210 This property (feature, misfeature, bug, whatever) has been a known property of
211 PostgreSQL since before it was called PostgreSQL -- it has always been this
212 way. However, the means by which an upgrade is performed is not readily
213 performed in a fully automated fashion, as a "dump-initdb-restore" cycle has
214 to be performed. This doesn't appear to be too difficult -- however, dumping
215 the old database requires the old executables -- and, if you've already done
216 an rpm -U postgresql* (or upgraded from an older version of RedHat and didn't
217 specifically exclude the postgresql rpms), you no longer have the older
218 executables to dump your data. And your data is useless (until you reinstall
219 the old version, that is). All RPM's prior to late releases of version 6.5.
220 1 have this upgrade issue.
222 The newest RPM's for PostgreSQL attempt to make your job in upgrading a little
223 easier. First, during the installation of the new RPM's, a copy is made of
224 all the executable files and libraries necessary to make a backup of your data.
225 Second, the initialization script in the new postgresql-server package detects
226 the version of any database found -- if the version is old, then the startup
227 of the new version is aborted. However, if no database is found, a new one
230 One thing must be remembered -- due to the restructuring of the PostgreSQL
231 RPM's, you will have to manually select the postgresql-server package if you
232 want the server -- it is not installed by default in an upgrade. You can either
233 select it during the upgrade/install, or you can mount your RedHat CD and
234 install manually with rpm -i.
236 To facilitate upgrading, the postgresql-dump utility has been provided. Look
237 at the man page for postgresql-dump to see its usage. All executables to
238 restore the immediately prior version of the PostgreSQL database are placed in
239 the directory /usr/lib/pgsql/backup, and are accessed by the postgresql-dump
240 script. The directory /usr/lib/pgsql/backup is owned by the postgres user --
241 you can use this directory to hold dump files and preserve directories.
243 The basic sequence is:
245 postgresql-dump -t /var/lib/pgsql/backup/db.bak -p /var/lib/pgsql/backup/old -d
246 (you can abort the ASCII dump with 'Q', as it uses more) Then, (as user root):
248 service postgresql start
250 (which will automatically create a new database structure) And finally,
253 psql -e template1 </var/lib/pgsql/backup/db.bak
255 Once you are satisfied that the data has been restored properly, you may remove
256 the dump file (/var/lib/pgsql/backup/db.bak) and the preserve directory
257 (/var/lib/pgsql/backup/old).
259 EXPLANATION OF STEPS:
260 -------------------------------------------------------------------------------
261 postgresql-dump: dumps the old database structure out, using the postmaster and
262 the backend saved during the rpm upgrade. This step MUST be done as user
265 /etc/rc.d/init.d/postgresql start: initializes the new database structure that
266 the data from your old version will be restored into, does some sanity
267 checking, and starts the postmaster. Due to the nature of some of the tasks,
268 this step must be done as root.
270 psql -e: restores the old database into the new structure created by the
274 -------------------------------------------------------------------------------
275 If you have added tables, indices, or basically anything to the template1
276 database which is the default administrative database this script will NOT
277 upgrade your database. As a matter of fact you will lose your data included
278 in the template1 database. Please look at www.postgresql.org for information
279 on upgrading the template1 database. This is a known bug in the PostgreSQL
280 pg_dump and pg_dumpall utilities.
283 -------------------------------------------------------------------------------
284 One of the features of the newer RPM sets is the capability to perform the
285 regression tests. These tests stress your database installation and produce
286 results that give you assurances that the installation is complete, and that
287 your database machine is up to the task.
289 To run the regression tests under the RPM installation, make sure that
290 postmaster has been started (if not, su to root and execute the
291 '/etc/rc.d/init.d/postgresql start' init script), cd to
292 /usr/lib/pgsql/test/regress, su to postgres, and execute the command line:
293 time ./pg_regress.sh --schedule=parallel_schedule
294 This command line will start the regression tests and will both show the
295 results to the screen and store the results in the file regress.out.
296 It will also give you a crude benchmark of how fast your machine performs.
298 If tests fail, please see the file regression.diffs in that directory. If
299 you need help interpreting that file, contact the pgsql-ports list on
302 There are some tests that will almost always fail with RedHat Linux 5.x and 6.x
303 installations. The geometry, float8, and on occassion the random test will
304 fail. These failures are normal for RedHat 5.2 and 6.1. For RedHat 6.1 with
305 certain i18n settings, there will be other tests fail.
307 For 7.1RC1, all 76 tests passed on RedHat 6.2 and RedHat 7.0. This
308 was accomplished by fiddling with the locale settings. In version 7.1.2 this
309 capability was removed -- you need to set your locale to 'C' before executing
310 the first postmaster startup, or many more regression tests will fail.
312 For interpretation of the regression tests, see the PostgreSQL documentation.
314 STARTING POSTMASTER AUTOMATICALLY AT SYSTEM STARTUP
315 -------------------------------------------------------------------------------
316 RedHat Linux uses the System V Init package. A startup script for PostgreSQL
317 is provided in the server package, as /etc/rc.d/init.d/postgresql. To start
318 the postmaster, with sanity checking, as root, run
319 /etc/rc.d/init.d/postgresql start
320 to shut postmaster down,
321 /etc/rc.d/init.d/postgresql stop
322 There are other parameters to this script -- /etc/rc.d/init.d/postgresql for a
325 To get this script to run at system startup or any time the system switches into
326 runlevels 3, 4, or 5, run:
327 chkconfig --add postgresql
328 chkconfig --level 345 postgresql on
329 and the proper symlinks will be created. Check the chkconfig man page for more
330 information. Note that this is manual -- while the startup script can include
331 tags to allow chkconfig to automatically perform the symlinking, this is not
334 SuSE has maintained their own RPMset for some time -- their documentation
335 supercedes any found in this file.
337 GRAND UNIFIED CONFIGURATION (GUC) FILE
338 -------------------------------------------------------------------------------
339 The PostgreSQL server has many tunable parameters -- the file
340 /var/lib/pgsql/data/postgresql.conf is the master configuration file for the
343 The RPM ships with the default file -- you will need to tune the
344 parameters for your installation. In particular, you might want to allow
345 TCP/IP socket connections -- in order to allow these, you will need to edit
346 the postgresql.conf file. The line in question contains the string
347 'tcpip_socket' --want to both uncomment the line and set the parameter to true
348 in order to get the TCP/IP socket to open.
350 This is the same behavior the -i command line switch provides. It is
351 preferable to use the postgresql.conf file, however, as future versions
352 of the RPMset will allow multiple postmaster instances -- and that will only
353 be possible thanks to the decoupling of settings out to each datadir.
355 REBUILDING FROM SOURCE RPM
356 -------------------------------------------------------------------------------
357 If your distribution is not supported by the binary RPM's from PostgreSQL.org,
358 you will need to rebuild from the source RPM. Download the .src.rpm for this
359 release. You will need to be root to rebuild, unless you have already set up
360 a non-root build environment.
362 Install the source RPM with rpm -i, then CD to the rpm building area (on RedHat
363 this is /usr/src/redhat by default). You will have to have a full development
364 environment to rebuild the full RPM set.
366 This release of the RPMset includes the ability to conditionally build
367 sets of packages. The parameters, their defaults, and the meanings are:
369 beta 0 #build with cassert and do not strip the binaries
370 perl 1 #build the postgresql-perl package.
371 tcl 1 #build the postgresql-tcl package.
372 tkpkg 1 #build the postgresql-tk package.
373 odbc 1 #build the postgresql-odbc package.
374 jdbc 1 #build the postgresql-jdbc package.
375 test 1 #build the postgresql-test package.
376 python 1 #build the postgresql-python package.
377 pltcl 1 #build the postgresql-pltcl package.
378 forceplperl 0 #don't force a build of pl/perl over libperl.a
379 plperl 0 #don't build the postgresql-plperl package.
380 ssl 1 #use OpenSSL support.
381 kerberos 1 #use Kerberos 5 support.
382 nls 1 #build with national language support.
383 enable_mb 1 #enable multibyte encodings.
384 pgaccess 1 #build the pgaccess client, part of postgresql-tk.
385 newintarray 0 #substitute a newer intarray contrib.
387 To use these defines, invoke a rebuild like this:
388 rpm --rebuild --define 'perl 0' --define 'tcl 0' --define 'tkpkg 0'\
389 --define 'test 0' --define 'newintarray 1' --define 'kerberos 0' \
390 postgresql-7.1.3-1PGDG.src.rpm
391 This line would disable the perl, tcl, tk, and test subpackages, enable the
392 newer intarray code, and disable kerberos support.
394 More of these conditionals will be added in the future.
398 -------------------------------------------------------------------------------
399 The contents of the contrib tree are packaged into the -contrib subpackage
400 and are compiled and placed into /usr/lib/pgsql/contrib with no further
401 processing. Please see each directory under contrib for details on how to
405 -------------------------------------------------------------------------------
406 To get rollable syslog set up, see the documentation for the file
407 postgresql.conf, by default in the directory /var/lib/pgsql/data, as relates to
408 the syslog options. Then, add a line to /etc/syslog.conf, using the man page
409 for syslog.conf as a source. Example:
410 If postgresql.conf has the following lines for the syslog settings:
411 syslog = 1 # range 0-2
412 syslog_facility = 'LOCAL0'
413 syslog_ident = 'postgres'
415 Then you need to add the line to /etc/syslog.conf:
416 local0.* /var/log/postgresql
418 Then set up an entry in /etc/logrotate.d to roll postgresql the way you want it
422 -------------------------------------------------------------------------------
423 You can get more information at http://www.postgresql.org
425 Please help make this packaging better -- let me know if you find problems, or
426 better ways of doing things. You can reach me by e-mail at
427 pgsql-ports@postgresql.org -- please include an [RPM] string in the subject, as
428 I use automatic mail folder processing to put mail in the right place.
430 SuSE information is available at SuSE's website and information contacts.
431 -----------------------------------------------------------------------------