/[gentoo]/xml/htdocs/doc/en/postgres-howto.xml
Gentoo

Contents of /xml/htdocs/doc/en/postgres-howto.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.6 - (hide annotations) (download) (as text)
Sat Aug 13 11:57:38 2011 UTC (3 years, 4 months ago) by swift
Branch: MAIN
Changes since 1.5: +632 -509 lines
File MIME type: application/xml
#330927 - Revamped documentation for PostgreSQL (almost a full rewrite), thanks to Aaron W. Swenson and Mikkel A. Clausen

1 neysx 1.1 <?xml version="1.0" encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 swift 1.6 <!-- $Header$ -->
4 neysx 1.1
5 swift 1.6 <guide link="/doc/en/postgresql-howto.xml" lang="en">
6     <title>PostgreSQL Quick Start Guide</title>
7 neysx 1.1
8     <author title="Author">
9 swift 1.6 <mail link="titanofold@gentoo.org">Aaron W. Swenson</mail>
10 neysx 1.1 </author>
11     <author title="Editor">
12 swift 1.6 <mail link="pgsql-bugs@gentoo.org">Mikkel A. Clausen</mail>
13 neysx 1.1 </author>
14    
15 swift 1.6
16 neysx 1.1 <abstract>
17 swift 1.6 This is a quick start guide to PostgreSQL. It covers emerging PostgreSQL and
18     configuring it. This is complementary to the official documentation, but does
19     not supplant it.
20 neysx 1.1 </abstract>
21    
22     <!-- The content of this document is licensed under the CC-BY-SA license -->
23     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
24     <license/>
25    
26 swift 1.6 <version>8</version>
27     <date>2011-08-08</date>
28 neysx 1.1
29     <chapter>
30     <title>Introduction</title>
31     <section>
32 swift 1.6 <title>A Little Bit About PostgreSQL</title>
33 neysx 1.1 <body>
34    
35     <p>
36 swift 1.6 <uri link="http://www.postgresql.org">PostgreSQL</uri> is a free and open source
37     relational database management system (RDBMS). It supports such things as
38     transactions, schemata and foreign keys, and is often touted to more strictly
39     adhere to the SQL standards and to be more secure, by default, than any other
40     database, commercial or otherwise.
41     </p>
42    
43     <p>
44     Visit the <uri link="http://www.postgresql.org/about/">About</uri> page on
45     postgresql.org for more information.
46 neysx 1.1 </p>
47    
48     </body>
49     </section>
50     <section>
51 swift 1.6 <title>What This Article Will Cover</title>
52 neysx 1.1 <body>
53    
54     <p>
55 swift 1.6 This article will guide you through the Gentoo specific steps to install the
56     PostgreSQL RDBMS.
57 neysx 1.1 </p>
58    
59 swift 1.6 <p>
60     The Ebuilds covered by this article are <uri
61     link="http://packages.gentoo.org/package/dev-db/postgresql-docs">dev-db/postgresql-docs</uri>,
62     <uri
63     link="http://packages.gentoo.org/package/dev-db/postgresql-base">dev-db/postgresql-base</uri>
64     and <uri
65     link="http://packages.gentoo.org/package/dev-db/postgresql-server">dev-db/postgresql-server</uri>.
66     </p>
67 neysx 1.1
68 swift 1.6 <p>
69     This article assumes that you will be installing the latest, stable version of
70     PostgreSQL; at the time of this writing, the version was 9.0.3. Adjust the
71     commands in this article as necessary for your specific version.
72     </p>
73 neysx 1.1
74 swift 1.6 <impo>
75     The 8.2 branch will have its upstream support dropped in December of 2011. Start
76     planning your migration now.
77     </impo>
78    
79     </body>
80     </section>
81     <section>
82     <title>About the Ebuilds</title>
83     <body>
84 neysx 1.1
85     <p>
86 swift 1.6 The PostgreSQL ebuilds in Portage feature slotting based on the major version.
87     This allows you to have two major versions of PostgreSQL operating
88     simultaneously; 8.4 and 9.0 libraries and servers can be installed and serve at
89     the same time. This is useful in such circumstances where you need to move data
90     from an older database to a new database, or need to have a production and a
91     testing database on the same machine. Also, this prevents a database,
92     corresponding libraries or executables from being overwritten by an incompatible
93     update. That would require migration which is described in this guide.
94 neysx 1.1 </p>
95    
96 swift 1.6 <p>
97     Additionally, bug and security fixes, which are delivered via minor version
98     updates, can be applied without fear of corrupting the database or the
99     PostgreSQL installation itself; 9.0.2 can be updated to 9.0.3 as they are
100     guaranteed to be compatible and require no more interaction from you than to
101     emerge it and restart the server process &mdash; neither migration,
102     reconfiguration nor initialization are necessary.
103     </p>
104 neysx 1.1
105     <p>
106 swift 1.6 Read the <uri link="http://www.postgresql.org/support/versioning">PostgreSQL
107     Versioning Policy</uri> for more information.
108 neysx 1.1 </p>
109    
110 swift 1.6 </body>
111     </section>
112     <section>
113     <title>What this Article Will Not Cover</title>
114     <body>
115 neysx 1.1
116     <p>
117 swift 1.6 There is quite a bit that will not be covered. The <uri
118     link="http://www.postgresql.org/docs/">official documentation</uri> is somewhere
119     in the neighborhood of 2,000 pages. So, a lot of details will be left out in
120     this quick start guide. Only Gentoo specific issues will be covered and some
121     basic configuration guidelines.
122 neysx 1.1 </p>
123    
124     </body>
125     </section>
126     </chapter>
127 swift 1.6
128     <chapter id="installation">
129     <title>Installation</title>
130 neysx 1.1 <section>
131 swift 1.6 <title>The Obsolete Ebuilds</title>
132 neysx 1.1 <body>
133    
134     <p>
135 swift 1.6 If you have any of the following ebuilds installed, then you have an older,
136     obsolete Gentoo installation of PostgreSQL and should migrate now:
137     dev-db/postgresql-libs, dev-db/postgresql-client, dev-db/libpq and/or
138     dev-db/postgresql.
139 neysx 1.1 </p>
140    
141     <p>
142 swift 1.6 This article does cover <uri link="#oldmigration">migrating</uri> from the old
143     ebuilds to the new ones.
144 neysx 1.1 </p>
145    
146 swift 1.6 </body>
147     </section>
148     <section>
149     <title>USE Flags</title>
150     <body>
151 neysx 1.1
152 swift 1.6 <table>
153     <tr>
154     <th>USE Flag</th>
155     <th>Meaning</th>
156     </tr>
157     <tr>
158     <ti>doc</ti>
159     <ti>
160     Include the <uri link="http://www.postgresql.org/docs/">online
161     documentation</uri> to be stored on your system
162     </ti>
163     </tr>
164     <tr>
165     <ti>kerberos</ti>
166     <ti>Support for utilizing Kerberos for authentication.</ti>
167     </tr>
168     <tr>
169     <ti>ldap</ti>
170     <ti>
171     Support for utilizing LDAP authentication and connection parameter lookup.
172     </ti>
173     </tr>
174     <tr>
175     <ti>nls</ti>
176     <ti>
177     Enable the ability to display messages in a language other than
178     English. Used in conjunction with the Portage variable LINGUAS.
179     </ti>
180     </tr>
181     <tr>
182     <ti>pam</ti>
183     <ti>
184     Support for utilizing Pluggable Authentication Modules for authentication.
185     </ti>
186     </tr>
187     <tr>
188     <ti>perl</ti>
189     <ti>
190     Enable support for using Perl to write functions and trigger procedures.
191     </ti>
192     </tr>
193     <tr>
194     <ti>pg-intdatetime (Deprecated)</ti>
195     <ti>
196     Use the newer, high resolution, 64-bit integer method for formatting
197     timestamps instead of the older, floating point method. Unless you had a
198     previous installation that utilized the deprecated method, leave this
199     enabled. (See note.)
200     </ti>
201     </tr>
202     <tr>
203     <ti>pg_legacytimestamp</ti>
204     <ti>
205     Use the older, floating-point method for formatting timestamps instead of
206     the higher resolution 64-bit integer method. Unless you had a previous
207     installation that utilized this deprecated method, leave this USE flag
208     disabled. (See note.)
209     </ti>
210     </tr>
211     <tr>
212     <ti>python</ti>
213     <ti>
214     Enable support for using Python to write functions and trigger procedures.
215     </ti>
216     </tr>
217     <tr>
218     <ti>readline</ti>
219     <ti>
220     You really want this enabled. Disabling removes command line editing and
221     history in psql.
222     </ti>
223     </tr>
224     <tr>
225     <ti>selinux</ti>
226     <ti>
227     Install respective SELinux policy. This can only be enabled by using the
228     SELinux profile.
229     </ti>
230     </tr>
231     <tr>
232     <ti>ssl</ti>
233     <ti>Enable support for SSL connections.</ti>
234     </tr>
235     <tr>
236     <ti>tcl</ti>
237     <ti>
238     Enable support for using Tcl to write functions and trigger procedures.
239     </ti>
240     </tr>
241     <tr>
242     <ti>threads</ti>
243     <ti>
244     Make the client libraries thread-safe. The rest of your system must be
245     thread-safe as well.
246     </ti>
247     </tr>
248     <tr>
249     <ti>uuid</ti>
250     <ti>
251     Include support to generate a 128 bit random unique identifier. This is
252     useful for merging databases together so the chances of collisions become
253     extremely low.
254     </ti>
255     </tr>
256     <tr>
257     <ti>xml</ti>
258     <ti>Enable SQL/XML support.</ti>
259     </tr>
260     <tr>
261     <ti>zlib</ti>
262     <ti>Support for compressed archives in pg_dump and pg_restore.</ti>
263     </tr>
264     </table>
265 neysx 1.1
266 swift 1.6 <note>
267     Flipping the 'pg-intdatetime' or the 'pg_legacytimestamp' will require you to do
268     a dump and restore if any of your databases utilize timestamps. The two methods
269     are incompatible with each other.
270     </note>
271 neysx 1.1
272 swift 1.6 </body>
273     </section>
274     <section>
275     <title>Start Emerging</title>
276     <body>
277 neysx 1.1
278 swift 1.6 <pre caption="Emerging PostgreSQL server">
279     # <i>emerge -av dev-db/postgresql-server</i>
280 neysx 1.1
281 swift 1.6 [ebuild N ] dev-db/postgresql-docs-9.0.3 0 kB
282     [ebuild N ]dev-db/postgresql-base-9.0.3 USE="doc nls pam readline ssl zlib
283     -kerberos -ldap -pg_legacytimestamp -threads" LINGUAS="-af -cs -de -es -fa -fr
284     -hr -hu -it -ko -nb -pl -pt_BR -ro -ru -sk -sl -sv -tr -zh_CN -zh_TW" 0 kB
285     [ebuild N ] dev-db/postgresql-server-9.0.3 USE="doc nls perl python
286     -pg_legacytimestamp (-selinux) -tcl -uuid -xml" LINGUAS="-af -cs -de -es -fa
287     -fr -hr -hu -it -ko -nb -pl -pt_BR -ro -ru -sk -sl -sv -tr -zh_CN -zh_TW" 0 kB
288 neysx 1.1 </pre>
289    
290     <p>
291 swift 1.6 You may receive a notice regarding that any of the above packages are blocked by
292     any or all of the following packages: dev-db/postgresql-libs,
293     dev-db/postgresql-client, dev-db/libpq or dev-db/postgresql. These packages are
294     <b>not maintained</b> and obsoleted. Refer to the section on <uri
295     link="#oldmigration">migration</uri> for how to handle this situation.
296 neysx 1.1 </p>
297    
298     </body>
299     </section>
300     <section>
301 swift 1.6 <title>Preparing to Initialize the Database Cluster</title>
302 neysx 1.1 <body>
303    
304     <p>
305 swift 1.6 Once the packages have finished emerging, you may want to edit
306     <path>/etc/conf.d/postgresql-9.0</path>. There are three lines that effect the
307     defaults of the server and <b>cannot</b> be changed later without deleting the
308     directory that contains the database cluster and reinitializing.
309 neysx 1.1 </p>
310    
311 swift 1.6 <p>
312     <e>PGDATA</e> defines where to place the configuration files. <e>DATA_DIR</e>
313     defines where to create the database cluster and related
314     files. <e>PG_INITDB_OPTS</e> may contain any <uri
315     link="http://www.postgresql.org/docs/current/static/app-initdb.html">extra
316     options</uri> you would care to set. The extra options are <b>not</b> required
317     as the reasonable defaults are, ahem, reasonable.
318     </p>
319    
320     <p>
321     In the following example, <e>PGDATA</e> states that the configuration files are
322     to be located in <path>/etc/postgresql-9.0/</path>. <e>DATA_DIR</e> states that
323     the database cluster should be installed to
324     <path>/var/lib/postgresql/9.0/data/</path>, which is the default. If you decide
325     to stray from the default, bear in mind that it is a <b>very good idea</b> to
326     keep the major version in the path. <e>PG_INITDB_OPTS</e> states that the
327     default locale should be <e>en_US.UTF-8</e>. That is, U.S. English ordering and
328     formatting, and UTF-8 character encoding.
329     </p>
330    
331     <pre caption="Example contents of /etc/conf.d/postgresql-8.4">
332     <comment># Location of configuration files</comment>
333     PGDATA="/etc/postgresql-9.0/"
334    
335     <comment># Where the data directory is located/to be created</comment>
336     DATA_DIR="/var/lib/postgresql/9.0/data"
337    
338     <comment># Additional options to pass to initdb.
339     # See 'man initdb' for available options.</comment>
340     PG_INITDB_OPTS="--locale=en_US.UTF-8"
341 neysx 1.1 </pre>
342    
343 swift 1.6 <note>
344     This only determines the default locale and character encoding. You can specify
345     different locales and/or character encodings at database creation time
346     (<c>CREATE DATABASE</c>) in the same database cluster.
347     </note>
348    
349 neysx 1.1 <p>
350 swift 1.6 There are six locale options that can be set to override <e>--locale=</e>. The
351     following table lists the six options that, if used, are to be formatted as:
352     <c>--option=lo_LO.ENCODING</c>.
353 neysx 1.1 </p>
354    
355 swift 1.6 <table>
356     <tr>
357     <th>Option</th>
358     <th>Effects</th>
359     </tr>
360     <tr>
361     <ti>lc-collate</ti>
362     <ti>String sort order</ti>
363     </tr>
364     <tr>
365     <ti>lc-ctype</ti>
366     <ti>
367     Character classification (What is a letter? Its upper-case equivalent?)
368     </ti>
369     </tr>
370     <tr>
371     <ti>lc-messages</ti>
372     <ti>Language of messages</ti>
373     </tr>
374     <tr>
375     <ti>lc-monetary</ti>
376     <ti>Formatting of currency amounts</ti>
377     </tr>
378     <tr>
379     <ti>lc-numeric</ti>
380     <ti>Formatting of numbers</ti>
381     </tr>
382     <tr>
383     <ti>lc-time</ti>
384     <ti>Formatting of dates and times</ti>
385     </tr>
386     </table>
387 neysx 1.1
388     <p>
389 swift 1.6 So, if you would like the default to be English, but you want messages in, say,
390     Swedish, then your <e>PG_INITDB_OPTS</e> would look like so:
391 neysx 1.1 </p>
392    
393 swift 1.6 <pre caption="Example">
394     PG_INITDB_OPTS="--locale=en_US.UTF-8 --lc-messages=sv_SE.UTF-8"
395 neysx 1.1 </pre>
396    
397     <p>
398 swift 1.6 A complete list of language and character encodings supported by the server can
399     be found in the documentation, but your system must also support the respective
400     languages and character encodings. Compare the output of <c>locale -a</c> to the
401     <uri
402     link="http://www.postgresql.org/docs/current/static/multibyte.html">encodings</uri>
403     in the documentation.
404 neysx 1.1 </p>
405    
406 swift 1.6 <p>
407     You can change your locale and encoding selections at database <uri
408     link="http://www.postgresql.org/docs/current/static/sql-createdatabase.html">creation
409     time.</uri> In order to change the locale for a database after you have
410     created it, you must drop the database and start over again.
411     </p>
412    
413     <pre caption="Finalize the installation">
414     # <i>emerge --config dev-db/postgresql-server:9.0</i>
415 neysx 1.1 </pre>
416    
417     <p>
418 swift 1.6 This will create the database cluster and store all the related server files
419     into <e>PGDATA</e> and <e>DATA_DIR</e>.
420 neysx 1.1 </p>
421    
422     </body>
423     </section>
424 swift 1.6 </chapter>
425    
426     <chapter>
427     <title>Configuration</title>
428 neysx 1.1 <section>
429 swift 1.6 <title>Where the Configuration Files are Located</title>
430 neysx 1.1 <body>
431    
432     <p>
433 swift 1.6 This time the focus is upon the files in the <e>PGDATA</e> directory,
434     <path>/etc/postgresql-9.0</path>, instead with primary focus on the
435     <path>postgresql.conf</path> and <path>pg_hba.conf</path> files.
436 neysx 1.1 </p>
437    
438 swift 1.6 </body>
439     </section>
440     <section>
441     <title>postgresql.conf</title>
442     <body>
443 neysx 1.1
444     <p>
445 swift 1.6 This is the main configuration file. The line that you may find of immediate
446     interest is <e>listen_addresses</e>. This variable defines to which addresses
447     PostgreSQL will bind. By default, only localhost and the Unix socket are
448     bound. Changing <e>listen_addresses</e> is not enough to enable remote
449     connections. That will be covered in the next section. The <uri
450     link="http://www.postgresql.org/docs/current/static/runtime-config.html">official
451     documentation</uri> is fairly easy to understand and is exhaustive on all the
452     settings available. It would behoove you to read that in addition to what is
453     covered here as some things may change.
454 neysx 1.1 </p>
455    
456 swift 1.6 <p>
457     Of secondary interest is the logging destination. By default, everything is
458     logged to <path>postmaster.log</path> in the <e>DATA_DIR</e> directory. There is
459     an entire subsection of <path>postgresql.conf</path> that covers a slew of
460     options for how, what and where to log. The subsection is marked: ERROR
461     REPORTING AND LOGGING.
462     </p>
463 neysx 1.1
464     <p>
465 swift 1.6 Other than <e>listen_addresses</e> and the logging options, the rest of the
466     defaults in <path>postgresql.conf</path> are reasonable enough to get you going.
467 neysx 1.1 </p>
468    
469     </body>
470     </section>
471     <section>
472 swift 1.6 <title>pg_hba.conf</title>
473 neysx 1.1 <body>
474    
475     <p>
476 swift 1.6 The <path>pg_hba.conf</path> file states who is allowed to connect to the
477     database server and which authentication method must be used to establish the
478     connection. Again, the documentation is quite exhaustive on the settings and
479     what they all mean, but a few things are covered here for clarification.
480 neysx 1.1 </p>
481    
482 swift 1.6 <pre caption="Default pg_hba.conf">
483     <comment># TYPE DATABASE USER CIDR-ADDRESS METHOD
484    
485     # "local" is for Unix domain socket connections only</comment>
486     local all all trust
487     <comment># IPv4 local connections:</comment>
488     host all all 127.0.0.1/32 trust
489     <comment># IPv6 local connections:</comment>
490     host all all ::1/128 trust
491 neysx 1.1 </pre>
492    
493     <p>
494 swift 1.6 As has been mentioned before, by default the server is secure. Kind of. There is
495     only one database role that is available for log in by default:
496     <e>postgres</e>. And, the only way to initiate a connection to the database is
497     through the <path>/var/run/postgresql/.s.PGSQL.5432</path> Unix socket, which is
498     owned by the <e>postgres</e> system user and system group, or via localhost. Now
499     for the "kind of" bit: Any user on the system can make a connection to the
500     database through the localhost. Even as the <e>postgres</e> database superuser.
501 neysx 1.1 </p>
502    
503 swift 1.6 <p>
504     To make a connection through the Unix socket, however, the users &mdash;
505     including the users for other services such as <e>apache</e> &mdash; must be in
506     the <e>postgres</e> system group. Use <c>gpasswd -a <e>user</e> postgres</c> to
507     add <e>user</e> to the <e>postgres</e> group. Users not in the <e>postgres</e>
508     group will be rejected with "Permission denied".
509     </p>
510    
511     <warn>
512     Never disable the Unix socket entirely. The initscripts require access to it in
513     order to operate properly. The method can be changed freely.
514     </warn>
515    
516     <p>
517     The <e>trust</e> method is what allows any user to log on as any user without a
518     password. It specifies just what it implies: Trust all connections for the given
519     type to the given database from the given database user (but not the system
520     user) from the given location without a password. This is what allows any user
521     on the system to log on as any user through the localhost connection from the
522     get go. This is not as dangerous as it seems, but does pose a serious security
523     risk in most circumstances.
524     </p>
525 neysx 1.1
526 swift 1.6 <p>
527     The two methods you will most likely use are: <e>password</e> and
528     <e>md5</e>. The password method only specifies that a password is required to
529     start the connection and the password is sent "in-the-clear". This method is
530     fine when such information will never leave the machine, such as connecting via
531     the Unix socket or localhost. The md5 method is like password, but protects the
532     password by using an md5 hash. This is what you want to use whenever the
533     password is going to traverse a network.
534     </p>
535 neysx 1.1
536 swift 1.6 <p>
537     At this point, this author would like to bring your attention to the last two
538     lines, four lines including comments, of the <path>pg_hba.conf</path>
539     file. PostgreSQL has native support for IPv6 regardless of your desires for such
540     support. Additionally, IPv4 addresses are automatically mapped to IPv6
541     addresses, <e>i.e.</e>, 127.0.0.1 will be mapped to ::FFFF:127.0.0.1 and as
542     "pure" IPv6 ::FFFF:7F00:0001.
543     </p>
544    
545     <p>
546     There seems to be some misunderstanding, though, as to how host names are mapped
547     to IP addresses. Let us take a look at the <path>/etc/hosts</path> file.
548     </p>
549    
550     <pre caption="Example /etc/hosts">
551     <comment># IPv4 and IPv6 localhost aliases</comment>
552     127.0.0.1 localhost
553     ::1 localhost
554 neysx 1.1 </pre>
555    
556     <p>
557 swift 1.6 From the example above you can see that both an IPv4 and an IPv6 IP address are
558     mapped to localhost. When <c>psql</c> refers to this file, it will grab the
559     first match and use that as the address; in this case 127.0.0.1. When PostgreSQL
560     parses this, it will match the IPv6 formatted address as well,
561     e.g. ::ffff:127.0.0.1. If, however, the IPv6 address appears first, then
562     <c>psql</c> will map to ::1 alone; ::1 is not the same as ::ffff:127.0.0.1. As
563     such, if you do not have ::1 as a permitted means of access, <c>psql</c> will
564     not be able to establish a connection. Furthermore, your kernel needs to support
565     the IPv6 protocol.
566     </p>
567    
568     <p>
569     So, it is better to specify IP addresses alone to <c>psql</c> and in
570     <path>pg_hba.conf</path> rather than to rely on <path>/etc/hosts</path> to be
571     ordered properly, and it removes any doubt as to which IP addresses are allowed
572     or to which server you will connect.
573 neysx 1.1 </p>
574    
575     </body>
576     </section>
577 swift 1.6 </chapter>
578    
579     <chapter>
580     <title>Starting the Server</title>
581 neysx 1.1 <section>
582 swift 1.6 <title>Give It a Go!</title>
583 neysx 1.1 <body>
584    
585     <p>
586 swift 1.6 Now start PostgreSQL and set the password for the database superuser
587     <e>postgres</e>. The commands are to be performed as 'root' in the following
588     code listing:
589     </p>
590    
591     <pre caption="Starting the Server">
592     <comment>(Change 'trust' to 'password' for the localhost connections.)</comment>
593     # <i>nano -w /etc/postgresql-9.0/pg_hba.conf</i>
594     # <i>/etc/init.d/postgresql-9.0 start</i>
595     postgresql-9.0 | * Starting PostgreSQL ... [ ok ]
596    
597     <comment>(Open a connection to the server and set the password.)</comment>
598     # <i>psql -U postgres</i>
599     psql (9.0.3)
600     Type "help" for help.
601 neysx 1.1
602 swift 1.6 postgres=# <i>\password</i>
603     Enter new password:
604     Enter it again:
605     postgres=# <i>\q</i>
606 neysx 1.1
607 swift 1.6 <comment>(Change 'trust' to 'password' for the local connection.)</comment>
608     # <i>nano -w /etc/postgresql-9.0/pg_hba.conf</i>
609     # <i>/etc/init.d/postgresql-9.0 reload</i>
610     postgresql-9.0 | * Reloading PostgreSQL configuration ... [ ok ]
611     # <i>rc-update add postgresql-9.0 default</i>
612     * service postgresql-9.0 added to runlevel default
613 neysx 1.1 </pre>
614    
615     <p>
616 swift 1.6 At this point you are ready to continue on with the official <uri
617     link="http://www.postgresql.org/docs/current/static/tutorial.html">PostgreSQL
618     Tutorial</uri>. The tutorial will guide you through creating roles, databases,
619     schemata and all that fun and useful stuff.
620 neysx 1.1 </p>
621    
622 swift 1.6 </body>
623     </section>
624     </chapter>
625    
626     <chapter id="migrating">
627     <title>Migrating PostgreSQL</title>
628     <section>
629     <title>When You Need to Migrate</title>
630     <body>
631 neysx 1.1
632     <p>
633 swift 1.6 There are only two reasons you would need to perform a migration: When moving
634     from one major version to another, <e>e.g.</e>, from PostgreSQL 8.4.7 to 9.0.3,
635     but not from 9.0.2 to 9.0.3; or when switching from the deprecated
636     floating-point timestamp format to the new 64-bit integer timestamp format.
637 neysx 1.1 </p>
638    
639 swift 1.6 <note>
640     You will need to migrate your database when you move from the obsolete ebuilds
641     &mdash; dev-db/libpq, dev-db/postgresql, dev-db/postgresql-libs, and
642     dev-db/postgresql-client &mdash; to the new ebuilds &mdash;
643     dev-db/postgresql-docs, dev-db/postgresql-base and dev-db/postgresql-server.
644     </note>
645    
646 neysx 1.1 </body>
647     </section>
648 swift 1.6 <section id="post90">
649     <title>Post-9.0 Migration</title>
650 neysx 1.1 <body>
651    
652     <p>
653 swift 1.6 <e>pg_upgrade</e>, a new utility that comes along with 9.0 and later, simplifies
654     the migration process rather drastically.
655 neysx 1.1 </p>
656    
657 swift 1.6 <p>
658     However, there are two caveats with using pg_upgrade. Firstly, it does not
659     support configuration files being in a different directory than where the data
660     is stored. This can be resolved by using symbolic links. Lastly, you can only
661     use it to migrate from a database from 8.3 or newer. If you have an older
662     database you will need to follow the <uri link="#pre90">Pre-9.0 Migration</uri>
663     instructions.
664     </p>
665    
666     <pre caption="Migrating with pg_upgrade">
667     <comment>(Stop the servers you're going to migrate from and to.)</comment>
668     # <i>/etc/init.d/postgresql-8.4 stop</i>
669     # <i>/etc/init.d/postgresql-9.0 stop</i>
670     # <i>ln -s /etc/postgresql-8.4/*.conf /var/lib/postgresql/8.4/data/</i>
671     # <i>ln -s /etc/postgresql-9.0/*.conf /var/lib/postgresql/9.0/data/</i>
672    
673     <comment>(Change the method of database user 'postgres' to trust on local
674     connections on all databases.)</comment>
675     # <i>nano -w /etc/postgresql-8.4/pg_hba.conf</i>
676     # <i>nano -w /etc/postgresql-9.0/pg_hba.conf</i>
677    
678     <comment>You may need to change the permissions of '/var/lib/postgresql/' before
679     you perform the next step.</comment>
680     # <i>su - postgres</i>
681     $ <i>pg_upgrade -u postgres \
682     -d /var/lib/postgresql/8.4/data -D /var/lib/postgresql/9.0/data \
683     -b /usr/lib/postgresql-8.4/bin -B /usr/lib/postgresql-9.0/bin</i>
684     <comment>(Perform the tasks pg_upgrade tells you to do , if any.)</comment>
685     $ <i>logout</i>
686    
687     <comment>(Remove the symbolic links we created earlier.)</comment>
688     # <i>rm /var/lib/postgresql/8.4/data/*.conf</i>
689     # <i>rm /var/lib/postgresql/9.0/data/*.conf</i>
690     # <i>/etc/init.d/postgresql-9.0 start</i>
691 neysx 1.1 </pre>
692    
693 swift 1.6 </body>
694     </section>
695     <section id="pre90">
696     <title>Pre-9.0 Migration: With the New Ebuilds</title>
697     <body>
698    
699 neysx 1.1 <p>
700 swift 1.6 Because the new ebuilds feature a more advanced slotting method than the
701     previous ones, the downtime is quite minimal, most likely minutes rather than
702     hours.
703 neysx 1.1 </p>
704    
705 swift 1.6 <p>
706     In the following examples, it is assumed that you are using the default
707     locations and port settings, and that you are migrating from 8.3 to 8.4. Adjust
708     accordingly if you have deviated from the default.
709     </p>
710 neysx 1.1
711 swift 1.6 <p>
712     If you have not already done so, follow the <uri
713     link="#installation">installation instructions</uri> before starting the
714     migration. Such a compile may hamper performance on the database server but it
715     can keep going.
716     </p>
717 neysx 1.1
718     <p>
719 swift 1.6 A couple of files need to be tweaked before beginning the migration. Edit
720     <e>PGPORT</e> in the <path>/etc/conf.d/postgresql-8.4</path> configuration file
721     to 6543. (Any port number other than what your old installation is bound to will
722     do.)
723 neysx 1.1 </p>
724    
725     <p>
726 swift 1.6 Next, edit <path>/etc/postgresql-8.3/pg_hba.conf</path> so that only the
727     database superuser <e>postgres</e> can access the database cluster via the Unix
728     socket.
729 neysx 1.1 </p>
730    
731 swift 1.6 <pre caption="Migrate with the New Ebuilds">
732     # <i>cp -p /etc/postgresql-8.3/pg_hba.conf /etc/postgresql-8.4/</i>
733    
734     <comment>(The following should be safe. Read the documentation to be sure.)</comment>
735     # <i> cp -p /etc/postgresql-8.3/postgresql.conf /etc/postgresql-8.4/</i>
736     <comment>
737     (Don't forget to copy over any other configuration files that you may need.)
738     </comment>
739     # <i>/etc/init.d/postgresql-8.3 reload</i>
740     # <i>/etc/init.d/postgresql-8.4 start</i>
741    
742     <comment>(Begin piping the data from the old cluster to the new cluster.)</comment>
743     # <i>pg_dumpall -U postgres -p 5432 | psql -U postgres -d postgres -p 6543</i>
744     # <i>/etc/init.d/postgresql-8.3 stop</i>
745     # <i>/etc/init.d/postgresql-8.4 stop</i>
746    
747     <comment>(Edit PGPORT back to 5432.)</comment>
748     # <i>nano -w /etc/conf.d/postgresql-8.4</i>
749 neysx 1.1
750 swift 1.6 <comment>(Allow users access once more.)</comment>
751     # <i>nano -w /etc/postgresql-8.4/pg_hba.conf</i>
752     # <i>/etc/init.d/postgresql-8.4 start</i>
753     # <i>rc-update del postgresql-8.3 &amp;&amp; rc-update add postgresql-8.4 default</i>
754 neysx 1.1 </pre>
755    
756     <p>
757 swift 1.6 Hopefully everything went according to plan and you have a successfully updated
758     server that contains precisely the same data, bit for bit, as the old server.
759 neysx 1.1 </p>
760    
761     </body>
762     </section>
763 swift 1.6 <section id="oldmigration">
764     <title>Pre-9.0 Migration: From the Obsolete Ebuilds</title>
765 neysx 1.1 <body>
766    
767     <p>
768 swift 1.6 You will need to schedule some downtime for your server. The old ebuilds
769     <b>cannot</b> be installed at the same time as the new ebuilds. As such, assume
770     that the server will have to be down for a few hours. Maybe for the weekend,
771     even.
772 neysx 1.1 </p>
773    
774     <p>
775 swift 1.6 Before starting, you will need to deny access to the server, so that no changes
776     are made. You may also want to backup your <path>postgresql.conf</path> and
777     <path>pg_hba.conf</path> and any other configuration file that you deem
778     important.
779 neysx 1.1 </p>
780    
781 swift 1.6 <pre caption="Steps to Migrate from the Obsolete Ebuilds">
782     # <i>pg_dumpall -U postgres > backup_file</i>
783     # <i>/etc/init.d/postgresql stop</i>
784     # <i>emerge -C dev-db/postgresql dev-db/libpq dev-db/postgresql-client \
785     dev-db/postgresql-client</i>
786     <comment>
787     (Follow the steps detailed in this article for installing and configuring the
788     server.)
789     </comment>
790     # <i>/etc/init.d/postgresql-8.4 start</i>
791     # <i>psql -f backup_file postgres</i>
792 neysx 1.1 </pre>
793    
794     <p>
795 swift 1.6 You may break some packages that were built against those packages, but once you
796     have installed dev-db/postgresql-base and/or dev-db/postgresql-server you can
797     run <c>revdep-rebuild</c> to reemerge any packages that may have been broken.
798 neysx 1.1 </p>
799    
800 swift 1.6 </body>
801     </section>
802     </chapter>
803 neysx 1.1
804 swift 1.6 <chapter>
805     <title>Utilities</title>
806     <section>
807     <title>pgAdmin III</title>
808     <body>
809 neysx 1.1
810     <p>
811 swift 1.6 <uri link="http://www.pgadmin.org/">pgAdmin III</uri> is a graphical utility
812     for managing PostgreSQL.
813 neysx 1.1 </p>
814    
815     </body>
816     </section>
817 swift 1.6 </chapter>
818    
819     <chapter>
820     <title>Troubleshooting</title>
821 neysx 1.1 <section>
822 swift 1.6 <title>Server Lacks Instrumentation Functions</title>
823 neysx 1.1 <body>
824    
825     <p>
826 swift 1.6 This problem is easy to solve. What is difficult about it is finding the
827     answer. What is required is an import from a file that already exists on the
828     storage drive: <path>adminpack.sql</path>. To resolve this issue, run this
829     command:
830 neysx 1.1 </p>
831    
832 swift 1.6 <pre caption="Command to Add Instrumentation Functions">
833     # <i>psql -U postgres --file /usr/share/postgresql-9.0/contrib/adminpack.sql</i>
834     </pre>
835    
836 neysx 1.1 </body>
837     </section>
838     </chapter>
839     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20