mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix path to initdb in installation instructions.

Browse Source 
General cleanup for 7.0.
This commit is contained in:
Thomas G. Lockhart 2000-04-07 13:30:58 +00:00
parent b2096a5512
commit 30e355fc80
11 changed files with 1233 additions and 896 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
doc/src/sgml/advanced.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.9 2000/03/31 03:27:40 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.10 2000/04/07 13:30:58 thomas Exp $
-->
<chapter id="advanced">
@ -106,10 +106,10 @@ SELECT c.name, c.altitude
Here the <quote>*</quote> after cities indicates that the query should
be run over cities and all classes below cities in the
inheritance hierarchy. Many of the commands that we
have already discussed (<command>select</command>,
<command>update</command> and <command>delete</command>)
have already discussed (<command>SELECT</command>,
<command>UPDATE</command> and <command>DELETE</command>)
support this <quote>*</quote> notation, as do others, like
<command>alter</command>.
<command>ALTER</command>.
</para>
</sect1>
@ -118,7 +118,8 @@ SELECT c.name, c.altitude
<para>
One of the tenets of the relational model is that the
attributes of a relation are atomic. <productname>Postgres</productname> does not
attributes of a relation are atomic.
<productname>Postgres</productname> does not
have this restriction; attributes can themselves contain
sub-values that can be accessed from the query
language. For example, you can create attributes that
@ -129,7 +130,8 @@ SELECT c.name, c.altitude
<title>Arrays</title>
<para>
<productname>Postgres</productname> allows attributes of an instance to be defined
<productname>Postgres</productname> allows attributes of an
instance to be defined
as fixed-length or variable-length multi-dimensional
arrays. Arrays of any base type or user-defined type
can be created. To illustrate their use, we first create a
@ -149,11 +151,14 @@ CREATE TABLE SAL_EMP (
a <firstterm>text</firstterm> string (name), a one-dimensional
array of <firstterm>int4</firstterm>
(pay_by_quarter), which represents the employee's
salary by quarter and a two-dimensional array of <firstterm>text</firstterm>
salary by quarter and a two-dimensional array of
<firstterm>text</firstterm>
(schedule), which represents the employee's weekly
schedule. Now we do some <firstterm>INSERTS</firstterm>s; note that when
schedule. Now we do some <firstterm>INSERTS</firstterm>s;
note that when
appending to an array, we enclose the values within
braces and separate them by commas. If you know <firstterm>C</firstterm>,
braces and separate them by commas. If you know
<firstterm>C</firstterm>,
this is not unlike the syntax for initializing structures.
<programlisting>
@ -168,7 +173,8 @@ INSERT INTO SAL_EMP
'{{"talk", "consult"}, {"meeting"}}');
</programlisting>
By default, <productname>Postgres</productname> uses the "one-based" numbering
By default, <productname>Postgres</productname> uses the
"one-based" numbering
convention for arrays -- that is, an array of n elements
starts with array[1] and ends with array[n].
Now, we can run some queries on SAL_EMP. First, we
@ -228,6 +234,11 @@ SELECT SAL_EMP.schedule[1:2][1:1]
</sect2>
</sect1>
<!--
We haven't had Time Travel for two or three years, so let's stop
mentioning it. - thomas 2000-04-02
<sect1>
<title>Time Travel</title>
@ -240,21 +251,27 @@ SELECT SAL_EMP.schedule[1:2][1:1]
</para>
<para>
New features such as triggers allow one to mimic the behavior of time travel when desired, without
incurring the overhead when it is not needed (for most users, this is most of the time).
See examples in the <filename>contrib</filename> directory for more information.
New features such as triggers allow one to mimic the behavior of
time travel when desired, without
incurring the overhead when it is not needed (for most users, this
is most of the time).
See examples in the <filename>contrib</filename> directory for
more information.
</para>
<note>
<title>Time travel is deprecated</title>
<para>
The remaining text in this section is retained only until it can be rewritten in the context
of new techniques to accomplish the same purpose. Volunteers? - thomas 1998-01-12
The remaining text in this section is retained only until it can
be rewritten in the context
of new techniques to accomplish the same purpose.
Volunteers? - thomas 1998-01-12
</para>
</note>
<para>
<productname>Postgres</productname> supports the notion of time travel. This feature
<productname>Postgres</productname> supports the notion of time
travel. This feature
allows a user to run historical queries. For
example, to find the current population of Mariposa
city, one would query:
@ -269,7 +286,8 @@ SELECT * FROM cities WHERE name = 'Mariposa';
+---------+------------+----------+
</programlisting>
<productname>Postgres</productname> will automatically find the version of Mariposa's
<productname>Postgres</productname> will automatically find the
version of Mariposa's
record valid at the current time.
One can also give a time range. For example to see the
past and present populations of Mariposa, one would
@ -313,18 +331,22 @@ SELECT name, population
abbreviated as ``[,].''
</para>
</sect1>
-->
<sect1>
<title>More Advanced Features</title>
<para>
<productname>Postgres</productname> has many features not touched upon in this
<productname>Postgres</productname> has many features not touched
upon in this
tutorial introduction, which has been oriented toward newer users of
<acronym>SQL</acronym>.
These are discussed in more detail in both the User's and Programmer's Guides.
These are discussed in more detail in both the User's and
Programmer's Guides.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file

106
doc/src/sgml/func.sgml
View File

@ -88,10 +88,10 @@
<entry>abs(-17.4)</entry>
</row>
<row>
<entry>sqrt(float8)</entry>
<entry>degrees(float8)</entry>
<entry>float8</entry>
<entry>square root</entry>
<entry>sqrt(2.0)</entry>
<entry>radians to degrees</entry>
<entry>degrees(0.5)</entry>
</row>
<row>
<entry>exp(float8)</entry>
@ -111,18 +111,36 @@
<entry>base 10 logarithm</entry>
<entry>log(2.0)</entry>
</row>
<row>
<entry>pi()</entry>
<entry>float8</entry>
<entry>fundamental constant</entry>
<entry>pi()</entry>
</row>
<row>
<entry>pow(float8,float8)</entry>
<entry>float8</entry>
<entry>raise a number to the specified exponent</entry>
<entry>pow(2.0, 16.0)</entry>
</row>
<row>
<entry>radians(float8)</entry>
<entry>float8</entry>
<entry>degrees to radians</entry>
<entry>radians(45.0)</entry>
</row>
<row>
<entry>round(float8)</entry>
<entry>float8</entry>
<entry>round to nearest integer</entry>
<entry>round(42.4)</entry>
</row>
<row>
<entry>sqrt(float8)</entry>
<entry>float8</entry>
<entry>square root</entry>
<entry>sqrt(2.0)</entry>
</row>
<row>
<entry>trunc(float8)</entry>
<entry>float8</entry>
@ -156,6 +174,88 @@
Most of the functions listed for FLOAT8 are also available for
type NUMERIC.
</para>
<para>
<table tocentry="1">
<title>Transcendental Mathematical Functions</title>
<tgroup cols="4">
<thead>
<row>
<entry>Function</entry>
<entry>Returns</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>acos(float8)</entry>
<entry>float8</entry>
<entry>arccosine</entry>
<entry>acos(10.0)</entry>
</row>
<row>
<entry>asin(float8)</entry>
<entry>float8</entry>
<entry>arcsine</entry>
<entry>asin(10.0)</entry>
</row>
<row>
<entry>atan(float8)</entry>
<entry>float8</entry>
<entry>arctangent</entry>
<entry>atan(10.0)</entry>
</row>
<row>
<entry>atan2(float8,float8)</entry>
<entry>float8</entry>
<entry>arctangent</entry>
<entry>atan3(10.0,20.0)</entry>
</row>
<row>
<entry>cos(float8)</entry>
<entry>float8</entry>
<entry>cosine</entry>
<entry>cos(0.4)</entry>
</row>
<row>
<entry>cot(float8)</entry>
<entry>float8</entry>
<entry>cotangent</entry>
<entry>cot(20.0)</entry>
</row>
<row>
<entry>sin(float8)</entry>
<entry>float8</entry>
<entry>sine</entry>
<entry>cos(0.4)</entry>
</row>
<row>
<entry>cos(float8)</entry>
<entry>float8</entry>
<entry>cosine</entry>
<entry>cos(0.4)</entry>
</row>
<row>
<entry>cos(float8)</entry>
<entry>float8</entry>
<entry>cosine</entry>
<entry>cos(0.4)</entry>
</row>
<row>
<entry>cos(float8)</entry>
<entry>float8</entry>
<entry>cosine</entry>
<entry>cos(0.4)</entry>
</row>
<row>
<entry>cos(float8)</entry>
<entry>float8</entry>
<entry>cosine</entry>
<entry>cos(0.4)</entry>
</row>
</sect1>
<sect1>

1042
doc/src/sgml/install.sgml
View File

File diff suppressed because it is too large Load Diff

24
doc/src/sgml/intro.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.11 2000/04/07 13:30:58 thomas Exp $
-->
<chapter id="intro">
@ -16,7 +16,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thoma
<productname>Postgres release 4.2</productname></ulink>.
The <productname>Postgres</productname> project,
led by Professor Michael Stonebraker, was sponsored by the
Defense Advanced Research Projects Agency (<acronym>DARPA</acronym>), the
Defense Advanced Research Projects Agency
(<acronym>DARPA</acronym>), the
Army Research Office (<acronym>ARO</acronym>), the National Science
Foundation (<acronym>NSF</acronym>), and ESL, Inc.
</para>
@ -37,7 +38,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thoma
models in part because of its "Spartan simplicity".
However, as mentioned, this simplicity often makes the
implementation of certain applications very difficult.
<productname>Postgres</productname> offers substantial additional
<productname>Postgres</productname> offers substantial additional
power by incorporating the following four additional
basic concepts in such a way that users can easily
extend the system:
@ -62,13 +63,16 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.10 2000/03/31 03:27:40 thoma
</para>
<para>
These features put <productname>Postgres</productname> into the category of databases
referred to as <firstterm>object-relational</firstterm>. Note that this is distinct
from those referred to as <firstterm>object-oriented</firstterm>, which in general
are not as well suited to supporting the traditional relational database languages.
So, although <productname>Postgres</productname> has some object-oriented features,
it is firmly in the relational database world. In fact, some commercial databases
have recently incorporated features pioneered by <productname>Postgres</productname>.
These features put <productname>Postgres</productname> into the
category of databases referred to as
<firstterm>object-relational</firstterm>. Note that this is distinct
from those referred to as <firstterm>object-oriented</firstterm>,
which in general are not as well suited to supporting the
traditional relational database languages.
So, although <productname>Postgres</productname> has some
object-oriented features, it is firmly in the relational database
world. In fact, some commercial databases have recently
incorporated features pioneered by <productname>Postgres</productname>.
</para>
</sect1>

14
doc/src/sgml/legal.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.7 2000/03/31 03:27:40 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.8 2000/04/07 13:30:58 thomas Exp $
-->
<sect1 id="copyright">
@ -7,7 +7,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.7 2000/03/31 03:27:40 thomas
<para>
<productname>PostgreSQL</productname> is Copyright &copy; 1996-2000
by the PostgreSQL Inc.
by PostgreSQL Inc.
and is distributed under the terms of the Berkeley license.
</para>
@ -35,14 +35,22 @@ $Header: /cvsroot/pgsql/doc/src/sgml/legal.sgml,v 1.7 2000/03/31 03:27:40 thomas
maintainance, support, updates, enhancements, or modifications.
</para>
<!--
How to keep track of all the trademarks? I'll try the strategy used at
www.qnx.com - thomas
<para>
<acronym>Unix</acronym> is a trademark of X/Open, Ltd. Sun4, SPARC, SunOS
and Solaris are trademarks of Sun Microsystems, Inc. DEC,
DECstation, Alpha AXP and ULTRIX are trademarks of Digital
DECstation, Alpha AXP and ULTRIX are trademarks of Compaq, formerly Digital
Equipment Corp. PA-RISC and HP-UX are trademarks of
Hewlett-Packard Co. OSF/1 is a trademark of the Open
Software Foundation.
</para>
-->
<para>
All trademarks are the property of their respective owners.
</para>
</sect1>
<!-- Keep this comment at the end of the file

27
doc/src/sgml/notation.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.8 2000/03/31 03:27:41 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.9 2000/04/07 13:30:58 thomas Exp $
-->
<sect1 id="terminology">
@ -25,13 +25,15 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.8 2000/03/31 03:27:41 tho
binaries and database files. As the database superuser, all
protection mechanisms may be bypassed and any data accessed
arbitrarily.
In addition, the <Productname>Postgres</Productname> superuser is allowed to execute
In addition, the <Productname>Postgres</Productname> superuser is
allowed to execute
some support programs which are generally not available to all users.
Note that the <Productname>Postgres</Productname> superuser is
<emphasis>not</emphasis>
the same as the Unix superuser (which will be referred to as <firstterm>root</firstterm>).
The superuser should have a non-zero user identifier (<firstterm>UID</firstterm>)
for security reasons.
the same as the Unix superuser (which will be referred to as
<firstterm>root</firstterm>).
The superuser should have a non-zero user identifier
(<firstterm>UID</firstterm>) for security reasons.
</para>
<para>
@ -82,18 +84,21 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.8 2000/03/31 03:27:41 tho
In a command synopsis, brackets
(<quote>[</quote> and <quote>]</quote>) indicate an optional phrase or keyword.
Anything in braces
(<quote>{</quote> and <quote>}</quote>) and containing vertical bars (<quote>|</quote>)
(<quote>{</quote> and <quote>}</quote>) and containing vertical bars
(<quote>|</quote>)
indicates that you must choose one.
</para>
<para>
In examples, parentheses (<quote>(</quote> and <quote>)</quote>) are used to group boolean
In examples, parentheses (<quote>(</quote> and <quote>)</quote>) are
used to group boolean
expressions. <quote>|</quote> is the boolean operator OR.
</para>
<para>
Examples will show commands executed from various accounts and programs.
Commands executed from the root account will be preceeded with <quote>&gt;</quote>.
Commands executed from the root account will be preceeded with
<quote>&gt;</quote>.
Commands executed from the <Productname>Postgres</Productname>
superuser account will be preceeded with <quote>%</quote>, while commands
executed from an unprivileged user's account will be preceeded with
@ -104,8 +109,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/notation.sgml,v 1.8 2000/03/31 03:27:41 tho
<note>
<para>
At the time of writing (<Productname>Postgres</Productname> v6.5) the notation for
flagging commands is not universally consistant throughout the documentation set.
At the time of writing (<Productname>Postgres</Productname> v7.0)
the notation for
flagging commands is not universally consistant throughout the
documentation set.
Please report problems to
<ulink url="mailto:docs@postgresql.org">the Documentation Mailing List</ulink>.
</para>

53
doc/src/sgml/ports.sgml
View File

@ -32,15 +32,15 @@
<row>
<entry>AIX 4.3.2</entry>
<entry>RS6000</entry>
<entry>v6.5</entry>
<entry>1999-05-26</entry>
<entry>v7.0</entry>
<entry>2000-04-05</entry>
<entry>(<ulink url="mailto:Andreas.Zeugswetter@telecom.at">Andreas Zeugswetter</ulink>)</entry>
</row>
<row>
<entry>BSDI</entry>
<entry>BSDI 4.01</entry>
<entry>x86</entry>
<entry>v6.5</entry>
<entry>1999-05-25</entry>
<entry>v7.0</entry>
<entry>2000-04-04</entry>
<entry>(<ulink url="mailto:maillist@candle.pha.pa.us">Bruce Momjian</ulink></entry>
</row>
<row>
@ -60,12 +60,11 @@
(<ulink url="mailto:pjlobo@euitt.upm.es">Pedro J. Lobo</ulink>)</entry>
</row>
<row>
<entry>FreeBSD 2.2.x-4.0</entry>
<entry>FreeBSD 4.0</entry>
<entry>x86</entry>
<entry>v6.5</entry>
<entry>1999-05-25</entry>
<entry>(<ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink>,
<ulink url="mailto:scrappy@hub.org">Marc Fournier</ulink>)</entry>
<entry>v7.0</entry>
<entry>2000-04-04</entry>
<entry>(<ulink url="mailto:scrappy@hub.org">Marc Fournier</ulink>)</entry>
</row>
<row>
<entry>HPUX</entry>
@ -136,17 +135,17 @@
(<ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink>)</entry>
</row>
<row>
<entry>Linux 2.0.x</entry>
<entry>Linux 2.2.5</entry>
<entry>Sparc</entry>
<entry>v6.4</entry>
<entry>1998-10-25</entry>
<entry>v7.0</entry>
<entry>2000-04-02</entry>
<entry>(<ulink url="mailto:szybist@boxhill.com">Tom Szybist</ulink>)</entry>
</row>
<row>
<entry>LinuxPPC R4 2.2.1/libc5</entry>
<entry>LinuxPPC R4</entry>
<entry>PPC603e</entry>
<entry>v7.0</entry>
<entry>2000-03-26</entry>
<entry>2000-04-04</entry>
<entry>Powerbook 2400c
(<ulink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ulink>)</entry>
</row>
@ -250,20 +249,20 @@
(<ulink url="mailto:ridderbusch.pad@sni.de">Frank Ridderbusch</ulink>)</entry>
</row>
<row>
<entry>Windows</entry>
<entry>Windows/Win32</entry>
<entry>x86</entry>
<entry>v6.4</entry>
<entry>1999-01-06</entry>
<entry>Client-side libraries or ODBC/JDBC. No server yet.
<entry>v7.0</entry>
<entry>2000-04-02</entry>
<entry>Client-side libraries or ODBC/JDBC. No server-side.
(<ulink url="mha@sollentuna.net">Magnus Hagander</ulink></entry>
</row>
<row>
<entry>Windows NT</entry>
<entry>WinNT/Cygwin</entry>
<entry>x86</entry>
<entry>v6.5</entry>
<entry>1999-05-26</entry>
<entry>v7.0</entry>
<entry>2000-03-30</entry>
<entry>Working with the Cygwin library.
(<ulink url="mailto:Dan.Horak@email.cz">Daniel Horak</ulink>) </entry>
(<ulink url="mailto:horak@sit.plzen-city.cz">Daniel Horak</ulink>) </entry>
</row>
</tbody>
</tgroup>
@ -273,8 +272,9 @@
<note>
<para>
For <productname>Windows NT</productname>,
the server-side port of <productname>Postgres</productname> has recently been
accomplished. The Cygnus library is required to compile it.
the server-side port of <productname>Postgres</productname> uses
the RedHat/Cygnus <productname>Cygwin</productname> library and
toolset.
</para>
</note>
</sect1>
@ -289,7 +289,8 @@
</para>
<para>
At the time of publication, the following platforms have been tested:
At the time of publication, the following platforms have not been
tested for v7.0:
<table tocentry="1">
<title>Obsolete Platforms</title>

121
doc/src/sgml/query.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.9 2000/03/31 03:27:41 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.10 2000/04/07 13:30:58 thomas Exp $
-->
<chapter id="query">
@ -8,20 +8,21 @@ $Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.9 2000/03/31 03:27:41 thomas
<para>
The <productname>Postgres</productname> query language is a variant of
the <acronym>SQL3</acronym> draft next-generation standard. It
has many extensions such as an extensible type system,
has many extensions to <acronym>SQL92</acronym> such as an
extensible type system,
inheritance, functions and production rules. These are
features carried over from the original <productname>Postgres</productname> query
language, <productname>PostQuel</productname>. This section provides an overview
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>, including
<!--
<XRef LinkEnd="MELT93"> and <XRef LinkEnd="DATE97">.
-->
[MELT93] and [DATE97].
<acronym>SQL92</acronym>, including
<xref linkend="MELT93" endterm="MELT93-title"> and
<xref linkend="DATE97" endterm="DATE97-title">.
You should be aware that some language features
are extensions to the <acronym>ANSI</acronym> standard.
</para>
@ -111,22 +112,26 @@ CREATE TABLE weather (
</para>
<para>
Note that both keywords and identifiers are case-insensitive; identifiers can become
case-sensitive by surrounding them with double-quotes as allowed
Note that both keywords and identifiers are case-insensitive;
identifiers can preserve case by surrounding them with
double-quotes as allowed
by <acronym>SQL92</acronym>.
<productname>Postgres</productname> <acronym>SQL</acronym> supports the usual
<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
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> <command>CREATE</command> command
So far, the <productname>Postgres</productname>
<command>CREATE</command> command
looks exactly like
the command used to create a table in a traditional
relational system. However, we will presently see that
@ -139,7 +144,7 @@ CREATE TABLE weather (
<title>Populating a Class with Instances</title>
<para>
The <command>insert</command> statement is used to populate a class with
The <command>INSERT</command> statement is used to populate a class with
instances:
<programlisting>
@ -149,9 +154,10 @@ INSERT INTO weather
</para>
<para>
You can also use the <command>copy</command> command to perform load large
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
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>
@ -159,7 +165,8 @@ COPY weather FROM '/home/user/weather.txt'
USING DELIMITERS '|';
</programlisting>
where the path name for the source file must be available to the backend server
where the path name for the source file must be available to the
backend server
machine, not the client, since the backend server reads the file directly.
</para>
</sect1>
@ -170,7 +177,7 @@ COPY weather FROM '/home/user/weather.txt'
<para>
The weather class can be queried with normal relational
selection and projection queries. A <acronym>SQL</acronym>
<command>select</command>
<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
@ -192,7 +199,8 @@ SELECT * FROM weather;
|Hayward | 37 | 54 | | 11-29-1994 |
+--------------+---------+---------+------+------------+
</programlisting>
You may specify any arbitrary expressions in the target list. For example, you can do:
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>
@ -200,7 +208,8 @@ SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
<para>
Arbitrary Boolean operators
(<command>and</command>, <command>or</command> and <command>not</command>) are
(<command>AND</command>, <command>OR</command> and
<command>NOT</command>) are
allowed in the qualification of any query. For example,
<programlisting>
@ -235,16 +244,16 @@ SELECT DISTINCT city
<title>Redirecting SELECT Queries</title>
<para>
Any select query can be redirected to a new class
Any <command>SELECT</command> 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
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
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>
@ -269,7 +278,8 @@ SELECT * INTO TABLE temp FROM weather;
<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.
be performed in a more efficient manner, but this is invisible
to the user.
</para>
</note>
@ -307,16 +317,18 @@ SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high,
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.
the <command>SELECT DISTINCT</command> statement.
</para>
</note>
</para>
<para>
In this case, both W1 and W2 are surrogates for an
In this case, both <literal>W1</literal> and
<literal>W2</literal> 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>.)
database systems, <literal>W1</literal> and <literal>W2</literal>
are known as <firstterm>range variables</firstterm>.)
A query can contain an arbitrary number of
class names and surrogates.
</para>
@ -326,7 +338,8 @@ SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high,
<title>Updates</title>
<para>
You can update existing instances using the update command.
You can update existing instances using the
<command>UPDATE</command> command.
Suppose you discover the temperature readings are
all off by 2 degrees as of Nov 28, you may update the
data as follow:
@ -343,7 +356,7 @@ UPDATE weather
<title>Deletions</title>
<para>
Deletions are performed using the <command>delete</command> command:
Deletions are performed using the <command>DELETE</command> command:
<programlisting>
DELETE FROM weather WHERE city = 'Hayward';
</programlisting>
@ -354,7 +367,7 @@ DELETE FROM weather WHERE city = 'Hayward';
DELETE FROM classname;
</programlisting>
Without a qualification, <command>delete</command> will simply
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.
@ -365,7 +378,7 @@ DELETE FROM classname;
<title>Using Aggregate Functions</title>
<para>
Like most other query languages,
Like most other relational database products,
<productname>PostgreSQL</productname> supports
aggregate functions.
An aggregate function computes a single result from multiple input rows.
@ -377,20 +390,20 @@ DELETE FROM classname;
<para>
It is important to understand the interaction between aggregates and
SQL's <command>where</command> and <command>having</command> clauses.
The fundamental difference between <command>where</command> and
<command>having</command> is this: <command>where</command> selects
SQL's <command>WHERE</command> and <command>HAVING</command> clauses.
The fundamental difference between <command>WHERE</command> and
<command>HAVING</command> is this: <command>WHERE</command> selects
input rows before groups and aggregates are computed (thus, it controls
which rows go into the aggregate computation), whereas
<command>having</command> selects group rows after groups and
<command>HAVING</command> selects group rows after groups and
aggregates are computed. Thus, the
<command>where</command> clause may not contain aggregate functions;
<command>WHERE</command> clause may not contain aggregate functions;
it makes no sense to try to use an aggregate to determine which rows
will be inputs to the aggregates. On the other hand,
<command>having</command> clauses always contain aggregate functions.
(Strictly speaking, you are allowed to write a <command>having</command>
<command>HAVING</command> clauses always contain aggregate functions.
(Strictly speaking, you are allowed to write a <command>HAVING</command>
clause that doesn't use aggregates, but it's wasteful; the same condition
could be used more efficiently at the <command>where</command> stage.)
could be used more efficiently at the <command>WHERE</command> stage.)
</para>
<para>
@ -408,13 +421,17 @@ SELECT max(temp_lo) FROM weather;
SELECT city FROM weather WHERE temp_lo = max(temp_lo);
</programlisting>
but this will not work since the aggregate max() can't be used in
<command>where</command>. However, as is often the case the query can be
but this will not work since the aggregate
<function>max</function> can't be used in
<command>WHERE</command>. 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);
SELECT city FROM weather
WHERE temp_lo = (SELECT max(temp_lo) FROM weather);
</programlisting>
This is OK because the sub-select is an independent computation that
computes its own aggregate separately from what's happening in the outer
select.
@ -422,24 +439,29 @@ SELECT city FROM weather WHERE temp_lo = (SELECT max(temp_lo) FROM weather);
<para>
Aggregates are also very useful in combination with
<firstterm>group by</firstterm> clauses. For example, we can get the
<command>GROUP BY</command> clauses. For example, we can get the
maximum low temperature observed in each city with
<programlisting>
SELECT city, max(temp_lo)
FROM weather
GROUP BY city;
</programlisting>
which gives us one output row per city. We can filter these grouped
rows using <command>having</command>:
rows using <command>HAVING</command>:
<programlisting>
SELECT city, max(temp_lo)
FROM weather
GROUP BY city
HAVING min(temp_lo) < 0;
</programlisting>
which gives us the same results for only the cities that have some
below-zero readings. Finally, if we only care about cities whose
names begin with 'P', we might do
names begin with "<literal>P</literal>", we might do
<programlisting>
SELECT city, max(temp_lo)
FROM weather
@ -447,11 +469,12 @@ SELECT city, max(temp_lo)
GROUP BY city
HAVING min(temp_lo) < 0;
</programlisting>
Note that we can apply the city-name restriction in
<command>where</command>, since it needs no aggregate. This is
more efficient than adding the restriction to <command>having</command>,
<command>WHERE</command>, since it needs no aggregate. This is
more efficient than adding the restriction to <command>HAVING</command>,
because we avoid doing the grouping and aggregate calculations
for all rows that fail the <command>where</command> check.
for all rows that fail the <command>WHERE</command> check.
</para>
</sect1>
</chapter>

142
doc/src/sgml/sql.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.8 2000/04/07 13:30:58 thomas Exp $
-->
<chapter id="sql">
@ -7,18 +7,28 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
<abstract>
<para>
This chapter originally appeared as a part of
This chapter introduces the mathematical concepts behind
relational databases. It is not required reading, so if you bog
down or want to get straight to some simple examples feel free to
jump ahead to the next chapter and come back when you have more
time and patience. This stuff is supposed to be fun!
</para>
<para>
This material originally appeared as a part of
Stefan Simkovics' Master's Thesis
(<xref linkend="SIM98" endterm="SIM98">).
</para>
</abstract>
<para>
<acronym>SQL</acronym> has become the most popular relational query language.
<acronym>SQL</acronym> has become the most popular relational query
language.
The name <quote><acronym>SQL</acronym></quote> is an abbreviation for
<firstterm>Structured Query Language</firstterm>.
In 1974 Donald Chamberlin and others defined the
language SEQUEL (<firstterm>Structured English Query Language</firstterm>) at IBM
language SEQUEL (<firstterm>Structured English Query
Language</firstterm>) at IBM
Research. This language was first implemented in an IBM
prototype called SEQUEL-XRM in 1974-75. In 1976-77 a revised version
of SEQUEL called SEQUEL/2 was defined and the name was changed to
@ -28,13 +38,15 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
<para>
A new prototype called System R was developed by IBM in 1977. System R
implemented a large subset of SEQUEL/2 (now <acronym>SQL</acronym>) and a number of
implemented a large subset of SEQUEL/2 (now <acronym>SQL</acronym>)
and a number of
changes were made to <acronym>SQL</acronym> during the project.
System R was installed in
a number of user sites, both internal IBM sites and also some selected
customer sites. Thanks to the success and acceptance of System R at
those user sites IBM started to develop commercial products that
implemented the <acronym>SQL</acronym> language based on the System R technology.
implemented the <acronym>SQL</acronym> language based on the System
R technology.
</para>
<para>
@ -48,16 +60,20 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
</para>
<para>
<acronym>SQL</acronym> is also an official standard now. In 1982 the American National
Standards Institute (<acronym>ANSI</acronym>) chartered its Database Committee X3H2 to
<acronym>SQL</acronym> is also an official standard now. In 1982
the American National
Standards Institute (<acronym>ANSI</acronym>) chartered its
Database Committee X3H2 to
develop a proposal for a standard relational language. This proposal
was ratified in 1986 and consisted essentially of the IBM dialect of
<acronym>SQL</acronym>. In 1987 this <acronym>ANSI</acronym>
standard was also accepted as an international
standard by the International Organization for Standardization
(<acronym>ISO</acronym>).
This original standard version of <acronym>SQL</acronym> is often referred to,
informally, as "<abbrev>SQL/86</abbrev>". In 1989 the original standard was extended
This original standard version of <acronym>SQL</acronym> is often
referred to,
informally, as "<abbrev>SQL/86</abbrev>". In 1989 the original
standard was extended
and this new standard is often, again informally, referred to as
"<abbrev>SQL/89</abbrev>". Also in 1989, a related standard called
<firstterm>Database Language Embedded <acronym>SQL</acronym></firstterm>
@ -73,12 +89,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
ratified standard - "International Standard ISO/IEC 9075:1992,
Database Language <acronym>SQL</acronym>" - in late 1992.
<acronym>SQL/92</acronym> is the version
normally meant when people refer to "the <acronym>SQL</acronym> standard". A detailed
normally meant when people refer to "the <acronym>SQL</acronym>
standard". A detailed
description of <acronym>SQL/92</acronym> is given in
<xref linkend="DATE97" endterm="DATE97">. At the time of
writing this document a new standard informally referred to
as <firstterm><acronym>SQL3</acronym></firstterm>
is under development. It is planned to make <acronym>SQL</acronym> a Turing-complete
is under development. It is planned to make <acronym>SQL</acronym>
a Turing-complete
language, i.e. all computable queries (e.g. recursive queries) will be
possible. This is a very complex task and therefore the completion of
the new standard can not be expected before 1999.
@ -100,8 +118,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
</para>
<para>
A <firstterm>relational database</firstterm> is a database that is perceived by its
users as a <firstterm>collection of tables</firstterm> (and nothing else but tables).
A <firstterm>relational database</firstterm> is a database that is
perceived by its
users as a <firstterm>collection of tables</firstterm> (and
nothing else but tables).
A table consists of rows and columns where each row represents a
record and each column represents an attribute of the records
contained in the table.
@ -154,13 +174,16 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
</para>
<para>
The tables PART and SUPPLIER may be regarded as <firstterm>entities</firstterm> and
SELLS may be regarded as a <firstterm>relationship</firstterm> between a particular
The tables PART and SUPPLIER may be regarded as
<firstterm>entities</firstterm> and
SELLS may be regarded as a <firstterm>relationship</firstterm>
between a particular
part and a particular supplier.
</para>
<para>
As we will see later, <acronym>SQL</acronym> operates on tables like the ones just
As we will see later, <acronym>SQL</acronym> operates on tables
like the ones just
defined but before that we will study the theory of the relational
model.
</para>
@ -171,7 +194,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
<para>
The mathematical concept underlying the relational model is the
set-theoretic <firstterm>relation</firstterm> which is a subset of the Cartesian
set-theoretic <firstterm>relation</firstterm> which is a subset of
the Cartesian
product of a list of domains. This set-theoretic relation gives
the model its name (do not confuse it with the relationship from the
<firstterm>Entity-Relationship model</firstterm>).
@ -184,7 +208,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.7 2000/03/31 03:27:41 thomas E
<para>
<!--
\begin{definition}
The <firstterm>Cartesian product</firstterm> of domains $D_{1}, D_{2},\ldots, D_{k}$ written
The <firstterm>Cartesian product</firstterm> of domains $D_{1},
D_{2},\ldots, D_{k}$ written
\mbox{$D_{1} \times D_{2} \times \ldots \times D_{k}$} is the set of
all $k$-tuples $(v_{1},v_{2},\ldots,v_{k})$ such that \mbox{$v_{1} \in
D_{1}, v_{2} \in D_{2}, \ldots, v_{k} \in D_{k}$}.
@ -304,8 +329,10 @@ attributes are taken from. We often write a relation scheme as
<note>
<para>
A <firstterm>relation scheme</firstterm> is just a kind of template
whereas a <firstterm>relation</firstterm> is an instance of a <firstterm>relation
scheme</firstterm>. The relation consists of tuples (and can therefore be
whereas a <firstterm>relation</firstterm> is an instance of a
<firstterm>relation
scheme</firstterm>. The relation consists of tuples (and can
therefore be
viewed as a table); not so the relation scheme.
</para>
</note>
@ -332,8 +359,10 @@ attributes are taken from. We often write a relation scheme as
<type>VARCHAR(20)</type> (this is the <acronym>SQL</acronym> type
for character strings of length &lt;= 20),
the type of <classname>SNO</classname> will be
<type>INTEGER</type>. With the assignment of a data type we also have selected
a domain for an attribute. The domain of <classname>SNAME</classname> is the set of all
<type>INTEGER</type>. With the assignment of a data type we also
have selected
a domain for an attribute. The domain of
<classname>SNAME</classname> is the set of all
character strings of length &lt;= 20,
the domain of <classname>SNO</classname> is the set of
all integer numbers.
@ -345,7 +374,8 @@ attributes are taken from. We often write a relation scheme as
<title id="operations">Operations in the Relational Data Model</title>
<para>
In the previous section (<xref linkend="formal-notion" endterm="formal-notion">)
In the previous section
(<xref linkend="formal-notion" endterm="formal-notion">)
we defined the mathematical notion of
the relational model. Now we know how the data can be stored using a
relational data model but we do not know what to do with all these
@ -357,7 +387,8 @@ attributes are taken from. We often write a relation scheme as
<itemizedlist>
<listitem>
<para>
The <firstterm>Relational Algebra</firstterm> which is an algebraic notation,
The <firstterm>Relational Algebra</firstterm> which is an
algebraic notation,
where queries are expressed by applying specialized operators to the
relations.
</para>
@ -365,7 +396,8 @@ attributes are taken from. We often write a relation scheme as
<listitem>
<para>
The <firstterm>Relational Calculus</firstterm> which is a logical notation,
The <firstterm>Relational Calculus</firstterm> which is a
logical notation,
where queries are expressed by formulating some logical restrictions
that the tuples in the answer must satisfy.
</para>
@ -383,7 +415,8 @@ attributes are taken from. We often write a relation scheme as
<itemizedlist>
<listitem>
<para>
SELECT (&sigma;): extracts <firstterm>tuples</firstterm> from a relation that
SELECT (&sigma;): extracts <firstterm>tuples</firstterm> from
a relation that
satisfy a given restriction. Let <parameter>R</parameter> be a
table that contains an attribute
<parameter>A</parameter>.
@ -441,10 +474,12 @@ attributes are taken from. We often write a relation scheme as
INTERSECT (&cap;): builds the set-theoretic intersection of two
tables. Given the tables <classname>R</classname> and
<classname>S</classname>,
<classname>R</classname> &cup; <classname>S</classname> is the set of tuples
<classname>R</classname> &cup; <classname>S</classname> is the
set of tuples
that are in <classname>R</classname> and in
<classname>S</classname>.
We again require that <classname>R</classname> and <classname>S</classname> have the
We again require that <classname>R</classname> and
<classname>S</classname> have the
same arity.
</para>
</listitem>
@ -455,7 +490,8 @@ attributes are taken from. We often write a relation scheme as
two tables. Let <classname>R</classname> and <classname>S</classname>
again be two tables with the same
arity. <classname>R</classname> - <classname>S</classname>
is the set of tuples in <classname>R</classname> but not in <classname>S</classname>.
is the set of tuples in <classname>R</classname> but not in
<classname>S</classname>.
</para>
</listitem>
@ -672,9 +708,9 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
the one underlying the most relational languages. For a detailed
discussion on <acronym>DRC</acronym> (and also
<acronym>TRC</acronym>) see
[<xref linkend="DATE94" endterm="DATE94">]
<xref linkend="DATE94" endterm="DATE94">
or
[<xref linkend="ULL88" endterm="ULL88">].
<xref linkend="ULL88" endterm="ULL88">.
</para>
</sect2>
@ -727,9 +763,9 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
algorithm</quote>) by which an arbitrary expression of the relational
calculus can be reduced to a semantically equivalent expression of
relational algebra. For a more detailed discussion on that refer to
[<xref linkend="DATE94" endterm="DATE94">]
<xref linkend="DATE94" endterm="DATE94">
and
[<xref linkend="ULL88" endterm="ULL88">].
<xref linkend="ULL88" endterm="ULL88">.
</para>
<para>
@ -750,9 +786,11 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
<acronym>SQL</acronym> is based on the tuple
relational calculus. As a result every query that can be formulated
using the tuple relational calculus (or equivalently, relational
algebra) can also be formulated using <acronym>SQL</acronym>. There are, however,
algebra) can also be formulated using
<acronym>SQL</acronym>. There are, however,
capabilities beyond the scope of relational algebra or calculus. Here
is a list of some additional features provided by <acronym>SQL</acronym> that are not
is a list of some additional features provided by
<acronym>SQL</acronym> that are not
part of relational algebra or calculus:
<itemizedlist>
@ -764,7 +802,8 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
<listitem>
<para>
Arithmetic capability: In <acronym>SQL</acronym> it is possible to involve
Arithmetic capability: In <acronym>SQL</acronym> it is possible
to involve
arithmetic operations as well as comparisons, e.g.
A &lt; B + 3.
@ -787,7 +826,8 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
<para>
Aggregate Functions: Operations such as
<firstterm>average</firstterm>, <firstterm>sum</firstterm>,
<firstterm>max</firstterm>, etc. can be applied to columns of a relation to
<firstterm>max</firstterm>, etc. can be applied to columns of a
relation to
obtain a single quantity.
</para>
</listitem>
@ -918,7 +958,8 @@ t<subscript>r</subscript>(A,B)=t&and;t<subscript>r</subscript>(C,D)=t<subscript>
Note that the word DOUBLE after the keyword AS is the new title of the
second column. This technique can be used for every element of the
target list to assign a new title to the resulting column. This new title
target list to assign a new title to the resulting
column. This new title
is often referred to as alias. The alias cannot be used throughout the
rest of the query.
</para>
@ -1508,8 +1549,10 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<para>
A view may be regarded as a <firstterm>virtual table</firstterm>,
i.e. a table that
does not <emphasis>physically</emphasis> exist in the database but looks to the user
as if it does. By contrast, when we talk of a <firstterm>base table</firstterm> there is
does not <emphasis>physically</emphasis> exist in the database
but looks to the user
as if it does. By contrast, when we talk of a
<firstterm>base table</firstterm> there is
really a physically stored counterpart of each row of the table
somewhere in the physical storage.
</para>
@ -1550,7 +1593,8 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<para>
Let the following view definition be given (we use
the tables from <xref linkend="supplier-fig" endterm="supplier-fig"> again):
the tables from
<xref linkend="supplier-fig" endterm="supplier-fig"> again):
<programlisting>
CREATE VIEW London_Suppliers
@ -1587,7 +1631,8 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<emphasis>hidden</emphasis>
access to the base tables SUPPLIER, SELLS and PART first. It
does so by executing the query given in the view definition against
those base tables. After that the additional qualifications (given in the
those base tables. After that the additional qualifications
(given in the
query against the view) can be applied to obtain the resulting
table.
</para>
@ -1746,11 +1791,12 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<!--
section
<xref linkend="view-impl" endterm="view-impl">.
<citetitle>SIM98</citetitle>
-->
<citetitle>SIM98</citetitle>
<xref linkend="SIM98" endterm="SIM98">
for a more detailed
description). For more information about system catalogs refer to
<citetitle>DATE</citetitle>.
<xref linkend="DATE94" endterm="DATE94">.
</para>
</sect2>
@ -1815,10 +1861,10 @@ The only tuple returned by both parts of the query is the one having $SNO=2$.
<para>
For a detailed discussion on embedded <acronym>SQL</acronym>
refer to
[<xref linkend="DATE97" endterm="DATE97">],
[<xref linkend="DATE94" endterm="DATE94">],
<xref linkend="DATE97" endterm="DATE97">,
<xref linkend="DATE94" endterm="DATE94">,
or
[<xref linkend="ULL88" endterm="ULL88">].
<xref linkend="ULL88" endterm="ULL88">.
</para>
</sect2>
</sect1>

533
doc/src/sgml/start.sgml
View File

@ -1,250 +1,333 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.9 2000/03/31 03:27:41 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.10 2000/04/07 13:30:58 thomas Exp $
-->
<Chapter Id="start">
<Title>Getting Started</Title>
<chapter id="start">
<title>Getting Started</title>
<Abstract>
<Para>
How to begin work with <ProductName>Postgres</ProductName> for a new user.
</Para>
</Abstract>
<abstract>
<para>
How to begin work with <productname>Postgres</productname> for a new user.
</para>
</abstract>
<Para>
Some of the steps required to use <ProductName>Postgres</ProductName>
can be performed by any Postgres user, and some must be done by
the site database administrator. This site administrator
is the person who installed the software, created
the database directories and started the <Application>postmaster</Application>
process. This person does not have to be the Unix
superuser (<Quote>root</Quote>)
or the computer system administrator; a person can install and use
<ProductName>Postgres</ProductName> without any special accounts or privileges.
</Para>
<para>
Some of the steps required to use <productname>Postgres</productname>
can be performed by any Postgres user, and some must be done by
the site database administrator. This site administrator
is the person who installed the software, created
the database directories and started the
<application>postmaster</application>
process. This person does not have to be the Unix
superuser (<quote>root</quote>)
or the computer system administrator; a person can install and use
<productname>Postgres</productname> without any special accounts or
privileges.
</para>
<Para>
If you are installing <ProductName>Postgres</ProductName> yourself, then
refer to the Administrator's Guide for instructions on installation, and return
to this guide when the installation is complete.
</Para>
<para>
If you are installing <productname>Postgres</productname> yourself, then
refer to the Administrator's Guide for instructions on
installation, and return
to this guide when the installation is complete.
</para>
<Para>
Throughout this manual, any examples that begin with
the character <Quote>%</Quote> are commands that should be typed
at the Unix shell prompt. Examples that begin with the
character <Quote>*</Quote> are commands in the Postgres query
language, Postgres <Acronym>SQL</Acronym>.
</Para>
<para>
Throughout this manual, any examples that begin with
the character <quote>%</quote> are commands that should be typed
at the Unix shell prompt. Examples that begin with the
character <quote>*</quote> are commands in the Postgres query
language, Postgres <acronym>SQL</acronym>.
</para>
<Sect1>
<Title>Setting Up Your Environment</Title>
<sect1>
<title>Setting Up Your Environment</title>
<Para>
This section discusses how to set up
your own environment so that you can use frontend
applications. We assume <ProductName>Postgres</ProductName> has already been
successfully installed and started; refer to the Administrator's Guide
and the installation notes
for how to install Postgres.
</Para>
<para>
This section discusses how to set up
your own environment so that you can use frontend
applications. We assume <productname>Postgres</productname> has
already been
successfully installed and started; refer to the Administrator's Guide
and the installation notes
for how to install Postgres.
</para>
<Para>
<ProductName>Postgres</ProductName> is a client/server application. As a user,
you only need access to the client portions of the installation (an example
of a client application is the interactive monitor <Application>psql</Application>).
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>
<para>
<productname>Postgres</productname> is a client/server
application. As a user,
you only need access to the client portions of the installation
(an example
of a client application is the interactive monitor
<application>psql</application>).
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 <FileName>.login</FileName> 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>
</programlisting>
in the <filename>.login</filename> 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 <Quote>setting a shell
variable</Quote> or <Quote>setting an environment variable</Quote> 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>
</programlisting>
<Para>
If your site administrator has 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 <Acronym>PGHOST</Acronym> environment variable to the name
of the database server machine. The environment variable
<Acronym>PGPORT</Acronym> 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 should immediately consult your site administrator to make sure that your
environment is properly set up.
</Para>
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 <quote>setting a shell
variable</quote> or <quote>setting an environment
variable</quote> 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>
</Sect1>
<para>
If your site administrator has 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 <acronym>PGHOST</acronym> environment
variable to the name
of the database server machine. The environment variable
<acronym>PGPORT</acronym> 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 should immediately consult your site administrator to make
sure that your
environment is properly set up.
</para>
<Sect1>
<Title>Starting the Interactive Monitor (psql)</Title>
</sect1>
<Para>
Assuming that your site administrator has properly
started the <Application>postmaster</Application> process and authorized you to
use the database, you (as a user) may begin to start up
applications. As previously mentioned, you should add
<FileName>/usr/local/pgsql/bin</FileName> to your shell search path.
In most cases, this is all you should have to do in
terms of preparation.
</Para>
<sect1>
<title>Starting the Interactive Monitor (psql)</title>
<Para>
As of <ProductName>Postgres</ProductName> v6.3, two different styles of connections
are supported. The site administrator will have chosen to allow TCP/IP network connections
or will have restricted database access to local (same-machine) socket connections only.
These choices become significant if you encounter problems in connecting to a database.
</Para>
<para>
Assuming that your site administrator has properly
started the <application>postmaster</application> process and
authorized you to
use the database, you (as a user) may begin to start up
applications. As previously mentioned, you should add
<filename>/usr/local/pgsql/bin</filename> to your shell search path.
In most cases, this is all you should have to do in
terms of preparation.
</para>
<Para>
If you get the following error message from a <ProductName>Postgres</ProductName>
command (such as <Application>psql</Application> or <Application>createdb</Application>):
<para>
Two different styles of connections
are supported. The site administrator will have chosen to allow
TCP/IP network connections
or will have restricted database access to local (same-machine)
socket connections only.
These choices become significant if you encounter problems in
connecting to a database, since you will want to confirm that you
are choosing an allowed connection option.
</para>
<ProgramListing>
<para>
If you get the following error message from a
<productname>Postgres</productname>
command (such as <application>psql</application> or
<application>createdb</application>):
<programlisting>
% psql template1
Connection to database 'postgres' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '5432'?
</ProgramListing>
</programlisting>
or
or
<ProgramListing>
<programlisting>
% psql -h localhost template1
Connection to database 'postgres' failed.
connectDB() failed: Is the postmaster running and accepting TCP/IP
(with -i) connections at 'localhost' on port '5432'?
</ProgramListing>
</programlisting>
it is usually because (1) the <Application>postmaster</Application> is not running,
or (2) you are attempting to connect to the wrong server host.
If you get the following error message:
it is usually because
<ProgramListing>
<itemizedlist mark="bullet" spacing="compact">
<listitem>
<para>
the <application>postmaster</application> is not running,
or
</para>
</listitem>
<listitem>
<para>
you are attempting to connect to the wrong server host.
</para>
</listitem>
</itemizedlist>
</para>
<para>
If you get the following error message:
<programlisting>
FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
</ProgramListing>
</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>
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>Managing a Database</Title>
<sect1>
<title>Managing a Database</title>
<Para>
Now that <ProductName>Postgres</ProductName> is up and running we can create some
databases to experiment with. Here, we describe the
basic commands for managing a database.
</Para>
<para>
Now that <productname>Postgres</productname> is up and running we
can create some
databases to experiment with. Here, we describe the
basic commands for managing a database.
</para>
<Para>
Most <ProductName>Postgres</ProductName>
applications assume that the database name, if not specified, is the same as the name on your computer
account.
</Para>
<para>
Most <productname>Postgres</productname>
applications assume that the database name, if not specified, is
the same as the name on your computer
account.
</para>
<Para>
If your database administrator has set up your account without database creation privileges,
then she should have told you what the name of your database is. If this is the case, then you
can skip the sections on creating and destroying databases.
</Para>
<para>
If your database administrator has set up your account without
database creation privileges,
then she should have told you what the name of your database is. If
this is the case, then you
can skip the sections on creating and destroying databases.
</para>
<Sect2>
<Title>Creating a Database</Title>
<sect2>
<title>Creating a Database</title>
<Para>
Let's say you want to create a database named <Database>mydb</Database>.
<para>
Let's say you want to create a database named
<database>mydb</database>.
You can do this with the following command:
<ProgramListing>
<programlisting>
% createdb mydb
</ProgramListing>
</Para>
</programlisting>
</para>
<Para>
If you do not have the privileges required to create a database, you will see
the following:
<ProgramListing>
<para>
If you do not have the privileges required to create a database,
you will see
the following:
<programlisting>
% createdb mydb
WARN:user "your username" is not allowed to create/destroy databases
createdb: database creation failed on mydb.
</ProgramListing>
</Para>
</programlisting>
</para>
<Para>
<ProductName>Postgres</ProductName> allows you to create any number of databases
<para>
<productname>Postgres</productname> allows you to create any
number of databases
at a given site and you automatically become the
database administrator of the database you just created. Database names must have an alphabetic first
database administrator of the database you just created.
Database names must have an alphabetic first
character and are limited to 32 characters in length.
Not every user has authorization to become a database
administrator. If <ProductName>Postgres</ProductName> refuses to create databases
administrator. If <productname>Postgres</productname> refuses to
create databases
for you, then the site administrator needs to grant you
permission to create databases. Consult your site
administrator if this occurs.
</Para>
</Sect2>
</para>
</sect2>
<Sect2>
<Title>Accessing a Database</Title>
<sect2>
<title>Accessing a Database</title>
<Para>
<para>
Once you have constructed a database, you can access it
by:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
running the <ProductName>Postgres</ProductName> terminal monitor programs
(e.g. <Application>psql</Application>) which allows you to interactively
enter, edit, and execute <Acronym>SQL</Acronym> commands.
</Para>
</ListItem>
<ListItem>
<Para>
writing a <Acronym>C</Acronym> program using the LIBPQ subroutine
library. This allows you to submit <Acronym>SQL</Acronym> commands
from <Acronym>C</Acronym> and get answers and status messages back to
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<para>
Running the <productname>Postgres</productname> terminal
monitor programs
(e.g. <application>psql</application>) which allows you to
interactively
enter, edit, and execute <acronym>SQL</acronym> commands.
</para>
</listitem>
<listitem>
<para>
Using an existing native frontend tool like
<application>pgaccess</application> or
<application>ApplixWare</application> (via
<acronym>ODBC</acronym>) to create and manipulate a
database.
</para>
</listitem>
<listitem>
<para>
Using a language like perl or tcl which has a supported
interface for <productname>Postgres</productname>. Some of
these languages also have convenient and powerful GUI toolkits
which can help you construct custom
applications. <application>pgaccess</application>, mentioned
above, is one such application written in tk/tcl and can be
used as an example.
</para>
</listitem>
<listitem>
<para>
Writing a <acronym>C</acronym> program using
the LIBPQ subroutine
library. This allows you to submit
<acronym>SQL</acronym> commands
from <acronym>C</acronym> and get answers and
status messages back to
your program. This interface is discussed further
in <citetitle>The PostgreSQL Programmer's Guide</citetitle>.
</Para>
</ListItem>
</ItemizedList>
</para>
</listitem>
</itemizedlist>
You might want to start up <Application>psql</Application>,
to try out the examples in this manual.
It can be activated for the <Database>mydb</Database>
You might want to start up <application>psql</application>,
to try out the examples in this manual.
It can be activated for the <database>mydb</database>
database by typing the command:
<ProgramListing>
<programlisting>
% psql mydb
</ProgramListing>
</programlisting>
You will be greeted with the following message:
<ProgramListing>
<programlisting>
Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL
@ -254,71 +337,79 @@ Welcome to the POSTGRESQL interactive sql monitor:
You are currently connected to the database: template1
mydb=>
</ProgramListing>
</Para>
</programlisting>
</para>
<Para>
This prompt indicates that the terminal monitor is listening
to you and that you can type <Acronym>SQL</Acronym> queries into a
<para>
This prompt indicates that the terminal monitor is listening
to you and that you can type <acronym>SQL</acronym> queries into a
workspace maintained by the terminal monitor.
The <Application>psql</Application> program responds to escape codes that begin
with the backslash character, <Quote>\</Quote> For example, you
The <application>psql</application> program responds to escape
codes that begin
with the backslash character, <quote>\</quote> For example, you
can get help on the syntax of various
<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> commands by typing:
<ProgramListing>
<productname>Postgres</productname> <acronym>SQL</acronym>
commands by typing:
<programlisting>
mydb=> \h
</ProgramListing>
</programlisting>
</para>
<para>
Once you have finished entering your queries into the
workspace, you can pass the contents of the workspace
to the <ProductName>Postgres</ProductName> server by typing:
<ProgramListing>
to the <productname>Postgres</productname> server by typing:
<programlisting>
mydb=> \g
</ProgramListing>
</programlisting>
This tells the server to process the query. If you
terminate your query with a semicolon, the <Quote>\g</Quote> is not
terminate your query with a semicolon, the <quote>\g</quote> is not
necessary.
<Application>psql</Application> will automatically process semicolon terminated queries.
<application>psql</application> will automatically process
semicolon terminated queries.
To read queries from a file, say myFile, instead of
entering them interactively, type:
<ProgramListing>
<programlisting>
mydb=> \i fileName
</ProgramListing>
</programlisting>
To get out of <Application>psql</Application> and return to Unix, type
<ProgramListing>
To get out of <application>psql</application> and return to Unix, type
<programlisting>
mydb=> \q
</ProgramListing>
</programlisting>
and <Application>psql</Application> will quit and return you to your command
shell. (For more escape codes, type <Command>\h</Command> at the monitor
prompt.)
and <application>psql</application> will quit and return
you to your command
shell. (For more escape codes, type <command>\h</command> at the
monitor prompt.)
White space (i.e., spaces, tabs and newlines) may be
used freely in <Acronym>SQL</Acronym> queries. Single-line comments are denoted by
<Quote>--</Quote>. Everything after the dashes up to the end of the
used freely in <acronym>SQL</acronym> queries. Single-line
comments are denoted by
<quote>--</quote>. Everything after the dashes up to the end of the
line is ignored. Multiple-line comments, and comments within a line,
are denoted by <Quote>/* ... */</Quote>
</Para>
</Sect2>
<Sect2>
<Title>Destroying a Database</Title>
are denoted by <quote>/* ... */</quote>
</para>
</sect2>
<Para>
<sect2>
<title>Destroying a Database</title>
<para>
If you are the database administrator for the database
<Database>mydb</Database>, you can destroy it using the following Unix command:
<ProgramListing>
<database>mydb</database>, you can destroy it using the
following Unix command:
<programlisting>
% dropdb mydb
</ProgramListing>
</programlisting>
This action physically removes all of the Unix files
associated with the database and cannot be undone, so
this should only be done with a great deal of forethought.
</Para>
</Sect2>
</Sect1>
</para>
</sect2>
</sect1>
</Chapter>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:

7
doc/src/sgml/y2k.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.5 2000/03/31 03:27:42 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.6 2000/04/07 13:30:58 thomas Exp $
-->
<sect1 id="y2k">
@ -11,7 +11,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.5 2000/03/31 03:27:42 th
<para>
Written by
<ulink url="mailto:lockhart@alumni.caltech.edu">Thomas Lockhart</ulink>
on 1998-10-22.
on 1998-10-22. Updated 2000-03-31.
</para>
</note>
@ -25,7 +25,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/y2k.sgml,v 1.5 2000/03/31 03:27:42 th
<itemizedlist>
<listitem>
<para>
The author of this statement, a volunteer on the <productname>Postgres</productname>
The author of this statement, a volunteer on the
<productname>Postgres</productname>
support team since November, 1996, is not aware of
any problems in the <productname>Postgres</productname> code base related
to time transitions around Jan 1, 2000 (Y2K).