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

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

Parent Directory | Revision Log | View Patch Patch

Revision 1.5		Revision 1.11
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.11 2012/06/13 09:10:59 nightmorph Exp $ -->
4		4
5	<guide link="/doc/en/postgres-howto.xml" lang="en">	5	<guide>
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>
16	This guide is meant to show the basic setup of PostgreSQL. The setup described	17	This is a quick start guide to PostgreSQL. It covers emerging PostgreSQL and
17	here should be sufficient enough to use for basic web appplications, and any	18	configuring it. This is complementary to the official documentation, but does
18	other program that provides PostgreSQL support.	19	not 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>11</version>
26	<date>2007-04-25</date>	27	<date>2012-06-13</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>
35	When talking to most developers about the different database solutions to use,
36	two major databases will usually form the answer. One would be <c>MySQL</c>,
37	and the other is what this document will refer to, <c>PostgreSQL</c>. The
38	advantages of one over the other is a somewhat long winded debate, however it
39	is just to say that PostgreSQL has had a more firm grasp on true relational
40	database 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
42	may be, this document assumes that you have selected PostgreSQL as the
43	database to use. The first place to start is the <c>emerge</c> process. In the
44	next section, the installation process through emerge will be described, as
45	well 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
		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>
50	<section>	49	</section>
51	<title>PostgreSQL installation</title>	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
52	<body>	79	</body>
		80	</section>
		81	<section>
		82	<title>About the Ebuilds</title>
		83	<body>
53		84
54	<p>
55	To begin, we must first <c>emerge</c> the PostgreSQL package. To do so, run the
56	following code to first ensure that the options for it are properly set:
57	</p>	85	<p>
58		86	The PostgreSQL ebuilds in Portage feature slotting based on the major version.
59	<pre caption="Checking the PostgreSQL build options">	87	This allows you to have two major versions of PostgreSQL operating
60	# <i>emerge -pv postgresql</i>	88	simultaneously; 8.4 and 9.0 libraries and servers can be installed and serve at
61		89	the same time. This is useful in such circumstances where you need to move data
62	These are the packages that I would merge, in order:	90	from an older database to a new database, or need to have a production and a
63		91	testing database on the same machine. Also, this prevents a database,
64	Calculating dependencies ...done!	92	corresponding 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	93	update. That would require migration which is described in this guide.
66	</pre>
67
68	<p>	94	</p>
69	Here's a list of what the different build options indicate:	95
70	</p>	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 — 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>
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>
176	Once you've customized PostgreSQL to meet your specific needs, go ahead and	267	Flipping the 'pg-intdatetime' or the 'pg_legacytimestamp' will require you to do
177	start the <c>emerge</c>:	268	a dump and restore if any of your databases utilize timestamps. The two methods
178	</p>	269	are 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>
		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.
195	<p>	296	</p>
196	As shown by the einfo output, there is some post setup that must be done. The	297
197	next 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>
		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-9.0">
		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>.
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>
210	As noted in the earlier <c>emerge</c> output, the initial database environment
211	must be setup. However, before this is done, one thing needs to be considered.
212	Unlike, say MySQL, PostgreSQL's "root" password is the password of the actual
213	user. However, only the user is created by the ebuild <e>not</e> the password.
214	So 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>
219	New UNIX password:
220	Retype new UNIX password:
221	passwd: password updated successfully
222	</pre>
223
224	<p>
225	Now that this is set up, the creation of the initial database environment can
226	occur:
227	</p>
228
229	<pre caption="Configuring the database environment with emerge --config">
230	# <i>emerge --config =postgresql-8.0.4</i>
231
232
233	Configuring pkg...
234
235	* Creating the data directory ...
236	* Initializing the database ...
237	The files belonging to this database system will be owned by user "postgres".
238	This user must also own the server process.
239
240	The database cluster will be initialized with locale C.
241
242	fixing permissions on existing directory /var/lib/postgresql/data ... ok
243	creating directory /var/lib/postgresql/data/global ... ok
244	creating directory /var/lib/postgresql/data/pg_xlog ... ok
245	creating directory /var/lib/postgresql/data/pg_xlog/archive_status ... ok
246	creating directory /var/lib/postgresql/data/pg_clog ... ok
247	creating directory /var/lib/postgresql/data/pg_subtrans ... ok
248	creating directory /var/lib/postgresql/data/base ... ok
249	creating directory /var/lib/postgresql/data/base/1 ... ok
250	creating directory /var/lib/postgresql/data/pg_tblspc ... ok
251	selecting default max_connections ... 100
252	selecting default shared_buffers ... 1000
253	creating configuration files ... ok
254	creating template1 database in /var/lib/postgresql/data/base/1 ... ok
255	initializing pg_shadow ... ok
256	enabling unlimited row size for system tables ... ok
257	initializing pg_depend ... ok
258	creating system views ... ok
259	loading pg_description ... ok
260	creating conversions ... ok
261	setting privileges on built-in objects ... ok
262	creating information schema ... ok
263	vacuuming database template1 ... ok
264	copying template1 to template0 ... ok
265
266	WARNING: enabling "trust" authentication for local connections
267	You can change this by editing pg_hba.conf or using the -A option the
268	next time you run initdb.
269
270	Success. You can now start the database server using:
271
272	/usr/bin/postmaster -D /var/lib/postgresql/data
273	or
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>
282	Now the initial database environment is setup. The next section will look at
283	verifying 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>
		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>
288	<section>	439	</section>
289	<title>PostgreSQL database setup</title>	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
290	<body>	469	</body>
		470	</section>
		471	<section>
		472	<title>pg_hba.conf</title>
		473	<body>
291		474
292	<p>
293	Now that PostgreSQL is setup, it's a good idea at this point to verify the
294	installation. First, make sure the service starts up ok:
295	</p>	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>
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>
		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 —
		505	including the users for other services such as <e>apache</e> — 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
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 ]	595	postgresql-9.0 \| * Starting PostgreSQL ... [ ok ]
300	</pre>
301		596
302	<p>	597	<comment>(Open a connection to the server and set the password.)</comment>
303	Once this is verified working, it's also a good idea to add it to the default	598	# <i>psql -U postgres</i>
304	runlevel so it starts at boot:	599	psql (9.0.3)
305	</p>	600	Type "help" for help.
306		601
307	<pre caption="Adding to the default runlevel">	602	postgres=# <i>\password</i>
308	# <i>rc-update add postgresql default</i>	603	Enter new password:
309	* postgresql added to runlevel default
310	</pre>
311
312	<p>
313	Now that the service has started, it's time to try setting up a test database.
314	To start out, let's create a test database by using the <c>createdb</c>
315	command. We'll also pass along the <c>-U</c> option to set the user (it
316	defaults to the current user name if you don't), and the <c>-W</c> option to
317	request the password we created earlier. Finally we give it the name of the
318	database we want to create:
319	</p>
320
321	<pre caption="Creating a database with createdb">
322	$ <i>createdb -U postgres -W test</i>
323	Password:
324	CREATE DATABASE
325	</pre>
326
327	<p>
328	The database was successfully created, and we can confirm that the database can
329	run 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>
335	Password:
336	DROP DATABASE
337	</pre>
338
339	<p>
340	Right now, only the postgres user can run commands. Obviously this is not the
341	sort of setup one would like in a multi-user environment. The next section will
342	look 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>
352	As mentioned earlier, having to login as the postgres user is somewhat
353	undesirable in a mult-user environment. In most cases there will be various
354	users and services accessing the server, and each have different permission
355	requirements. So, to handle this, the <c>createuser</c> command can be used.
356	This command is an alternative to running a few SQL queries, and is a lot more
357	flexible 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>
364	Enter password for new user:
365	Enter it again:	604	Enter it again:
366	Password:	605	postgres=# <i>\q</i>
367	CREATE USER
368	</pre>
369		606
370	<p>	607	<comment>(Change 'trust' to 'password' for the local connection.)</comment>
371	There, 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>
372	that 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>
373	databases. <c>-P</c> let's you enter a password for the user and <c>-E</c> will	610	postgresql-9.0 \| * Reloading PostgreSQL configuration ... [ ok ]
374	encrypt it for security purposes. Now then, we'll test this new user's	611	# <i>rc-update add postgresql-9.0 default</i>
375	permissions out by setting up our standard user:	612	* service postgresql-9.0 added to runlevel default
		613	</pre>
		614
376	</p>	615	<p>
377		616	At this point you are ready to continue on with the official <uri
378	<pre caption="Setting up the standard user">	617	link="http://www.postgresql.org/docs/current/static/tutorial.html">PostgreSQL
379	<comment>(replace chris with the username you've just created)</comment>	618	Tutorial</uri>. The tutorial will guide you through creating roles, databases,
380	$ <i>createuser -A -D -P -E -U chris -W testuser</i>	619	schemata and all that fun and useful stuff.
381	Enter password for new user:
382	Enter it again:
383	Password:
384	CREATE USER
385	</pre>
386
387	<p>
388	Success! 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
390	instead deny the user the ability to create other users and databases. Now that
391	there are users to work with, the next chapter will look at using the new
392	database.
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>
		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	— dev-db/libpq, dev-db/postgresql, dev-db/postgresql-libs, and
		642	dev-db/postgresql-client — to the new ebuilds —
		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>(Check available versions, then select yours)</comment>
		674	# <i>eselect postgresql list</i>
		675	# <i>eselect postgresql set 9.0</i>
		676
		677	<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	</pre>
		696
		697	</body>
		698	</section>
		699	<section id="pre90">
		700	<title>Pre-9.0 Migration: With the New Ebuilds</title>
		701	<body>
		702
		703	<p>
		704	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	</p>
		708
		709	<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
		715	<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
		722	<p>
		723	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	</p>
		728
		729	<p>
		730	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	</p>
		734
		735	<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
		754	<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 && rc-update add postgresql-8.4 default</i>
		758	</pre>
		759
		760	<p>
		761	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	</p>
		764
		765	</body>
		766	</section>
		767	<section id="oldmigration">
		768	<title>Pre-9.0 Migration: From the Obsolete Ebuilds</title>
		769	<body>
		770
		771	<p>
		772	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	</p>
		777
		778	<p>
		779	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	</p>
		784
		785	<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	</pre>
		797
		798	<p>
		799	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	</p>
		803
		804	</body>
		805	</section>
		806	</chapter>
		807
398	<chapter>	808	<chapter>
399	<title>Using PostgreSQL</title>	809	<title>Utilities</title>
400	<section>
401	<title>Setting up permissions</title>
402	<body>
403
404	<p>
405	Now there is a user that can create databases and add other users, and the main
406	postgres user that can do anything. The user created earlier can currently login
407	to the server, and that's about it. In general, users need to be able to insert
408	data and retrieve data, and sometimes any other number of tasks. So, for this
409	new user to be able to do anything, they must be setup with the proper
410	permissions. 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
412	superuser 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>
417	Password:
418	CREATE DATABASE
419	</pre>
420
421	<p>
422	Alright, now we have a new MyDB database, and a testuser that can access it.
423	To test this out, we'll login as the testuser to the new MyDB database. We'll
424	do this with the <c>psql</c> program. This program is what's used to connect to
425	the PostgreSQL database from command line. So connect to the new database like
426	so:
427	</p>
428
429	<pre caption="Logging into the MyDB database as the testuser">
430	$ <i>psql -U testuser -W MyDB</i>
431	Password:
432	Welcome to psql 8.0.4, the PostgreSQL interactive terminal.
433
434	Type: \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
440	MyDB=>
441	</pre>
442
443	<p>
444	So, the testuser is now logged into the database, and can begin to initiate
445	some commands. To get a feel for using PostgreSQL, the next section will take a
446	look at some of the basic commands in navigating the <c>psql</c> client.
447	</p>
448
449	</body>
450	</section>	810	<section>
		811	<title>pgAdmin III</title>
		812	<body>
		813
		814	<p>
		815	<uri link="http://www.pgadmin.org/">pgAdmin III</uri> is a graphical utility
		816	for managing PostgreSQL.
		817	</p>
		818
		819	</body>
451	<section>	820	</section>
452	<title>Basic PostgreSQL commands and creating a table</title>	821	</chapter>
453	<body>
454		822
455	<p>	823	<chapter>
456	For those who are used to MySQL, this is somewhat of a definite read. This is	824	<title>Troubleshooting</title>
457	where PostgreSQL may get somewhat unique with regards to running commands. To
458	start, 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>
503	With the exception of <c>\c[onnect]</c>, all the commands shown will be used
504	later on in the section. So right now the database is empty. That said, we need
505	to insert some data. The first step to inserting data, however, is to put it in
506	a table. Right now there are no tables in the database, so we need to create
507	one. This is done with the <c>CREATE TABLE</c> command. We'll make a table of
508	items. They will contain a Product ID, Description, and price:
509	</p>
510
511	<pre caption="Creating the products table">
512	MyDB=> CREATE TABLE products (
513	MyDB(> product_id SERIAL,
514	MyDB(> description TEXT,
515	MyDB(> price DECIMAL
516	MyDB(> );
517	NOTICE: CREATE TABLE will create implicit sequence "products_product_id_seq"
518	for serial column "products.product_id"
519	CREATE TABLE
520	</pre>
521
522	<p>
523	You can ignore the NOTICE, it's perfectly harmless. Looking at the last line of
524	the function, <c>CREATE TABLE</c> seems to indicate that the command has
525	succeeded. However, let's go ahead and verify that the table was indeed
526	successfully created with the <c>\d</c> command:
527	</p>
528
529	<pre caption="Looking at the newly created table">
530	MyDB=> <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>
540	Indeed the table was successfully created. Now that the table is created, it
541	needs to be populated with data. The next section will look at populating the
542	database with data.
543	</p>
544
545	</body>
546	</section>	825	<section>
547	<section>	826	<title>Server Lacks Instrumentation Functions</title>
548	<title>Inserting data into the database</title>
549	<body>
550
551	<p>
552	This section will look at the two ways of populating the newly created table
553	with data. First let's look at the most basic command, <c>INSERT</c>:
554	</p>
555
556	<pre caption="INSERT syntax">
557	INSERT 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
563	values into. VALUES(value1,value2,value3) is the listing of values. The values
564	are inserted into the same order as the columns (column1 gets value1, column2
565	gets value2, column3 gets value3). These counts <e>must</e> be the same. So
566	let's go ahead and insert an item into the table:
567	</p>
568
569	<impo>
570	From 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
572	using <c>INSERT INTO</c> without specifying columns. This is unproductive, as
573	if a new column gets added to the database, it will cause in error if the value
574	to column count is not the same. You should <e>always</e> specify the columns
575	unless you're 300% sure you'll never add a column.
576	</impo>
577
578	<pre caption="Inserting data into the table">
579	MyDB=> <i>INSERT INTO products (description,price) VALUES('A test product', 12.00);</i>
580	INSERT 17273 1
581	</pre>
582
583	<p>
584	The last line needs a bit of explaining. The return of an insert command is an
585	OID (Object Identifier) and the number of rows inserted. OID's are a bit beyond
586	the scope of this guide, and the <uri
587	link="http://www.postgresql.org/docs/8.1/static/datatype-oid.html">PostgreSQL
588	manual</uri> has some good information on it. Now, for a situation where you
589	have 20,000 products, these insert statements can be a little tedious. However,
590	not all is lost. The <c>COPY</c> command can be used to insert data into a
591	table 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
593	price. The file looks like this:
594	</p>
595
596	<pre caption="products.csv">
597	2,meat,6.79
598	3,soup,0.69
599	4,soda,1.79
600	</pre>
601
602	<p>
603	Now we'll use the <c>COPY</c> command to populate our data:
604	</p>
605
606	<impo>
607	The <c>COPY FROM STDIN</c> command is used because only the postgres user can
608	insert data from a file (for obvious security reasons).
609	</impo>
610
611	<pre caption="Using COPY to populate the products table">
612	MyDB=> <i>COPY products FROM STDIN WITH DELIMITER AS ',';</i>
613	Enter data to be copied followed by a newline.
614	End 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>
622	Unfortunately, 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
624	section will look at running queries to check our data.
625	</p>
626
627	</body>	827	<body>
628	</section>
629	<section>
630	<title>Using PostgreSQL queries</title>
631	<body>
632		828
633	<p>
634	This section will look at using the <c>SELECT</c> statement to view data in our
635	tables. The basic <c>SELECT</c> format looks like this:
636	</p>	829	<p>
637		830	This problem is easy to solve, with the solution depending on the version you
638	<pre caption="SELECT syntax">	831	are using. What is difficult about it is finding the answer. What is required is
639	SELECT (column1,column2\|*) FROM (table) [WHERE (conditionals)]	832	an import from a file that already exists on the storage drive:
640	</pre>	833	<path>adminpack.sql</path>. To resolve this issue, run the command appropriate
641		834	to the version you have:
642	<p>	835	</p>
643	There are two ways to select columns. The first is using <c>*</c> to select all	836
644	columns, and the second is to specify a list of specific columns you wish to	837	<pre caption="Add instrumentation functions for versions less than 9.1">
645	see. The second is quite handy when you want to find a specific column in a	838	# <i>psql -U postgres --file /usr/share/postgresql-9.0/contrib/adminpack.sql</i>
646	rather large list of them. Let's start out with using <c>SELECT</c> with
647	<c>*</c> to specify all columns:
648	</p>	839	</pre>
649		840
650	<pre caption="Viewing the products table">	841	<pre caption="Add instrumentation functions for version 9.1 and up">
651	MyDB=> <i>SELECT * FROM products;</i>	842	# <i>psql -U postgres -c "CREATE EXTENSION adminpack;"</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>
662	As shown here, all the data we inserted earlier is indeed in the table. Now
663	let's say we only want to see the description and the price, and don't care
664	about the product id. In this case we'll use the column specific SELECT form:
665	</p>	843	</pre>
666
667	<pre caption="Viewing specific columns from the products table">
668	MyDB=> <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>
679	Now only the product and price is shown, letting us focus on only the important
680	data. 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">
685	MyDB=> <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>
694	Now a listing of products over $2.00 is displayed, focusing the data even more.
695	These forms of querying for information are very powerful, and can help create
696	extremely useful reports.
697	</p>
698
699	</body>
700	</section>
701	<section>
702	<title>Conclusion</title>
703	<body>
704
705	<p>
706	This concludes the PostgreSQL Guide. A big thanks goes to Masatomo Nakano, the
707	previous Gentoo PostgreSQL maintainer for his help in answering my questions.
708	Any 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		844
713	</body>	845	</body>
714	</section>	846	</section>
715	</chapter>	847	</chapter>
716	</guide>	848	</guide>

 Legend:



Removed from v.1.5
 


changed lines


 
Added in v.1.11
 Legend:



Removed from v.1.5
 


changed lines


 
Added in v.1.11
-Removed from v.1.5
+Added in v.1.11

	ViewVC Help
Powered by ViewVC 1.1.13