/[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 - (show annotations) (download) (as text)
Sat Aug 13 11:57:38 2011 UTC (2 years, 8 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 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <!-- $Header$ -->
4
5 <guide link="/doc/en/postgresql-howto.xml" lang="en">
6 <title>PostgreSQL Quick Start Guide</title>
7
8 <author title="Author">
9 <mail link="titanofold@gentoo.org">Aaron W. Swenson</mail>
10 </author>
11 <author title="Editor">
12 <mail link="pgsql-bugs@gentoo.org">Mikkel A. Clausen</mail>
13 </author>
14
15
16 <abstract>
17 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 </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 <version>8</version>
27 <date>2011-08-08</date>
28
29 <chapter>
30 <title>Introduction</title>
31 <section>
32 <title>A Little Bit About PostgreSQL</title>
33 <body>
34
35 <p>
36 <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 </p>
47
48 </body>
49 </section>
50 <section>
51 <title>What This Article Will Cover</title>
52 <body>
53
54 <p>
55 This article will guide you through the Gentoo specific steps to install the
56 PostgreSQL RDBMS.
57 </p>
58
59 <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
68 <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
74 <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
85 <p>
86 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 </p>
95
96 <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
105 <p>
106 Read the <uri link="http://www.postgresql.org/support/versioning">PostgreSQL
107 Versioning Policy</uri> for more information.
108 </p>
109
110 </body>
111 </section>
112 <section>
113 <title>What this Article Will Not Cover</title>
114 <body>
115
116 <p>
117 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 </p>
123
124 </body>
125 </section>
126 </chapter>
127
128 <chapter id="installation">
129 <title>Installation</title>
130 <section>
131 <title>The Obsolete Ebuilds</title>
132 <body>
133
134 <p>
135 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 </p>
140
141 <p>
142 This article does cover <uri link="#oldmigration">migrating</uri> from the old
143 ebuilds to the new ones.
144 </p>
145
146 </body>
147 </section>
148 <section>
149 <title>USE Flags</title>
150 <body>
151
152 <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
266 <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
272 </body>
273 </section>
274 <section>
275 <title>Start Emerging</title>
276 <body>
277
278 <pre caption="Emerging PostgreSQL server">
279 # <i>emerge -av dev-db/postgresql-server</i>
280
281 [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 </pre>
289
290 <p>
291 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 </p>
297
298 </body>
299 </section>
300 <section>
301 <title>Preparing to Initialize the Database Cluster</title>
302 <body>
303
304 <p>
305 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 </p>
310
311 <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 </pre>
342
343 <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 <p>
350 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 </p>
354
355 <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
388 <p>
389 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 </p>
392
393 <pre caption="Example">
394 PG_INITDB_OPTS="--locale=en_US.UTF-8 --lc-messages=sv_SE.UTF-8"
395 </pre>
396
397 <p>
398 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 </p>
405
406 <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 </pre>
416
417 <p>
418 This will create the database cluster and store all the related server files
419 into <e>PGDATA</e> and <e>DATA_DIR</e>.
420 </p>
421
422 </body>
423 </section>
424 </chapter>
425
426 <chapter>
427 <title>Configuration</title>
428 <section>
429 <title>Where the Configuration Files are Located</title>
430 <body>
431
432 <p>
433 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 </p>
437
438 </body>
439 </section>
440 <section>
441 <title>postgresql.conf</title>
442 <body>
443
444 <p>
445 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 </p>
455
456 <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
464 <p>
465 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 </p>
468
469 </body>
470 </section>
471 <section>
472 <title>pg_hba.conf</title>
473 <body>
474
475 <p>
476 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 </p>
481
482 <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 </pre>
492
493 <p>
494 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 </p>
502
503 <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
526 <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
536 <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 </pre>
555
556 <p>
557 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 </p>
574
575 </body>
576 </section>
577 </chapter>
578
579 <chapter>
580 <title>Starting the Server</title>
581 <section>
582 <title>Give It a Go!</title>
583 <body>
584
585 <p>
586 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
602 postgres=# <i>\password</i>
603 Enter new password:
604 Enter it again:
605 postgres=# <i>\q</i>
606
607 <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 </pre>
614
615 <p>
616 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 </p>
621
622 </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
632 <p>
633 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 </p>
638
639 <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 </body>
647 </section>
648 <section id="post90">
649 <title>Post-9.0 Migration</title>
650 <body>
651
652 <p>
653 <e>pg_upgrade</e>, a new utility that comes along with 9.0 and later, simplifies
654 the migration process rather drastically.
655 </p>
656
657 <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 </pre>
692
693 </body>
694 </section>
695 <section id="pre90">
696 <title>Pre-9.0 Migration: With the New Ebuilds</title>
697 <body>
698
699 <p>
700 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 </p>
704
705 <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
711 <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
718 <p>
719 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 </p>
724
725 <p>
726 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 </p>
730
731 <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
750 <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 </pre>
755
756 <p>
757 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 </p>
760
761 </body>
762 </section>
763 <section id="oldmigration">
764 <title>Pre-9.0 Migration: From the Obsolete Ebuilds</title>
765 <body>
766
767 <p>
768 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 </p>
773
774 <p>
775 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 </p>
780
781 <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 </pre>
793
794 <p>
795 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 </p>
799
800 </body>
801 </section>
802 </chapter>
803
804 <chapter>
805 <title>Utilities</title>
806 <section>
807 <title>pgAdmin III</title>
808 <body>
809
810 <p>
811 <uri link="http://www.pgadmin.org/">pgAdmin III</uri> is a graphical utility
812 for managing PostgreSQL.
813 </p>
814
815 </body>
816 </section>
817 </chapter>
818
819 <chapter>
820 <title>Troubleshooting</title>
821 <section>
822 <title>Server Lacks Instrumentation Functions</title>
823 <body>
824
825 <p>
826 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 </p>
831
832 <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 </body>
837 </section>
838 </chapter>
839 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20