1 files changed, 114 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5e48b28
--- /dev/null
+++ b/README.md
@@ -0,0 +1,114 @@
+Multi-Version/Multi-Cluster PostgreSQL architecture
+===================================================
+2004, Oliver Elphick, Martin Pitt
+
+Solving a problem
+-----------------
+
+When a new major version of PostgreSQL is released, it is necessary to dump and
+reload the database. The old software must be used for the dump, and the new
+software for the reload.
+
+This was a major problem for RedHat and Debian, because a dump and reload was
+not required by every upgrade and by the time the need for a dump is realised,
+the old software might have been deleted. Debian had certain rather unreliable
+procedures to save the old software and use it to do a dump, but these
+procedures often went wrong. RedHat's installation environment is so rigid that
+it is not practicable for the RedHat packages to attempt an automatic upgrade.
+Debian offered a debconf choice for whether to attempt automatic upgrading; if
+it failed or was not allowed, a manual upgrade had to be done, either from a
+pre-existing dump or by manual invocation of the postgresql-dump script.
+
+It is possible to run different versions of PostgreSQL simultaneously, and
+indeed to run the same version on separate database clusters simultaneously. To
+do so, each postgres instance must listen on a different port, so each client
+must specify the correct port. By having two separate versions of the
+PostgreSQL packages installed simultaneously, it is simple to do database
+upgrades by dumping from the old version and uploading to the new. The
+PostgreSQL client wrapper is designed to permit this.
+
+General Architecture idea
+-------------------------
+
+The Debian packaging has been changed to create a new package for each major
+version. The criterion for creating a new package is that initdb is required
+when upgrading from the previous version. Thus, there are now source packages
+`postgresql-8.1` and `postgresql-8.3` (and similarly for all the binary
+packages).
+
+The legacy postgresql and the other existing binary package names have become
+dummy packages depending on one of the versioned equivalents. Their only
+purpose is now to ensure a smooth upgrade and to register the existing database
+cluster to the new architecture. These packages will be removed from the
+archive as soon as the next Debian release after Sarge (Etch) is released.
+
+Each versioned package installs into `/usr/lib/postgresql/version`.  In order
+to allow users easily to select the right version and cluster when working, the
+`postgresql-common` package provides the `pg_wrapper` program, which reads the
+per-user and system wide configuration file and forks the correct executable
+with the correct library versions according to those preferences.  `/usr/bin`
+provides executables soft-linked to `pg_wrapper`.
+
+This architecture also allows separate database clusters to be maintained for
+the use of different groups of users; these clusters need not all be of the
+same major version.  This allows much greater flexibility for those people who
+need to make application software changes consequent on a PostgreSQL upgrade.
+
+Detailed structure
+------------------
+
+### Configuration hierarchy
+
+* `/etc/postgresql-common/user_clusters`: maps users against clusters and
+  default databases
+
+* `$HOME/.postgresqlrc`: per-user preferences for default version/cluster and
+  database; overrides `/etc/postgresql-common/user_clusters`
+
+* `/etc/postgresql/version/clustername`: cluster-specific configuration files:
+
+  * `postgresql.conf`, `pg_hba.conf`, `pg_ident.conf`
+  * optionally `start.conf`: startup mode of the cluster: `auto` (start/stop in
+    init script), `manual` (do not start/stop in init script, but manual
+    control with `pg_ctlcluster` is possible), `disabled` (`pg_ctlcluster`
+    is not allowed).
+  * optionally `pg_ctl.conf`: options to be passed to `pg_ctl`.
+  * optionally a symbolic link `log` which points to the postgres log file.
+    Defaults to `/var/log/postgresql/postgresql-version-cluster.conf`.
+    Explicitly setting `log_directory` and/or `log_filename` in
+    `postgresql.conf` overrides this.
+
+### Per-version files and programs
+
+* `/usr/lib/postgresql/version`
+* `/usr/share/postgresql/version`
+* `/usr/share/doc/postgresql/postgresql-doc-version`:
+version specific program and data files
+
+### Common programs
+
+* `/usr/share/postgresql-common/pg_wrapper`: environment chooser and program selector
+* `/usr/bin/program`: symbolic links to pg_wrapper, for all client programs
+* `/usr/bin/pg_lsclusters`: list all available clusters with their status and configuration
+* `/usr/bin/pg_createcluster: wrapper for `initdb`, sets up the necessary configuration structure
+* `/usr/bin/pg_ctlcluster`: wrapper for `pg_ctl`, control the cluster postgres server
+* `/usr/bin/pg_upgradecluster`: upgrade a cluster to a newer major version
+* `/usr/bin/pg_dropcluster`: remove a cluster and its configuration
+
+### /etc/init.d/postgresql
+
+This script handles the postgres server processes for each version and all
+their clusters. However, most of the actual work is done by the new
+`pg_ctlcluster` program.
+
+### pg_upgradecluster
+
+This program replaces postgresql-dump (a Debian specific program).
+
+It is used to migrate a cluster from one major version to another.
+
+Usage: `pg_upgradecluster [-v newversion] version name [data_dir]`
+
+`-v`: specifies the version to upgrade to; defaults to the newest available version.
+
+ -- The Debian PostgreSQL maintainers