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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.5 Revision 1.6
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/postgres-howto.xml,v 1.5 2008/05/19 21:09:45 swift Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/postgres-howto.xml,v 1.6 2011/08/13 11:57:38 swift Exp $ -->
4 4
5<guide link="/doc/en/postgres-howto.xml" lang="en"> 5<guide link="/doc/en/postgresql-howto.xml" lang="en">
6<title>PostgreSQL Guide</title> 6<title>PostgreSQL Quick Start Guide</title>
7 7
8<author title="Author"> 8<author title="Author">
9 <mail link="chriswhite@gentoo.org">Chris White</mail> 9 <mail link="titanofold@gentoo.org">Aaron W. Swenson</mail>
10</author> 10</author>
11<author title="Editor"> 11<author title="Editor">
12 <mail link="neysx@gentoo.org">Xavier Neys</mail> 12 <mail link="pgsql-bugs@gentoo.org">Mikkel A. Clausen</mail>
13</author> 13</author>
14 14
15
15<abstract> 16<abstract>
16This guide is meant to show the basic setup of PostgreSQL. The setup described 17This is a quick start guide to PostgreSQL. It covers emerging PostgreSQL and
17here should be sufficient enough to use for basic web appplications, and any 18configuring it. This is complementary to the official documentation, but does
18other program that provides PostgreSQL support. 19not supplant it.
19</abstract> 20</abstract>
20 21
21<!-- The content of this document is licensed under the CC-BY-SA license --> 22<!-- The content of this document is licensed under the CC-BY-SA license -->
22<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 23<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
23<license/> 24<license/>
24 25
25<version>1.2</version> 26<version>8</version>
26<date>2007-04-25</date> 27<date>2011-08-08</date>
27 28
28<chapter> 29<chapter>
29<title>Introduction</title> 30<title>Introduction</title>
30<section> 31<section>
31<title>PostgreSQL introduction</title> 32<title>A Little Bit About PostgreSQL</title>
32<body>
33
34<p>
35When talking to most developers about the different database solutions to use,
36two major databases will usually form the answer. One would be <c>MySQL</c>,
37and the other is what this document will refer to, <c>PostgreSQL</c>. The
38advantages of one over the other is a somewhat long winded debate, however it
39is just to say that PostgreSQL has had a more firm grasp on true relational
40database structure than MySQL. Most of the standard features such as
41<b>FOREIGN KEY</b> was only just added in MySQL 5. However, whatever the case
42may be, this document assumes that you have selected PostgreSQL as the
43database to use. The first place to start is the <c>emerge</c> process. In the
44next section, the installation process through emerge will be described, as
45well as the basic configuration.
46</p>
47
48</body> 33<body>
49</section> 34
35<p>
36<uri link="http://www.postgresql.org">PostgreSQL</uri> is a free and open source
37relational database management system (RDBMS). It supports such things as
38transactions, schemata and foreign keys, and is often touted to more strictly
39adhere to the SQL standards and to be more secure, by default, than any other
40database, commercial or otherwise.
41</p>
42
43<p>
44Visit the <uri link="http://www.postgresql.org/about/">About</uri> page on
45postgresql.org for more information.
46</p>
47
48</body>
50<section> 49</section>
51<title>PostgreSQL installation</title> 50<section>
51<title>What This Article Will Cover</title>
52<body>
53
54<p>
55This article will guide you through the Gentoo specific steps to install the
56PostgreSQL RDBMS.
57</p>
58
59<p>
60The Ebuilds covered by this article are <uri
61link="http://packages.gentoo.org/package/dev-db/postgresql-docs">dev-db/postgresql-docs</uri>,
62<uri
63link="http://packages.gentoo.org/package/dev-db/postgresql-base">dev-db/postgresql-base</uri>
64and <uri
65link="http://packages.gentoo.org/package/dev-db/postgresql-server">dev-db/postgresql-server</uri>.
66</p>
67
68<p>
69This article assumes that you will be installing the latest, stable version of
70PostgreSQL; at the time of this writing, the version was 9.0.3. Adjust the
71commands in this article as necessary for your specific version.
72</p>
73
74<impo>
75The 8.2 branch will have its upstream support dropped in December of 2011. Start
76planning your migration now.
77</impo>
78
52<body> 79</body>
80</section>
81<section>
82<title>About the Ebuilds</title>
83<body>
53 84
54<p>
55To begin, we must first <c>emerge</c> the PostgreSQL package. To do so, run the
56following code to first ensure that the options for it are properly set:
57</p> 85<p>
58 86The PostgreSQL ebuilds in Portage feature slotting based on the major version.
59<pre caption="Checking the PostgreSQL build options"> 87This allows you to have two major versions of PostgreSQL operating
60# <i>emerge -pv postgresql</i> 88simultaneously; 8.4 and 9.0 libraries and servers can be installed and serve at
61 89the same time. This is useful in such circumstances where you need to move data
62These are the packages that I would merge, in order: 90from an older database to a new database, or need to have a production and a
63 91testing database on the same machine. Also, this prevents a database,
64Calculating dependencies ...done! 92corresponding libraries or executables from being overwritten by an incompatible
65[ebuild N ] dev-db/postgresql-8.0.4 -doc -kerberos +nls +pam +perl -pg-intdatetime +python +readline (-selinux) +ssl -tcl +xml +zlib 0 kB 93update. That would require migration which is described in this guide.
66</pre>
67
68<p> 94</p>
69Here's a list of what the different build options indicate: 95
70</p> 96<p>
97Additionally, bug and security fixes, which are delivered via minor version
98updates, can be applied without fear of corrupting the database or the
99PostgreSQL installation itself; 9.0.2 can be updated to 9.0.3 as they are
100guaranteed to be compatible and require no more interaction from you than to
101emerge it and restart the server process &mdash; neither migration,
102reconfiguration nor initialization are necessary.
103</p>
104
105<p>
106Read the <uri link="http://www.postgresql.org/support/versioning">PostgreSQL
107Versioning 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>
117There is quite a bit that will not be covered. The <uri
118link="http://www.postgresql.org/docs/">official documentation</uri> is somewhere
119in the neighborhood of 2,000 pages. So, a lot of details will be left out in
120this quick start guide. Only Gentoo specific issues will be covered and some
121basic 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>
135If you have any of the following ebuilds installed, then you have an older,
136obsolete Gentoo installation of PostgreSQL and should migrate now:
137dev-db/postgresql-libs, dev-db/postgresql-client, dev-db/libpq and/or
138dev-db/postgresql.
139</p>
140
141<p>
142This article does cover <uri link="#oldmigration">migrating</uri> from the old
143ebuilds to the new ones.
144</p>
145
146</body>
147</section>
148<section>
149<title>USE Flags</title>
150<body>
71 151
72<table> 152<table>
73<tr> 153 <tr>
74 <th>USE Flag</th> 154 <th>USE Flag</th>
75 <th>Meaning</th> 155 <th>Meaning</th>
76</tr> 156 </tr>
77<tr> 157 <tr>
78 <ti>doc</ti> 158 <ti>doc</ti>
79 <ti> 159 <ti>
80 This USE flag enables or disables the installation of documentation 160 Include the <uri link="http://www.postgresql.org/docs/">online
81 outside of the standard man pages. The one good time to disable this 161 documentation</uri> to be stored on your system
82 option is if you are low on space, or you have alternate methods of
83 getting a hold of the documentation (online, etc.)
84 </ti> 162 </ti>
85</tr> 163 </tr>
86<tr> 164 <tr>
87 <ti>kerberos</ti> 165 <ti>kerberos</ti>
166 <ti>Support for utilizing Kerberos for authentication.</ti>
167 </tr>
168 <tr>
169 <ti>ldap</ti>
88 <ti> 170 <ti>
89 When connecting to the database, with this option enabled, the admin 171 Support for utilizing LDAP authentication and connection parameter lookup.
90 has the option of using <c>kerberos</c> to authenticate their
91 users/services to the database.
92 </ti> 172 </ti>
93</tr> 173 </tr>
94<tr> 174 <tr>
95 <ti>nls</ti> 175 <ti>nls</ti>
96 <ti> 176 <ti>
97 If this option is enabled, PostgreSQL can utilize translated strings for 177 Enable the ability to display messages in a language other than
98 non-English speaking users. 178 English. Used in conjunction with the Portage variable LINGUAS.
99 </ti> 179 </ti>
100</tr> 180 </tr>
101<tr> 181 <tr>
102 <ti>pam</ti> 182 <ti>pam</ti>
103 <ti> 183 <ti>
104 If this option is enabled, and the admin configures the PostgreSQL 184 Support for utilizing Pluggable Authentication Modules for authentication.
105 configuration file properly, users/services will be able to login to a
106 PostgreSQL database using <c>PAM</c> (Pluggable Authentication Module).
107 </ti> 185 </ti>
108</tr> 186 </tr>
109<tr> 187 <tr>
110 <ti>perl</ti> 188 <ti>perl</ti>
111 <ti> 189 <ti>
112 If this option is enabled, <c>perl</c> bindings for PostgreSQL will be 190 Enable support for using Perl to write functions and trigger procedures.
113 built.
114 </ti> 191 </ti>
115</tr> 192 </tr>
116<tr> 193 <tr>
117 <ti>pg-intdatetime</ti> 194 <ti>pg-intdatetime (Deprecated)</ti>
118 <ti> 195 <ti>
119 If this option is enabled, PostgreSQL will support 64 bit integer date 196 Use the newer, high resolution, 64-bit integer method for formatting
120 types. 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.)
121 </ti> 200 </ti>
122</tr> 201 </tr>
123<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>
124 <ti>python</ti> 212 <ti>python</ti>
125 <ti> 213 <ti>
126 If this option is enabled, PostgreSQL will be built with 214 Enable support for using Python to write functions and trigger procedures.
127 <c>python</c> bindings.
128 </ti> 215 </ti>
129</tr> 216 </tr>
130<tr> 217 <tr>
131 <ti>readline</ti> 218 <ti>readline</ti>
132 <ti> 219 <ti>
133 If this option is enabled, PostgreSQL will support <c>readline</c> style 220 You really want this enabled. Disabling removes command line editing and
134 command line editing. This includes command history and isearch. 221 history in psql.
135 </ti> 222 </ti>
136</tr> 223 </tr>
137<tr> 224 <tr>
138 <ti>selinux</ti> 225 <ti>selinux</ti>
139 <ti> 226 <ti>
140 If this option is enabled, an <c>selinux</c> policy for PostgreSQL will be 227 Install respective SELinux policy. This can only be enabled by using the
141 installed. 228 SELinux profile.
142 </ti> 229 </ti>
143</tr> 230 </tr>
144<tr> 231 <tr>
145 <ti>ssl</ti> 232 <ti>ssl</ti>
146 <ti> 233 <ti>Enable support for SSL connections.</ti>
147 If this option is enabled, PostgreSQL will utilize the <c>OpenSSL</c>
148 library to encrypt traffic between PostgreSQL clients and servers.
149 </ti> 234 </tr>
150</tr>
151<tr> 235 <tr>
152 <ti>tcl</ti> 236 <ti>tcl</ti>
153 <ti> 237 <ti>
154 If this option is enabled, PostgreSQL will build <c>tcl</c> bindings. 238 Enable support for using Tcl to write functions and trigger procedures.
155 </ti> 239 </ti>
156</tr> 240 </tr>
157<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>
158 <ti>xml</ti> 257 <ti>xml</ti>
159 <ti> 258 <ti>Enable SQL/XML support.</ti>
160 If this option is enabled, <c>XPATH</c> style xml support will be built.
161 More information on using xml support with PostgreSQL can be found on:
162 <uri link="http://www.throwingbeans.org/postgresql_and_xml.html">
163 PostgreSQL and XML</uri>.
164 </ti> 259 </tr>
165</tr>
166<tr> 260 <tr>
167 <ti>zlib</ti> 261 <ti>zlib</ti>
168 <ti> 262 <ti>Support for compressed archives in pg_dump and pg_restore.</ti>
169 This isn't really used by PostgreSQL itself, but by <c>pg_dump</c> to
170 compress the dumps it produces.
171 </ti> 263 </tr>
172</tr>
173</table> 264</table>
174 265
175<p> 266<note>
176Once you've customized PostgreSQL to meet your specific needs, go ahead and 267Flipping the 'pg-intdatetime' or the 'pg_legacytimestamp' will require you to do
177start the <c>emerge</c>: 268a dump and restore if any of your databases utilize timestamps. The two methods
178</p> 269are incompatible with each other.
270</note>
179 271
272</body>
273</section>
274<section>
275<title>Start Emerging</title>
276<body>
277
180<pre caption="Emerge-ing PostgreSQL"> 278<pre caption="Emerging PostgreSQL server">
181# <i>emerge postgresql</i> 279# <i>emerge -av dev-db/postgresql-server</i>
182<comment>(Output shortened)</comment>
183>>> /usr/lib/libecpg.so.5 -> libecpg.so.5.0
184>>> /usr/bin/postmaster -> postgres
185 * Make sure the postgres user in /etc/passwd has an account setup with /bin/bash as the shell
186 *
187 * Execute the following command
188 * emerge --config =postgresql-8.0.4
189 * to setup the initial database environment.
190 *
191>>> Regenerating /etc/ld.so.cache...
192>>> dev-db/postgresql-8.0.4 merged.
193</pre>
194 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>
291You may receive a notice regarding that any of the above packages are blocked by
292any or all of the following packages: dev-db/postgresql-libs,
293dev-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
295link="#oldmigration">migration</uri> for how to handle this situation.
195<p> 296</p>
196As shown by the einfo output, there is some post setup that must be done. The 297
197next chapter will look at the actual configuration of PostgreSQL. 298</body>
299</section>
300<section>
301<title>Preparing to Initialize the Database Cluster</title>
302<body>
303
304<p>
305Once 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
307defaults of the server and <b>cannot</b> be changed later without deleting the
308directory 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>
313defines where to create the database cluster and related
314files. <e>PG_INITDB_OPTS</e> may contain any <uri
315link="http://www.postgresql.org/docs/current/static/app-initdb.html">extra
316options</uri> you would care to set. The extra options are <b>not</b> required
317as the reasonable defaults are, ahem, reasonable.
318</p>
319
320<p>
321In the following example, <e>PGDATA</e> states that the configuration files are
322to be located in <path>/etc/postgresql-9.0/</path>. <e>DATA_DIR</e> states that
323the database cluster should be installed to
324<path>/var/lib/postgresql/9.0/data/</path>, which is the default. If you decide
325to stray from the default, bear in mind that it is a <b>very good idea</b> to
326keep the major version in the path. <e>PG_INITDB_OPTS</e> states that the
327default locale should be <e>en_US.UTF-8</e>. That is, U.S. English ordering and
328formatting, 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>
333PGDATA="/etc/postgresql-9.0/"
334
335<comment># Where the data directory is located/to be created</comment>
336DATA_DIR="/var/lib/postgresql/9.0/data"
337
338<comment># Additional options to pass to initdb.
339# See 'man initdb' for available options.</comment>
340PG_INITDB_OPTS="--locale=en_US.UTF-8"
341</pre>
342
343<note>
344This only determines the default locale and character encoding. You can specify
345different locales and/or character encodings at database creation time
346(<c>CREATE DATABASE</c>) in the same database cluster.
347</note>
348
349<p>
350There are six locale options that can be set to override <e>--locale=</e>. The
351following 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>
389So, if you would like the default to be English, but you want messages in, say,
390Swedish, then your <e>PG_INITDB_OPTS</e> would look like so:
391</p>
392
393<pre caption="Example">
394PG_INITDB_OPTS="--locale=en_US.UTF-8 --lc-messages=sv_SE.UTF-8"
395</pre>
396
397<p>
398A complete list of language and character encodings supported by the server can
399be found in the documentation, but your system must also support the respective
400languages and character encodings. Compare the output of <c>locale -a</c> to the
401<uri
402link="http://www.postgresql.org/docs/current/static/multibyte.html">encodings</uri>
403in the documentation.
404</p>
405
406<p>
407You 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
410created 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>
418This will create the database cluster and store all the related server files
419into <e>PGDATA</e> and <e>DATA_DIR</e>.
198</p> 420</p>
199 421
200</body> 422</body>
201</section> 423</section>
202</chapter> 424</chapter>
425
203<chapter> 426<chapter>
204<title>PostgreSQL configuration</title> 427<title>Configuration</title>
205<section>
206<title>Setting up the initial database environment</title>
207<body>
208
209<p>
210As noted in the earlier <c>emerge</c> output, the initial database environment
211must be setup. However, before this is done, one thing needs to be considered.
212Unlike, say MySQL, PostgreSQL's "root" password is the password of the actual
213user. However, only the user is created by the ebuild <e>not</e> the password.
214So before we can begin, the password must be set for the postgres user:
215</p>
216
217<pre caption="Setting the password">
218# <i>passwd postgres</i>
219New UNIX password:
220Retype new UNIX password:
221passwd: password updated successfully
222</pre>
223
224<p>
225Now that this is set up, the creation of the initial database environment can
226occur:
227</p>
228
229<pre caption="Configuring the database environment with emerge --config">
230# <i>emerge --config =postgresql-8.0.4</i>
231
232
233Configuring pkg...
234
235 * Creating the data directory ...
236 * Initializing the database ...
237The files belonging to this database system will be owned by user "postgres".
238This user must also own the server process.
239
240The database cluster will be initialized with locale C.
241
242fixing permissions on existing directory /var/lib/postgresql/data ... ok
243creating directory /var/lib/postgresql/data/global ... ok
244creating directory /var/lib/postgresql/data/pg_xlog ... ok
245creating directory /var/lib/postgresql/data/pg_xlog/archive_status ... ok
246creating directory /var/lib/postgresql/data/pg_clog ... ok
247creating directory /var/lib/postgresql/data/pg_subtrans ... ok
248creating directory /var/lib/postgresql/data/base ... ok
249creating directory /var/lib/postgresql/data/base/1 ... ok
250creating directory /var/lib/postgresql/data/pg_tblspc ... ok
251selecting default max_connections ... 100
252selecting default shared_buffers ... 1000
253creating configuration files ... ok
254creating template1 database in /var/lib/postgresql/data/base/1 ... ok
255initializing pg_shadow ... ok
256enabling unlimited row size for system tables ... ok
257initializing pg_depend ... ok
258creating system views ... ok
259loading pg_description ... ok
260creating conversions ... ok
261setting privileges on built-in objects ... ok
262creating information schema ... ok
263vacuuming database template1 ... ok
264copying template1 to template0 ... ok
265
266WARNING: enabling "trust" authentication for local connections
267You can change this by editing pg_hba.conf or using the -A option the
268next time you run initdb.
269
270Success. You can now start the database server using:
271
272 /usr/bin/postmaster -D /var/lib/postgresql/data
273or
274 /usr/bin/pg_ctl -D /var/lib/postgresql/data -l logfile start
275
276 *
277 * You can use /etc/init.d/postgresql script to run PostgreSQL instead of pg_ctl.
278 *
279</pre>
280
281<p>
282Now the initial database environment is setup. The next section will look at
283verifying the install and setting up users to access the database.
284</p>
285
286</body>
287</section> 428<section>
429<title>Where the Configuration Files are Located</title>
430<body>
431
432<p>
433This 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>
288<section> 439</section>
289<title>PostgreSQL database setup</title> 440<section>
441<title>postgresql.conf</title>
442<body>
443
444<p>
445This is the main configuration file. The line that you may find of immediate
446interest is <e>listen_addresses</e>. This variable defines to which addresses
447PostgreSQL will bind. By default, only localhost and the Unix socket are
448bound. Changing <e>listen_addresses</e> is not enough to enable remote
449connections. That will be covered in the next section. The <uri
450link="http://www.postgresql.org/docs/current/static/runtime-config.html">official
451documentation</uri> is fairly easy to understand and is exhaustive on all the
452settings available. It would behoove you to read that in addition to what is
453covered here as some things may change.
454</p>
455
456<p>
457Of secondary interest is the logging destination. By default, everything is
458logged to <path>postmaster.log</path> in the <e>DATA_DIR</e> directory. There is
459an entire subsection of <path>postgresql.conf</path> that covers a slew of
460options for how, what and where to log. The subsection is marked: ERROR
461REPORTING AND LOGGING.
462</p>
463
464<p>
465Other than <e>listen_addresses</e> and the logging options, the rest of the
466defaults in <path>postgresql.conf</path> are reasonable enough to get you going.
467</p>
468
290<body> 469</body>
470</section>
471<section>
472<title>pg_hba.conf</title>
473<body>
291 474
292<p>
293Now that PostgreSQL is setup, it's a good idea at this point to verify the
294installation. First, make sure the service starts up ok:
295</p> 475<p>
476The <path>pg_hba.conf</path> file states who is allowed to connect to the
477database server and which authentication method must be used to establish the
478connection. Again, the documentation is quite exhaustive on the settings and
479what they all mean, but a few things are covered here for clarification.
480</p>
296 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>
486local all all trust
487<comment># IPv4 local connections:</comment>
488host all all 127.0.0.1/32 trust
489<comment># IPv6 local connections:</comment>
490host all all ::1/128 trust
491</pre>
492
493<p>
494As has been mentioned before, by default the server is secure. Kind of. There is
495only 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
497through the <path>/var/run/postgresql/.s.PGSQL.5432</path> Unix socket, which is
498owned by the <e>postgres</e> system user and system group, or via localhost. Now
499for the "kind of" bit: Any user on the system can make a connection to the
500database through the localhost. Even as the <e>postgres</e> database superuser.
501</p>
502
503<p>
504To make a connection through the Unix socket, however, the users &mdash;
505including the users for other services such as <e>apache</e> &mdash; must be in
506the <e>postgres</e> system group. Use <c>gpasswd -a <e>user</e> postgres</c> to
507add <e>user</e> to the <e>postgres</e> group. Users not in the <e>postgres</e>
508group will be rejected with "Permission denied".
509</p>
510
511<warn>
512Never disable the Unix socket entirely. The initscripts require access to it in
513order to operate properly. The method can be changed freely.
514</warn>
515
516<p>
517The <e>trust</e> method is what allows any user to log on as any user without a
518password. It specifies just what it implies: Trust all connections for the given
519type to the given database from the given database user (but not the system
520user) from the given location without a password. This is what allows any user
521on the system to log on as any user through the localhost connection from the
522get go. This is not as dangerous as it seems, but does pose a serious security
523risk in most circumstances.
524</p>
525
526<p>
527The 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
529start the connection and the password is sent "in-the-clear". This method is
530fine when such information will never leave the machine, such as connecting via
531the Unix socket or localhost. The md5 method is like password, but protects the
532password by using an md5 hash. This is what you want to use whenever the
533password is going to traverse a network.
534</p>
535
536<p>
537At this point, this author would like to bring your attention to the last two
538lines, four lines including comments, of the <path>pg_hba.conf</path>
539file. PostgreSQL has native support for IPv6 regardless of your desires for such
540support. Additionally, IPv4 addresses are automatically mapped to IPv6
541addresses, <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>
546There seems to be some misunderstanding, though, as to how host names are mapped
547to 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>
552127.0.0.1 localhost
553::1 localhost
554</pre>
555
556<p>
557From the example above you can see that both an IPv4 and an IPv6 IP address are
558mapped to localhost. When <c>psql</c> refers to this file, it will grab the
559first match and use that as the address; in this case 127.0.0.1. When PostgreSQL
560parses this, it will match the IPv6 formatted address as well,
561e.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
563such, if you do not have ::1 as a permitted means of access, <c>psql</c> will
564not be able to establish a connection. Furthermore, your kernel needs to support
565the IPv6 protocol.
566</p>
567
568<p>
569So, 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
571ordered properly, and it removes any doubt as to which IP addresses are allowed
572or 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>
586Now 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
588code listing:
589</p>
590
297<pre caption="Starting up the PostgreSQL service"> 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>
298# <i>/etc/init.d/postgresql start</i> 594# <i>/etc/init.d/postgresql-9.0 start</i>
299* Starting PostgreSQL ... [ ok ] 595postgresql-9.0 | * Starting PostgreSQL ... [ ok ]
300</pre>
301 596
302<p> 597<comment>(Open a connection to the server and set the password.)</comment>
303Once this is verified working, it's also a good idea to add it to the default 598# <i>psql -U postgres</i>
304runlevel so it starts at boot: 599psql (9.0.3)
305</p> 600Type "help" for help.
306 601
307<pre caption="Adding to the default runlevel"> 602postgres=# <i>\password</i>
308# <i>rc-update add postgresql default</i> 603Enter new password:
309* postgresql added to runlevel default
310</pre>
311
312<p>
313Now that the service has started, it's time to try setting up a test database.
314To start out, let's create a test database by using the <c>createdb</c>
315command. We'll also pass along the <c>-U</c> option to set the user (it
316defaults to the current user name if you don't), and the <c>-W</c> option to
317request the password we created earlier. Finally we give it the name of the
318database we want to create:
319</p>
320
321<pre caption="Creating a database with createdb">
322$ <i>createdb -U postgres -W test</i>
323Password:
324CREATE DATABASE
325</pre>
326
327<p>
328The database was successfully created, and we can confirm that the database can
329run basic tasks. We'll go ahead and drop this database (remove it) with the
330<c>dropdb</c> command:
331</p>
332
333<pre caption="Dropping a database with dropdb">
334$ <i>dropdb -U postgres -W test</i>
335Password:
336DROP DATABASE
337</pre>
338
339<p>
340Right now, only the postgres user can run commands. Obviously this is not the
341sort of setup one would like in a multi-user environment. The next section will
342look at working with user accounts.
343</p>
344
345</body>
346</section>
347<section>
348<title>Setting up database user accounts</title>
349<body>
350
351<p>
352As mentioned earlier, having to login as the postgres user is somewhat
353undesirable in a mult-user environment. In most cases there will be various
354users and services accessing the server, and each have different permission
355requirements. So, to handle this, the <c>createuser</c> command can be used.
356This command is an alternative to running a few SQL queries, and is a lot more
357flexible from an admin standpoint. We'll go ahead and create two users, a
358'superuser' that can add other users and administer the db, and a standard user:
359</p>
360
361<pre caption="Setting up the superuser">
362<comment>(replace chris with the username you'd like to use)</comment>
363$ <i>createuser -a -d -P -E -U postgres -W chris</i>
364Enter password for new user:
365Enter it again: 604Enter it again:
366Password: 605postgres=# <i>\q</i>
367CREATE USER
368</pre>
369 606
370<p> 607<comment>(Change 'trust' to 'password' for the local connection.)</comment>
371There, we've created the superuser. The command line option <c>-a</c> specifies 608# <i>nano -w /etc/postgresql-9.0/pg_hba.conf</i>
372that this user can add other users. <c>-d</c> means that this user can create 609# <i>/etc/init.d/postgresql-9.0 reload</i>
373databases. <c>-P</c> let's you enter a password for the user and <c>-E</c> will 610postgresql-9.0 | * Reloading PostgreSQL configuration ... [ ok ]
374encrypt it for security purposes. Now then, we'll test this new user's 611# <i>rc-update add postgresql-9.0 default</i>
375permissions out by setting up our standard user: 612 * service postgresql-9.0 added to runlevel default
613</pre>
614
376</p> 615<p>
377 616At this point you are ready to continue on with the official <uri
378<pre caption="Setting up the standard user"> 617link="http://www.postgresql.org/docs/current/static/tutorial.html">PostgreSQL
379<comment>(replace chris with the username you've just created)</comment> 618Tutorial</uri>. The tutorial will guide you through creating roles, databases,
380$ <i>createuser -A -D -P -E -U chris -W testuser</i> 619schemata and all that fun and useful stuff.
381Enter password for new user:
382Enter it again:
383Password:
384CREATE USER
385</pre>
386
387<p>
388Success! Our new user was created using the previously created superuser. The
389<c>-A</c> and <c>-D</c> options do the opposite of <c>-a</c> and <c>-d</c>, and
390instead deny the user the ability to create other users and databases. Now that
391there are users to work with, the next chapter will look at using the new
392database.
393</p> 620</p>
394 621
395</body> 622</body>
396</section> 623</section>
397</chapter> 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>
633There are only two reasons you would need to perform a migration: When moving
634from one major version to another, <e>e.g.</e>, from PostgreSQL 8.4.7 to 9.0.3,
635but not from 9.0.2 to 9.0.3; or when switching from the deprecated
636floating-point timestamp format to the new 64-bit integer timestamp format.
637</p>
638
639<note>
640You 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
642dev-db/postgresql-client &mdash; to the new ebuilds &mdash;
643dev-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
654the migration process rather drastically.
655</p>
656
657<p>
658However, there are two caveats with using pg_upgrade. Firstly, it does not
659support configuration files being in a different directory than where the data
660is stored. This can be resolved by using symbolic links. Lastly, you can only
661use it to migrate from a database from 8.3 or newer. If you have an older
662database you will need to follow the <uri link="#pre90">Pre-9.0 Migration</uri>
663instructions.
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
674connections 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
679you 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>
700Because the new ebuilds feature a more advanced slotting method than the
701previous ones, the downtime is quite minimal, most likely minutes rather than
702hours.
703</p>
704
705<p>
706In the following examples, it is assumed that you are using the default
707locations and port settings, and that you are migrating from 8.3 to 8.4. Adjust
708accordingly if you have deviated from the default.
709</p>
710
711<p>
712If you have not already done so, follow the <uri
713link="#installation">installation instructions</uri> before starting the
714migration. Such a compile may hamper performance on the database server but it
715can keep going.
716</p>
717
718<p>
719A 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
721to 6543. (Any port number other than what your old installation is bound to will
722do.)
723</p>
724
725<p>
726Next, edit <path>/etc/postgresql-8.3/pg_hba.conf</path> so that only the
727database superuser <e>postgres</e> can access the database cluster via the Unix
728socket.
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>
757Hopefully everything went according to plan and you have a successfully updated
758server 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>
768You 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
770that the server will have to be down for a few hours. Maybe for the weekend,
771even.
772</p>
773
774<p>
775Before starting, you will need to deny access to the server, so that no changes
776are 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
778important.
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
788server.)
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>
795You may break some packages that were built against those packages, but once you
796have installed dev-db/postgresql-base and/or dev-db/postgresql-server you can
797run <c>revdep-rebuild</c> to reemerge any packages that may have been broken.
798</p>
799
800</body>
801</section>
802</chapter>
803
398<chapter> 804<chapter>
399<title>Using PostgreSQL</title> 805<title>Utilities</title>
400<section>
401<title>Setting up permissions</title>
402<body>
403
404<p>
405Now there is a user that can create databases and add other users, and the main
406postgres user that can do anything. The user created earlier can currently login
407to the server, and that's about it. In general, users need to be able to insert
408data and retrieve data, and sometimes any other number of tasks. So, for this
409new user to be able to do anything, they must be setup with the proper
410permissions. This can easily be done by passing the <c>-O</c> parameter to
411<c>createdb</c>. We'll start by making a new database, <b>MyDB</b> with our
412superuser that will be owned by the previous testuser:
413</p>
414
415<pre caption="Creating the MyDB database">
416$ <i>createdb -O testuser -U chris -W MyDB</i>
417Password:
418CREATE DATABASE
419</pre>
420
421<p>
422Alright, now we have a new MyDB database, and a testuser that can access it.
423To test this out, we'll login as the testuser to the new MyDB database. We'll
424do this with the <c>psql</c> program. This program is what's used to connect to
425the PostgreSQL database from command line. So connect to the new database like
426so:
427</p>
428
429<pre caption="Logging into the MyDB database as the testuser">
430$ <i>psql -U testuser -W MyDB</i>
431Password:
432Welcome to psql 8.0.4, the PostgreSQL interactive terminal.
433
434Type: \copyright for distribution terms
435 \h for help with SQL commands
436 \? for help with psql commands
437 \g or terminate with semicolon to execute query
438 \q to quit
439
440MyDB=&gt;
441</pre>
442
443<p>
444So, the testuser is now logged into the database, and can begin to initiate
445some commands. To get a feel for using PostgreSQL, the next section will take a
446look at some of the basic commands in navigating the <c>psql</c> client.
447</p>
448
449</body>
450</section> 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
812for managing PostgreSQL.
813</p>
814
815</body>
451<section> 816</section>
452<title>Basic PostgreSQL commands and creating a table</title> 817</chapter>
453<body>
454 818
455<p> 819<chapter>
456For those who are used to MySQL, this is somewhat of a definite read. This is 820<title>Troubleshooting</title>
457where PostgreSQL may get somewhat unique with regards to running commands. To
458start, here is a list of some commands that will be discussed:
459</p>
460
461<table>
462<tr>
463 <th>Command</th>
464 <th>Usage</th>
465 <th>MySQL Equivalent</th>
466</tr>
467<tr>
468 <ti>\c[onnect] [DBNAME|- [USER]]</ti>
469 <ti>Connects to another database</ti>
470 <ti>USE DATABASE</ti>
471</tr>
472<tr>
473 <ti>\q</ti>
474 <ti>Quit the <c>psql</c> client</ti>
475 <ti>quit</ti>
476</tr>
477<tr>
478 <ti>\i FILE</ti>
479 <ti>Run commands from <c>FILE</c></ti>
480 <ti>source FILE</ti>
481</tr>
482<tr>
483 <ti>\o [FILE]</ti>
484 <ti>Send query results to <c>FILE</c></ti>
485 <ti>INTO OUTFILE, but outputs everything (not just SELECTS)</ti>
486</tr>
487<tr>
488 <ti>\d [NAME]</ti>
489 <ti>Describe a database or table (as well as other items)</ti>
490 <ti>DESC(RIBE)</ti>
491</tr>
492<tr>
493 <ti>\db [PATTERN]</ti>
494 <ti>
495 List available tables that match <c>PATTERN</c> (all if no pattern
496 is given)
497 </ti>
498 <ti>SHOW TABLES</ti>
499</tr>
500</table>
501
502<p>
503With the exception of <c>\c[onnect]</c>, all the commands shown will be used
504later on in the section. So right now the database is empty. That said, we need
505to insert some data. The first step to inserting data, however, is to put it in
506a table. Right now there are no tables in the database, so we need to create
507one. This is done with the <c>CREATE TABLE</c> command. We'll make a table of
508items. They will contain a Product ID, Description, and price:
509</p>
510
511<pre caption="Creating the products table">
512MyDB=> CREATE TABLE products (
513MyDB(&gt; product_id SERIAL,
514MyDB(&gt; description TEXT,
515MyDB(&gt; price DECIMAL
516MyDB(&gt; );
517NOTICE: CREATE TABLE will create implicit sequence "products_product_id_seq"
518for serial column "products.product_id"
519CREATE TABLE
520</pre>
521
522<p>
523You can ignore the NOTICE, it's perfectly harmless. Looking at the last line of
524the function, <c>CREATE TABLE</c> seems to indicate that the command has
525succeeded. However, let's go ahead and verify that the table was indeed
526successfully created with the <c>\d</c> command:
527</p>
528
529<pre caption="Looking at the newly created table">
530MyDB=&gt; <i>\d products</i>
531 Table "public.products"
532 Column | Type | Modifiers
533-------------+---------+------------------------------------------------------------------
534 product_id | integer | not null default nextval('public.products_product_id_seq'::text)
535 description | text |
536 price | numeric |
537</pre>
538
539<p>
540Indeed the table was successfully created. Now that the table is created, it
541needs to be populated with data. The next section will look at populating the
542database with data.
543</p>
544
545</body>
546</section> 821<section>
547<section> 822<title>Server Lacks Instrumentation Functions</title>
548<title>Inserting data into the database</title>
549<body>
550
551<p>
552This section will look at the two ways of populating the newly created table
553with data. First let's look at the most basic command, <c>INSERT</c>:
554</p>
555
556<pre caption="INSERT syntax">
557INSERT INTO [tablename] (column1,column2,column3) VALUES(value1,value2,value3)
558</pre>
559
560<p>
561<c>tablename</c> contains the name of the table to insert the data into.
562(column1,column2,column3) lets you specify the specific columns to insert the
563values into. VALUES(value1,value2,value3) is the listing of values. The values
564are inserted into the same order as the columns (column1 gets value1, column2
565gets value2, column3 gets value3). These counts <e>must</e> be the same. So
566let's go ahead and insert an item into the table:
567</p>
568
569<impo>
570From working with databases for a long time, I personally recommend specifying
571<c>INSERT</c> statements exactly as above. Developers often make the mistake of
572using <c>INSERT INTO</c> without specifying columns. This is unproductive, as
573if a new column gets added to the database, it will cause in error if the value
574to column count is not the same. You should <e>always</e> specify the columns
575unless you're 300% sure you'll never add a column.
576</impo>
577
578<pre caption="Inserting data into the table">
579MyDB=&gt; <i>INSERT INTO products (description,price) VALUES('A test product', 12.00);</i>
580INSERT 17273 1
581</pre>
582
583<p>
584The last line needs a bit of explaining. The return of an insert command is an
585OID (Object Identifier) and the number of rows inserted. OID's are a bit beyond
586the scope of this guide, and the <uri
587link="http://www.postgresql.org/docs/8.1/static/datatype-oid.html">PostgreSQL
588manual</uri> has some good information on it. Now, for a situation where you
589have 20,000 products, these insert statements can be a little tedious. However,
590not all is lost. The <c>COPY</c> command can be used to insert data into a
591table from a file or stdin. In this example, let's assume that you have a csv
592(comma separated values) file, which contains the product id, description, and
593price. The file looks like this:
594</p>
595
596<pre caption="products.csv">
5972,meat,6.79
5983,soup,0.69
5994,soda,1.79
600</pre>
601
602<p>
603Now we'll use the <c>COPY</c> command to populate our data:
604</p>
605
606<impo>
607The <c>COPY FROM STDIN</c> command is used because only the postgres user can
608insert data from a file (for obvious security reasons).
609</impo>
610
611<pre caption="Using COPY to populate the products table">
612MyDB=&gt; <i>COPY products FROM STDIN WITH DELIMITER AS ',';</i>
613Enter data to be copied followed by a newline.
614End with a backslash and a period on a line by itself.
615>> <i>2,meat,6.79</i>
616>> <i>3,soup,0.69</i>
617>> <i>4,soda,1.79</i>
618>> <i>\.</i>
619</pre>
620
621<p>
622Unfortunately, this line doesn't return the same status information as the
623<c>INSERT INTO</c> statement. How do we know the data was inserted? The next
624section will look at running queries to check our data.
625</p>
626
627</body> 823<body>
628</section>
629<section>
630<title>Using PostgreSQL queries</title>
631<body>
632 824
633<p>
634This section will look at using the <c>SELECT</c> statement to view data in our
635tables. The basic <c>SELECT</c> format looks like this:
636</p> 825<p>
637 826This problem is easy to solve. What is difficult about it is finding the
638<pre caption="SELECT syntax"> 827answer. What is required is an import from a file that already exists on the
639SELECT (column1,column2|*) FROM (table) [WHERE (conditionals)] 828storage drive: <path>adminpack.sql</path>. To resolve this issue, run this
640</pre> 829command:
641
642<p> 830</p>
643There are two ways to select columns. The first is using <c>*</c> to select all 831
644columns, and the second is to specify a list of specific columns you wish to 832<pre caption="Command to Add Instrumentation Functions">
645see. The second is quite handy when you want to find a specific column in a 833# <i>psql -U postgres --file /usr/share/postgresql-9.0/contrib/adminpack.sql</i>
646rather large list of them. Let's start out with using <c>SELECT</c> with
647<c>*</c> to specify all columns:
648</p> 834</pre>
649
650<pre caption="Viewing the products table">
651MyDB=&gt; <i>SELECT * FROM products;</i>
652 product_id | description | price
653------------+----------------+-------
654 1 | A test product | 12.00
655 2 | meat | 6.79
656 3 | soup | 0.69
657 4 | soda | 1.79
658(4 rows)
659</pre>
660
661<p>
662As shown here, all the data we inserted earlier is indeed in the table. Now
663let's say we only want to see the description and the price, and don't care
664about the product id. In this case we'll use the column specific SELECT form:
665</p>
666
667<pre caption="Viewing specific columns from the products table">
668MyDB=&gt; <i>SELECT description,price FROM products;</i>
669 description | price
670----------------+-------
671 A test product | 12.00
672 meat | 6.79
673 soup | 0.69
674 soda | 1.79
675(4 rows)
676</pre>
677
678<p>
679Now only the product and price is shown, letting us focus on only the important
680data. Now let's say that we want to see only the items that are greater than
681$2.00. Here's where the <c>WHERE</c> clause comes in handy:
682</p>
683
684<pre caption="Viewing specific rows from the products table">
685MyDB=&gt; <i>SELECT description,price FROM products WHERE price > 2.00;</i>
686 description | price
687----------------+-------
688 A test product | 12.00
689 meat | 6.79
690(2 rows)
691</pre>
692
693<p>
694Now a listing of products over $2.00 is displayed, focusing the data even more.
695These forms of querying for information are very powerful, and can help create
696extremely useful reports.
697</p>
698
699</body>
700</section>
701<section>
702<title>Conclusion</title>
703<body>
704
705<p>
706This concludes the PostgreSQL Guide. A big thanks goes to Masatomo Nakano, the
707previous Gentoo PostgreSQL maintainer for his help in answering my questions.
708Any suggestions on this guide should be sent to
709<mail>chriswhite@gentoo.org</mail>. For more extensive documentation, see the
710<uri link="http://www.postgresql.org">PostgreSQL website</uri>.
711</p>
712 835
713</body> 836</body>
714</section> 837</section>
715</chapter> 838</chapter>
716</guide> 839</guide>

Legend:
Removed from v.1.5  
changed lines
  Added in v.1.6

  ViewVC Help
Powered by ViewVC 1.1.20