[gentoo-commits] proj/pgsql-patches:documentation commit in: /

[Aaron Swenson]

commit:     8c4e0857d0808c07f16bd2cc4452b254ef66ab46
Author:     Aaron W. Swenson <titanofold <AT> gentoo <DOT> org>
AuthorDate: Wed Jun 15 19:46:26 2011 +0000
Commit:     Aaron Swenson <titanofold <AT> gentoo <DOT> org>
CommitDate: Wed Jun 15 19:46:26 2011 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/pgsql-patches.git;a=commit;h=8c4e0857

Cleaned up some. Removed section about Sandbox as the ebuild now depends on the
proper version of Sandbox.

---
 postgresql.xml |  123 +++++++++++++++++++++++---------------------------------
 1 files changed, 51 insertions(+), 72 deletions(-)

diff --git a/postgresql.xml b/postgresql.xml
index c7bac14..174a384 100644
--- a/postgresql.xml
+++ b/postgresql.xml
@@ -158,9 +158,8 @@ ebuilds to the new ones.
   <tr>
     <ti>doc</ti>
     <ti>
-      Include the <uri 
-      link="http://www.postgresql.org/docs/">online documentation</uri> to be 
-      stored on your system
+      Include the <uri link="http://www.postgresql.org/docs/">online
+      documentation</uri> to be stored on your system
     </ti>
   </tr>
   <tr>
@@ -195,15 +194,19 @@ ebuilds to the new ones.
   <tr>
     <ti>pg-intdatetime (Deprecated)</ti>
     <ti>
-      Use the newer method for formatting time stamps. Unless you had a previous
-      installation that utilized the deprecated method, leave this enabled.
+      Use the newer, high resolution, 64-bit integer method for formatting
+      timestamps instead of the older, floating point method. Unless you had a
+      previous installation that utilized the deprecated method, leave this
+      enabled. (See note.)
     </ti>
   </tr>
   <tr>
     <ti>pg_legacytimestamp</ti>
     <ti>
-      Use the older method for formatting time stamps. Unless you had a previous
-      installation that utilized the deprecated method, leave this disabled.
+      Use the older, floating-point method for formatting timestamps instead of
+      the higher resolution 64-bit integer method. Unless you had a previous
+      installation that utilized this deprecated method, leave this USE flag
+      disabled. (See note.)
     </ti>
   </tr>
   <tr>
@@ -247,7 +250,7 @@ ebuilds to the new ones.
     <ti>uuid</ti>
     <ti>
       Include support to generate a 128 bit random unique identifier. This is
-      useful for merging databases together so the chances of collisions become 
+      useful for merging databases together so the chances of collisions become
       extremely low.
     </ti>
   </tr>
@@ -261,6 +264,12 @@ ebuilds to the new ones.
   </tr>
 </table>
 
+<note>
+Flipping the 'pg-intdatetime' or the 'pg_legacytimestamp' will required you to
+do a dump and restore if any of your databases utilize timestamps. The two
+methods are incompatible with each other.
+</note>
+
 </body>
 </section>
 <section>
@@ -460,8 +469,8 @@ covered here as some things may change.
 Of secondary interest is the logging destination. By default, everything is
 logged to <path>postmaster.log</path> in the <e>DATA_DIR</e> directory. There is
 an entire subsection of <path>postgresql.conf</path> that covers a slew of
-options for how, what and where to log. The section is marked: ERROR REPORTING
-AND LOGGING.
+options for how, what and where to log. The subsection is marked: ERROR
+REPORTING AND LOGGING.
 </p>
 
 <p>
@@ -506,9 +515,9 @@ database through the localhost. Even as the <e>postgres</e> database superuser.
 <p>
 To make a connection through the Unix socket, however, the users &mdash;
 including the users for other services such as <e>apache</e> &mdash; must be in
-the <e>postgres</e> system group. Use <c>gpasswd -a <e>user</e> postgres</c>
-to add <e>user</e> to the <e>postgres</e> group.  Users not in the
-<e>postgres</e> group will be rejected with "Permission denied".
+the <e>postgres</e> system group. Use <c>gpasswd -a <e>user</e> postgres</c> to
+add <e>user</e> to the <e>postgres</e> group.  Users not in the <e>postgres</e>
+group will be rejected with "Permission denied".
 </p>
 
 <warn>
@@ -519,11 +528,11 @@ order to operate properly. The method can be changed freely.
 <p>
 The <e>trust</e> method is what allows any user to log on as any user without a
 password. It specifies just what it implies: Trust all connections for the given
-type to the given database from the given database user (but not the system user)
-from the given location without a password. This is what allows any user on the
-system to log on as any user through the localhost connection from the get
-go. This is not as dangerous as it seems, but does pose a serious security risk
-in most circumstances.
+type to the given database from the given database user (but not the system
+user) from the given location without a password. This is what allows any user
+on the system to log on as any user through the localhost connection from the
+get go. This is not as dangerous as it seems, but does pose a serious security
+risk in most circumstances.
 </p>
 
 <p>
@@ -532,8 +541,8 @@ The two methods you will most likely use are: <e>password</e> and
 start the connection and the password is sent "in-the-clear". This method is
 fine when such information will never leave the machine, such as connecting via
 the Unix socket or localhost. The md5 method is like password, but protects the
-password by using an md5 hash. This is what you want to use whenever the password
-is going to traverse a network.
+password by using an md5 hash. This is what you want to use whenever the
+password is going to traverse a network.
 </p>
 
 <p>
@@ -618,8 +627,8 @@ postgresql-9.0 | * Reloading PostgreSQL configuration ...               [ ok ]
 <p>
 At this point you are ready to continue on with the official <uri
 src="http://www.postgresql.org/docs/current/static/tutorial.html">PostgreSQL
-Tutorial</uri>. The tutorial will guide you through creating roles,
-databases, schemata and all that fun and useful stuff.
+Tutorial</uri>. The tutorial will guide you through creating roles, databases,
+schemata and all that fun and useful stuff.
 </p>
 
 </body>
@@ -627,15 +636,16 @@ databases, schemata and all that fun and useful stuff.
 </chapter>
 
 <chapter id="migrating">
-<title>Migrating from an Older Version of PostgreSQL</title>
+<title>Migrating PostgreSQL</title>
 <section>
 <title>When You Need to Migrate</title>
 <body>
 
 <p>
-You only need to perform a migration when moving from one major version to
-another, <e>e.g.</e>, from PostgreSQL 8.4.7 to 9.0.3, but not from 9.0.2 to
-9.0.3.
+There are only two reasons you would need to perform a migration: When moving
+from one major version to another, <e>e.g.</e>, from PostgreSQL 8.4.7 to 9.0.3,
+but not from 9.0.2 to 9.0.3; or when switching from the deprecated
+floating-point timestamp format to the new 64-bit integer timestamp format.
 </p>
 
 <note>
@@ -659,24 +669,27 @@ the migration process rather drastically.
 <p>
 However, there are two caveats with using pg_upgrade. Firstly, it does not
 support configuration files being in a different directory than where the data
-is stored. This is resolved by using a symbolic link. Lastly, you can only use
-it to migrate from a database from 8.3 or newer. If you have an older database
-you will need to follow the "Pre-9.0 Migration" instructions.
+is stored. This is resolved by using symbolic links. Lastly, you can only use it
+to migrate from a database from 8.3 or newer. If you have an older database you
+will need to follow the "Pre-9.0 Migration" instructions.
 </p>
 
 <pre caption="Migrating with pg_upgrade">
-<comment>Stop the servers you're going to migrate from and to.</comment>
+<comment>(Stop the servers you're going to migrate from and to.)</comment>
 # <i>/etc/init.d/postgresql-8.4 stop</i>
 # <i>/etc/init.d/postgresql-9.0 stop</i>
 # <i>ln -s /etc/postgresql-8.4/*.conf /var/lib/postgresql/8.4/data/</i>
 # <i>ln -s /etc/postgresql-9.0/*.conf /var/lib/postgresql/9.0/data/</i>
-<comment>Change the method of 'postgres' to trust on local connections</comment>
+
+<comment>(Change the method of 'postgres' to trust on local connections)</comment>
 # <i>nano -w /etc/postgresql-8.4/pg_hba.conf</i>
 # <i>nano -w /etc/postgresql-9.0/pg_hba.conf</i>
-# <i>pg_upgrade -u postgres -d /var/lib/postgresql/8.4/data \
-  -D /var/lib/postgresql/9.0 -b /usr/lib/postgresql-8.4/bin \
-  -B /usr/lib/postgresql-9.0/bin</i>
-<comment>Perform the tasks pg_upgrade tells you to.</comment>
+# <i>pg_upgrade -u postgres \
+  -d /var/lib/postgresql/8.4/data -D /var/lib/postgresql/9.0 \
+  -b /usr/lib/postgresql-8.4/bin -B /usr/lib/postgresql-9.0/bin</i>
+<comment>(Perform the tasks pg_upgrade tells you to.)</comment>
+
+<comment>(Remove the symbolic links  we created earlier.)</comment>
 # <i>rm /var/lib/postgresql/8.4/data/*.conf</i>
 # <i>rm /var/lib/postgresql/9.0/data/*.conf</i>
 # <i>/etc/init.d/postgresql-9.0 start</i>
@@ -701,10 +714,10 @@ accordingly if you have deviated from the default.
 </p>
 
 <p>
-If you have not already done so, follow the <uri 
+If you have not already done so, follow the <uri
 link="#installation">installation instructions</uri> before starting the
-migration. Such a compile may hamper performance on the database server
-but it can keep going.
+migration. Such a compile may hamper performance on the database server but it
+can keep going.
 </p>
 
 <p>
@@ -827,39 +840,5 @@ command:
 
 </body>
 </section>
-<section>
-<title>Thread Safety Test Program Failed</title>
-<body>
-
-<p>
-If you get an error upon emerging dev-db/postgresql-base that reads as follows:
-</p>
-
-<pre caption="Thread Test Program Failed Error Message">
-# <i>emerge dev-db/postgresql-base</i>
-. . .
-configure: error: thread test program failed
-This platform is not thread-safe.  Check the file 'config.log' for the
-exact reason.
-
-You can use the configure option --enable-thread-safety-force to force
-threads to be enabled.  But you must then run the program in
-src/test/thread and add locking function calls to your applications to
-guarantee thread safety.
-</pre>
-
-<p>
-The solution, in most cases, is to update sandbox to a version greater than or
-equal to 2.0.
-</p>
-
-<pre caption="Emerge Newer Sandbox">
-# <i>echo '>=sys-apps/sandbox-2.0' >> /etc/portage/package.keywords</i>
-# <i>emerge -av '>=sys-apps/sandbox-2.0'</i>
-# <i>emerge -av dev-db/postgresql-base</i>
-</pre>
-
-</body>
-</section>
 </chapter>
 </guide>