Skip to content

P
Postgres FD Implementation
Commit c8cfb0ce authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

SGML source for new documentation.

parent 878531f1
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 19988 additions and 0 deletions
doc/src/Makefile 0 → 100644
View file @ c8cfb0ce
# Postgres documentation makefile
# Thomas Lockhart
PGDOCS= ..
SRCDIR= ../../src
HPATH=$(PGDOCS)/doc
PPATH=$(PGDOCS)/doc
#HSTYLE=/usr/lib/sgml/stylesheets/jade/docbook/html
#PSTYLE=/usr/lib/sgml/stylesheets/jade/docbook/print
HSTYLE=/home/tgl/SGML/db107.d/docbook/html
PSTYLE=/home/tgl/SGML/db107.d/docbook/print
HDSL=$(HSTYLE)/docbook.dsl
PDSL=$(PSTYLE)/docbook.dsl
#DBOPTS=-V %no-split-output% -V %no-make-index%
TAR= tar
TAREXCLUDE= --exclude=Makefile --exclude='*.sgml'
# Pick up Makefile.custom from the source area
# This is the only resource from the code source area and is optional
ifneq ($(wildcard $(SRCDIR)/Makefile.custom), )
include $(SRCDIR)/Makefile.custom
endif
TARGETS= postgres tutorial user admin programmer
HTARGETS=#make this a mapping from targets
PTARGETS=#make this a mapping from targets
.PRECIOUS: postgres.html postgres.tex postgres.dvi
.PHONY: sources clean
install::
$(MAKE) all
(mv -rf *.gz ..)
all:: $(SGO) $(SGP)
sources::
($(TAR) zcf sources.tar.gz --exclude='*.htm*' --exclude='*.gz' .)
user.tar.gz:
$(MAKE) -C sgml clean
$(MAKE) -C sgml user.html
($(TAR) zcf $@ $(TAREXCLUDE) -C sgml .)
tutorial.tar.gz:
$(MAKE) -C sgml clean
$(MAKE) -C sgml tutorial.html
($(TAR) zcf $@ $(TAREXCLUDE) -C sgml . -C .. -C graphics clientserver.gif)
clean::
(rm -rf *.html *.htm)
distclean::
$(MAKE) -C sgml clean
# Generic production rules
# Compressed file
%.gz: %
(gzip -f $<)
# TAR file for HTML package
%.tar: %.html # %.ps
(tar cf $@ $*.html index.html *.htm *.gif) # $*.ps
(rm -rf index.html *.htm)
# (mkdir $*)
# (rm -rf $*/*)
# (mv *.htm $*/)
# (cd $*/; ln -sf book01.htm index.html)
# (tar cf $@ $*)
# HTML
# Include some softlinks to the generic default file names
%.html: %.sgml $(HDSL)
(rm -rf *.htm)
jade $(DBOPTS) -D sgml -d $(HDSL) -t sgml $<
(ln -sf book01.htm index.html)
(ln -sf book01.htm $*.html)
# (mkdir $(HPATH)/$*) # be sure there is somewhere to put them
# (rm -rf $(HPATH)/$*/*) # remove existing files since some names may be obsolete
# (mv *.htm $(HPATH)/$*/) # and copy 'em over
# (cd $(HPATH)/$*/; ln -sf book01.htm index.html)
# RTF to allow minor editing for hardcopy
# This is used for v6.3 docs
%.rtf: %.sgml $(PDSL)
jade $(DBOPTS) -d $(PDSL) -t rtf $<
# TeX and DVI
%.tex: %.sgml $(PDSL)
jade $(DBOPTS) -d $(PDSL) -t tex $<
%.dvi: %.tex
jadetex $<
jadetex $<
# Postscript from TeX
%.ps: %.dvi
dvips -o $@ $<
# Graphics
%.gif:
cp -p graphics/%.gif .
doc/src/sgml/admin.sgml 0 → 100644
View file @ c8cfb0ce
<!-- admin.sgml
-
- Postgres administrator's guide.
- Derived from postgres.sgml.
- thomas 1998-02-27
-
- -->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity intro SYSTEM "intro.sgml">
<!entity install SYSTEM "install.sgml">
<!entity ports SYSTEM "ports.sgml">
<!entity recovery SYSTEM "recovery.sgml">
<!entity regress SYSTEM "regress.sgml">
<!entity release SYSTEM "release.sgml">
<!entity start-ag SYSTEM "start-ag.sgml">
<!entity biblio SYSTEM "biblio.sgml">
]>
<!-- entity manpages SYSTEM "man/manpages.sgml" subdoc -->
<Book>
<!-- Title information -->
<Title>PostgreSQL Administrator's Guide</Title>
<BookInfo>
<ReleaseInfo>Covering v6.3 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
</AuthorGroup>
<!-- editor in authorgroup is not supported
<AuthorGroup>
-->
<Editor>
<FirstName>Thomas</FirstName>
<SurName>Lockhart</SurName>
<Affiliation>
<OrgName>Caltech/JPL</OrgName>
</Affiliation>
</Editor>
<!--
</AuthorGroup>
-->
<!--
<AuthorInitials>TGL</AuthorInitials>
-->
<Date>(last updated 1998-02-23)</Date>
</BookBiblio>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
</Para>
</LegalNotice>
</BookInfo>
<!--
<TOC> </TOC>
<LOT> </LOT>
-->
<!--
<Dedication>
<Para>
Your name here...
</Para>
</Dedication>
-->
<Preface>
<Title>Summary</Title>
<Para>
<ProductName>Postgres</ProductName>,
developed originally in the UC Berkeley Computer Science Department,
pioneered many of the object-relational concepts
now becoming available in some commercial databases.
It provides SQL92/SQL3 language support,
transaction integrity, and type extensibility.
<ProductName>PostgreSQL</ProductName> is a public-domain, open source descendant
of this original Berkeley code.
</Para>
</Preface>
&intro;
&ports;
&install;
&start-ag;
&recovery;
&regress;
&release;
&biblio;
<INDEX> </INDEX>
</Book>
doc/src/sgml/advanced.sgml 0 → 100644
View file @ c8cfb0ce
<Chapter>
<Title>Advanced <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> Features</Title>
<Para>
Having covered the basics of using <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> to
access your data, we will now discuss those features of
<ProductName>Postgres</ProductName> that distinguish it from conventional data
managers. These features include inheritance, time
travel and non-atomic data values (array- and
set-valued attributes).
Examples in this section can also be found in
<FileName>advance.sql</FileName> in the tutorial directory.
(Refer to <XRef LinkEnd="QUERY"> for how to use it.)
</Para>
<Sect1>
<Title>Inheritance</Title>
<Para>
Let's create two classes. The capitals class contains
state capitals which are also cities. Naturally, the
capitals class should inherit from cities.
<ProgramListing>
CREATE TABLE cities (
name text,
population float,
altitude int -- (in ft)
);
CREATE TABLE capitals (
state char2
) INHERITS (cities);
</ProgramListing>
In this case, an instance of capitals <FirstTerm>inherits</FirstTerm> all
attributes (name, population, and altitude) from its
parent, cities. The type of the attribute name is
<Type>text</Type>, a native <ProductName>Postgres</ProductName> type for variable length
ASCII strings. The type of the attribute population is
<Type>float</Type>, a native <ProductName>Postgres</ProductName> type for double precision
floating point numbers. State capitals have an extra
attribute, state, that shows their state. In <ProductName>Postgres</ProductName>,
a class can inherit from zero or more other classes,
and a query can reference either all instances of a
class or all instances of a class plus all of its
descendants.
<Note>
<Para>
The inheritance hierarchy is a directed acyclic graph.
</Para>
</Note>
For example, the following query finds
all the cities that are situated at an attitude of 500ft or higher:
<ProgramListing>
SELECT name, altitude
FROM cities
WHERE altitude &gt; 500;
+----------+----------+
|name | altitude |
+----------+----------+
|Las Vegas | 2174 |
+----------+----------+
|Mariposa | 1953 |
+----------+----------+
</ProgramListing>
<Para>
On the other hand, to find the names of all cities,
including state capitals, that are located at an altitude
over 500ft, the query is:
<ProgramListing>
SELECT c.name, c.altitude
FROM cities* c
WHERE c.altitude > 500;
</ProgramListing>
which returns:
<ProgramListing>
+----------+----------+
|name | altitude |
+----------+----------+
|Las Vegas | 2174 |
+----------+----------+
|Mariposa | 1953 |
+----------+----------+
|Madison | 845 |
+----------+----------+
</ProgramListing>
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>)
support this <Quote>*</Quote> notation, as do others, like <Command>alter</Command>.
</Para>
</Sect1>
<Sect1>
<Title>Non-Atomic Values</Title>
<Para>
One of the tenets of the relational model is that the
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
are arrays of base types.
<Sect2>
<Title>Arrays</Title>
<Para>
<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
class with arrays of base types.
<ProgramListing>
CREATE TABLE SAL_EMP (
name text,
pay_by_quarter int4[],
schedule char16[][]
);
</ProgramListing>
</Para>
<Para>
The above query will create a class named SAL_EMP with
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>char16</FirstTerm>
(schedule), which represents the employee's weekly
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>,
this is not unlike the syntax for initializing structures.
<ProgramListing>
INSERT INTO SAL_EMP
VALUES ('Bill',
'{10000, 10000, 10000, 10000}',
'{{"meeting", "lunch"}, {}}');
INSERT INTO SAL_EMP
VALUES ('Carol',
'{20000, 25000, 25000, 25000}',
'{{"talk", "consult"}, {"meeting"}}');
</ProgramListing>
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
show how to access a single element of an array at a
time. This query retrieves the names of the employees
whose pay changed in the second quarter:
<ProgramListing>
SELECT name
FROM SAL_EMP
WHERE SAL_EMP.pay_by_quarter[1] &lt;&gt;
SAL_EMP.pay_by_quarter[2];
+------+
|name |
+------+
|Carol |
+------+
</ProgramListing>
</Para>
<Para>
This query retrieves the third quarter pay of all
employees:
<ProgramListing>
SELECT SAL_EMP.pay_by_quarter[3] FROM SAL_EMP;
+---------------+
|pay_by_quarter |
+---------------+
|10000 |
+---------------+
|25000 |
+---------------+
</ProgramListing>
</Para>
<Para>
We can also access arbitrary slices of an array, or
subarrays. This query retrieves the first item on
Bill's schedule for the first two days of the week.
<ProgramListing>
SELECT SAL_EMP.schedule[1:2][1:1]
FROM SAL_EMP
WHERE SAL_EMP.name = 'Bill';
+-------------------+
|schedule |
+-------------------+
|{{"meeting"},{""}} |
+-------------------+
</ProgramListing>
</Para>
</Sect1>
<Sect1>
<Title>Time Travel</Title>
<Para>
As of <ProductName>Postgres</ProductName> v6.2, <Emphasis>time travel is no longer supported</Emphasis>. There are
several reasons for this: performance impact, storage size, and a pg_time file which grows
toward infinite size in a short period of time.
</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.
</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
</Para>
</Note>
<Para>
<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:
<ProgramListing>
SELECT * FROM cities WHERE name = 'Mariposa';
+---------+------------+----------+
|name | population | altitude |
+---------+------------+----------+
|Mariposa | 1320 | 1953 |
+---------+------------+----------+
</ProgramListing>
<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
query:
<ProgramListing>
SELECT name, population
FROM cities['epoch', 'now']
WHERE name = 'Mariposa';
</ProgramListing>
where "epoch" indicates the beginning of the system
clock.
<Note>
<Para>
On UNIX systems, this is always midnight, January 1, 1970 GMT.
</Para>
</Note>
</Para>
If you have executed all of the examples so
far, then the above query returns:
<ProgramListing>
+---------+------------+
|name | population |
+---------+------------+
|Mariposa | 1200 |
+---------+------------+
|Mariposa | 1320 |
+---------+------------+
</ProgramListing>
<Para>
The default beginning of a time range is the earliest
time representable by the system and the default end is
the current time; thus, the above time range can be
abbreviated as ``[,].''
</Para>
<Sect1>
<Title>More Advanced Features</Title>
<Para>
<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.
</Chapter>
doc/src/sgml/arch-dev.sgml 0 → 100644
View file @ c8cfb0ce
<Chapter>
<TITLE>Architecture</TITLE>
<Sect1>
<Title><ProductName>Postgres</ProductName> Architectural Concepts</Title>
<Para>
Before we continue, you should understand the basic
<ProductName>Postgres</ProductName> system architecture. Understanding how the
parts of <ProductName>Postgres</ProductName> interact will make the next chapter
somewhat clearer.
In database jargon, <ProductName>Postgres</ProductName> uses a simple "process
per-user" client/server model. A <ProductName>Postgres</ProductName> session
consists of the following cooperating UNIX processes (programs):
<ItemizedList>
<ListItem>
<Para>
A supervisory daemon process (<Application>postmaster</Application>),
</Para>
</ListItem>
<ListItem>
<Para>
the user's frontend application (e.g., the <Application>psql</Application> program), and
</Para>
</ListItem>
<ListItem>
<Para>
the one or more backend database servers (the <Application>postgres</Application> process itself).
</Para>
</ListItem>
</ItemizedList>
<Para>
A single <Application>postmaster</Application> manages a given collection of
databases on a single host. Such a collection of
databases is called an installation or site. Frontend
applications that wish to access a given database
within an installation make calls to the library.
The library sends user requests over the network to the
<Application>postmaster</Application> (<XRef LinkEnd="ARCHDEV-CONNECTIONS" EndTerm="ARCHDEV-CONNECTIONS">(a)), which in turn starts a new
backend server process (<XRef LinkEnd="ARCHDEV-CONNECTIONS" EndTerm="ARCHDEV-CONNECTIONS">(b))
<Figure id="ARCHDEV-CONNECTIONS">
<Title>How a connection is established</Title>
<Graphic Align="center" FileRef="connections.gif" Format="GIF"></Graphic>
</Figure>
and connects the
frontend process to the new server (<XRef LinkEnd="ARCHDEV-CONNECTIONS" EndTerm="ARCHDEV-CONNECTIONS">(c)). From
that point on, the frontend process and the backend
server communicate without intervention by the
<Application>postmaster</Application>. Hence, the <Application>postmaster</Application> is always running, waiting
for requests, whereas frontend and backend processes
come and go. The <FileName>libpq</FileName> library allows a single
frontend to make multiple connections to backend processes.
However, the frontend application is still a
single-threaded process. Multithreaded frontend/backend
connections are not currently supported in <FileName>libpq</FileName>.
One implication of this architecture is that the
<Application>postmaster</Application> and the backend always run on the same
machine (the database server), while the frontend
application may run anywhere. You should keep this
in mind,
because the files that can be accessed on a client
machine may not be accessible (or may only be accessed
using a different filename) on the database server
machine.
You should also be aware that the <Application>postmaster</Application> and
postgres servers run with the user-id of the <ProductName>Postgres</ProductName>
"superuser." Note that the <ProductName>Postgres</ProductName> superuser does not
have to be a special user (e.g., a user named
"postgres"). Furthermore, the <ProductName>Postgres</ProductName> superuser
should
definitely not be the UNIX superuser, "root"! In any
case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser.
</Para>
</Chapter>
doc/src/sgml/arch-pg.sgml 0 → 100644
View file @ c8cfb0ce
<Chapter>
<TITLE>Architecture</TITLE>
<Sect1>
<Title><ProductName>Postgres</ProductName> Architectural Concepts</Title>
<Para>
Before we continue, you should understand the basic
<ProductName>Postgres</ProductName> system architecture. Understanding how the
parts of <ProductName>Postgres</ProductName> interact will make the next chapter
somewhat clearer.
In database jargon, <ProductName>Postgres</ProductName> uses a simple "process
per-user" client/server model. A <ProductName>Postgres</ProductName> session
consists of the following cooperating UNIX processes (programs):
<ItemizedList>
<ListItem>
<Para>
A supervisory daemon process (<Application>postmaster</Application>),
</Para>
</ListItem>
<ListItem>
<Para>
the user's frontend application (e.g., the <Application>psql</Application> program), and
</Para>
</ListItem>
<ListItem>
<Para>
the one or more backend database servers (the <Application>postgres</Application> process itself).
</Para>
</ListItem>
</ItemizedList>
<Para>
A single <Application>postmaster</Application> manages a given collection of
databases on a single host. Such a collection of
databases is called an installation or site. Frontend
applications that wish to access a given database
within an installation make calls to the library.
The library sends user requests over the network to the
<Application>postmaster</Application>
(<XRef LinkEnd="PGARCH-CONNECTIONS" EndTerm="PGARCH-CONNECTIONS">(a)),
which in turn starts a new backend server process
(<XRef LinkEnd="PGARCH-CONNECTIONS" EndTerm="PGARCH-CONNECTIONS">(b))
<Figure Id="PGARCH-CONNECTIONS">
<Title>How a connection is established</Title>
<Graphic Align="center" FileRef="connections.gif" Format="GIF"></Graphic>
</Figure>
and connects the frontend process to the new server
(<XRef LinkEnd="PGARCH-CONNECTIONS" EndTerm="PGARCH-CONNECTIONS">(c)).
From that point on, the frontend process and the backend
server communicate without intervention by the
<Application>postmaster</Application>. Hence, the <Application>postmaster</Application> is always running, waiting
for requests, whereas frontend and backend processes
come and go. The <FileName>libpq</FileName> library allows a single
frontend to make multiple connections to backend processes.
However, the frontend application is still a
single-threaded process. Multithreaded frontend/backend
connections are not currently supported in <FileName>libpq</FileName>.
One implication of this architecture is that the
<Application>postmaster</Application> and the backend always run on the same
machine (the database server), while the frontend
application may run anywhere. You should keep this
in mind,
because the files that can be accessed on a client
machine may not be accessible (or may only be accessed
using a different filename) on the database server
machine.
You should also be aware that the <Application>postmaster</Application> and
postgres servers run with the user-id of the <ProductName>Postgres</ProductName>
"superuser."
Note that the <ProductName>Postgres</ProductName> superuser does not
have to be a special user (e.g., a user named
"postgres"), although many systems are installed that way.
Furthermore, the <ProductName>Postgres</ProductName> superuser should
definitely not be the UNIX superuser, "root"! In any
case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser.
</Para>
</Chapter>
doc/src/sgml/arch.sgml 0 → 100644
View file @ c8cfb0ce
<Chapter>
<TITLE>Architecture</TITLE>
<Sect1>
<Title><ProductName>Postgres</ProductName> Architectural Concepts</Title>
<Para>
Before we begin, you should understand the basic
<ProductName>Postgres</ProductName> system architecture. Understanding how the
parts of <ProductName>Postgres</ProductName> interact will make the next chapter
somewhat clearer.
In database jargon, <ProductName>Postgres</ProductName> uses a simple "process
per-user" client/server model. A <ProductName>Postgres</ProductName> session
consists of the following cooperating UNIX processes (programs):
<ItemizedList>
<ListItem>
<Para>
A supervisory daemon process (<Application>postmaster</Application>),
</Para>
</ListItem>
<ListItem>
<Para>
the user's frontend application (e.g., the <Application>psql</Application> program), and
</Para>
</ListItem>
<ListItem>
<Para>
the one or more backend database servers (the <Application>postgres</Application> process itself).
</Para>
</ListItem>
</ItemizedList>
<Para>
A single <Application>postmaster</Application> manages a given collection of
databases on a single host. Such a collection of
databases is called an installation or site. Frontend
applications that wish to access a given database
within an installation make calls to the library.
The library sends user requests over the network to the
<Application>postmaster</Application> (<XRef LinkEnd="ARCH-CLIENTSERVER" EndTerm="ARCH-CLIENTSERVER">),
which in turn starts a new backend server process
<Figure Id="ARCH-CLIENTSERVER">
<Title>How a connection is established</Title>
<Graphic Align="center" FileRef="clientserver.gif" Format="GIF"></Graphic>
</Figure>
and connects the
frontend process to the new server. From
that point on, the frontend process and the backend
server communicate without intervention by the
<Application>postmaster</Application>. Hence, the <Application>postmaster</Application> is always running, waiting
for requests, whereas frontend and backend processes
come and go.
<Para>
The <FileName>libpq</FileName> library allows a single
frontend to make multiple connections to backend processes.
However, the frontend application is still a
single-threaded process. Multithreaded frontend/backend
connections are not currently supported in <FileName>libpq</FileName>.
One implication of this architecture is that the
<Application>postmaster</Application> and the backend always run on the same
machine (the database server), while the frontend
application may run anywhere. You should keep this
in mind,
because the files that can be accessed on a client
machine may not be accessible (or may only be accessed
using a different filename) on the database server
machine.
<Para>
You should also be aware that the <Application>postmaster</Application> and
postgres servers run with the user-id of the <ProductName>Postgres</ProductName>
"superuser." Note that the <ProductName>Postgres</ProductName> superuser does not
have to be a special user (e.g., a user named
"postgres"). Furthermore, the <ProductName>Postgres</ProductName> superuser
should
definitely not be the UNIX superuser ("root")! In any
case, all files relating to a database should belong to
this <ProductName>Postgres</ProductName> superuser.
</Para>
</Chapter>
doc/src/sgml/array.sgml 0 → 100644
View file @ c8cfb0ce
<Chapter>
<Title>Arrays</Title>
<Para>
<Note>
<Para>
This must become a chapter on array behavior. Volunteers? - thomas 1998-01-12
</Para>
</Note>
</Para>
<Para>
<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
class with arrays of base types.
<ProgramListing>
CREATE TABLE SAL_EMP (
name text,
pay_by_quarter int4[],
schedule char16[][]
);
</ProgramListing>
</Para>
<Para>
The above query will create a class named SAL_EMP with
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>char16</FirstTerm>
(schedule), which represents the employee's weekly
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>,
this is not unlike the syntax for initializing structures.
<ProgramListing>
INSERT INTO SAL_EMP
VALUES ('Bill',
'{10000, 10000, 10000, 10000}',
'{{"meeting", "lunch"}, {}}');
INSERT INTO SAL_EMP
VALUES ('Carol',
'{20000, 25000, 25000, 25000}',
'{{"talk", "consult"}, {"meeting"}}');
</ProgramListing>
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
show how to access a single element of an array at a
time. This query retrieves the names of the employees
whose pay changed in the second quarter:
<ProgramListing>
SELECT name
FROM SAL_EMP
WHERE SAL_EMP.pay_by_quarter[1] &lt;&gt;
SAL_EMP.pay_by_quarter[2];
+------+
|name |
+------+
|Carol |
+------+
</ProgramListing>
</Para>
<Para>
This query retrieves the third quarter pay of all
employees:
<ProgramListing>
SELECT SAL_EMP.pay_by_quarter[3] FROM SAL_EMP;
+---------------+
|pay_by_quarter |
+---------------+
|10000 |
+---------------+
|25000 |
+---------------+
</ProgramListing>
</Para>
<Para>
We can also access arbitrary slices of an array, or
subarrays. This query retrieves the first item on
Bill's schedule for the first two days of the week.
<ProgramListing>
SELECT SAL_EMP.schedule[1:2][1:1]
FROM SAL_EMP
WHERE SAL_EMP.name = 'Bill';
+-------------------+
|schedule |
+-------------------+
|{{"meeting"},{""}} |
+-------------------+
</ProgramListing>
</Para>
</Chapter>
doc/src/sgml/biblio.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/compiler.sgml 0 → 100644
View file @ c8cfb0ce
<Chapter>
<DocInfo>
<AuthorGroup>
<Author>
<FirstName>Brian</FirstName>
<Surname>Gallew</Surname>
</Author>
</AuthorGroup>
<Date>Transcribed 1998-02-12</Date>
</DocInfo>
<Title>GCC Default Optimizations</Title>
<Para>
<Note>
<Para>
Contributed by <ULink url="mailto:geek+@cmu.edu">Brian Gallew</ULink>
</Para>
</Note>
<Para>
Configuring gcc to use certain flags by default is a simple matter of
editing the
<FileName>/usr/local/lib/gcc-lib/<Replaceable>platform</Replaceable>/<Replaceable>version</Replaceable>/specs</FileName>
file.
The format of this file pretty simple. The file is broken into
sections, each of which is three lines long. The first line is
"*<Replaceable>section_name</Replaceable>:" (e.g. "*asm:").
The second line is a list of flags,
and the third line is blank.
<Para>
The easiest change to make is to append
the desired default flags to the list in the appropriate section. As
an example, let's suppose that I have linux running on a '486 with gcc
2.7.2 installed in the default location. In the file
/usr/local/lib/gcc-lib/i486-linux/2.7.2/specs, 13 lines down I find
the following section:
<ProgramListing>
- ----------SECTION----------
*cc1:
- ----------SECTION----------
</ProgramListing>
As you can see, there aren't any default flags. If I always wanted
compiles of C code to use "-m486 -fomit-frame-pointer", I would
change it to look like:
<ProgramListing>
- ----------SECTION----------
*cc1:
- -m486 -fomit-frame-pointer
- ----------SECTION----------
</ProgramListing>
If I wanted to be able to generate 386 code for another, older linux
box lying around, I'd have to make it look like this:
<ProgramListing>
- ----------SECTION----------
*cc1:
%{!m386:-m486} -fomit-frame-pointer
- ----------SECTION----------
</ProgramListing>
This will always omit frame pointers, any will build 486-optimized
code unless -m386 is specified on the command line.
<Para>
You can actually do quite a lot of customization with the specs file.
Always remember, however, that these changes are global, and affect
all users of the system.
</Chapter>
doc/src/sgml/contacts.sgml 0 → 100644
View file @ c8cfb0ce
<Appendix label="B">
<Title>Contacts</Title>
<Sect1>
<Title>Introduction</Title>
<Para>
</Para>
<Sect1>
<Title>People</Title>
<Para>
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
<ULink url="http://alumni.caltech.edu/~lockhart">Thomas Lockhart</ULink>
works on SQL standards compliance and documentation.
</Para>
</ListItem>
</ItemizedList>
</Para>
</Appendix>
doc/src/sgml/datatype.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/dfunc.sgml 0 → 100644
View file @ c8cfb0ce
<Chapter>
<Title>Linking Dynamically-Loaded Functions</Title>
<Para>
After you have created and registered a user-defined
function, your work is essentially done. <ProductName>Postgres</ProductName>,
however, must load the object code (e.g., a <FileName>.o</FileName> file, or
a shared library) that implements your function. As
previously mentioned, <ProductName>Postgres</ProductName> loads your code at
runtime, as required. In order to allow your code to be
dynamically loaded, you may have to compile and
linkedit it in a special way. This section briefly
describes how to perform the compilation and
linkediting required before you can load your user-defined
functions into a running <ProductName>Postgres</ProductName> server. Note that
this process has changed as of Version 4.2.
<Tip>
<Para>
The old <ProductName>Postgres</ProductName> dynamic
loading mechanism required
in-depth knowledge in terms of executable format, placement
and alignment of executable instructions within memory, etc.
on the part of the person writing the dynamic loader. Such
loaders tended to be slow and buggy. As of Version 4.2, the
<ProductName>Postgres</ProductName> dynamic loading mechanism has been rewritten to use
the dynamic loading mechanism provided by the operating
system. This approach is generally faster, more reliable and
more portable than our previous dynamic loading mechanism.
The reason for this is that nearly all modern versions of
UNIX use a dynamic loading mechanism to implement shared
libraries and must therefore provide a fast and reliable
mechanism. On the other hand, the object file must be
postprocessed a bit before it can be loaded into <ProductName>Postgres</ProductName>. We
hope that the large increase in speed and reliability will
make up for the slight decrease in convenience.
<Para>
</Tip>
You should expect to read (and reread, and re-reread) the
manual pages for the C compiler, cc(1), and the link
editor, ld(1), if you have specific questions. In
addition, the regression test suites in the directory
<FileName>PGROOT/src/regress</FileName> contain several
working examples of this process. If you copy what these
tests do, you should not have any problems.
The following terminology will be used below:
<ItemizedList>
<ListItem>
<Para>
<FirstTerm>Dynamic loading</FirstTerm>
is what <ProductName>Postgres</ProductName> does to an object file. The
object file is copied into the running <ProductName>Postgres</ProductName>
server and the functions and variables within the
file are made available to the functions within
the <ProductName>Postgres</ProductName> process. <ProductName>Postgres</ProductName> does this using
the dynamic loading mechanism provided by the
operating system.
</Para>
</ListItem>
<ListItem>
<Para>
<FirstTerm>Loading and link editing</FirstTerm>
is what you do to an object file in order to produce
another kind of object file (e.g., an executable
program or a shared library). You perform
this using the link editing program, ld(1).
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
The following general restrictions and notes also apply
to the discussion below:
<ItemizedList>
<ListItem>
<Para>
Paths given to the create function command must be
absolute paths (i.e., start with "/") that refer to
directories visible on the machine on which the
<ProductName>Postgres</ProductName> server is running.
<Tip>
<Para>
Relative paths do in fact work,
but are relative to
the directory where the database resides (which is generally
invisible to the frontend application). Obviously, it makes
no sense to make the path relative to the directory in which
the user started the frontend application, since the server
could be running on a completely different machine!
</Para>
</Tip>
</Para>
</ListItem>
<ListItem>
<Para>
The <ProductName>Postgres</ProductName> user must be able to traverse the path
given to the create function command and be able to
read the object file. This is because the <ProductName>Postgres</ProductName>
server runs as the <ProductName>Postgres</ProductName> user, not as the user
who starts up the frontend process. (Making the
file or a higher-level directory unreadable and/or
unexecutable by the "postgres" user is an extremely
common mistake.)
</Para>
</ListItem>
<ListItem>
<Para>
Symbol names defined within object files must not
conflict with each other or with symbols defined in
<ProductName>Postgres</ProductName>.
</Para>
</ListItem>
<ListItem>
<Para>
The GNU C compiler usually does not provide the special
options that are required to use the operating
system's dynamic loader interface. In such cases,
the C compiler that comes with the operating system
must be used.
</Para>
</ListItem>
</ItemizedList>
<Sect1>
<Title><Acronym>ULTRIX</Acronym></Title>
<Para>
It is very easy to build dynamically-loaded object
files under ULTRIX. ULTRIX does not have any sharedlibrary
mechanism and hence does not place any restrictions on
the dynamic loader interface. On the other
hand, we had to (re)write a non-portable dynamic loader
ourselves and could not use true shared libraries.
Under ULTRIX, the only restriction is that you must
produce each object file with the option -G 0. (Notice
that that's the numeral ``0'' and not the letter
``O''). For example,
<ProgramListing>
# simple ULTRIX example
% cc -G 0 -c foo.c
</ProgramListing>
produces an object file called foo.o that can then be
dynamically loaded into <ProductName>Postgres</ProductName>. No additional loading or link-editing must be performed.
</Para>
</Sect1>
<Sect1>
<Title><Acronym>DEC OSF/1</Acronym></Title>
<Para>
Under DEC OSF/1, you can take any simple object file
and produce a shared object file by running the ld command over it with the correct options. The commands to
do this look like:
<ProgramListing>
# simple DEC OSF/1 example
% cc -c foo.c
% ld -shared -expect_unresolved '*' -o foo.so foo.o
</ProgramListing>
The resulting shared object file can then be loaded
into <ProductName>Postgres</ProductName>. When specifying the object file name to
the create function command, one must give it the name
of the shared object file (ending in .so) rather than
the simple object file.
<Tip>
<Para>
Actually, <ProductName>Postgres</ProductName> does not care
what you name the
file as long as it is a shared object file. If you prefer
to name your shared object files with the extension .o, this
is fine with <ProductName>Postgres</ProductName> so long as you make sure that the correct
file name is given to the create function command. In
other words, you must simply be consistent. However, from a
pragmatic point of view, we discourage this practice because
you will undoubtedly confuse yourself with regards to which
files have been made into shared object files and which have
not. For example, it's very hard to write Makefiles to do
the link-editing automatically if both the object file and
the shared object file end in .o!
</Para>
</Tip>
If the file you specify is
not a shared object, the backend will hang!
</Para>
</Sect1>
<Sect1>
<Title>
<Acronym>SunOS 4.x</Acronym>, <Acronym>Solaris 2.x</Acronym> and <Acronym>HP-UX</Acronym></Title>
<Para>
Under SunOS 4.x, Solaris 2.x and HP-UX, the simple
object file must be created by compiling the source
file with special compiler flags and a shared library
must be produced.
The necessary steps with HP-UX are as follows. The +z
flag to the HP-UX C compiler produces so-called
"Position Independent Code" (PIC) and the +u flag
removes
some alignment restrictions that the PA-RISC architecture
normally enforces. The object file must be turned
into a shared library using the HP-UX link editor with
the -b option. This sounds complicated but is actually
very simple, since the commands to do it are just:
<ProgramListing>
# simple HP-UX example
&percnt; cc +z +u -c foo.c
&percnt; ld -b -o foo.sl foo.o
</ProgramListing>
</Para>
<Para>
As with the .so files mentioned in the last subsection,
the create function command must be told which file is
the correct file to load (i.e., you must give it the
location of the shared library, or .sl file).
Under SunOS 4.x, the commands look like:
<ProgramListing>
# simple SunOS 4.x example
&percnt; cc -PIC -c foo.c
&percnt; ld -dc -dp -Bdynamic -o foo.so foo.o
</ProgramListing>
and the equivalent lines under Solaris 2.x are:
<ProgramListing>
# simple Solaris 2.x example
&percnt; cc -K PIC -c foo.c
or
&percnt; gcc -fPIC -c foo.c
&percnt; ld -G -Bdynamic -o foo.so foo.o
</ProgramListing>
</Para>
<Para>
When linking shared libraries, you may have to specify
some additional shared libraries (typically system
libraries, such as the C and math libraries) on your ld
command line.
</Para>
</Sect1>
</Chapter>
doc/src/sgml/docguide.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/ecpg.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/environ.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/extend.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/func-ref.sgml 0 → 100644
View file @ c8cfb0ce
<Chapter>
<Title>Functions</Title>
<Abstract>
<Para>
Reference information for user-callable functions.
</Para>
</Abstract>
<Note>
<Para>
This section needs to be written. Volunteers?
</Para>
</Note>
<Para>
</Para>
</Chapter>
doc/src/sgml/geqo.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/gist.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/inherit.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/install.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/intro-pg.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/intro.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/jdbc.sgml 0 → 100644
View file @ c8cfb0ce
<Chapter>
<Title>JDBC Interface</Title>
<Para>
There is a JDBC interface available for Postgres. It is documented elsewhere using
the accepted tool for Java-language code.
</Chapter>
doc/src/sgml/libpgtcl.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/libpq.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/lobj.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/manage.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/odbc.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/pgaccess.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/ports.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/postgres.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/programmer.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/protocol.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/psql.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/query-ug.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/query.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/recovery.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/regress.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/release.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/rules.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/spi.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/start-ag.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/start.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/storage.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/trigger.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/tutorial.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/user.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/xaggr.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/xfunc.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/xindex.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/xoper.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
doc/src/sgml/xtypes.sgml 0 → 100644
View file @ c8cfb0ce
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment