Using pg upgrade on Ubuntu/Debian

Instructions for how to convert/upgrade a PostgreSQL database cluster using pg_upgrade on Ubuntu or Debian. For the sake of example, I'm upgrading from version 9.1 to 9.2, but it should work with any version (8.3 and up -- subject to limitations in pg_upgrade).
Simply replace any version numbers on the example command lines given below.
== WARNING! ==
These instructions are experimental! This way of upgrading is not yet supported by Ubuntu upstream. Do it at your own risk. Always test in a staging environment before running on production. I have tested this on Ubuntu 12.04.
When in doubt, use the old but slower pg_upgradecluster method.
Update: postgresql-common 141 (released in April 2013) supports pg_upgrade via pg_upgradecluster --method=upgrade. See the manpage for details.
== Prerequisites ==
First you need to install relevant packages: postgresql-VER and postgresql-server-dev-VER. If you're using contrib extensions, you also need postgresql-contrib-VER, and possibly other modules like postgresql-plpython-VER...
 sudo apt-get install postgresql-9.1 postgresql-contrib-9.1 postgresql-server-dev-9.1 \
 postgresql-9.2 postgresql-contrib-9.2 postgresql-server-dev-9.2
By default, Ubuntu creates a database cluster named "main" with each installed version. We will use these. Verify that these are configured:
 # sudo pg_lsclusters
 Version Cluster Port Status Owner Data directory Log file
 9.1 main 5432 down postgres /var/lib/postgresql/9.1/main /var/log/postgresql/postgresql-9.1-main.log
 9.2 main 5433 down postgres /var/lib/postgresql/9.2/main /var/log/postgresql/postgresql-9.2-main.log
== Upgrading to version 9.2 or later ==
First you need to stop the relevant database clusters. To stop all clusters, run:
 sudo /etc/init.d/postgresql stop
(If you don't want to stop all clusters, you can also use pg_ctlcluster to manage them one by one)
Do the upgrade... (For extra performance, you can use the --link option to pg_upgrade; please read pg_upgrade documentation first)
 cd /tmp
 sudo -H -u postgres /usr/lib/postgresql/9.2/bin/pg_upgrade \
 -b /usr/lib/postgresql/9.1/bin \
 -B /usr/lib/postgresql/9.2/bin \
 -d /var/lib/postgresql/9.1/main \
 -D /var/lib/postgresql/9.2/main \
 -o ' -c config_file=/etc/postgresql/9.1/main/postgresql.conf' \
 -O ' -c config_file=/etc/postgresql/9.2/main/postgresql.conf'
See if it worked...
 sudo pg_ctlcluster 9.2 main start
 sudo -u postgres psql --cluster 9.2/main
 postgres=# select version();
 PostgreSQL 9.2rc1 on x86_64-unknown-linux-gnu, compiled by gcc (Ubuntu/Linaro 4.6.3-1ubuntu5) 4.6.3, 64-bit
 postgres=# \l+
 ... list of databases ...
== Upgrading to version 9.1 ==
The above instructions don't work when you upgrade to PostgreSQL 9.1. You have to jump through some hoops.
First, stop all clusters:
 sudo /etc/init.d/postgresql stop
Note that I'm now using version numbers 9.0 and 9.1:
 # sudo pg_lsclusters
 Version Cluster Port Status Owner Data directory Log file
 9.0 main 5432 down postgres /var/lib/postgresql/9.0/main /var/log/postgresql/postgresql-9.0-main.log
 9.1 main 5433 down postgres /var/lib/postgresql/9.1/main /var/log/postgresql/postgresql-9.1-main.log
First you have to symlink the configuration files to respective PostgreSQL data directories, where pg_upgrade expects to find them.
 ln -s /etc/postgresql/9.1/main/postgresql.conf /var/lib/postgresql/9.1/main/
 ln -s /etc/postgresql/9.0/main/postgresql.conf /var/lib/postgresql/9.0/main/
And now you have to run the pg_upgrade script with your respective configured port numbers:
 cd /tmp
 sudo -H -u postgres /usr/lib/postgresql/9.1/bin/pg_upgrade \
 -b /usr/lib/postgresql/9.0/bin \
 -B /usr/lib/postgresql/9.1/bin \
 -d /var/lib/postgresql/9.0/main \
 -D /var/lib/postgresql/9.1/main \
 -p 5432 \
 -P 5433
Afterwards, you may delete the unnecessary config file links (but it's safe to leave them there if you want)
 rm /var/lib/postgresql/9.1/main/postgresql.conf
 rm /var/lib/postgresql/9.0/main/postgresql.conf
== What next ==
Don't forget to merge your configuration changes in postgresql.conf, pg_hba.conf and other files.
If you upgraded from 9.0 or earlier and you're using contrib modules or other addons, it is recommended to migrate them to proper extensions. For example:
CREATE EXTENSION hstore SCHEMA public FROM unpackaged;
== Troubleshooting ==
==== New cluster database "XXX" is not empty ====
The new cluster version already contains some data. If you want to get rid of it -- delete all data in the 9.2 version cluster, run:
 pg_dropcluster 9.2 main
 pg_createcluster 9.2 main
==== Where do I get PostgreSQL 9.2? ====
On Ubuntu, you can simply install 9.2 from the semi-official "PPA" repository:
 sudo apt-get install python-software-properties
 sudo apt-add-repository ppa:pitti/postgresql
 sudo apt-get update
 sudo apt-get install postgresql-9.2 postgresql-contrib-9.2 postgresql-server-dev-9.2
Warning: Support for the current major version in the PPA may be dropped when a new major version is released. If you want to use this PPA, be prepared to always upgrade to the newest major version soon after it's released.