← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/upgrading.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/upgrading.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<HTML
 
3
><HEAD
 
4
><TITLE
 
5
>Upgrading a PostgreSQL Cluster</TITLE
 
6
><META
 
7
NAME="GENERATOR"
 
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
 
9
REV="MADE"
 
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
 
11
REL="HOME"
 
12
TITLE="PostgreSQL 9.1beta1 Documentation"
 
13
HREF="index.html"><LINK
 
14
REL="UP"
 
15
TITLE="Server Setup and Operation"
 
16
HREF="runtime.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="Shutting Down the Server"
 
19
HREF="server-shutdown.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="Preventing Server Spoofing"
 
22
HREF="preventing-server-spoofing.html"><LINK
 
23
REL="STYLESHEET"
 
24
TYPE="text/css"
 
25
HREF="stylesheet.css"><META
 
26
HTTP-EQUIV="Content-Type"
 
27
CONTENT="text/html; charset=ISO-8859-1"><META
 
28
NAME="creation"
 
29
CONTENT="2011-04-27T21:20:33"></HEAD
 
30
><BODY
 
31
CLASS="SECT1"
 
32
><DIV
 
33
CLASS="NAVHEADER"
 
34
><TABLE
 
35
SUMMARY="Header navigation table"
 
36
WIDTH="100%"
 
37
BORDER="0"
 
38
CELLPADDING="0"
 
39
CELLSPACING="0"
 
40
><TR
 
41
><TH
 
42
COLSPAN="5"
 
43
ALIGN="center"
 
44
VALIGN="bottom"
 
45
><A
 
46
HREF="index.html"
 
47
>PostgreSQL 9.1beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="Shutting Down the Server"
 
57
HREF="server-shutdown.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
TITLE="Server Setup and Operation"
 
67
HREF="runtime.html"
 
68
>Fast Backward</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
>Chapter 17. Server Setup and Operation</TD
 
75
><TD
 
76
WIDTH="10%"
 
77
ALIGN="right"
 
78
VALIGN="top"
 
79
><A
 
80
TITLE="Server Setup and Operation"
 
81
HREF="runtime.html"
 
82
>Fast Forward</A
 
83
></TD
 
84
><TD
 
85
WIDTH="10%"
 
86
ALIGN="right"
 
87
VALIGN="top"
 
88
><A
 
89
TITLE="Preventing Server Spoofing"
 
90
HREF="preventing-server-spoofing.html"
 
91
ACCESSKEY="N"
 
92
>Next</A
 
93
></TD
 
94
></TR
 
95
></TABLE
 
96
><HR
 
97
ALIGN="LEFT"
 
98
WIDTH="100%"></DIV
 
99
><DIV
 
100
CLASS="SECT1"
 
101
><H1
 
102
CLASS="SECT1"
 
103
><A
 
104
NAME="UPGRADING"
 
105
>17.6. Upgrading a <SPAN
 
106
CLASS="PRODUCTNAME"
 
107
>PostgreSQL</SPAN
 
108
> Cluster</A
 
109
></H1
 
110
><P
 
111
>   This section discusses how to upgrade your database data from one
 
112
   <SPAN
 
113
CLASS="PRODUCTNAME"
 
114
>PostgreSQL</SPAN
 
115
> release to a newer one.
 
116
  </P
 
117
><P
 
118
>   <SPAN
 
119
CLASS="PRODUCTNAME"
 
120
>PostgreSQL</SPAN
 
121
> major versions are represented by the
 
122
   first two digit groups of the version number, e.g., 8.4.
 
123
   <SPAN
 
124
CLASS="PRODUCTNAME"
 
125
>PostgreSQL</SPAN
 
126
> minor versions are represented by the
 
127
   third group of version digits, e.g., 8.4.2 is the second minor
 
128
   release of 8.4.  Minor releases never change the internal storage
 
129
   format and are always compatible with earlier and later minor
 
130
   releases of the same major version number, e.g., 8.4.2 is compatible
 
131
   with 8.4, 8.4.1 and 8.4.6.  To update between compatible versions,
 
132
   you simply replace the executables while the server is down and
 
133
   restart the server.  The data directory remains unchanged &mdash;
 
134
   minor upgrades are that simple.
 
135
  </P
 
136
><P
 
137
>   For <SPAN
 
138
CLASS="emphasis"
 
139
><I
 
140
CLASS="EMPHASIS"
 
141
>major</I
 
142
></SPAN
 
143
> releases of <SPAN
 
144
CLASS="PRODUCTNAME"
 
145
>PostgreSQL</SPAN
 
146
>, the
 
147
   internal data storage format is subject to change, thus complicating
 
148
   upgrades.  The traditional method for moving data to a new major version
 
149
   is to dump and reload the database.  Other methods are available,
 
150
   as discussed below.
 
151
  </P
 
152
><P
 
153
>   New major versions also typically introduce some user-visible
 
154
   incompatibilities, so application programming changes might be required.
 
155
   All user-visible changes are listed in the release notes (<A
 
156
HREF="release.html"
 
157
>Appendix E</A
 
158
>);  pay particular attention to the section
 
159
   labeled "Migration".  If you are upgrading across several major
 
160
   versions, be sure to read the release notes for each intervening
 
161
   version.
 
162
  </P
 
163
><P
 
164
>   Cautious users will want to test their client applications on the new
 
165
   version before switching over fully; therefore, it's often a good idea to
 
166
   set up concurrent installations of old and new versions.  When
 
167
   testing a <SPAN
 
168
CLASS="PRODUCTNAME"
 
169
>PostgreSQL</SPAN
 
170
> major upgrade, consider the
 
171
   following categories of possible changes:
 
172
  </P
 
173
><P
 
174
></P
 
175
><DIV
 
176
CLASS="VARIABLELIST"
 
177
><DL
 
178
><DT
 
179
>Administration</DT
 
180
><DD
 
181
><P
 
182
>      The capabilities available for administrators to monitor and control
 
183
      the server often change and improve in each major release.
 
184
     </P
 
185
></DD
 
186
><DT
 
187
>SQL</DT
 
188
><DD
 
189
><P
 
190
>      Typically this includes new SQL command capabilities and not changes
 
191
      in behavior, unless specifically mentioned in the release notes.
 
192
     </P
 
193
></DD
 
194
><DT
 
195
>Library API</DT
 
196
><DD
 
197
><P
 
198
>      Typically libraries like <SPAN
 
199
CLASS="APPLICATION"
 
200
>libpq</SPAN
 
201
> only add new
 
202
      functionality, again unless mentioned in the release notes.
 
203
     </P
 
204
></DD
 
205
><DT
 
206
>System Catalogs</DT
 
207
><DD
 
208
><P
 
209
>      System catalog changes usually only affect database management tools.
 
210
     </P
 
211
></DD
 
212
><DT
 
213
>Server C-language API</DT
 
214
><DD
 
215
><P
 
216
>      This involves changes in the backend function API, which is written
 
217
      in the C programming language.  Such changes affect code that
 
218
      references backend functions deep inside the server.
 
219
     </P
 
220
></DD
 
221
></DL
 
222
></DIV
 
223
><DIV
 
224
CLASS="SECT2"
 
225
><H2
 
226
CLASS="SECT2"
 
227
><A
 
228
NAME="UPGRADE-METHODS-PGDUMP"
 
229
>17.6.1. Upgrading Data via <SPAN
 
230
CLASS="APPLICATION"
 
231
>pg_dump</SPAN
 
232
></A
 
233
></H2
 
234
><P
 
235
>    To dump data from one major version of <SPAN
 
236
CLASS="PRODUCTNAME"
 
237
>PostgreSQL</SPAN
 
238
> and
 
239
    reload it in another, you must use <SPAN
 
240
CLASS="APPLICATION"
 
241
>pg_dump</SPAN
 
242
>; file system
 
243
    level backup methods will not work. (There are checks in place that prevent
 
244
    you from using a data directory with an incompatible version of
 
245
    <SPAN
 
246
CLASS="PRODUCTNAME"
 
247
>PostgreSQL</SPAN
 
248
>, so no great harm can be done by
 
249
    trying to start the wrong server version on a data directory.)
 
250
   </P
 
251
><P
 
252
>    It is recommended that you use the <SPAN
 
253
CLASS="APPLICATION"
 
254
>pg_dump</SPAN
 
255
> and
 
256
    <SPAN
 
257
CLASS="APPLICATION"
 
258
>pg_dumpall</SPAN
 
259
> programs from the newer version of
 
260
    <SPAN
 
261
CLASS="PRODUCTNAME"
 
262
>PostgreSQL</SPAN
 
263
>, to take advantage of enhancements
 
264
    that might have been made in these programs.  Current releases of the
 
265
    dump programs can read data from any server version back to 7.0.
 
266
   </P
 
267
><P
 
268
>    These instructions assume that your existing installation is under the
 
269
    <TT
 
270
CLASS="FILENAME"
 
271
>/usr/local/pgsql</TT
 
272
> directory, and that the data area is in
 
273
    <TT
 
274
CLASS="FILENAME"
 
275
>/usr/local/pgsql/data</TT
 
276
>.  Substitute your paths
 
277
    appropriately.
 
278
   </P
 
279
><DIV
 
280
CLASS="PROCEDURE"
 
281
><OL
 
282
TYPE="1"
 
283
><LI
 
284
CLASS="STEP"
 
285
><P
 
286
>      If making a backup, make sure that your database is not being updated.
 
287
      This does not affect the integrity of the backup, but the changed
 
288
      data would of course not be included. If necessary, edit the
 
289
      permissions in the file <TT
 
290
CLASS="FILENAME"
 
291
>/usr/local/pgsql/data/pg_hba.conf</TT
 
292
>
 
293
      (or equivalent) to disallow access from everyone except you.
 
294
      See <A
 
295
HREF="client-authentication.html"
 
296
>Chapter 19</A
 
297
> for additional information on
 
298
      access control.
 
299
     </P
 
300
><P
 
301
>      
 
302
 
 
303
      To back up your database installation, type:
 
304
</P><PRE
 
305
CLASS="SCREEN"
 
306
><KBD
 
307
CLASS="USERINPUT"
 
308
>pg_dumpall &gt; <TT
 
309
CLASS="REPLACEABLE"
 
310
><I
 
311
>outputfile</I
 
312
></TT
 
313
></KBD
 
314
></PRE
 
315
><P>
 
316
      If you need to preserve OIDs (such as when using them as
 
317
      foreign keys), then use the <TT
 
318
CLASS="OPTION"
 
319
>-o</TT
 
320
> option when running
 
321
      <SPAN
 
322
CLASS="APPLICATION"
 
323
>pg_dumpall</SPAN
 
324
>.
 
325
     </P
 
326
><P
 
327
>      To make the backup, you can use the <SPAN
 
328
CLASS="APPLICATION"
 
329
>pg_dumpall</SPAN
 
330
>
 
331
      command from the version you are currently running.  For best
 
332
      results, however, try to use the <SPAN
 
333
CLASS="APPLICATION"
 
334
>pg_dumpall</SPAN
 
335
>
 
336
      command from <SPAN
 
337
CLASS="PRODUCTNAME"
 
338
>PostgreSQL</SPAN
 
339
> 9.1beta1,
 
340
      since this version contains bug fixes and improvements over older
 
341
      versions.  While this advice might seem idiosyncratic since you
 
342
      haven't installed the new version yet, it is advisable to follow
 
343
      it if you plan to install the new version in parallel with the
 
344
      old version.  In that case you can complete the installation
 
345
      normally and transfer the data later.  This will also decrease
 
346
      the downtime.
 
347
     </P
 
348
></LI
 
349
><LI
 
350
CLASS="STEP"
 
351
><P
 
352
>      Shut down the old server:
 
353
</P><PRE
 
354
CLASS="SCREEN"
 
355
><KBD
 
356
CLASS="USERINPUT"
 
357
>pg_ctl stop</KBD
 
358
></PRE
 
359
><P>
 
360
      On systems that have <SPAN
 
361
CLASS="PRODUCTNAME"
 
362
>PostgreSQL</SPAN
 
363
> started at boot time,
 
364
      there is probably a start-up file that will accomplish the same thing. For
 
365
      example, on a <SPAN
 
366
CLASS="SYSTEMITEM"
 
367
>Red Hat Linux</SPAN
 
368
> system one
 
369
      might find that this works:
 
370
</P><PRE
 
371
CLASS="SCREEN"
 
372
><KBD
 
373
CLASS="USERINPUT"
 
374
>/etc/rc.d/init.d/postgresql stop</KBD
 
375
></PRE
 
376
><P>
 
377
      See <A
 
378
HREF="runtime.html"
 
379
>Chapter 17</A
 
380
> for details about starting and
 
381
      stoping the server.
 
382
     </P
 
383
></LI
 
384
><LI
 
385
CLASS="STEP"
 
386
><P
 
387
>      If restoring from backup, rename or delete the old installation
 
388
      directory.  It is a good idea to rename the directory, rather than
 
389
      delete it, in case you have trouble and need to revert to it.  Keep
 
390
      in mind the directory might consume significant disk space.  To rename
 
391
      the directory, use a command like this:
 
392
</P><PRE
 
393
CLASS="SCREEN"
 
394
><KBD
 
395
CLASS="USERINPUT"
 
396
>mv /usr/local/pgsql /usr/local/pgsql.old</KBD
 
397
></PRE
 
398
><P>
 
399
     (Be sure to move the directory as a single unit so relative paths
 
400
     remain unchanged.)
 
401
     </P
 
402
></LI
 
403
><LI
 
404
CLASS="STEP"
 
405
><P
 
406
>      Install the new version of <SPAN
 
407
CLASS="PRODUCTNAME"
 
408
>PostgreSQL</SPAN
 
409
> as
 
410
      outlined in 
 
411
      <A
 
412
HREF="install-procedure.html"
 
413
>Section 15.4</A
 
414
>.
 
415
     </P
 
416
></LI
 
417
><LI
 
418
CLASS="STEP"
 
419
><P
 
420
>      Create a new database cluster if needed.  Remember that you must
 
421
      execute these commands while logged in to the special database user
 
422
      account (which you already have if you are upgrading).
 
423
</P><PRE
 
424
CLASS="PROGRAMLISTING"
 
425
><KBD
 
426
CLASS="USERINPUT"
 
427
>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</KBD
 
428
></PRE
 
429
><P>
 
430
     </P
 
431
></LI
 
432
><LI
 
433
CLASS="STEP"
 
434
><P
 
435
>      Restore your previous <TT
 
436
CLASS="FILENAME"
 
437
>pg_hba.conf</TT
 
438
> and any
 
439
      <TT
 
440
CLASS="FILENAME"
 
441
>postgresql.conf</TT
 
442
> modifications.
 
443
     </P
 
444
></LI
 
445
><LI
 
446
CLASS="STEP"
 
447
><P
 
448
>      Start the database server, again using the special database user
 
449
      account:
 
450
</P><PRE
 
451
CLASS="PROGRAMLISTING"
 
452
><KBD
 
453
CLASS="USERINPUT"
 
454
>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</KBD
 
455
></PRE
 
456
><P>
 
457
     </P
 
458
></LI
 
459
><LI
 
460
CLASS="STEP"
 
461
><P
 
462
>      Finally, restore your data from backup with:
 
463
</P><PRE
 
464
CLASS="SCREEN"
 
465
><KBD
 
466
CLASS="USERINPUT"
 
467
>/usr/local/pgsql/bin/psql -d postgres -f <TT
 
468
CLASS="REPLACEABLE"
 
469
><I
 
470
>outputfile</I
 
471
></TT
 
472
></KBD
 
473
></PRE
 
474
><P>
 
475
      using the <SPAN
 
476
CLASS="emphasis"
 
477
><I
 
478
CLASS="EMPHASIS"
 
479
>new</I
 
480
></SPAN
 
481
> <SPAN
 
482
CLASS="APPLICATION"
 
483
>psql</SPAN
 
484
>.
 
485
     </P
 
486
></LI
 
487
></OL
 
488
></DIV
 
489
><P
 
490
>    The least downtime can be achieved by installing the new server in
 
491
    a different directory and running both the old and the new servers
 
492
    in parallel, on different ports. Then you can use something like:
 
493
 
 
494
</P><PRE
 
495
CLASS="PROGRAMLISTING"
 
496
>pg_dumpall -p 5432 | psql -d postgres -p 5433</PRE
 
497
><P>
 
498
    to transfer your data.
 
499
   </P
 
500
></DIV
 
501
><DIV
 
502
CLASS="SECT2"
 
503
><H2
 
504
CLASS="SECT2"
 
505
><A
 
506
NAME="UPGRADING-METHODS-OTHER"
 
507
>17.6.2. Non-Dump Upgrade Methods</A
 
508
></H2
 
509
><P
 
510
>    The <A
 
511
HREF="pgupgrade.html"
 
512
>pg_upgrade</A
 
513
> module allows an
 
514
    installation to be migrated in-place from one major
 
515
    <SPAN
 
516
CLASS="PRODUCTNAME"
 
517
>PostgreSQL</SPAN
 
518
> version to the next.  Upgrades can be
 
519
    performed in minutes.
 
520
   </P
 
521
><P
 
522
>    It is also possible to use certain replication methods, such as
 
523
    <SPAN
 
524
CLASS="PRODUCTNAME"
 
525
>Slony</SPAN
 
526
>, to create a standby server with the updated version of
 
527
    <SPAN
 
528
CLASS="PRODUCTNAME"
 
529
>PostgreSQL</SPAN
 
530
>.  This is possible because Slony supports
 
531
    replication between different major versions of
 
532
    <SPAN
 
533
CLASS="PRODUCTNAME"
 
534
>PostgreSQL</SPAN
 
535
>.  The standby can be on the same computer or
 
536
    a different computer.  Once it has synced up with the master server
 
537
    (running the older version of <SPAN
 
538
CLASS="PRODUCTNAME"
 
539
>PostgreSQL</SPAN
 
540
>), you can
 
541
    switch masters and make the standby the master and shut down the older
 
542
    database instance.  Such a switch-over results in only several seconds
 
543
    of downtime for an upgrade.
 
544
   </P
 
545
></DIV
 
546
></DIV
 
547
><DIV
 
548
CLASS="NAVFOOTER"
 
549
><HR
 
550
ALIGN="LEFT"
 
551
WIDTH="100%"><TABLE
 
552
SUMMARY="Footer navigation table"
 
553
WIDTH="100%"
 
554
BORDER="0"
 
555
CELLPADDING="0"
 
556
CELLSPACING="0"
 
557
><TR
 
558
><TD
 
559
WIDTH="33%"
 
560
ALIGN="left"
 
561
VALIGN="top"
 
562
><A
 
563
HREF="server-shutdown.html"
 
564
ACCESSKEY="P"
 
565
>Prev</A
 
566
></TD
 
567
><TD
 
568
WIDTH="34%"
 
569
ALIGN="center"
 
570
VALIGN="top"
 
571
><A
 
572
HREF="index.html"
 
573
ACCESSKEY="H"
 
574
>Home</A
 
575
></TD
 
576
><TD
 
577
WIDTH="33%"
 
578
ALIGN="right"
 
579
VALIGN="top"
 
580
><A
 
581
HREF="preventing-server-spoofing.html"
 
582
ACCESSKEY="N"
 
583
>Next</A
 
584
></TD
 
585
></TR
 
586
><TR
 
587
><TD
 
588
WIDTH="33%"
 
589
ALIGN="left"
 
590
VALIGN="top"
 
591
>Shutting Down the Server</TD
 
592
><TD
 
593
WIDTH="34%"
 
594
ALIGN="center"
 
595
VALIGN="top"
 
596
><A
 
597
HREF="runtime.html"
 
598
ACCESSKEY="U"
 
599
>Up</A
 
600
></TD
 
601
><TD
 
602
WIDTH="33%"
 
603
ALIGN="right"
 
604
VALIGN="top"
 
605
>Preventing Server Spoofing</TD
 
606
></TR
 
607
></TABLE
 
608
></DIV
 
609
></BODY
 
610
></HTML
 
611
>
 
 
b'\\ No newline at end of file'