mirror of https://github.com/postgres/postgres
Add reference pages for utilities and remove standalone chapters for same. Add material for an appendix on date/time properties, but not yet integrated with the User's Guide. Break up the former chapter on pg_options into Admin and Programmer's Guides.REL6_5_PATCHES
Thomas G. Lockhart
27 years ago
parent
c3a4d8ed54
commit
32cfa65e49
@ -0,0 +1,155 @@ |
||||
From - Mon May 10 15:59:27 1999 |
||||
Received: from localhost (lockhart@localhost [127.0.0.1]) |
||||
by localhost (8.8.7/8.8.7) with ESMTP id PAA24871 |
||||
for <lockhart@localhost>; Wed, 14 Apr 1999 15:45:24 GMT |
||||
Received: from apop-server.alumni.caltech.edu |
||||
by localhost with POP3 (fetchmail-4.7.9) |
||||
for lockhart@localhost (single-drop); Wed, 14 Apr 1999 15:45:26 +0000 (UTC) |
||||
Received: from bologna.nettuno.it (bologna.nettuno.it [193.43.2.1]) |
||||
by alumnus.caltech.edu (8.9.1/8.9.1) with ESMTP id IAA18386 |
||||
for <lockhart@alumni.caltech.edu>; Wed, 14 Apr 1999 08:41:45 -0700 (PDT) |
||||
Received: from proxy.sferacarta.com (mail@sfcabop1.nettuno.it [193.207.10.213]) |
||||
by bologna.nettuno.it (8.8.6/8.8.6/NETTuno 3.1) with ESMTP id RAA15888; |
||||
Wed, 14 Apr 1999 17:41:33 +0200 (MDT) |
||||
Received: from rosso.sferacarta.com (sferacarta.com) [10.20.30.5] |
||||
by proxy.sferacarta.com with esmtp (Exim 2.05 #1 (Debian)) |
||||
id 10XTfQ-00083Z-00; Wed, 14 Apr 1999 17:41:40 +0000 |
||||
Message-ID: <3714B6B6.F745D41D@sferacarta.com> |
||||
Date: Wed, 14 Apr 1999 17:39:34 +0200 |
||||
From: José Soares <jose@sferacarta.com> |
||||
X-Mailer: Mozilla 4.5 [it] (Win95; I) |
||||
X-Accept-Language: it |
||||
MIME-Version: 1.0 |
||||
To: Thomas Lockhart <lockhart@alumni.caltech.edu> |
||||
CC: hackers <pgsql-hackers@postgresql.org>, |
||||
general <pgsql-general@postgresql.org> |
||||
Subject: Re: [GENERAL] Re: [HACKERS] Gregorian Calendar |
||||
References: <3711B1E5.80213DF6@sferacarta.com> <37135951.88FDB948@alumni.caltech.edu> |
||||
Content-Transfer-Encoding: 8bit |
||||
Content-Type: text/plain; charset=iso-8859-1 |
||||
X-UIDL: 25f0580d2a532247ac6af3aee9737b7c |
||||
X-Mozilla-Status: 8011 |
||||
X-Mozilla-Status2: 00000000 |
||||
|
||||
Hi Thomas, |
||||
|
||||
Thomas Lockhart ha scritto: |
||||
|
||||
> > I have a question about dates. |
||||
> > The Gregorian reform of calendar skiped 10 days on Oct, 1582. |
||||
> > This reform was accepted by Great Britain and Dominions (including |
||||
> > what is now the USA) only in 1752. |
||||
> > If I insert a date that doesn't exist PostgreSQL accepts it. |
||||
> > Should it be considered normal ? |
||||
> |
||||
> As Peter says, this is tricky. |
||||
> |
||||
> Date conventions before the 19th century make for interesting reading, |
||||
> but are not imho consistant enough to warrant coding into a date/time |
||||
> handler. |
||||
> |
||||
> As you probably have noticed, we use Julian date calculations for our |
||||
> date/time support. |
||||
|
||||
I suppose you refer to Julian Day invented by the French scholar |
||||
Joseph Justus Scaliger (1540-1609) |
||||
that probably takes its name from the Scaliger's father, |
||||
the Italian scholar Julius Caesar Scaliger (1484-1558). |
||||
Astronomers have used the Julian period to assign a unique number to |
||||
every day since 1 January 4713 BC. This is the so-called Julian Day |
||||
(JD). JD 0 designates the 24 hours from noon UTC on 1 January 4713 BC |
||||
to noon UTC on 2 January 4713 BC. |
||||
|
||||
Julian Day is different from Julian Date |
||||
|
||||
The Julian calendar was introduced by Julius Caesar in 45 BC. It was |
||||
in common use until the 1582, when countries started changing to the |
||||
Gregorian calendar. |
||||
|
||||
In the Julian calendar, the tropical year is approximated as 365 1/4 |
||||
days = 365.25 days. This gives an error of 1 day in approximately 128 |
||||
|
||||
and this is why pope Gregory XIII in accordance with instructions |
||||
from the Council of Trent reformed the calendar to correct this error. |
||||
|
||||
In the Gregorian calendar, the tropical year is approximated as |
||||
365 + 97 / 400 days = 365.2425 days. Thus it takes approximately 3300 |
||||
years for the tropical year to shift one day with respect to the |
||||
Gregorian calendar. |
||||
|
||||
The approximation 365+97/400 is achieved by having 97 leap years |
||||
every 400 years. |
||||
|
||||
The Gregorian calendar has 97 leap years every 400 years: |
||||
|
||||
Every year divisible by 4 is a leap year. |
||||
However, every year divisible by 100 is not a leap year. |
||||
However, every year divisible by 400 is a leap year after all. |
||||
|
||||
So, 1700, 1800, 1900, 2100, and 2200 are not leap years. But 1600, |
||||
2000, and 2400 are leap years. |
||||
|
||||
instead in the Julian calendar only years divisible by 4 are leap years. |
||||
|
||||
The papal bull of February 1582 decreed that 10 days should be dropped |
||||
from October 1582 so that 15 October should follow immediately after |
||||
4 October. |
||||
This was observed in Italy, Poland, Portugal, and Spain. Other Catholic |
||||
countries followed shortly after, but Protestant countries were |
||||
reluctant to change, and the Greek orthodox countries didn't change |
||||
until the start of this century. |
||||
|
||||
The reform was observed by Great Britain and Dominions (including what is |
||||
now the USA) |
||||
in 1752. |
||||
The 2 Sep 1752 was followed by 14 Sep 1752. |
||||
|
||||
This is why unix has the cal 9 1752 like this: |
||||
September 1752 |
||||
S M Tu W Th F S |
||||
1 2 14 15 16 |
||||
17 18 19 20 21 22 23 |
||||
24 25 26 27 28 29 30 |
||||
|
||||
My question is: |
||||
^^^^^^^^^^^^ |
||||
|
||||
If SQL92 says: |
||||
|
||||
(Second Informal Review Draft) ISO/IEC 9075:1992, Database |
||||
Language SQL- July 30, 1992 |
||||
|
||||
5.3 literals |
||||
22)Within the definition of a <datetime literal>, the <datetime |
||||
value>s are constrained by the natural rules for dates and |
||||
times |
||||
according to the Gregorian calendar. |
||||
^^^^^^^^^^^^^^^ |
||||
|
||||
Dates between 1752-09-03 and 1752-09-13. |
||||
Are they valid dates? |
||||
^^^^^^^^^^^^^^^^ |
||||
|
||||
> They have the nice property of correctly |
||||
> predicting/calculating any date more recent than something like 4013BC |
||||
> to far into the future, using the assumption that the length of the |
||||
> year is 365.25 days. This is a very recently adopted convention |
||||
> (sometime in the 1800s I had thought, but perhaps it was during the |
||||
> same "reform" in 1752). |
||||
> |
||||
> I've toyed with the idea of implementing a Chinese dynastic calendar, |
||||
> since it seems to be more predictable than historical European |
||||
> calendars. |
||||
|
||||
People's Republic of China uses the Gregorian calendar |
||||
for civil purposes. Chinese calendar is used for determining |
||||
festivals. |
||||
|
||||
The beginnings of the Chinese calendar can be traced back to the 14th |
||||
century BC. Legend has it that the Emperor Huangdi invented the |
||||
calendar in 2637 B |
||||
|
||||
José |
||||
|
||||
|
||||
|
||||
@ -0,0 +1,78 @@ |
||||
<chapter id="layout"> |
||||
<Title>System Layout</Title> |
||||
|
||||
<Para> |
||||
<Figure Id="ADMIN-LAYOUT"> |
||||
<Title><ProductName>Postgres</ProductName> file layout</Title> |
||||
<Graphic Align="center" FileRef="layout.gif" Format="GIF"></Graphic> |
||||
</Figure> |
||||
|
||||
<XRef LinkEnd="ADMIN-LAYOUT" EndTerm="ADMIN-LAYOUT"> |
||||
shows how the <ProductName>Postgres</ProductName> distribution is laid |
||||
out when installed in the default way. For simplicity, |
||||
we will assume that <ProductName>Postgres</ProductName> |
||||
has been installed in the |
||||
directory <filename>/usr/local/pgsql</filename>. Therefore, wherever |
||||
you see the directory <filename>/usr/local/pgsql</filename> you should |
||||
substitute the name of the directory where |
||||
<ProductName>Postgres</ProductName> is |
||||
actually installed. |
||||
All <ProductName>Postgres</ProductName> commands are installed |
||||
in the directory |
||||
<filename>/usr/local/pgsql/bin</filename>. Therefore, you should add |
||||
this directory to your shell command path. If you use |
||||
a variant of the Berkeley C shell, such as csh or tcsh, |
||||
you would add |
||||
<ProgramListing> |
||||
set path = ( /usr/local/pgsql/bin path ) |
||||
</ProgramListing> |
||||
in the .login file in your home directory. If you use |
||||
a variant of the Bourne shell, such as sh, ksh, or |
||||
bash, then you would add |
||||
<ProgramListing> |
||||
PATH=/usr/local/pgsql/bin:$PATH |
||||
export PATH |
||||
</ProgramListing> |
||||
to the .profile file in your home directory. |
||||
From now on, we will assume that you have added the |
||||
<ProductName>Postgres</ProductName> bin directory to your path. |
||||
In addition, we |
||||
will make frequent reference to "setting a shell |
||||
variable" or "setting an environment variable" throughout |
||||
this document. If you did not fully understand the |
||||
last paragraph on modifying your search path, you |
||||
should consult the UNIX manual pages that describe your |
||||
shell before going any further. |
||||
</Para> |
||||
|
||||
<Para> |
||||
If you have not set things up in the |
||||
default way, you may have some more work to do. |
||||
For example, if the database server machine is a remote machine, you |
||||
will need to set the <envar>PGHOST</envar> environment variable to the name |
||||
of the database server machine. The environment variable |
||||
<envar>PGPORT</envar> may also have to be set. The bottom line is this: if |
||||
you try to start an application program and it complains |
||||
that it cannot connect to the <Application>postmaster</Application>, |
||||
you must go back and make sure that your |
||||
environment is properly set up. |
||||
</Para> |
||||
|
||||
</Chapter> |
||||
|
||||
<!-- Keep this comment at the end of the file |
||||
Local variables: |
||||
mode: sgml |
||||
sgml-omittag:nil |
||||
sgml-shorttag:t |
||||
sgml-minimize-attributes:nil |
||||
sgml-always-quote-attributes:t |
||||
sgml-indent-step:1 |
||||
sgml-indent-data:t |
||||
sgml-parent-document:nil |
||||
sgml-default-dtd-file:"./reference.ced" |
||||
sgml-exposed-tags:nil |
||||
sgml-local-catalogs:"/usr/lib/sgml/CATALOG" |
||||
sgml-local-ecat-files:nil |
||||
End: |
||||
--> |
||||
@ -1,8 +0,0 @@ |
||||
<Chapter Id="pgaccess"> |
||||
<Title><Command>pgaccess</Command></Title> |
||||
|
||||
<Para> |
||||
This section needs to be written. Volunteers? |
||||
</Para> |
||||
|
||||
</Chapter> |
||||
@ -1,45 +0,0 @@ |
||||
<Chapter Id="psql"> |
||||
<Title><Command>psql</Command></Title> |
||||
|
||||
<Para> |
||||
This section needs to be converted from the original psql man page. Volunteers? |
||||
</Para> |
||||
|
||||
<Tip> |
||||
<Para> |
||||
To change the paging behavior of your results, set/unset your PAGER environment variable. |
||||
</Para> |
||||
</Tip> |
||||
|
||||
<Sect1> |
||||
<Title>Paging To Screen</Title> |
||||
|
||||
<Note> |
||||
<Title>Author</Title> |
||||
<Para> |
||||
From Brett McCormick on the mailing list 1998-04-04. |
||||
</Para> |
||||
</Note> |
||||
|
||||
<Para> |
||||
To affect the paging behavior of your <Command>psql</Command> output, |
||||
set or unset your PAGER environment variable. I always have to set mine |
||||
before it will pause. And of course you have to do this before |
||||
starting the program. |
||||
</para> |
||||
|
||||
<Para> |
||||
In csh/tcsh or other C shells: |
||||
|
||||
<ProgramListing> |
||||
unsetenv PAGER |
||||
</ProgramListing> |
||||
|
||||
while in sh/bash or other Bourne shells: |
||||
|
||||
<ProgramListing> |
||||
unset PAGER |
||||
</ProgramListing> |
||||
</para> |
||||
</sect1> |
||||
</Chapter> |
||||
@ -1,363 +0,0 @@ |
||||
<Chapter Id="query-ug"> |
||||
<TITLE>The Query Language</TITLE> |
||||
|
||||
<Para> |
||||
<Note> |
||||
<Para> |
||||
This chapter must go into depth on each area of the query language. |
||||
Currently a copy of the tutorial. |
||||
- thomas 1998-01-12 |
||||
</Para> |
||||
</Note> |
||||
</Para> |
||||
|
||||
<Para> |
||||
The <ProductName>Postgres</ProductName> query language is a variant of |
||||
<Acronym>SQL3</Acronym>. It |
||||
has many extensions such as an extensible type system, |
||||
inheritance, functions and production rules. Those are |
||||
features carried over from the original <ProductName>Postgres</ProductName> |
||||
query |
||||
language, <ProductName>PostQuel</ProductName>. |
||||
This section provides an overview |
||||
of how to use <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> |
||||
to perform simple operations. |
||||
This manual is only intended to give you an idea of our |
||||
flavor of <Acronym>SQL</Acronym> and is in no way a complete tutorial on |
||||
<Acronym>SQL</Acronym>. Numerous books have been written on <Acronym>SQL</Acronym>. For |
||||
instance, consult <xref linkend="MELT93" endterm="MELT93-full"> or |
||||
<xref linkend="DATE97" endterm="DATE97-full">. You should also |
||||
be aware that some features of <ProductName>Postgres</ProductName> |
||||
are not part of the <Acronym>ANSI</Acronym> standard. |
||||
</Para> |
||||
|
||||
<Sect1> |
||||
<Title>Concepts</Title> |
||||
|
||||
<Para> |
||||
The fundamental notion in <ProductName>Postgres</ProductName> |
||||
is that of a class, |
||||
which is a named collection of object instances. Each |
||||
instance has the same collection of named attributes, |
||||
and each attribute is of a specific type. Furthermore, |
||||
each instance has a permanent <FirstTerm>object |
||||
identifier</FirstTerm> (<Acronym>OID</Acronym>) |
||||
that is unique throughout the installation. Because |
||||
<Acronym>SQL</Acronym> syntax refers to tables, we will use the terms |
||||
<FirstTerm>table</FirstTerm> and <FirstTerm>class</FirstTerm> interchangeably. |
||||
Likewise, an <Acronym>SQL</Acronym> <FirstTerm>row</FirstTerm> is an |
||||
<FirstTerm>instance</FirstTerm> and <Acronym>SQL</Acronym> |
||||
<FirstTerm>columns</FirstTerm> |
||||
are <FirstTerm>attributes</FirstTerm>. |
||||
As previously discussed, classes are grouped into |
||||
databases, and a collection of databases managed by a |
||||
single <FileName>postmaster</FileName> process constitutes an installation |
||||
or site. |
||||
</Para> |
||||
</sect1> |
||||
|
||||
<Sect1> |
||||
<Title>Creating a New Class</Title> |
||||
|
||||
<Para> |
||||
You can create a new class by specifying the class |
||||
name, along with all attribute names and their types: |
||||
|
||||
<ProgramListing> |
||||
CREATE TABLE weather ( |
||||
city varchar(80), |
||||
temp_lo int, -- low temperature |
||||
temp_hi int, -- high temperature |
||||
prcp real, -- precipitation |
||||
date date |
||||
); |
||||
</ProgramListing> |
||||
</para> |
||||
|
||||
<Para> |
||||
Note that keywords are case-insensitive and identifiers |
||||
are usually case-insensitive. |
||||
<Acronym>Postgres</Acronym> allows <Acronym>SQL92</Acronym> <FirstTerm>delimited identifiers</FirstTerm> |
||||
(identifiers surrounded by double-quotes) to include mixed-case and spaces, tabs, etc. |
||||
</para> |
||||
|
||||
<Para> |
||||
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> supports the usual |
||||
<Acronym>SQL</Acronym> types <Type>int</Type>, |
||||
<Type>float</Type>, <Type>real</Type>, <Type>smallint</Type>, <Type>char(N)</Type>, |
||||
<Type>varchar(N)</Type>, <Type>date</Type>, <Type>time</Type>, |
||||
and <Type>timestamp</Type>, as well as other types of general utility and |
||||
a rich set of geometric types. As we will |
||||
see later, <ProductName>Postgres</ProductName> can be customized with an |
||||
arbitrary number of |
||||
user-defined data types. Consequently, type names are |
||||
not syntactical keywords, except where required to support special cases in the <Acronym>SQL92</Acronym> standard. |
||||
So far, the <ProductName>Postgres</ProductName> create command looks exactly like |
||||
the command used to create a table in a traditional |
||||
relational system. However, we will presently see that |
||||
classes have properties that are extensions of the |
||||
relational model. |
||||
</Para> |
||||
</sect1> |
||||
|
||||
<Sect1> |
||||
<Title>Populating a Class with Instances</Title> |
||||
|
||||
<Para> |
||||
The <Command>insert</Command> statement is used to populate a class with |
||||
instances: |
||||
|
||||
<ProgramListing> |
||||
INSERT INTO weather |
||||
VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994') |
||||
</ProgramListing> |
||||
</para> |
||||
|
||||
<Para> |
||||
You can also use the <Command>copy</Command> command to perform load large |
||||
amounts of data from flat (<Acronym>ASCII</Acronym>) files. |
||||
This is usually faster because the data is read (or written) as a single atomic |
||||
transaction directly to or from the target table. An example would be: |
||||
|
||||
<ProgramListing> |
||||
COPY INTO weather FROM '/home/user/weather.txt' |
||||
USING DELIMITERS '|'; |
||||
</ProgramListing> |
||||
|
||||
where the path name for the source file must be available to the backend server |
||||
machine, not just the client. |
||||
</para> |
||||
</sect1> |
||||
|
||||
<Sect1> |
||||
<Title>Querying a Class</Title> |
||||
|
||||
<Para> |
||||
The weather class can be queried with normal relational |
||||
selection and projection queries. A <Acronym>SQL</Acronym> <Command>select</Command> |
||||
statement is used to do this. The statement is divided into |
||||
a target list (the part that lists the attributes to be |
||||
returned) and a qualification (the part that specifies |
||||
any restrictions). For example, to retrieve all the |
||||
rows of weather, type: |
||||
<ProgramListing> |
||||
SELECT * FROM WEATHER; |
||||
</ProgramListing> |
||||
|
||||
and the output should be: |
||||
<ProgramListing> |
||||
+--------------+---------+---------+------+------------+ |
||||
|city | temp_lo | temp_hi | prcp | date | |
||||
+--------------+---------+---------+------+------------+ |
||||
|San Francisco | 46 | 50 | 0.25 | 11-27-1994 | |
||||
+--------------+---------+---------+------+------------+ |
||||
|San Francisco | 43 | 57 | 0 | 11-29-1994 | |
||||
+--------------+---------+---------+------+------------+ |
||||
|Hayward | 37 | 54 | | 11-29-1994 | |
||||
+--------------+---------+---------+------+------------+ |
||||
</ProgramListing> |
||||
You may specify any arbitrary expressions in the target list. For example, you can do: |
||||
<ProgramListing> |
||||
SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather; |
||||
</ProgramListing> |
||||
</para> |
||||
|
||||
<Para> |
||||
Arbitrary Boolean operators |
||||
(<Command>and</Command>, <Command>or</Command> and <Command>not</Command>) are |
||||
allowed in the qualification of any query. For example, |
||||
|
||||
<ProgramListing> |
||||
SELECT * FROM weather |
||||
WHERE city = 'San Francisco' |
||||
AND prcp > 0.0; |
||||
|
||||
+--------------+---------+---------+------+------------+ |
||||
|city | temp_lo | temp_hi | prcp | date | |
||||
+--------------+---------+---------+------+------------+ |
||||
|San Francisco | 46 | 50 | 0.25 | 11-27-1994 | |
||||
+--------------+---------+---------+------+------------+ |
||||
</ProgramListing> |
||||
</Para> |
||||
|
||||
<Para> |
||||
As a final note, you can specify that the results of a |
||||
select can be returned in a <FirstTerm>sorted order</FirstTerm> |
||||
or with <FirstTerm>duplicate instances</FirstTerm> removed. |
||||
|
||||
<ProgramListing> |
||||
SELECT DISTINCT city |
||||
FROM weather |
||||
ORDER BY city; |
||||
</ProgramListing> |
||||
</Para> |
||||
</sect1> |
||||
|
||||
<Sect1> |
||||
<Title>Redirecting SELECT Queries</Title> |
||||
|
||||
<Para> |
||||
Any select query can be redirected to a new class |
||||
<ProgramListing> |
||||
SELECT * INTO TABLE temp FROM weather; |
||||
</ProgramListing> |
||||
</para> |
||||
|
||||
<Para> |
||||
This forms an implicit <Command>create</Command> command, creating a new |
||||
class temp with the attribute names and types specified |
||||
in the target list of the <Command>select into</Command> command. We can |
||||
then, of course, perform any operations on the resulting |
||||
class that we can perform on other classes. |
||||
</Para> |
||||
</sect1> |
||||
|
||||
<Sect1> |
||||
<Title>Joins Between Classes</Title> |
||||
|
||||
<Para> |
||||
Thus far, our queries have only accessed one class at a |
||||
time. Queries can access multiple classes at once, or |
||||
access the same class in such a way that multiple |
||||
instances of the class are being processed at the same |
||||
time. A query that accesses multiple instances of the |
||||
same or different classes at one time is called a join |
||||
query. |
||||
As an example, say we wish to find all the records that |
||||
are in the temperature range of other records. In |
||||
effect, we need to compare the temp_lo and temp_hi |
||||
attributes of each EMP instance to the temp_lo and |
||||
temp_hi attributes of all other EMP instances. |
||||
<Note> |
||||
<Para> |
||||
This is only a conceptual model. The actual join may |
||||
be performed in a more efficient manner, but this is invisible to the user. |
||||
</Para> |
||||
</Note> |
||||
|
||||
We can do this with the following query: |
||||
|
||||
<ProgramListing> |
||||
SELECT W1.city, W1.temp_lo, W1.temp_hi, |
||||
W2.city, W2.temp_lo, W2.temp_hi |
||||
FROM weather W1, weather W2 |
||||
WHERE W1.temp_lo < W2.temp_lo |
||||
AND W1.temp_hi > W2.temp_hi; |
||||
|
||||
+--------------+---------+---------+---------------+---------+---------+ |
||||
|city | temp_lo | temp_hi | city | temp_lo | temp_hi | |
||||
+--------------+---------+---------+---------------+---------+---------+ |
||||
|San Francisco | 43 | 57 | San Francisco | 46 | 50 | |
||||
+--------------+---------+---------+---------------+---------+---------+ |
||||
|San Francisco | 37 | 54 | San Francisco | 46 | 50 | |
||||
+--------------+---------+---------+---------------+---------+---------+ |
||||
</ProgramListing> |
||||
|
||||
<Note> |
||||
<Para> |
||||
The semantics of such a join are |
||||
that the qualification |
||||
is a truth expression defined for the Cartesian product of |
||||
the classes indicated in the query. For those instances in |
||||
the Cartesian product for which the qualification is true, |
||||
<ProductName>Postgres</ProductName> computes and returns the values specified in the |
||||
target list. <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> does not assign any meaning to |
||||
duplicate values in such expressions. This means that <ProductName>Postgres</ProductName> |
||||
sometimes recomputes the same target list several times; |
||||
this frequently happens when Boolean expressions are connected |
||||
with an "or". To remove such duplicates, you must use |
||||
the <Command>select distinct</Command> statement. |
||||
</Para> |
||||
</Note> |
||||
</para> |
||||
|
||||
<Para> |
||||
In this case, both W1 and W2 are surrogates for an |
||||
instance of the class weather, and both range over all |
||||
instances of the class. (In the terminology of most |
||||
database systems, W1 and W2 are known as <FirstTerm>range variables</FirstTerm>.) |
||||
A query can contain an arbitrary number of |
||||
class names and surrogates. |
||||
</Para> |
||||
</sect1> |
||||
|
||||
<Sect1> |
||||
<Title>Updates</Title> |
||||
|
||||
<Para> |
||||
You can update existing instances using the update command. |
||||
Suppose you discover the temperature readings are |
||||
all off by 2 degrees as of Nov 28, you may update the |
||||
data as follow: |
||||
|
||||
<ProgramListing> |
||||
UPDATE weather |
||||
SET temp_hi = temp_hi - 2, temp_lo = temp_lo - 2 |
||||
WHERE date > '11/28/1994'; |
||||
</ProgramListing> |
||||
</Para> |
||||
</sect1> |
||||
|
||||
<Sect1> |
||||
<Title>Deletions</Title> |
||||
|
||||
<Para> |
||||
Deletions are performed using the <Command>delete</Command> command: |
||||
<ProgramListing> |
||||
DELETE FROM weather WHERE city = 'Hayward'; |
||||
</ProgramListing> |
||||
|
||||
All weather recording belongs to Hayward is removed. |
||||
One should be wary of queries of the form |
||||
<ProgramListing> |
||||
DELETE FROM classname; |
||||
</ProgramListing> |
||||
|
||||
Without a qualification, <Command>delete</Command> will simply |
||||
remove all instances of the given class, leaving it |
||||
empty. The system will not request confirmation before |
||||
doing this. |
||||
</Para> |
||||
</sect1> |
||||
|
||||
<Sect1> |
||||
<Title>Using Aggregate Functions</Title> |
||||
|
||||
<Para> |
||||
Like most other query languages, <ProductName>PostgreSQL</ProductName> supports |
||||
aggregate functions. |
||||
The current implementation of <ProductName>Postgres</ProductName> aggregate functions have some limitations. |
||||
Specifically, while there are aggregates to compute |
||||
such functions as the <Function>count</Function>, <Function>sum</Function>, |
||||
<Function>avg</Function> (average), <Function>max</Function> (maximum) and |
||||
<Function>min</Function> (minimum) over a set of instances, aggregates can only |
||||
appear in the target list of a query and not directly in the |
||||
qualification (the <FirstTerm>where</FirstTerm> clause). As an example, |
||||
|
||||
<ProgramListing> |
||||
SELECT max(temp_lo) FROM weather; |
||||
</ProgramListing> |
||||
|
||||
is allowed, while |
||||
|
||||
<ProgramListing> |
||||
SELECT city FROM weather WHERE temp_lo = max(temp_lo); |
||||
</ProgramListing> |
||||
|
||||
is not. However, as is often the case the query can be restated to accomplish |
||||
the intended result; here by using a <FirstTerm>subselect</FirstTerm>: |
||||
<ProgramListing> |
||||
SELECT city FROM weather WHERE temp_lo = (SELECT max(temp_lo) FROM weather); |
||||
</ProgramListing> |
||||
</Para> |
||||
|
||||
<Para> |
||||
Aggregates may also have <FirstTerm>group by</FirstTerm> clauses: |
||||
<ProgramListing> |
||||
SELECT city, max(temp_lo) |
||||
FROM weather |
||||
GROUP BY city; |
||||
</ProgramListing> |
||||
</Para> |
||||
</sect1> |
||||
</Chapter> |
||||
@ -1,93 +1,632 @@ |
||||
<Chapter Id="runtime"> |
||||
<Title>Runtime Environment</Title> |
||||
|
||||
<Para> |
||||
This chapter outlines the interaction between <Productname>Postgres</Productname> and |
||||
the operating system. |
||||
</para> |
||||
<sect1> |
||||
<title>Using <Productname>Postgres</Productname> from Unix</title> |
||||
|
||||
<para> |
||||
All <Productname>Postgres</Productname> commands that are executed |
||||
directly from a Unix shell are |
||||
found in the directory <quote>.../bin</quote>. Including this directory in |
||||
your search path will make executing the commands easier. |
||||
</para> |
||||
<para> |
||||
A collection of system catalogs exist at each site. These include a |
||||
class (<literal>pg_user</literal>) that contains an instance for each valid |
||||
<Productname>Postgres</Productname> user. The instance specifies a set of |
||||
<Productname>Postgres</Productname> privileges, such as |
||||
the ability to act as <Productname>Postgres</Productname> super-user, |
||||
the ability to create/destroy |
||||
databases, and the ability to update the system catalogs. A Unix |
||||
user cannot do anything with <Productname>Postgres</Productname> |
||||
until an appropriate instance is |
||||
installed in this class. Further information on the system catalogs |
||||
is available by running queries on the appropriate classes. |
||||
</para> |
||||
</sect1> |
||||
</chapter> |
||||
|
||||
<chapter id="layout"> |
||||
<Title>System Layout</Title> |
||||
|
||||
<Para> |
||||
<Figure Id="ADMIN-LAYOUT"> |
||||
<Title><ProductName>Postgres</ProductName> file layout</Title> |
||||
<Graphic Align="center" FileRef="layout.gif" Format="GIF"></Graphic> |
||||
</Figure> |
||||
|
||||
<XRef LinkEnd="ADMIN-LAYOUT" EndTerm="ADMIN-LAYOUT"> |
||||
shows how the <ProductName>Postgres</ProductName> distribution is laid |
||||
out when installed in the default way. For simplicity, |
||||
we will assume that <ProductName>Postgres</ProductName> |
||||
has been installed in the |
||||
directory <filename>/usr/local/pgsql</filename>. Therefore, wherever |
||||
you see the directory <filename>/usr/local/pgsql</filename> you should |
||||
substitute the name of the directory where |
||||
<ProductName>Postgres</ProductName> is |
||||
actually installed. |
||||
All <ProductName>Postgres</ProductName> commands are installed |
||||
in the directory |
||||
<filename>/usr/local/pgsql/bin</filename>. Therefore, you should add |
||||
this directory to your shell command path. If you use |
||||
a variant of the Berkeley C shell, such as csh or tcsh, |
||||
you would add |
||||
<ProgramListing> |
||||
set path = ( /usr/local/pgsql/bin path ) |
||||
</ProgramListing> |
||||
in the .login file in your home directory. If you use |
||||
a variant of the Bourne shell, such as sh, ksh, or |
||||
bash, then you would add |
||||
<ProgramListing> |
||||
PATH=/usr/local/pgsql/bin:$PATH |
||||
export PATH |
||||
</ProgramListing> |
||||
to the .profile file in your home directory. |
||||
From now on, we will assume that you have added the |
||||
<ProductName>Postgres</ProductName> bin directory to your path. |
||||
In addition, we |
||||
will make frequent reference to "setting a shell |
||||
variable" or "setting an environment variable" throughout |
||||
this document. If you did not fully understand the |
||||
last paragraph on modifying your search path, you |
||||
should consult the UNIX manual pages that describe your |
||||
shell before going any further. |
||||
</Para> |
||||
|
||||
<Para> |
||||
If you have not set things up in the |
||||
default way, you may have some more work to do. |
||||
For example, if the database server machine is a remote machine, you |
||||
will need to set the <envar>PGHOST</envar> environment variable to the name |
||||
of the database server machine. The environment variable |
||||
<envar>PGPORT</envar> may also have to be set. The bottom line is this: if |
||||
you try to start an application program and it complains |
||||
that it cannot connect to the <Application>postmaster</Application>, |
||||
you must go back and make sure that your |
||||
environment is properly set up. |
||||
</Para> |
||||
<Chapter Id="runtime"> |
||||
<Title>Runtime Environment</Title> |
||||
|
||||
<Para> |
||||
This chapter outlines the interaction between <Productname>Postgres</Productname> and |
||||
the operating system. |
||||
</para> |
||||
|
||||
<sect1> |
||||
<title>Using <Productname>Postgres</Productname> from Unix</title> |
||||
|
||||
<para> |
||||
All <Productname>Postgres</Productname> commands that are executed |
||||
directly from a Unix shell are |
||||
found in the directory <quote>.../bin</quote>. Including this directory in |
||||
your search path will make executing the commands easier. |
||||
</para> |
||||
|
||||
<para> |
||||
A collection of system catalogs exist at each site. These include a |
||||
class (<literal>pg_user</literal>) that contains an instance for each valid |
||||
<Productname>Postgres</Productname> user. The instance specifies a set of |
||||
<Productname>Postgres</Productname> privileges, such as |
||||
the ability to act as <Productname>Postgres</Productname> super-user, |
||||
the ability to create/destroy |
||||
databases, and the ability to update the system catalogs. A Unix |
||||
user cannot do anything with <Productname>Postgres</Productname> |
||||
until an appropriate instance is |
||||
installed in this class. Further information on the system catalogs |
||||
is available by running queries on the appropriate classes. |
||||
</para> |
||||
</sect1> |
||||
|
||||
<sect1 Id="postmaster"> |
||||
<Title>Starting <Application>postmaster</Application></Title> |
||||
|
||||
<Para> |
||||
Nothing can happen to a database unless the |
||||
<Application>postmaster</Application> |
||||
process is running. As the site administrator, there |
||||
are a number of things you should remember before |
||||
starting the <Application>postmaster</Application>. |
||||
These are discussed in the installation and configuration sections |
||||
of this manual. |
||||
However, if <ProductName>Postgres</ProductName> has been installed by following |
||||
the installation instructions exactly as written, the |
||||
following simple command is all you should |
||||
need to start the <Application>postmaster</Application>: |
||||
|
||||
<ProgramListing> |
||||
% postmaster |
||||
</ProgramListing> |
||||
</para> |
||||
|
||||
<para> |
||||
The <Application>postmaster</Application> occasionally prints out |
||||
messages which |
||||
are often helpful during troubleshooting. If you wish |
||||
to view debugging messages from the <Application>postmaster</Application>, |
||||
you can |
||||
start it with the -d option and redirect the output to |
||||
the log file: |
||||
|
||||
<ProgramListing> |
||||
% postmaster -d >& pm.log & |
||||
</ProgramListing> |
||||
|
||||
If you do not wish to see these messages, you can type |
||||
<ProgramListing> |
||||
% postmaster -S |
||||
</ProgramListing> |
||||
and the <Application>postmaster</Application> will be "S"ilent. |
||||
Notice that there |
||||
is no ampersand ("&") at the end of the last example so |
||||
postmaster will be running in the foreground. |
||||
</Para> |
||||
</sect1> |
||||
|
||||
<sect1 Id="pg-options"> |
||||
<Title id="pg-options-title">Using pg_options</Title> |
||||
|
||||
<Para> |
||||
<Note> |
||||
<Para> |
||||
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink> |
||||
</Para> |
||||
</Note> |
||||
</para> |
||||
<Para> |
||||
The optional file <filename>data/pg_options</filename> contains runtime |
||||
options used by the backend to control trace messages and other backend |
||||
tunable parameters. |
||||
The file is re-read by a backend |
||||
when it receives a SIGHUP signal, making thus possible to change run-time |
||||
options on the fly without needing to restart |
||||
<productname>Postgres</productname>. |
||||
The options specified in this file may be debugging flags used by the trace |
||||
package (<filename>backend/utils/misc/trace.c</filename>) or numeric |
||||
parameters which can be used by the backend to control its behaviour. |
||||
</para> |
||||
|
||||
<para> |
||||
All pg_options are initialized to zero at backend startup. |
||||
New or modified options will be read by all new backends when they are started. |
||||
To make effective any changes for all running backends we need to send a |
||||
SIGHUP to the postmaster. The signal will be automatically sent to all the |
||||
backends. We can also activate the changes only for a specific backend by |
||||
sending the SIGHUP directly to it. |
||||
</para> |
||||
<para> |
||||
pg_options can also be specified with the <option>-T</option> switch of |
||||
<productname>Postgres</productname>: |
||||
|
||||
<programlisting> |
||||
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-" |
||||
</programlisting> |
||||
</para> |
||||
|
||||
<Para> |
||||
The functions used for printing errors and debug messages can now make use |
||||
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout |
||||
or stderr are prefixed by a timestamp containing also the backend pid: |
||||
|
||||
<programlisting> |
||||
#timestamp #pid #message |
||||
980127.17:52:14.173 [29271] StartTransactionCommand |
||||
980127.17:52:14.174 [29271] ProcessUtility: drop table t; |
||||
980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full |
||||
980127.17:52:14.186 [29286] Async_NotifyHandler |
||||
980127.17:52:14.186 [29286] Waking up sleeping backend process |
||||
980127.19:52:14.292 [29286] Async_NotifyFrontEnd |
||||
980127.19:52:14.413 [29286] Async_NotifyFrontEnd done |
||||
980127.19:52:14.466 [29286] Async_NotifyHandler done |
||||
</programlisting> |
||||
</para> |
||||
<para> |
||||
This format improves readability of the logs and allows people to understand |
||||
exactly which backend is doing what and at which time. It also makes |
||||
easier to write simple awk or perl scripts which monitor the log to |
||||
detect database errors or problem, or to compute transaction time statistics. |
||||
</para> |
||||
<para> |
||||
Messages printed to syslog use the log facility LOG_LOCAL0. |
||||
The use of syslog can be controlled with the syslog pg_option. |
||||
Unfortunately many functions call directly <function>printf()</function> |
||||
to print their messages to stdout or stderr and this output can't be |
||||
redirected to syslog or have timestamps in it. |
||||
It would be advisable that all calls to printf would be replaced with the |
||||
PRINTF macro and output to stderr be changed to use EPRINTF instead so that |
||||
we can control all output in a uniform way. |
||||
</Para> |
||||
|
||||
<para> |
||||
The format of the <filename>pg_options</filename> file is as follows: |
||||
|
||||
<programlisting> |
||||
# <replaceable>comment</replaceable> |
||||
<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable> # set value for <replaceable>option</replaceable> |
||||
<replaceable>option</replaceable> # set <replaceable>option</replaceable> = 1 |
||||
<replaceable>option</replaceable>+ # set <replaceable>option</replaceable> = 1 |
||||
<replaceable>option</replaceable>- # set <replaceable>option</replaceable> = 0 |
||||
</programlisting> |
||||
|
||||
Note that <replaceable class="parameter">keyword</replaceable> can also be |
||||
an abbreviation of the option name defined in |
||||
<filename>backend/utils/misc/trace.c</filename>. |
||||
|
||||
<example> |
||||
<title>pg_options File</title> |
||||
|
||||
<para> |
||||
For example my pg_options file contains the following values: |
||||
|
||||
<programlisting> |
||||
verbose=2 |
||||
query |
||||
hostlookup |
||||
showportnumber |
||||
</programlisting> |
||||
</para> |
||||
</example> |
||||
</para> |
||||
|
||||
<sect2> |
||||
<title>Recognized Options</title> |
||||
|
||||
<Para> |
||||
The options currently defined are: |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term> |
||||
all |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Global trace flag. Allowed values are: |
||||
</para> |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term> |
||||
0 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Trace messages enabled individually |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
1 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Enable all trace messages |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
-1 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Disable all trace messages |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
</variablelist> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
verbose |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Verbosity flag. Allowed values are: |
||||
</para> |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term> |
||||
0 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
No messages. This is the default. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
1 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Print information messages. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
2 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Print more information messages. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
</variablelist> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
query |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Query trace flag. Allowed values are: |
||||
</para> |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term> |
||||
0 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Don't print query. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
1 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Print a condensed query in one line. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
4 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Print the full query. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
</variablelist> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
plan |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Print query plan. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
parse |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Print parser output. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
rewritten |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Print rewritten query. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
parserstats |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Print parser statistics. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
plannerstats |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Print planner statistics. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
executorstats |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Print executor statistics. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
shortlocks |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Currently unused but needed to enable features in the future. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
locks |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Trace locks. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
userlocks |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Trace user locks. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
spinlocks |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Trace spin locks. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
notify |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Trace notify functions. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
malloc |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Currently unused. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
palloc |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Currently unused. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
lock_debug_oidmin |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Minimum relation oid traced by locks. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
lock_debug_relid |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
oid, if not zero, of relation traced by locks. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
lock_read_priority |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Currently unused. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
deadlock_timeout |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Deadlock check timer. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
syslog |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
syslog flag. Allowed values are: |
||||
</para> |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term> |
||||
0 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Messages to stdout/stderr. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
1 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Messages to stdout/stderr and syslog. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
2 |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Messages only to syslog. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
</variablelist> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
hostlookup |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Enable hostname lookup in ps_status. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
showportnumber |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Show port number in ps_status. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
notifyunlock |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Unlock of pg_listener after notify. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
notifyhack |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Remove duplicate tuples from pg_listener. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
</variablelist> |
||||
</para> |
||||
</sect2> |
||||
</sect1> |
||||
|
||||
</Chapter> |
||||
|
||||
<!-- Keep this comment at the end of the file |
||||
Local variables: |
||||
mode: sgml |
||||
sgml-omittag:nil |
||||
sgml-shorttag:t |
||||
sgml-minimize-attributes:nil |
||||
sgml-always-quote-attributes:t |
||||
sgml-indent-step:1 |
||||
sgml-indent-data:t |
||||
sgml-parent-document:nil |
||||
sgml-default-dtd-file:"./reference.ced" |
||||
sgml-exposed-tags:nil |
||||
sgml-local-catalogs:"/usr/lib/sgml/CATALOG" |
||||
sgml-local-ecat-files:nil |
||||
End: |
||||
--> |
||||
|
||||
@ -0,0 +1,166 @@ |
||||
<Chapter Id="trouble"> |
||||
<Title>Troubleshooting</Title> |
||||
|
||||
<sect1> |
||||
<title>Client Connections</title> |
||||
<Para> |
||||
If you get the following error message from a |
||||
<ProductName>Postgres</ProductName> |
||||
command (such as <Application>psql</Application> or |
||||
<Application>createdb</Application>): |
||||
|
||||
<ProgramListing> |
||||
connectDB() failed: Is the postmaster running at 'localhost' on port '5432'? |
||||
</ProgramListing> |
||||
|
||||
it is usually because either the <Application>postmaster</Application> is not running, |
||||
or you are attempting to connect to the wrong server host. |
||||
If you get the following error message: |
||||
|
||||
<ProgramListing> |
||||
FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268) |
||||
</ProgramListing> |
||||
|
||||
it means that the site administrator started the <Application>postmaster</Application> |
||||
as the wrong user. Tell him to restart it as |
||||
the <ProductName>Postgres</ProductName> superuser. |
||||
</Para> |
||||
</sect1> |
||||
|
||||
<sect1> |
||||
<title>Debugging Messages</title> |
||||
|
||||
<para> |
||||
The <Application>postmaster</Application> occasionally prints out |
||||
messages which |
||||
are often helpful during troubleshooting. If you wish |
||||
to view debugging messages from the <Application>postmaster</Application>, |
||||
you can |
||||
start it with the -d option and redirect the output to |
||||
the log file: |
||||
|
||||
<ProgramListing> |
||||
% postmaster -d >& pm.log & |
||||
</ProgramListing> |
||||
|
||||
If you do not wish to see these messages, you can type |
||||
<ProgramListing> |
||||
% postmaster -S |
||||
</ProgramListing> |
||||
and the <Application>postmaster</Application> will be "S"ilent. |
||||
Notice that there |
||||
is no ampersand ("&") at the end of the last example so |
||||
postmaster will be running in the foreground. |
||||
</Para> |
||||
|
||||
<sect2 Id="pg-options-trouble"> |
||||
<Title>pg_options</Title> |
||||
|
||||
<Para> |
||||
<Note> |
||||
<Para> |
||||
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink> |
||||
</Para> |
||||
</Note> |
||||
</para> |
||||
<Para> |
||||
The optional file <filename>data/pg_options</filename> contains runtime |
||||
options used by the backend to control trace messages and other backend |
||||
tunable parameters. |
||||
What makes this file interesting is the fact that it is re-read by a backend |
||||
when it receives a SIGHUP signal, making thus possible to change run-time |
||||
options on the fly without needing to restart |
||||
<productname>Postgres</productname>. |
||||
The options specified in this file may be debugging flags used by the trace |
||||
package (<filename>backend/utils/misc/trace.c</filename>) or numeric |
||||
parameters which can be used by the backend to control its behaviour. |
||||
New options and parameters must be defined in |
||||
<filename>backend/utils/misc/trace.c</filename> and |
||||
<filename>backend/include/utils/trace.h</filename>. |
||||
</para> |
||||
|
||||
<para> |
||||
pg_options can also be specified with the <option>-T</option> switch of |
||||
<productname>Postgres</productname>: |
||||
|
||||
<programlisting> |
||||
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-" |
||||
</programlisting> |
||||
</para> |
||||
|
||||
<Para> |
||||
The functions used for printing errors and debug messages can now make use |
||||
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout |
||||
or stderr are prefixed by a timestamp containing also the backend pid: |
||||
|
||||
<programlisting> |
||||
#timestamp #pid #message |
||||
980127.17:52:14.173 [29271] StartTransactionCommand |
||||
980127.17:52:14.174 [29271] ProcessUtility: drop table t; |
||||
980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full |
||||
980127.17:52:14.186 [29286] Async_NotifyHandler |
||||
980127.17:52:14.186 [29286] Waking up sleeping backend process |
||||
980127.19:52:14.292 [29286] Async_NotifyFrontEnd |
||||
980127.19:52:14.413 [29286] Async_NotifyFrontEnd done |
||||
980127.19:52:14.466 [29286] Async_NotifyHandler done |
||||
</programlisting> |
||||
</para> |
||||
|
||||
<para> |
||||
This format improves readability of the logs and allows people to understand |
||||
exactly which backend is doing what and at which time. It also makes |
||||
easier to write simple awk or perl scripts which monitor the log to |
||||
detect database errors or problem, or to compute transaction time statistics. |
||||
</para> |
||||
|
||||
<para> |
||||
Messages printed to syslog use the log facility LOG_LOCAL0. |
||||
The use of syslog can be controlled with the syslog pg_option. |
||||
Unfortunately many functions call directly <function>printf()</function> |
||||
to print their messages to stdout or stderr and this output can't be |
||||
redirected to syslog or have timestamps in it. |
||||
It would be advisable that all calls to printf would be replaced with the |
||||
PRINTF macro and output to stderr be changed to use EPRINTF instead so that |
||||
we can control all output in a uniform way. |
||||
</Para> |
||||
|
||||
<para> |
||||
The format of the <filename>pg_options</filename> file is as follows: |
||||
|
||||
<programlisting> |
||||
# <replaceable>comment</replaceable> |
||||
<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable> # set value for <replaceable>option</replaceable> |
||||
<replaceable>option</replaceable> # set <replaceable>option</replaceable> = 1 |
||||
<replaceable>option</replaceable>+ # set <replaceable>option</replaceable> = 1 |
||||
<replaceable>option</replaceable>- # set <replaceable>option</replaceable> = 0 |
||||
</programlisting> |
||||
|
||||
Note that <replaceable class="parameter">keyword</replaceable> can also be |
||||
an abbreviation of the option name defined in |
||||
<filename>backend/utils/misc/trace.c</filename>. |
||||
</Para> |
||||
|
||||
<Para> |
||||
Refer to <xref linkend="pg-options-title" endterm="pg-options-title"> |
||||
for a complete list of option keywords and possible values. |
||||
</para> |
||||
</sect2> |
||||
</sect1> |
||||
</Chapter> |
||||
|
||||
<!-- Keep this comment at the end of the file |
||||
Local variables: |
||||
mode: sgml |
||||
sgml-omittag:nil |
||||
sgml-shorttag:t |
||||
sgml-minimize-attributes:nil |
||||
sgml-always-quote-attributes:t |
||||
sgml-indent-step:1 |
||||
sgml-indent-data:t |
||||
sgml-parent-document:nil |
||||
sgml-default-dtd-file:"./reference.ced" |
||||
sgml-exposed-tags:nil |
||||
sgml-local-catalogs:"/usr/lib/sgml/CATALOG" |
||||
sgml-local-ecat-files:nil |
||||
End: |
||||
--> |
||||
Loading…
Reference in new issue