diff options
| author |   Aaron W. Swenson <titanofold@gentoo.org> | 2011-03-27 08:18:00 -0400 |
|---|---|---|
| committer | Aaron W. Swenson <titanofold@gentoo.org> | 2011-03-27 08:18:00 -0400 |
| commit | daa89b823dcee2f77a0e2a3f26f3c69f0e0f505c (patch) | |
| tree | 4f53381cc70339dafad94ae09f3dae4bfcc1f523 | |
| parent | Initial commit of Gentoo specific PostgreSQL documentation. (diff) | |
| download | patches-daa89b823dcee2f77a0e2a3f26f3c69f0e0f505c.tar.gz patches-daa89b823dcee2f77a0e2a3f26f3c69f0e0f505c.tar.bz2 patches-daa89b823dcee2f77a0e2a3f26f3c69f0e0f505c.zip | |
Fixed 80 column width. Prepping to merge suggestions from bug 330927.
| -rw-r--r-- | 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. <body> <p> -<uri link="http://www.postgresql.org">PostgreSQL</uri> is a free and open -source relational database management system (RDBMS). It supports such things -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. +<uri link="http://www.postgresql.org">PostgreSQL</uri> is a free and open source +relational database management system (RDBMS). It supports such things 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. </p> </body> @@ -69,13 +69,13 @@ commands in this article as necessary for your specific version. <impo> The 7.4 and 8.0 branch of PostgreSQL had their support dropped in October of 2010. The 8.1 branch had its support dropped in November of 2010. If you have -not done so already, you should start <uri link="#migrating">migrating</uri> -to a more recent version of PostgreSQL. +not done so already, you should start <uri link="#migrating">migrating</uri> to +a more recent version of PostgreSQL. </impo> <impo> -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. </impo> </body> @@ -85,21 +85,21 @@ planning 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 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. </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. +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. </p> <p> @@ -115,10 +115,9 @@ Versioning Policy</uri> for more information. <p> There is quite a bit that cannot 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. +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. </p> </body> @@ -157,9 +156,8 @@ Ebuilds to the new ones. <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>. + Include the documentation. The documentation is the same as can be found + <uri link="http://www.postgresql.org/docs/">on line</uri>. </ti> </tr> <tr> @@ -169,8 +167,7 @@ Ebuilds to the new ones. <tr> <ti>ldap</ti> <ti> - Support for utilizing LDAP authentication and connection parameter - lookup. + Support for utilizing LDAP authentication and connection parameter lookup. </ti> </tr> <tr> @@ -183,8 +180,7 @@ Ebuilds to the new ones. <tr> <ti>pam</ti> <ti> - Support for utilizing Pluggable Authentication Module for - authentication. + Support for utilizing Pluggable Authentication Module for authentication. </ti> </tr> <tr> @@ -196,24 +192,21 @@ 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 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. + 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. + Enable support for using Python to write functions and trigger procedures. </ti> </tr> <tr> @@ -284,10 +277,10 @@ Ebuilds to the new ones. </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 +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 link="#migrating">migration</uri> for how to handle this situation. </p> @@ -305,8 +298,8 @@ 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. +The ebuilds are Prefix compatible, so adjust the paths as necessary for your set +up. </note> <p> @@ -319,16 +312,14 @@ as the reasonable defaults are, ahem, reasonable. </p> <p> -In the following example, <e>PGDATA</e> states that the configuration -files are to be located in -<path>/etc/postgresql-9.0/</path>. <e>DATA_DIR</e> states that the -database cluster should be installed to -<path>/var/lib/postgresql/9.0/data/</path>, which is the default. If -you decide to stray from the default, bear in mind that it is a -<b>very good idea</b> to keep the major version in the -path. <e>PG_INITDB_OPTS</e> states that the default locale should be -<e>en_US.UTF-8</e>. That is, U.S. English ordering and formatting, and -UTF-8 character encoding. +In the following example, <e>PGDATA</e> states that the configuration files are +to be located in <path>/etc/postgresql-9.0/</path>. <e>DATA_DIR</e> states that +the database cluster should be installed to +<path>/var/lib/postgresql/9.0/data/</path>, which is the default. If you decide +to stray from the default, bear in mind that it is a <b>very good idea</b> to +keep the major version in the path. <e>PG_INITDB_OPTS</e> states that the +default locale should be <e>en_US.UTF-8</e>. That is, U.S. English ordering and +formatting, and UTF-8 character encoding. </p> <pre caption="Example contents of /etc/conf.d/postgresql-8.4"> @@ -344,9 +335,9 @@ DATA_DIR="/var/lib/postgresql/9.0/data" </pre> <note> -This only determines the default locale and character encoding. You -can specify different locales and/or character encodings at database -creation time (<c>CREATE DATABASE</c>) 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 +(<c>CREATE DATABASE</c>) in the same database cluster. </note> <p> @@ -389,8 +380,8 @@ following table lists the six options that, if used, are to be formatted as: </table> <p> -So, if you would like the default to be English, but you want messages in, -say, Swedish, then your <e>PG_INITDB_OPTS</e> would look like so: +So, if you would like the default to be English, but you want messages in, say, +Swedish, then your <e>PG_INITDB_OPTS</e> would look like so: </p> <pre caption="Example"> @@ -398,20 +389,20 @@ PG_INITDB_OPTS="--locale=en_US.UTF-8 --lc-messages=sv_SE.UTF-8" </pre> <p> -A complete list of language and character encodings supported by the server -can be found in the documentation, but your system must also support the -respective languages and character encodings. Compare the output of <c>locale --a</c> to the <uri +A complete list of language and character encodings supported by the server can +be found in the documentation, but your system must also support the respective +languages and character encodings. Compare the output of <c>locale -a</c> to the +<uri link="http://www.postgresql.org/docs/current/static/multibyte.html">encodings</uri> in the documentation. </p> <p> -You can change your locale and encoding selections at database -creation time (<uri +You can change your locale and encoding selections at database creation time +(<uri link="http://www.postgresql.org/docs/current/static/sql-createdatabase.html"><c>CREATE -DATABASE</c></uri>). In order to change the locale for a database -after you have created it, you must drop the database and start over again. +DATABASE</c></uri>). In order to change the locale for a database after you have +created it, you must drop the database and start over again. </p> </body> @@ -461,13 +452,13 @@ interest is <e>listen_addresses</e>. This variable defines to which addresses PostgreSQL will bind. By default, only loopback devices and Unix sockets are bound; localhost and <path>/var/run/postgresql/.s.PGSQL.5432</path>. Changing <e>listen_addresses</e> is not enough, though, to enable remote -connections. There is another file that actually controls the connections, -which is covered in the next subsection. The <uri +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 rather than it be covered +here as some things may change, and this author would not be able to clarify it +any further. </p> </body> @@ -478,16 +469,15 @@ clarify it any further. <p> 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 +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 and where to log. The section is marked: ERROR REPORTING AND LOGGING. </p> <p> Other than <e>listen_addresses</e> and the logging options, the rest of the -defaults in <path>postgresql.conf</path> are reasonable enough to get you -going. +defaults in <path>postgresql.conf</path> are reasonable enough to get you going. </p> </body> @@ -497,9 +487,9 @@ going. <body> <p> -The <path>pg_hba.conf</path> file states who is allowed to and in which way -they may connect to the database. Again, the documentation is quite exhaustive -on the settings and what they all mean, but a few things are covered here for +The <path>pg_hba.conf</path> file states who is allowed to and in which way they +may connect to the database. Again, the documentation is quite exhaustive on the +settings and what they all mean, but a few things are covered here for clarification. </p> @@ -515,62 +505,60 @@ host all all ::1/128 trust </pre> <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. +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. </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> 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. +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> +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> -Never disable the Unix socket entirely. The initscripts require access to it -in order to operate properly. The method can be changed without consequence. +Never disable the Unix socket entirely. The initscripts require access to it in +order to operate properly. The method can be changed without consequence. </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, 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. +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, +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> 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. +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. </p> <p> 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 +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 "pure" IPv6 ::FFFF:7F00:0001. </p> <p> -There seems to be some misunderstanding, though, as to how host names are -mapped to IP addresses. Let us take a look at the <path>/etc/hosts</path> -file. +There seems to be some misunderstanding, though, as to how host names are mapped +to IP addresses. Let us take a look at the <path>/etc/hosts</path> file. </p> <pre caption="Example /etc/hosts"> @@ -580,22 +568,22 @@ file. </pre> <p> -From the example above you can see that both an IPv4 and an IPv6 IP address -are mapped to localhost. When <c>psql</c> refers to this file, it will grab -the first match and use that as the address; in this case 127.0.0.1. When -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 address are +mapped to localhost. When <c>psql</c> refers to this file, it will grab the +first match and use that as the address; in this case 127.0.0.1. When PostgreSQL +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 <c>psql</c> 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, <c>psql</c> 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. </p> <p> So, it is better to specify IP addresses alone to <c>psql</c> and in <path>pg_hba.conf</path> rather than to rely on <path>/etc/hosts</path> 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. </p> </body> @@ -675,16 +663,16 @@ dev-db/postgresql-docs, dev-db/postgresql-base and dev-db/postgresql-server. <body> <p> -<e>pg_upgrade</e>, a new utility that comes along with 9.0 and later, -simplifies the migration process rather drastically. +<e>pg_upgrade</e>, a new utility that comes along with 9.0 and later, simplifies +the migration process rather drastically. </p> <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. +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. </p> <pre caption="Migrating with pg_upgrade"> @@ -719,28 +707,26 @@ hours. <p> In the following examples, it is assumed that you've stuck with 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. +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="#doc_chap1">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 -<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.) +<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. +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. </p> <pre caption="Migrate with the New Ebuilds"> @@ -769,9 +755,8 @@ Unix socket. </pre> <p> -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 -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 server. </p> </body> @@ -782,16 +767,16 @@ server. <p> 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. +<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. </p> <p> -Before starting, you will need to deny access to the server, so that no -changes are made. You may also want to backup your -<path>postgresql.conf</path> and <path>pg_hba.conf</path> 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 <path>postgresql.conf</path> and +<path>pg_hba.conf</path> and any other configuration file that you deem +important. </p> <pre caption="Steps to Migrate from the Obsolete Ebuilds"> @@ -808,10 +793,10 @@ server.) </pre> <p> -You may break some packages that were built against those ancient packages, -but once you have installed dev-db/postgresql-base and/or -dev-db/postgresql-server you can run <c>revdep-rebuild</c> to reemerge any -packages that may have been broken. +You may break some packages that were built against those ancient packages, but +once you have installed dev-db/postgresql-base and/or dev-db/postgresql-server +you can run <c>revdep-rebuild</c> to reemerge any packages that may have been +broken. </p> </body> @@ -825,7 +810,7 @@ packages that may have been broken. <body> <p> -<uri link="http://www.pgadmin.org/"> pgAdmin III</uri> is a graphical utility +<uri link="http://www.pgadmin.org/">pgAdmin III</uri> is a graphical utility for managing PostgreSQL. </p> @@ -861,8 +846,7 @@ command: <body> <p> -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 follows: </p> <pre caption="Thread Test Program Failed Error Message"> |