From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from pigeon.gentoo.org ([208.92.234.80] helo=lists.gentoo.org) by finch.gentoo.org with esmtp (Exim 4.60) (envelope-from ) id 1Q4NYz-0004LG-Vu for garchives@archives.gentoo.org; Tue, 29 Mar 2011 01:17:43 +0000 Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id D94E71C046; Tue, 29 Mar 2011 01:17:33 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) by pigeon.gentoo.org (Postfix) with ESMTP id 5F2A51C046 for ; Tue, 29 Mar 2011 01:17:33 +0000 (UTC) Received: from pelican.gentoo.org (unknown [66.219.59.40]) (using TLSv1 with cipher ADH-CAMELLIA256-SHA (256/256 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id A90252AC015 for ; Tue, 29 Mar 2011 01:17:32 +0000 (UTC) Received: from localhost.localdomain (localhost [127.0.0.1]) by pelican.gentoo.org (Postfix) with ESMTP id 1B9A08006A for ; Tue, 29 Mar 2011 01:17:32 +0000 (UTC) From: "Aaron Swenson" To: gentoo-commits@lists.gentoo.org Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Aaron Swenson" Message-ID: Subject: [gentoo-commits] proj/pgsql-patches:documentation commit in: / X-VCS-Repository: proj/pgsql-patches X-VCS-Files: postgresql.xml X-VCS-Directories: / X-VCS-Committer: titanofold X-VCS-Committer-Name: Aaron Swenson X-VCS-Revision: daa89b823dcee2f77a0e2a3f26f3c69f0e0f505c Date: Tue, 29 Mar 2011 01:17:32 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: quoted-printable X-Archives-Salt: X-Archives-Hash: 85eb58e36fc0b9ae5494cd9f5a3d81f1 commit: daa89b823dcee2f77a0e2a3f26f3c69f0e0f505c Author: Aaron W. Swenson gentoo org> AuthorDate: Sun Mar 27 12:18:00 2011 +0000 Commit: Aaron Swenson gentoo org> CommitDate: Sun Mar 27 12:18:00 2011 +0000 URL: http://git.overlays.gentoo.org/gitweb/?p=3Dproj/pgsql-patches= .git;a=3Dcommit;h=3Ddaa89b82 Fixed 80 column width. Prepping to merge suggestions from bug 330927. --- postgresql.xml | 290 ++++++++++++++++++++++++++------------------------= ----- 1 files changed, 137 insertions(+), 153 deletions(-) diff --git a/postgresql.xml b/postgresql.xml index b4423f3..0cc191a 100644 --- a/postgresql.xml +++ b/postgresql.xml @@ -33,11 +33,11 @@ not supplant it. =20

-PostgreSQL is a free and o= pen -source relational database management system (RDBMS). It supports such t= hings -as transactions, schemata and foreign keys, and is often touted to more -strictly adhere to the SQL standards and to be more secure, by default, = than -any other database, commercial or otherwise. +PostgreSQL is a free and o= pen source +relational database management system (RDBMS). It supports such things a= s +transactions, schemata and foreign keys, and is often touted to more str= ictly +adhere to the SQL standards and to be more secure, by default, than any = other +database, commercial or otherwise.

=20 @@ -69,13 +69,13 @@ commands in this article as necessary for your specif= ic version. The 7.4 and 8.0 branch of PostgreSQL had their support dropped in Octobe= r of 2010. The 8.1 branch had its support dropped in November of 2010. If you= have -not done so already, you should start migrating= -to a more recent version of PostgreSQL. +not done so already, you should start migrating= to +a more recent version of PostgreSQL. =20 -The 8.2 branch will have its support dropped in December of 2011. Start -planning your migration now. +The 8.2 branch will have its support dropped in December of 2011. Start = planning +your migration now. =20 @@ -85,21 +85,21 @@ planning your migration now. =20

-The Ebuilds in Portage feature slotting matching the major version. This -allows you to have two major versions of PostgreSQL operating simultaneo= usly; -8.4 and 9.0 can serve at the same time. This is useful in such circumsta= nces -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, t= his -prevents a database, corresponding libraries or executables from being -overwritten by an incompatible update. +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 whe= re you +need to move data from an older database to a new database, or need to h= ave a +production and a testing database on the same machine. Also, this preven= ts a +database, corresponding libraries or executables from being overwritten = by an +incompatible update.

=20

Additionally, bug and security fixes, which are delivered via minor vers= ion -updates, can be applied without fear of corrupting data; 9.0.2 can be up= dated -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 &m= dash; -no migration, reconfiguration or initialization are necessary. +updates, can be applied without fear of corrupting data; 9.0.2 can be up= dated to +9.0.3 as they are guaranteed to be compatible and require no more intera= ction +from you than to emerge it and restart the server process — no mig= ration, +reconfiguration or initialization are necessary.

=20

@@ -115,10 +115,9 @@ Versioning Policy for more information. =20

There is quite a bit that cannot be covered. The official documentation is -somewhere in the neighborhood of 2,000 pages. A lot of details will be l= eft -out. Only Gentoo specific issues will be covered and some basic configur= ation -guidelines. +link=3D"http://www.postgresql.org/docs/">official documentation is= somewhere +in the neighborhood of 2,000 pages. A lot of details will be left out. O= nly +Gentoo specific issues will be covered and some basic configuration guid= elines.

=20 @@ -157,9 +156,8 @@ Ebuilds to the new ones. doc - Include the documentation. The documentation is the same as can - be found on - line. + Include the documentation. The documentation is the same as can be fo= und + on line. @@ -169,8 +167,7 @@ Ebuilds to the new ones. ldap - Support for utilizing LDAP authentication and connection parameter - lookup. + Support for utilizing LDAP authentication and connection parameter lo= okup. @@ -183,8 +180,7 @@ Ebuilds to the new ones. pam - Support for utilizing Pluggable Authentication Module for - authentication. + Support for utilizing Pluggable Authentication Module for authenticat= ion. @@ -196,24 +192,21 @@ Ebuilds to the new ones. pg-intdatetime (Deprecated) - 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 method for formatting time stamps. Unless you had a pre= vious + installation that utilized the deprecated method, leave this enabled. pg_legacytimestamp - 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 method for formatting time stamps. Unless you had a pre= vious + installation that utilized the deprecated method, leave this disabled= . python - Enable support for using Python to write functions and trigger - procedures. + Enable support for using Python to write functions and trigger proced= ures. @@ -284,10 +277,10 @@ Ebuilds to the new ones. =20

-You may receive a notice regarding that any of the above packages are bl= ocked -by any or all of the following packages: dev-db/postgresql-libs, -dev-db/postgresql-client, dev-db/libpq or dev-db/postgresql. These packa= ges -are not maintained and are ancient. Refer to the section o= n not maintained and are ancient. Refer to the section on migration for how to handle this situation.

=20 @@ -305,8 +298,8 @@ directory that contains the database cluster and rein= itializing.

=20 -The ebuilds are Prefix compatible, so adjust the paths as necessary -for your set up. +The ebuilds are Prefix compatible, so adjust the paths as necessary for = your set +up. =20

@@ -319,16 +312,14 @@ as the reasonable defaults are, ahem, reasonable.

=20

-In the following example, PGDATA states that the configuration -files are to be located in -/etc/postgresql-9.0/. DATA_DIR states that the -database cluster should be installed to -/var/lib/postgresql/9.0/data/, which is the default. If -you decide to stray from the default, bear in mind that it is a -very good idea to keep the major version in the -path. PG_INITDB_OPTS states that the default locale should be -en_US.UTF-8. That is, U.S. English ordering and formatting, and -UTF-8 character encoding. +In the following example, PGDATA states that the configuration fi= les are +to be located in /etc/postgresql-9.0/. DATA_DIR stat= es that +the database cluster should be installed to +/var/lib/postgresql/9.0/data/, which is the default. If you= decide +to stray from the default, bear in mind that it is a very good idea to +keep the major version in the path. PG_INITDB_OPTS states that th= e +default locale should be en_US.UTF-8. That is, U.S. English order= ing and +formatting, and UTF-8 character encoding.

=20
@@ -344,9 +335,9 @@ DATA_DIR=3D"/var/lib/postgresql/9.0/data"
=20 -This only determines the default locale and character encoding. You -can specify different locales and/or character encodings at database -creation time (CREATE DATABASE) in the same database cluster. +This only determines the default locale and character encoding. You can = specify +different locales and/or character encodings at database creation time +(CREATE DATABASE) in the same database cluster. =20
@@ -389,8 +380,8 @@ following table lists the six options that, if used, = are to be formatted as: =20
-So, if you would like the default to be English, but you want messages i= n, -say, Swedish, then your PG_INITDB_OPTS would look like so: +So, if you would like the default to be English, but you want messages i= n, say, +Swedish, then your PG_INITDB_OPTS would look like so:
=20
@@ -398,20 +389,20 @@ PG_INITDB_OPTS=3D"--locale=3Den_US.UTF-8 --lc-messa= ges=3Dsv_SE.UTF-8"
=20
-A complete list of language and character encodings supported by the ser= ver -can be found in the documentation, but your system must also support the -respective languages and character encodings. Compare the output of l= ocale --a to the locale -a to the +en= codings in the documentation.
=20
-You can change your locale and encoding selections at database -creation time (CREATE -DATABASE). In order to change the locale for a database -after you have created it, you must drop the database and start over aga= in. +DATABASE). In order to change the locale for a database after = you have +created it, you must drop the database and start over again.
=20 @@ -461,13 +452,13 @@ interest is listen_addresses. This variable = defines to which addresses PostgreSQL will bind. By default, only loopback devices and Unix sockets= are bound; localhost and /var/run/postgresql/.s.PGSQL.5432. Cha= nging listen_addresses is not enough, though, to enable remote -connections. There is another file that actually controls the connection= s, -which is covered in the next subsection. The official documentation is fairly easy to understand and is exhaustive on al= l 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 abl= e to -clarify it any further. +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 cla= rify it +any further.
=20 @@ -478,16 +469,15 @@ clarify it any further. =20
Of secondary interest is the logging destination. By default, everything= is -logged to postmaster.log in the DATA_DIR directory. = There -is an entire subsection of postgresql.conf that covers a sl= ew of +logged to postmaster.log in the DATA_DIR directory. = There is +an entire subsection of postgresql.conf that covers a slew = of options for how and where to log. The section is marked: ERROR REPORTING= AND LOGGING.
=20
Other than listen_addresses and the logging options, the rest of = the -defaults in postgresql.conf are reasonable enough to get yo= u -going. +defaults in postgresql.conf are reasonable enough to get yo= u going.
=20 @@ -497,9 +487,9 @@ going. =20
-The pg_hba.conf file states who is allowed to and in which = way -they may connect to the database. Again, the documentation is quite exha= ustive -on the settings and what they all mean, but a few things are covered her= e for +The pg_hba.conf file states who is allowed to and in which = way they +may connect to the database. Again, the documentation is quite exhaustiv= e on the +settings and what they all mean, but a few things are covered here for clarification.
=20 @@ -515,62 +505,60 @@ host all all ::1/128 = trust =20
-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, -postgres, and the only way to initiate a connection to the databa= se is -through the /var/run/postgresql/.s.PGSQL.5432 Unix socket, = which -is owned by the postgres 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 postgre= s -database superuser. +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, postg= res, +and the only way to initiate a connection to the database is through the +/var/run/postgresql/.s.PGSQL.5432 Unix socket, which is own= ed by +the postgres 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 datab= ase +through the localhost. Even as the postgres database superuser.
=20
To make a connection through the Unix socket, however, the users — -including the users for other services such as apache — mus= t be -in the postgres system group. Use usermod -a -G postgres -user to add user to the postgres group. Users = not in -the postgres group will be rejected with: Permission denied. +including the users for other services such as apache — mus= t be in +the postgres system group. Use usermod -a -G postgres user<= /e> +to add user to the postgres group. Users not in the +postgres group will be rejected with: Permission denied.
=20 -Never disable the Unix socket entirely. The initscripts require access t= o it -in order to operate properly. The method can be changed without conseque= nce. +Never disable the Unix socket entirely. The initscripts require access t= o it in +order to operate properly. The method can be changed without consequence= . =20
-The trust method is what allows any user to log on as any user wi= thout -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 s= ystem -user, from the given location without a password. This is what allows an= y user -on the system to log on as any user through the localhost connection fro= m the -get go. This is not as dangerous as it seems, but does pose a serious se= curity -risk in most circumstances. +The trust method is what allows any user to log on as any user wi= thout a +password. It specifies just what it implies: Trust all connections for t= he given +type to the given database from the given database user, 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 g= et +go. This is not as dangerous as it seems, but does pose a serious securi= ty risk +in most circumstances.
=20
The two methods you will most likely use are: password and md5. The password method only specifies that a password is requir= ed to start the connection and the password is sent "in-the-clear". This metho= d is -fine when such information will never leave the machine, such as connect= ing -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 yo= u -want to use whenever the password is going to traverse a network. +fine when such information will never leave the machine, such as connect= ing via +the Unix socket or localhost. The md5 method is like password, but requi= res 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.
=20
At this point, this author would like to bring your attention to the las= t two lines, four lines including comments, of the pg_hba.conf -file. PostgreSQL has native support for IPv6 regardless of your desires = for -such support. Additionally, IPv4 addresses are automatically mapped to I= Pv6 +file. PostgreSQL has native support for IPv6 regardless of your desires = for such +support. Additionally, IPv4 addresses are automatically mapped to IPv6 addresses, id est, 127.0.0.1 will be mapped to ::FFFF:127.0.0.1 a= nd as "pure" IPv6 ::FFFF:7F00:0001.
=20
-There seems to be some misunderstanding, though, as to how host names ar= e -mapped to IP addresses. Let us take a look at the /etc/hosts -file. +There seems to be some misunderstanding, though, as to how host names ar= e mapped +to IP addresses. Let us take a look at the /etc/hosts file.
=20
@@ -580,22 +568,22 @@ file.
=20
-From the example above you can see that both an IPv4 and an IPv6 IP addr= ess -are mapped to localhost. When psql refers to this file, it will g= rab -the first match and use that as the address; in this case 127.0.0.1. Whe= n -PostgreSQL parses this, it will match the IPv6 formatted address as well= , +From the example above you can see that both an IPv4 and an IPv6 IP addr= ess are +mapped to localhost. When psql refers to this file, it will grab = the +first match and use that as the address; in this case 127.0.0.1. When Po= stgreSQL +parses this, it will match the IPv6 formatted address as well, e.g. ::ffff:127.0.0.1. If, however, the IPv6 address appears first, then psql will map to ::1 alone; ::1 is not the same as ::ffff:127.0.0= .1. As such, if you do not have ::1 as a permitted means of access, psql= will -not be able to establish a connection. Furthermore, your kernel needs to -support the IPv6 protocol. +not be able to establish a connection. Furthermore, your kernel needs to= support +the IPv6 protocol.
=20
So, it is better to specify IP addresses alone to psql and in pg_hba.conf rather than to rely on /etc/hosts = to be -ordered properly, and it removes any doubt as to which IP addresses are -allowed or to which server you will connect. +ordered properly, and it removes any doubt as to which IP addresses are = allowed +or to which server you will connect.
=20 @@ -675,16 +663,16 @@ dev-db/postgresql-docs, dev-db/postgresql-base and = dev-db/postgresql-server. =20
-pg_upgrade, a new utility that comes along with 9.0 and later, -simplifies the migration process rather drastically. +pg_upgrade, a new utility that comes along with 9.0 and later, si= mplifies +the migration process rather drastically.
=20
However, there are two caveats with using pg_upgrade. Firstly, it does n= ot -support configuration files being in a different directory than where th= e -data is stored. This is resolved by using a symbolic link. Lastly, you c= an -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" instructi= ons. +support configuration files being in a different directory than where th= e data +is stored. This is resolved by using a symbolic link. Lastly, you can on= ly use +it to migrate from a database from 8.3 or newer. If you have an older da= tabase +you will need to follow the "Pre-9.0 Migration" instructions.
=20
@@ -719,28 +707,26 @@ hours. =20
In the following examples, it is assumed that you've stuck with the defa= ult -locations and port settings, and that you are migrating from 8.3 to -8.4. Adjust accordingly if you have deviated from 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.
=20
-If you have not already done so, follow the installation instructions 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 ins= tallation +instructions before starting the migration. Such a compile may ham= per +performance on the database server, but it can keep going.
=20
A couple files need to be tweaked before beginning the migration. Edit -PGPORT in the /etc/conf.d/postgresql-8.4 configurati= on -file to 6543. (Any port number other than what your old installation is = bound -to will do.) +PGPORT in the /etc/conf.d/postgresql-8.4 configurati= on file +to 6543. (Any port number other than what your old installation is bound= to will +do.)
=20
-Then edit /etc/postgresql-8.3/pg_hba.conf so that only the -database superuser postgres can access the database cluster via t= he -Unix socket. +Then edit /etc/postgresql-8.3/pg_hba.conf so that only the = database +superuser postgres can access the database cluster via the Unix s= ocket.
=20
@@ -769,9 +755,8 @@ Unix socket.
=20
-Hopefully everything went according to plan and you have a successfully -updated server that contains precisely the same data, bit for bit, as th= e old -server. +Hopefully everything went according to plan and you have a successfully = updated +server that contains precisely the same data, bit for bit, as the old se= rver.
=20 @@ -782,16 +767,16 @@ server. =20
You will need to schedule some downtime for your server. The old Ebuilds -cannot 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 t= he -weekend, even. +cannot 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 week= end, +even.
=20
-Before starting, you will need to deny access to the server, so that no -changes are made. You may also want to backup your -postgresql.conf and pg_hba.conf and any other -configuration file that you deem important. +Before starting, you will need to deny access to the server, so that no = changes +are made. You may also want to backup your postgresql.conf = and +pg_hba.conf and any other configuration file that you deem +important.
=20
@@ -808,10 +793,10 @@ server.)
=20
-You may break some packages that were built against those ancient packag= es, -but once you have installed dev-db/postgresql-base and/or -dev-db/postgresql-server you can run revdep-rebuild to reemerge a= ny -packages that may have been broken. +You may break some packages that were built against those ancient packag= es, but +once you have installed dev-db/postgresql-base and/or dev-db/postgresql-= server +you can run revdep-rebuild to reemerge any packages that may have= been +broken.
=20 @@ -825,7 +810,7 @@ packages that may have been broken. =20
- pgAdmin III is a graphical = utility +pgAdmin III is a graphical u= tility for managing PostgreSQL.
=20 @@ -861,8 +846,7 @@ command: =20
-If you get an error upon emerging dev-db/postgresql-base that reads as -follows: +If you get an error upon emerging dev-db/postgresql-base that reads as f= ollows:
=20