granicus.if.org Git - postgresql/blob - contrib/pg_upgrade/IMPLEMENTATION

   1 contrib/pg_upgrade/IMPLEMENTATION
   2
   3 ------------------------------------------------------------------------------
   4 PG_UPGRADE: IN-PLACE UPGRADES FOR POSTGRESQL
   5 ------------------------------------------------------------------------------
   6
   7 Upgrading a PostgreSQL database from one major release to another can be
   8 an expensive process. For minor upgrades, you can simply install new
   9 executables and forget about upgrading existing data. But for major
  10 upgrades, you have to export all of your data using pg_dump, install the
  11 new release, run initdb to create a new cluster, and then import your
  12 old data. If you have a lot of data, that can take a considerable amount
  13 of time. If you have too much data, you may have to buy more storage
  14 since you need enough room to hold the original data plus the exported
  15 data.  pg_upgrade can reduce the amount of time and disk space required
  16 for many upgrades.
  17
  18 The URL http://momjian.us/main/writings/pgsql/pg_upgrade.pdf contains a
  19 presentation about pg_upgrade internals that mirrors the text
  20 description below.
  21
  22 ------------------------------------------------------------------------------
  23 WHAT IT DOES
  24 ------------------------------------------------------------------------------
  25
  26 pg_upgrade is a tool that performs an in-place upgrade of existing
  27 data. Some upgrades change the on-disk representation of data;
  28 pg_upgrade cannot help in those upgrades.  However, many upgrades do
  29 not change the on-disk representation of a user-defined table.  In those
  30 cases, pg_upgrade can move existing user-defined tables from the old
  31 database cluster into the new cluster.
  32
  33 There are two factors that determine whether an in-place upgrade is
  34 practical.
  35
  36 Every table in a cluster shares the same on-disk representation of the
  37 table headers and trailers and the on-disk representation of tuple
  38 headers. If this changes between the old version of PostgreSQL and the
  39 new version, pg_upgrade cannot move existing tables to the new cluster;
  40 you will have to pg_dump the old data and then import that data into the
  41 new cluster.
  42
  43 Second, all data types should have the same binary representation
  44 between the two major PostgreSQL versions.
  45
  46 ------------------------------------------------------------------------------
  47 HOW IT WORKS
  48 ------------------------------------------------------------------------------
  49
  50 To use pg_upgrade during an upgrade, start by installing a fresh
  51 cluster using the newest version in a new directory. When you've
  52 finished installation, the new cluster will contain the new executables
  53 and the usual template0, template1, and postgres, but no user-defined
  54 tables. At this point, you can shut down the old and new postmasters and
  55 invoke pg_upgrade.
  56
  57 When pg_upgrade starts, it ensures that all required executables are
  58 present and contain the expected version numbers. The verification
  59 process also checks the old and new $PGDATA directories to ensure that
  60 the expected files and subdirectories are in place.  If the verification
  61 process succeeds, pg_upgrade starts the old postmaster and runs
  62 pg_dumpall --schema-only to capture the metadata contained in the old
  63 cluster. The script produced by pg_dumpall will be used in a later step
  64 to recreate all user-defined objects in the new cluster.
  65
  66 Note that the script produced by pg_dumpall will only recreate
  67 user-defined objects, not system-defined objects.  The new cluster will
  68 contain the system-defined objects created by the latest version of
  69 PostgreSQL.
  70
  71 Once pg_upgrade has extracted the metadata from the old cluster, it
  72 performs a number of bookkeeping tasks required to 'sync up' the new
  73 cluster with the existing data.
  74
  75 First, pg_upgrade copies the commit status information and 'next
  76 transaction ID' from the old cluster to the new cluster. This is the
  77 steps ensures that the proper tuples are visible from the new cluster.
  78 Remember, pg_upgrade does not export/import the content of user-defined
  79 tables so the transaction IDs in the new cluster must match the
  80 transaction IDs in the old data. pg_upgrade also copies the starting
  81 address for write-ahead logs from the old cluster to the new cluster.
  82
  83 Now pg_upgrade begins reconstructing the metadata obtained from the old
  84 cluster using the first part of the pg_dumpall output.
  85
  86 Next, pg_upgrade executes the remainder of the script produced earlier
  87 by pg_dumpall --- this script effectively creates the complete
  88 user-defined metadata from the old cluster to the new cluster.  It
  89 preserves the relfilenode numbers so TOAST and other references
  90 to relfilenodes in user data is preserved.  (See binary-upgrade usage
  91 in pg_dump).
  92
  93 Finally, pg_upgrade links or copies each user-defined table and its
  94 supporting indexes and toast tables from the old cluster to the new
  95 cluster.
  96
  97 An important feature of the pg_upgrade design is that it leaves the
  98 original cluster intact --- if a problem occurs during the upgrade, you
  99 can still run the previous version, after renaming the tablespaces back
 100 to the original names.