/[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.11 - (hide annotations) (download) (as text)
Wed Jun 13 09:10:59 2012 UTC (2 years, 3 months ago) by nightmorph
Branch: MAIN
Changes since 1.10: +7 -3 lines
File MIME type: application/xml
add eselect step per comment #8 of bug #410717

1 neysx 1.1 <?xml version="1.0" encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 nightmorph 1.11 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/postgres-howto.xml,v 1.10 2012/05/04 06:44:35 nightmorph Exp $ -->
4 neysx 1.1
5 nightmorph 1.10 <guide>
6 swift 1.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 nightmorph 1.11 <version>11</version>
27     <date>2012-06-13</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 swift 1.9 <pre caption="Example contents of /etc/conf.d/postgresql-9.0">
332 swift 1.6 <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 nightmorph 1.11 <comment>(Check available versions, then select yours)</comment>
674     # <i>eselect postgresql list</i>
675     # <i>eselect postgresql set 9.0</i>
676    
677 swift 1.6 <comment>(Change the method of database user 'postgres' to trust on local
678     connections on all databases.)</comment>
679     # <i>nano -w /etc/postgresql-8.4/pg_hba.conf</i>
680     # <i>nano -w /etc/postgresql-9.0/pg_hba.conf</i>
681    
682     <comment>You may need to change the permissions of '/var/lib/postgresql/' before
683     you perform the next step.</comment>
684     # <i>su - postgres</i>
685     $ <i>pg_upgrade -u postgres \
686     -d /var/lib/postgresql/8.4/data -D /var/lib/postgresql/9.0/data \
687     -b /usr/lib/postgresql-8.4/bin -B /usr/lib/postgresql-9.0/bin</i>
688     <comment>(Perform the tasks pg_upgrade tells you to do , if any.)</comment>
689     $ <i>logout</i>
690    
691     <comment>(Remove the symbolic links we created earlier.)</comment>
692     # <i>rm /var/lib/postgresql/8.4/data/*.conf</i>
693     # <i>rm /var/lib/postgresql/9.0/data/*.conf</i>
694     # <i>/etc/init.d/postgresql-9.0 start</i>
695 neysx 1.1 </pre>
696    
697 swift 1.6 </body>
698     </section>
699     <section id="pre90">
700     <title>Pre-9.0 Migration: With the New Ebuilds</title>
701     <body>
702    
703 neysx 1.1 <p>
704 swift 1.6 Because the new ebuilds feature a more advanced slotting method than the
705     previous ones, the downtime is quite minimal, most likely minutes rather than
706     hours.
707 neysx 1.1 </p>
708    
709 swift 1.6 <p>
710     In the following examples, it is assumed that you are using the default
711     locations and port settings, and that you are migrating from 8.3 to 8.4. Adjust
712     accordingly if you have deviated from the default.
713     </p>
714 neysx 1.1
715 swift 1.6 <p>
716     If you have not already done so, follow the <uri
717     link="#installation">installation instructions</uri> before starting the
718     migration. Such a compile may hamper performance on the database server but it
719     can keep going.
720     </p>
721 neysx 1.1
722     <p>
723 swift 1.6 A couple of files need to be tweaked before beginning the migration. Edit
724     <e>PGPORT</e> in the <path>/etc/conf.d/postgresql-8.4</path> configuration file
725     to 6543. (Any port number other than what your old installation is bound to will
726     do.)
727 neysx 1.1 </p>
728    
729     <p>
730 swift 1.6 Next, edit <path>/etc/postgresql-8.3/pg_hba.conf</path> so that only the
731     database superuser <e>postgres</e> can access the database cluster via the Unix
732     socket.
733 neysx 1.1 </p>
734    
735 swift 1.6 <pre caption="Migrate with the New Ebuilds">
736     # <i>cp -p /etc/postgresql-8.3/pg_hba.conf /etc/postgresql-8.4/</i>
737    
738     <comment>(The following should be safe. Read the documentation to be sure.)</comment>
739     # <i> cp -p /etc/postgresql-8.3/postgresql.conf /etc/postgresql-8.4/</i>
740     <comment>
741     (Don't forget to copy over any other configuration files that you may need.)
742     </comment>
743     # <i>/etc/init.d/postgresql-8.3 reload</i>
744     # <i>/etc/init.d/postgresql-8.4 start</i>
745    
746     <comment>(Begin piping the data from the old cluster to the new cluster.)</comment>
747     # <i>pg_dumpall -U postgres -p 5432 | psql -U postgres -d postgres -p 6543</i>
748     # <i>/etc/init.d/postgresql-8.3 stop</i>
749     # <i>/etc/init.d/postgresql-8.4 stop</i>
750    
751     <comment>(Edit PGPORT back to 5432.)</comment>
752     # <i>nano -w /etc/conf.d/postgresql-8.4</i>
753 neysx 1.1
754 swift 1.6 <comment>(Allow users access once more.)</comment>
755     # <i>nano -w /etc/postgresql-8.4/pg_hba.conf</i>
756     # <i>/etc/init.d/postgresql-8.4 start</i>
757     # <i>rc-update del postgresql-8.3 &amp;&amp; rc-update add postgresql-8.4 default</i>
758 neysx 1.1 </pre>
759    
760     <p>
761 swift 1.6 Hopefully everything went according to plan and you have a successfully updated
762     server that contains precisely the same data, bit for bit, as the old server.
763 neysx 1.1 </p>
764    
765     </body>
766     </section>
767 swift 1.6 <section id="oldmigration">
768     <title>Pre-9.0 Migration: From the Obsolete Ebuilds</title>
769 neysx 1.1 <body>
770    
771     <p>
772 swift 1.6 You will need to schedule some downtime for your server. The old ebuilds
773     <b>cannot</b> be installed at the same time as the new ebuilds. As such, assume
774     that the server will have to be down for a few hours. Maybe for the weekend,
775     even.
776 neysx 1.1 </p>
777    
778     <p>
779 swift 1.6 Before starting, you will need to deny access to the server, so that no changes
780     are made. You may also want to backup your <path>postgresql.conf</path> and
781     <path>pg_hba.conf</path> and any other configuration file that you deem
782     important.
783 neysx 1.1 </p>
784    
785 swift 1.6 <pre caption="Steps to Migrate from the Obsolete Ebuilds">
786     # <i>pg_dumpall -U postgres > backup_file</i>
787     # <i>/etc/init.d/postgresql stop</i>
788     # <i>emerge -C dev-db/postgresql dev-db/libpq dev-db/postgresql-client \
789     dev-db/postgresql-client</i>
790     <comment>
791     (Follow the steps detailed in this article for installing and configuring the
792     server.)
793     </comment>
794     # <i>/etc/init.d/postgresql-8.4 start</i>
795     # <i>psql -f backup_file postgres</i>
796 neysx 1.1 </pre>
797    
798     <p>
799 swift 1.6 You may break some packages that were built against those packages, but once you
800     have installed dev-db/postgresql-base and/or dev-db/postgresql-server you can
801     run <c>revdep-rebuild</c> to reemerge any packages that may have been broken.
802 neysx 1.1 </p>
803    
804 swift 1.6 </body>
805     </section>
806     </chapter>
807 neysx 1.1
808 swift 1.6 <chapter>
809     <title>Utilities</title>
810     <section>
811     <title>pgAdmin III</title>
812     <body>
813 neysx 1.1
814     <p>
815 swift 1.6 <uri link="http://www.pgadmin.org/">pgAdmin III</uri> is a graphical utility
816     for managing PostgreSQL.
817 neysx 1.1 </p>
818    
819     </body>
820     </section>
821 swift 1.6 </chapter>
822    
823     <chapter>
824     <title>Troubleshooting</title>
825 neysx 1.1 <section>
826 swift 1.6 <title>Server Lacks Instrumentation Functions</title>
827 neysx 1.1 <body>
828    
829     <p>
830 nightmorph 1.10 This problem is easy to solve, with the solution depending on the version you
831     are using. What is difficult about it is finding the answer. What is required is
832     an import from a file that already exists on the storage drive:
833     <path>adminpack.sql</path>. To resolve this issue, run the command appropriate
834     to the version you have:
835 neysx 1.1 </p>
836    
837 nightmorph 1.10 <pre caption="Add instrumentation functions for versions less than 9.1">
838 swift 1.6 # <i>psql -U postgres --file /usr/share/postgresql-9.0/contrib/adminpack.sql</i>
839     </pre>
840    
841 nightmorph 1.10 <pre caption="Add instrumentation functions for version 9.1 and up">
842     # <i>psql -U postgres -c "CREATE EXTENSION adminpack;"</i>
843     </pre>
844    
845 neysx 1.1 </body>
846     </section>
847     </chapter>
848     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20