Skip to content

Commit cef2cc5

Browse files
tglsfdctglsfdc
committed
Some small docs improvements motivated by reading the comments for the
7.4 interactive docs.
1 parent 3b5152c commit cef2cc5

File tree

4 files changed

+127
-26
lines changed

4 files changed

+127
-26
lines changed

‎doc/src/sgml/ddl.sgml

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.35 2004/12/23 05:37:39 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.36 2005/01/08 01:44:05 tgl Exp $ -->
22

33
<chapter id="ddl">
44
<title>Data Definition</title>
@@ -395,7 +395,28 @@ CREATE TABLE products (
395395
evaluated whenever the default value is inserted
396396
(<emphasis>not</emphasis> when the table is created). A common example
397397
is that a timestamp column may have a default of <literal>now()</>,
398-
so that it gets set to the time of row insertion.
398+
so that it gets set to the time of row insertion. Another common
399+
example is generating a <quote>serial number</> for each row.
400+
In <productname>PostgreSQL</productname> this is typically done by
401+
something like
402+
<programlisting>
403+
CREATE TABLE products (
404+
product_no integer <emphasis>DEFAULT nextval('products_product_no_seq')</emphasis>,
405+
...
406+
);
407+
</programlisting>
408+
where the <literal>nextval()</> function supplies successive values
409+
from a <firstterm>sequence object</> (see <xref
410+
linkend="functions-sequence">). This arrangement is sufficiently common
411+
that there's a special shorthand for it:
412+
<programlisting>
413+
CREATE TABLE products (
414+
product_no <emphasis>SERIAL</emphasis>,
415+
...
416+
);
417+
</programlisting>
418+
The <literal>SERIAL</> shorthand is discussed further in <xref
419+
linkend="datatype-serial">.
399420
</para>
400421
</sect1>
401422

@@ -1138,6 +1159,12 @@ WHERE c.altitude &gt; 500 and c.tableoid = p.oid;
11381159

11391160
</para>
11401161

1162+
<para>
1163+
A table can inherit from more than one parent table, in which case it has
1164+
the union of the columns defined by the parent tables (plus any columns
1165+
declared specifically for the child table).
1166+
</para>
1167+
11411168
<para>
11421169
A serious limitation of the inheritance feature is that indexes (including
11431170
unique constraints) and foreign key constraints only apply to single

‎doc/src/sgml/history.sgml

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/history.sgml,v 1.23 2003/11/29 19:51:37 pgsql Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/history.sgml,v 1.24 2005/01/08 01:44:05 tgl Exp $
33
-->
44

55
<sect1 id="history">
@@ -128,10 +128,11 @@ $PostgreSQL: pgsql/doc/src/sgml/history.sgml,v 1.23 2003/11/29 19:51:37 pgsql Ex
128128

129129
<listitem>
130130
<para>
131-
In addition to the monitor program, a new program
131+
A new program
132132
(<application>psql</application>) was provided for interactive
133133
SQL queries, which used <acronym>GNU</acronym>
134-
<application>Readline</application>.
134+
<application>Readline</application>. This largely superseded
135+
the old <application>monitor</> program.
135136
</para>
136137
</listitem>
137138

‎doc/src/sgml/query.sgml

Lines changed: 67 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/query.sgml,v 1.41 2004/12/17 04:50:32 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/query.sgml,v 1.42 2005/01/08 01:44:08 tgl Exp $
33
-->
44

55
<chapter id="tutorial-sql">
@@ -293,14 +293,19 @@ COPY weather FROM '/home/user/weather.txt';
293293
<programlisting>
294294
SELECT * FROM weather;
295295
</programlisting>
296-
(here <literal>*</literal> means <quote>all columns</quote>).
296+
Here <literal>*</literal> is a shorthand for <quote>all columns</quote>.
297297
<footnote>
298298
<para>
299299
While <literal>SELECT *</literal> is useful for off-the-cuff
300300
queries, it is widely considered bad style in production code,
301301
since adding a column to the table would change the results.
302302
</para>
303303
</footnote>
304+
So the same result would be had with:
305+
<programlisting>
306+
SELECT city, temp_lo, temp_hi, prcp, date FROM weather;
307+
</programlisting>
308+
304309
The output should be:
305310

306311
<screen>
@@ -314,8 +319,8 @@ SELECT * FROM weather;
314319
</para>
315320

316321
<para>
317-
You may specify any arbitrary expressions in the select list. For
318-
example, you can do:
322+
You can write expressions, not just simple column references, in the
323+
select list. For example, you can do:
319324
<programlisting>
320325
SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
321326
</programlisting>
@@ -333,15 +338,18 @@ SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
333338
</para>
334339

335340
<para>
336-
Arbitrary Boolean operators (<literal>AND</literal>,
341+
A query can be <quote>qualified</> by adding a <literal>WHERE</>
342+
clause that specifies which rows are wanted. The <literal>WHERE</>
343+
clause contains a Boolean (truth value) expression, and only rows for
344+
which the Boolean expression is true are returned. The usual
345+
Boolean operators (<literal>AND</literal>,
337346
<literal>OR</literal>, and <literal>NOT</literal>) are allowed in
338-
the qualification of a query. For example, the following
347+
the qualification. For example, the following
339348
retrieves the weather of San Francisco on rainy days:
340349

341350
<programlisting>
342351
SELECT * FROM weather
343-
WHERE city = 'San Francisco'
344-
AND prcp > 0.0;
352+
WHERE city = 'San Francisco' AND prcp &gt; 0.0;
345353
</programlisting>
346354
Result:
347355
<screen>
@@ -354,16 +362,43 @@ SELECT * FROM weather
354362

355363
<para>
356364
<indexterm><primary>ORDER BY</primary></indexterm>
365+
366+
You can request that the results of a query
367+
be returned in sorted order:
368+
369+
<programlisting>
370+
SELECT * FROM weather
371+
ORDER BY city;
372+
</programlisting>
373+
374+
<screen>
375+
city | temp_lo | temp_hi | prcp | date
376+
---------------+---------+---------+------+------------
377+
Hayward | 37 | 54 | | 1994-11-29
378+
San Francisco | 43 | 57 | 0 | 1994-11-29
379+
San Francisco | 46 | 50 | 0.25 | 1994-11-27
380+
</screen>
381+
382+
In this example, the sort order isn't fully specified, and so you
383+
might get the San Francisco rows in either order. But you'd always
384+
get the results shown above if you do
385+
386+
<programlisting>
387+
SELECT * FROM weather
388+
ORDER BY city, temp_lo;
389+
</programlisting>
390+
</para>
391+
392+
<para>
357393
<indexterm><primary>DISTINCT</primary></indexterm>
358394
<indexterm><primary>duplicate</primary></indexterm>
359395

360-
As a final note, you can request that the results of a query can
361-
be returned in sorted order or with duplicate rows removed:
396+
You can request that duplicate rows be removed from the result of
397+
a query:
362398

363399
<programlisting>
364400
SELECT DISTINCT city
365-
FROM weather
366-
ORDER BY city;
401+
FROM weather;
367402
</programlisting>
368403

369404
<screen>
@@ -374,8 +409,26 @@ SELECT DISTINCT city
374409
(2 rows)
375410
</screen>
376411

377-
<literal>DISTINCT</literal> and <literal>ORDER BY</literal> can be
378-
used separately, of course.
412+
Here again, the result row ordering might vary.
413+
You can ensure consistent results by using <literal>DISTINCT</literal> and
414+
<literal>ORDER BY</literal> together:
415+
<footnote>
416+
<para>
417+
In some database systems, including older versions of
418+
<productname>PostgreSQL</productname>, the implementation of
419+
<literal>DISTINCT</literal> automatically orders the rows and
420+
so <literal>ORDER BY</literal> is redundant. But this is not
421+
required by the SQL standard, and current
422+
<productname>PostgreSQL</productname> doesn't guarantee that
423+
<literal>DISTINCT</literal> causes the rows to be ordered.
424+
</para>
425+
</footnote>
426+
427+
<programlisting>
428+
SELECT DISTINCT city
429+
FROM weather
430+
ORDER BY city;
431+
</programlisting>
379432
</para>
380433
</sect1>
381434

‎doc/src/sgml/start.sgml

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/start.sgml,v 1.37 2004/12/17 04:50:32 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/start.sgml,v 1.38 2005/01/08 01:44:08 tgl Exp $
33
-->
44

55
<chapter id="tutorial-start">
@@ -146,7 +146,7 @@ $PostgreSQL: pgsql/doc/src/sgml/start.sgml,v 1.37 2004/12/17 04:50:32 tgl Exp $
146146
<para>
147147
Possibly, your site administrator has already created a database
148148
for your use. He should have told you what the name of your
149-
database is. In this case you can omit this step and skip ahead
149+
database is. In that case you can omit this step and skip ahead
150150
to the next section.
151151
</para>
152152

@@ -194,8 +194,28 @@ No such file or directory
194194
</para>
195195

196196
<para>
197-
If you do not have the privileges required to create a database,
198-
you will see the following:
197+
Another response could be this:
198+
<screen>
199+
createdb: could not connect to database template1: FATAL: user "joe" does not
200+
exist
201+
</screen>
202+
where your own login name is mentioned. This will happen if the
203+
administrator has not created a <productname>PostgreSQL</> user account
204+
for you. (<productname>PostgreSQL</> user accounts are distinct from
205+
operating system user accounts.) If you are the administrator, see
206+
<xref linkend="user-manag"> for help creating accounts. You will need to
207+
become the operating system user under which <productname>PostgreSQL</>
208+
was installed (usually <literal>postgres</>) to create the first user
209+
account. It could also be that you were assigned a
210+
<productname>PostgreSQL</> user name that is different from your
211+
operating system user name; in that case you need to use the <option>-U</>
212+
switch or set the <envar>PGUSER</> environment variable to specify your
213+
<productname>PostgreSQL</> user name.
214+
</para>
215+
216+
<para>
217+
If you have a user account but it does not have the privileges required to
218+
create a database, you will see the following:
199219
<screen>
200220
createdb: database creation failed: ERROR: permission denied to create database
201221
</screen>
@@ -340,10 +360,10 @@ mydb=#
340360
</para>
341361

342362
<para>
343-
If you have encountered problems starting <command>psql</command>
363+
If you encounter problems starting <command>psql</command>
344364
then go back to the previous section. The diagnostics of
345-
<command>psql</command> and <command>createdb</command> are
346-
similar, and if the latter worked the former should work as well.
365+
<command>createdb</command> and <command>psql</command> are
366+
similar, and if the former worked the latter should work as well.
347367
</para>
348368

349369
<para>

0 commit comments

Comments
 (0)