diff options
| author |   Aaron W. Swenson <titanofold@gentoo.org> | 2011-03-28 21:16:06 -0400 |
|---|---|---|
| committer | Aaron W. Swenson <titanofold@gentoo.org> | 2011-03-28 21:16:06 -0400 |
| commit | f8317be1c97202f4edecef8f21c074cd50843cf8 (patch) | |
| tree | 39f4a0c070601589f692d350cc458ba8e138a5c0 | |
| parent | Fixed 80 column width. Prepping to merge suggestions from bug 330927. (diff) | |
| download | patches-f8317be1c97202f4edecef8f21c074cd50843cf8.tar.gz patches-f8317be1c97202f4edecef8f21c074cd50843cf8.tar.bz2 patches-f8317be1c97202f4edecef8f21c074cd50843cf8.zip | |
Merged changes from bug 330927.
https://bugs.gentoo.org/attachment.cgi?id=264045
| -rw-r--r-- | postgresql.xml | 289 |
1 files changed, 142 insertions, 147 deletions
diff --git a/postgresql.xml b/postgresql.xml index 0cc191a..5ab1044 100644 --- a/postgresql.xml +++ b/postgresql.xml @@ -24,7 +24,7 @@ not supplant it. <license/> <version>7</version> -<date>2010-08-02</date> +<date>2011-03-28</date> <chapter> <title>Introduction</title> @@ -85,21 +85,22 @@ your migration now. <body> <p> -The Ebuilds in Portage feature slotting matching the major version. This allows -you to have two major versions of PostgreSQL operating simultaneously; 8.4 and -9.0 can serve at the same time. This is useful in such circumstances where you -need to move data from an older database to a new database, or need to have a -production and a testing database on the same machine. Also, this prevents a -database, corresponding libraries or executables from being overwritten by an -incompatible update. +The PostgreSQL ebuilds in Portage feature slotting based on the major version. +This allows you to have two major versions of PostgreSQL operating +simultaneously; 8.4 and 9.0 libraries and servers can be installed and server at +the same time. This is useful in such circumstances where you need to move data +from an older database to a new database, or need to have a production and a +testing database on the same machine. Also, this prevents a database, +corresponding libraries or executables from being overwritten by an incompatible +update. </p> <p> Additionally, bug and security fixes, which are delivered via minor version updates, can be applied without fear of corrupting data; 9.0.2 can be updated to 9.0.3 as they are guaranteed to be compatible and require no more interaction -from you than to emerge it and restart the server process — no migration, -reconfiguration or initialization are necessary. +from you than to emerge it and restart the server process — neither +migration, reconfiguration nor initialization are necessary. </p> <p> @@ -114,32 +115,33 @@ Versioning Policy</uri> for more information. <body> <p> -There is quite a bit that cannot be covered. The <uri +There is quite a bit that will not be covered. The <uri link="http://www.postgresql.org/docs/">official documentation</uri> is somewhere -in the neighborhood of 2,000 pages. A lot of details will be left out. Only -Gentoo specific issues will be covered and some basic configuration guidelines. +in the neighborhood of 2,000 pages. So, a lot of details will be left out in +this quick start guide. Only Gentoo specific issues will be covered and some +basic configuration guidelines. </p> </body> </section> </chapter> -<chapter> +<chapter id="installation"> <title>Installation</title> <section> <title>The Obsolete Ebuilds</title> <body> <p> -The obsolete Ebuilds are: dev-db/postgresql-libs, dev-db/postgresql-client, -dev-db/libpq and dev-db/postgresql. The new Ebuilds are incompatible with the -old Ebuilds. Entirely, completely, disastrously. +If you have any of the following ebuilds installed, then you have an older, +obsolete Gentoo installation of PostgreSQL: dev-db/postgresql-libs, +dev-db/postgresql-client, dev-db/libpq and/or dev-db/postgresql. </p> <p> This article does cover <uri link="#migrating">migrating</uri> from an old -database to a new one. Including the steps needed for migrating from the old -Ebuilds to the new ones. +database to a new one, and includes the steps needed for migrating from the old +ebuilds to the new ones. </p> </body> @@ -150,111 +152,112 @@ Ebuilds to the new ones. <table> <tr> - <th>USE Flag</th> - <th>Meaning</th> + <th>USE Flag</th> + <th>Meaning</th> </tr> <tr> - <ti>doc</ti> - <ti> - Include the documentation. The documentation is the same as can be found - <uri link="http://www.postgresql.org/docs/">on line</uri>. - </ti> + <ti>doc</ti> + <ti> + Include the <uri + link="http://www.postgresql.org/docs/">online documentation</uri> to be + stored on your system + </ti> </tr> <tr> - <ti>kerberos</ti> - <ti>Support for utilizing Kerberos for authentication.</ti> + <ti>kerberos</ti> + <ti>Support for utilizing Kerberos for authentication.</ti> </tr> <tr> - <ti>ldap</ti> - <ti> - Support for utilizing LDAP authentication and connection parameter lookup. - </ti> + <ti>ldap</ti> + <ti> + Support for utilizing LDAP authentication and connection parameter lookup. + </ti> </tr> <tr> - <ti>nls</ti> - <ti> - Enable the ability to display messages in a language other than - English. Used in conjunction with the Portage variable LINGUAS. - </ti> + <ti>nls</ti> + <ti> + Enable the ability to display messages in a language other than + English. Used in conjunction with the Portage variable LINGUAS. + </ti> </tr> <tr> - <ti>pam</ti> - <ti> - Support for utilizing Pluggable Authentication Module for authentication. - </ti> + <ti>pam</ti> + <ti> + Support for utilizing Pluggable Authentication Modules for authentication. + </ti> </tr> <tr> - <ti>perl</ti> - <ti> - Enable support for using Perl to write functions and trigger procedures. - </ti> + <ti>perl</ti> + <ti> + Enable support for using Perl to write functions and trigger procedures. + </ti> </tr> <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. - </ti> + <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. + </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. - </ti> + <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. + </ti> </tr> <tr> - <ti>python</ti> - <ti> - Enable support for using Python to write functions and trigger procedures. - </ti> + <ti>python</ti> + <ti> + Enable support for using Python to write functions and trigger procedures. + </ti> </tr> <tr> - <ti>readline</ti> - <ti> - You really want this enabled. Disabling removes command line editing and - history in psql. - </ti> + <ti>readline</ti> + <ti> + You really want this enabled. Disabling removes command line editing and + history in psql. + </ti> </tr> <tr> - <ti>selinux</ti> - <ti> - Install respective SELinux policy. This can only be enabled by using the - SELinux profile. - </ti> + <ti>selinux</ti> + <ti> + Install respective SELinux policy. This can only be enabled by using the + SELinux profile. + </ti> </tr> <tr> - <ti>ssl</ti> - <ti>Enable support for SSL connections.</ti> + <ti>ssl</ti> + <ti>Enable support for SSL connections.</ti> </tr> <tr> - <ti>tcl</ti> - <ti> - Enable support for using Tcl to write functions and trigger procedures. - </ti> + <ti>tcl</ti> + <ti> + Enable support for using Tcl to write functions and trigger procedures. + </ti> </tr> <tr> - <ti>threads</ti> - <ti> - Make the client libraries thread-safe. The rest of your system must be - thread-safe as well. - </ti> + <ti>threads</ti> + <ti> + Make the client libraries thread-safe. The rest of your system must be + thread-safe as well. + </ti> </tr> <tr> - <ti>uuid</ti> - <ti> - Include support to generate a 128 bit random unique identifier. This is - useful for merging databases together as the chances of collision are - extremely low. - </ti> + <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 + extremely low. + </ti> </tr> <tr> - <ti>xml</ti> - <ti>Enable SQL/XML support.</ti> + <ti>xml</ti> + <ti>Enable SQL/XML support.</ti> </tr> <tr> - <ti>zlib</ti> - <ti>Support for compressed archives in pg_dump and pg_restore.</ti> + <ti>zlib</ti> + <ti>Support for compressed archives in pg_dump and pg_restore.</ti> </tr> </table> @@ -269,18 +272,18 @@ Ebuilds to the new ones. [ebuild N ] dev-db/postgresql-docs-9.0.3 0 kB [ebuild N ]dev-db/postgresql-base-9.0.3 USE="doc nls pam readline ssl zlib --kerberos -ldap -pg_legacytimestamp -threads" LINGUAS="-af -cs -de -es -fa -fr --hr -hu -it -ko -nb -pl -pt_BR -ro -ru -sk -sl -sv -tr -zh_CN -zh_TW" 0 kB + -kerberos -ldap -pg_legacytimestamp -threads" LINGUAS="-af -cs -de -es -fa -fr + -hr -hu -it -ko -nb -pl -pt_BR -ro -ru -sk -sl -sv -tr -zh_CN -zh_TW" 0 kB [ebuild N ] dev-db/postgresql-server-9.0.3 USE="doc nls perl python --pg_legacytimestamp (-selinux) -tcl -uuid -xml" LINGUAS="-af -cs -de -es -fa -fr --hr -hu -it -ko -nb -pl -pt_BR -ro -ru -sk -sl -sv -tr -zh_CN -zh_TW" 0 kB + -pg_legacytimestamp (-selinux) -tcl -uuid -xml" LINGUAS="-af -cs -de -es -fa + -fr -hr -hu -it -ko -nb -pl -pt_BR -ro -ru -sk -sl -sv -tr -zh_CN -zh_TW" 0 kB </pre> <p> You may receive a notice regarding that any of the above packages are blocked by any or all of the following packages: dev-db/postgresql-libs, dev-db/postgresql-client, dev-db/libpq or dev-db/postgresql. These packages are -<b>not maintained</b> and are <b>ancient</b>. Refer to the section on <uri +<b>not maintained</b> and obsoleted. Refer to the section on <uri link="#migrating">migration</uri> for how to handle this situation. </p> @@ -297,11 +300,6 @@ defaults of the server and <b>cannot</b> be changed later without deleting the directory that contains the database cluster and reinitializing. </p> -<note> -The ebuilds are Prefix compatible, so adjust the paths as necessary for your set -up. -</note> - <p> <e>PGDATA</e> defines where to place the configuration files. <e>DATA_DIR</e> defines where to create the database cluster and related @@ -348,12 +346,12 @@ following table lists the six options that, if used, are to be formatted as: <table> <tr> - <th>Option</th> - <th>Effects</th> + <th>Option</th> + <th>Effects</th> </tr> <tr> - <ti>lc-collate</ti> - <ti>String sort order</ti> + <ti>lc-collate</ti> + <ti>String sort order</ti> </tr> <tr> <ti>lc-ctype</ti> @@ -362,20 +360,20 @@ following table lists the six options that, if used, are to be formatted as: </ti> </tr> <tr> - <ti>lc-messages</ti> - <ti>Language of messages</ti> + <ti>lc-messages</ti> + <ti>Language of messages</ti> </tr> <tr> - <ti>lc-monetary</ti> - <ti>Formatting of currency amounts</ti> + <ti>lc-monetary</ti> + <ti>Formatting of currency amounts</ti> </tr> <tr> - <ti>lc-numeric</ti> - <ti>Formatting of numbers</ti> + <ti>lc-numeric</ti> + <ti>Formatting of numbers</ti> </tr> <tr> - <ti>lc-time</ti> - <ti>Formatting of dates and times</ti> + <ti>lc-time</ti> + <ti>Formatting of dates and times</ti> </tr> </table> @@ -436,7 +434,7 @@ into <e>DATA_DIR</e>. <p> This time the focus is upon the files in the <e>PGDATA</e> directory -<path>/etc/postgresql-9.0/</path> instead. Primarily, the +<path>/etc/postgresql-8.4</path> instead with primary focus on the <path>postgresql.conf</path> and <path>pg_hba.conf</path> files. </p> @@ -456,9 +454,8 @@ connections. There is another file that actually controls the connections, which is covered in the next subsection. The <uri link="http://www.postgresql.org/docs/current/static/runtime-config.html">official documentation</uri> is fairly easy to understand and is exhaustive on all the -settings available. It would behoove you to read that rather than it be covered -here as some things may change, and this author would not be able to clarify it -any further. +settings available. It would behoove you to read that in addition to what is +covered here as some things may change. </p> </body> @@ -506,31 +503,31 @@ host all all ::1/128 trust <p> As has been mentioned before, by default the server is secure. Kind of. There is -only one database role that is available for log in by default, <e>postgres</e>, -and the only way to initiate a connection to the database is through the -<path>/var/run/postgresql/.s.PGSQL.5432</path> Unix socket, which is owned by -the <e>postgres</e> system user and system group, or via localhost. Now for the -"kind of" bit: Any user on the system can make a connection to the database -through the localhost. Even as the <e>postgres</e> database superuser. +only one database role that is available for log in by default: +<e>postgres</e>. And, the only way to initiate a connection to the database is +through the <path>/var/run/postgresql/.s.PGSQL.5432</path> Unix socket, which is +owned by the <e>postgres</e> system user and system group, or via localhost. Now +for the "kind of" bit: Any user on the system can make a connection to the +database through the localhost. Even as the <e>postgres</e> database superuser. </p> <p> To make a connection through the Unix socket, however, the users — including the users for other services such as <e>apache</e> — must be in -the <e>postgres</e> system group. Use <c>usermod -a -G postgres <e>user</e></c> +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. +<e>postgres</e> group will be rejected with "Permission denied". </p> <warn> Never disable the Unix socket entirely. The initscripts require access to it in -order to operate properly. The method can be changed without consequence. +order to operate properly. The method can be changed freely. </warn> <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, not the system user, +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 @@ -542,9 +539,9 @@ The two methods you will most likely use are: <e>password</e> and <e>md5</e>. The password method only specifies that a password is required to 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 requires the -password to be encrypted using an md5 hash. This is what you want to use -whenever the password is going to traverse a network. +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. </p> <p> @@ -552,7 +549,7 @@ At this point, this author would like to bring your attention to the last two lines, four lines including comments, of the <path>pg_hba.conf</path> file. PostgreSQL has native support for IPv6 regardless of your desires for such support. Additionally, IPv4 addresses are automatically mapped to IPv6 -addresses, <e>id est</e>, 127.0.0.1 will be mapped to ::FFFF:127.0.0.1 and as +addresses, <e>i.e.</e>, 127.0.0.1 will be mapped to ::FFFF:127.0.0.1 and as "pure" IPv6 ::FFFF:7F00:0001. </p> @@ -645,8 +642,8 @@ databases, schemata and all that fun and useful stuff. <p> You only need to perform a migration when moving from one major version to -another, <e>exempli gratia</e>, from PostgreSQL 8.4.7 to 9.0.3, but not from -9.0.2 to 9.0.3. +another, <e>e.g.</e>, from PostgreSQL 8.4.7 to 9.0.3, but not from 9.0.2 to +9.0.3. </p> <note> @@ -700,33 +697,35 @@ you will need to follow the "Pre-9.0 Migration" instructions. <body> <p> -Because the new Ebuilds feature a more advanced slotting method than the -previous ones, the downtime is quite minimal. Most likely minutes rather than +Because the new ebuilds feature a more advanced slotting method than the +previous ones, the downtime is quite minimal, most likely minutes rather than hours. </p> <p> -In the following examples, it is assumed that you've stuck with the default +In the following examples, it is assumed that you are using the default locations and port settings, and that you are migrating from 8.3 to 8.4. Adjust accordingly if you have deviated from the default. </p> <p> -If you have not already done so, follow the <uri link="#doc_chap1">installation -instructions</uri> before starting the migration. Such a compile may hamper -performance on the database server, but it can keep going. +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. </p> <p> -A couple files need to be tweaked before beginning the migration. Edit +A couple of files need to be tweaked before beginning the migration. Edit <e>PGPORT</e> in the <path>/etc/conf.d/postgresql-8.4</path> configuration file to 6543. (Any port number other than what your old installation is bound to will do.) </p> <p> -Then edit <path>/etc/postgresql-8.3/pg_hba.conf</path> so that only the database -superuser <e>postgres</e> can access the database cluster via the Unix socket. +Next, edit <path>/etc/postgresql-8.3/pg_hba.conf</path> so that only the +database superuser <e>postgres</e> can access the database cluster via the Unix +socket. </p> <pre caption="Migrate with the New Ebuilds"> @@ -766,7 +765,7 @@ server that contains precisely the same data, bit for bit, as the old server. <body> <p> -You will need to schedule some downtime for your server. The old Ebuilds +You will need to schedule some downtime for your server. The old ebuilds <b>cannot</b> be installed at the same time as the new Ebuilds. As such, assume that the server will have to be down for a few hours. Maybe for the weekend, even. @@ -814,10 +813,6 @@ broken. for managing PostgreSQL. </p> -<pre> -# <i>emerge -av pgadmin3</i> -</pre> - </body> </section> </chapter> @@ -863,7 +858,7 @@ guarantee thread safety. </pre> <p> -The solution, in most cases, is to update Sandbox to a version greater than or +The solution, in most cases, is to update sandbox to a version greater than or equal to 2.0. </p> |