Skip to content

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

Accumulated fixups. 

Add some chapters on new topics.
Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0
Grepped for and fixed apparent tag mangling from emacs
 "Normalize" operation. Should be the last of those.
parent 2cc8e6ac
Hide whitespace changes
Inline Side-by-side
Showing with 1475 additions and 1410 deletions
doc/src/sgml/admin.sgml
View file @ f75bf187
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.19 2000/03/28 14:16:06 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.20 2000/03/30 22:22:40 thomas Exp $
Postgres Administrator's Guide.
Derived from postgres.sgml.
- thomas 1998-10-27
$Log: admin.sgml,v $
Revision 1.20 2000/03/30 22:22:40 thomas
Accumulated fixups.
Add some chapters on new topics.
Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0
Grepped for and fixed apparent tag mangling from emacs
"Normalize" operation. Should be the last of those.
Revision 1.19 2000/03/28 14:16:06 thomas
Update SGML catalog references to DocBook 3.1 on FreeBSD.
Matches postgresql.org/hub.org environment.
......@@ -34,6 +41,7 @@ Clean out duplicate stuff in odbc.sgml resulting from a faulty patch.
<!entity info SYSTEM "info.sgml">
<!entity legal SYSTEM "legal.sgml">
<!entity notation SYSTEM "notation.sgml">
<!entity problems SYSTEM "problems.sgml">
<!entity y2k SYSTEM "y2k.sgml">
<!entity config SYSTEM "config.sgml">
......
doc/src/sgml/advanced.sgml
View file @ f75bf187
......@@ -3,7 +3,7 @@
<para>
Having covered the basics of using
<productname>e>Postgr</productname>e> <acronym>SQL</acronym> to
<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
......@@ -103,7 +103,7 @@ SELECT c.name, c.altitude
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>and>up</command>and> and <command>delete</command>)
<command>update</command> and <command>delete</command>)
support this <quote>*</quote> notation, as do others, like
<command>alter</command>.
</para>
......
doc/src/sgml/bug-reporting.sgml deleted 100644 → 0
View file @ 2cc8e6ac
<Sect1>
<title>Bug Reporting Guidelines</title>
<para>
When you encounter a bug in <productname>PostgreSQL</productname> we want to
hear about it. Your bug reports are an important part in making
<productname>PostgreSQL</productname> more reliable because even the utmost
care cannot guarantee that every part of PostgreSQL will work on every
platform under every circumstance.
</para>
<para>
The following suggestions are intended to assist you in forming bug reports
that can be handled in an effective fashion. No one is required to follow
them but it tends to be to everyone's advantage.
</para>
<para>
We cannot promise to fix every bug right away. If the bug is obvious, critical,
or affects a lot of users, chances are good that someone will look into it. It
could also happen that we tell you to update to a newer version to see if the
bug happens there. Or we might decide that the bug
cannot be fixed before some major rewrite we might be planning is done. Or
perhaps it's simply too hard and there are more important things on the agenda.
If you need help immediately, consider obtaining a commercial support contract.
</para>
<Sect2>
<title>Identifying Bugs</title>
<para>
Before you ask <quote>Is this a bug?</quote>, please read and re-read the
documentation to verify that you can really do whatever it is you are
trying. If it is not clear from the documentation whether you can do
something or not, please report that too, it's a bug in the documentation.
If it turns out that the program does something different from what the
documentation says, that's a bug. That might include, but is not limited to,
the following circumstances:
<itemizedlist>
<listitem>
<para>
A program terminates with a fatal signal or an operating system
error message that would point to a problem in the program (for
example not <quote>disk full</quote>).
</para>
</listitem>
<listitem>
<para>
A program produces the wrong output for any given input.
</para>
</listitem>
<listitem>
<para>
A program refuses to accept valid input.
</para>
</listitem>
<listitem>
<para>
A program accepts invalid input without a notice or error message.
</para>
</listitem>
<listitem>
<para>
<productname>PostgreSQL</productname> fails to compile, build, or
install according to the instructions on supported platforms.
</para>
</listitem>
</itemizedlist>
Here <quote>program</quote> refers to any executable, not only the backend server.
</para>
<para>
Being slow or resource-hogging is not necessarily a bug. Read the documentation
or ask on one of the mailing lists for help in tuning your applications. Failing
to comply to <acronym>SQL</acronym> is not a bug unless compliance for the
specific feature is explicitly claimed.
</para>
<para>
Before you continue, check on the TODO list and in the FAQ to see if your bug is
already known. If you can't decode the information on the TODO list, report your
problem. The least we can do is make the TODO list clearer.
</para>
</Sect2>
<Sect2>
<title>What to report</title>
<para>
The most important thing to remember about bug reporting is to state all
the facts and only facts. Do not speculate what you think went wrong, what
<quote>it seemed to do</quote>, or which part of the program has a fault.
If you are not familiar with the implementation you would probably guess
wrong and not help us a bit. And even if you are, educated explanations are
a great supplement to but no substitute for facts. If we are going to fix
the bug we still have to see it happen for ourselves first.
Reporting the bare facts
is relatively straightforward (you can probably copy and paste them from the
screen) but all too often important details are left out because someone
thought it doesn't matter or the report would <quote>ring a bell</quote>
anyway.
</para>
<para>
The following items should be contained in every bug report:
<itemizedlist>
<listitem>
<para>
The exact sequence of steps <emphasis>from program startup</emphasis>
necessary to reproduce the problem. This should be self-contained;
it is not enough to send in a bare select statement without the
preceeding create table and insert statements, if the output should
depend on the data in the tables. We do not have the time
to decode your database schema, and if we are supposed to make up
our own data we would probably miss the problem.
The best format for a test case for
query-language related problems is a file that can be run through the
<application>psql</application> frontend
that shows the problem. (Be sure to not have anything in your
<filename>~/.psqlrc</filename> startup file.) You are encouraged to
minimize the size of your example, but this is not absolutely necessary.
If the bug is reproduceable, we'll find it either way.
</para>
<para>
If your application uses some other client interface, such as PHP, then
please try to isolate the offending queries. We probably won't set up a
web server to reproduce your problem. In any case remember to provide
the exact input files, do not guess that the problem happens for
<quote>large files</quote> or <quote>mid-size databases</quote>, etc.
</para>
</listitem>
<listitem>
<para>
The output you got. Please do not say that it <quote>didn't work</quote> or
<quote>failed</quote>. If there is an error message,
show it, even if you don't understand it. If the program terminates with
an operating system error, say which. If nothing at all happens, say so.
Even if the result of your test case is a program crash or otherwise obvious
it might not happen on our platform. The easiest thing is to copy the output
from the terminal, if possible.
</para>
<note>
<para>
In case of fatal errors, the error message provided by the client might
not contain all the information available. In that case, also look at the
output of the database server. If you do not keep your server output,
this would be a good time to start doing so.
</para>
</note>
</listitem>
<listitem>
<para>
The output you expected is very important to state. If you just write
<quote>This command gives me that output.</quote> or <quote>This is not
what I expected.</quote>, we might run it ourselves, scan the output, and
think it looks okay and is exactly what we expected. We shouldn't have to
spend the time to decode the exact semantics behind your commands.
Especially refrain from merely saying that <quote>This is not what SQL says/Oracle
does.</quote> Digging out the correct behavior from <acronym>SQL</acronym>
is not a fun undertaking, nor do we all know how all the other relational
databases out there behave. (If your problem is a program crash you can
obviously omit this item.)
</para>
</listitem>
<listitem>
<para>
Any command line options and other startup options, including concerned
environment variables or configuration files that you changed from the
default. Again, be exact. If you are using a pre-packaged
distribution that starts the database server at boot time, you should try
to find out how that is done.
</para>
</listitem>
<listitem>
<para>
Anything you did at all differently from the installation instructions.
</para>
</listitem>
<listitem>
<para>
The PostgreSQL version. You can run the command
<literal>SELECT version();</literal> to
find out. If this function does not exist, say so, then we know that
your version is old enough. If you can't start up the server or a
client, look into the README file in the source directory or at the
name of your distribution file or package name. If your version is older
than 6.5 we will almost certainly tell you to upgrade. There are tons
of bugs in old versions, that's why we write new ones.
</para>
<para>
If you run a pre-packaged version, such as RPMs, say so, including any
subversion the package may have. If you are talking about a CVS
snapshot, mention that, including its date and time.
</para>
</listitem>
<listitem>
<para>
Platform information. This includes the kernel name and version, C library,
processor, memory information. In most cases it is sufficient to report
the vendor and version, but do not assume everyone knows what exactly
<quote>Debian</quote> contains or that everyone runs on Pentiums. If
you have installation problems information about compilers, make, etc.
is also necessary.
</para>
</listitem>
</itemizedlist>
Do not be afraid if your bug report becomes rather lengthy. That is a fact of life.
It's better to report everything the first time than us having to squeeze the
facts out of you. On the other hand, if your input files are huge, it is
fair to ask first whether somebody is interested in looking into it.
</para>
<para>
Do not spend all your time to figure out which changes in the input make
the problem go away. This will probably not help solving it. If it turns
out that the bug can't be fixed right away, you will still have time to
find and share your work around. Also, once again, do not waste your time
guessing why the bug exists. We'll find that out soon enough.
</para>
<para>
When writing a bug report, please choose non-confusing terminology.
The software package as such is called <quote>PostgreSQL</quote>,
sometimes <quote>Postgres</quote> for short. (Sometimes
the abbreviation <quote>Pgsql</quote> is used but don't do that.) When you
are specifically talking about the backend server, mention that, don't
just say <quote>Postgres crashes</quote>. The interactive frontend is called
<quote>psql</quote> and is for all intends and purposes completely separate
from the backend.
</para>
</Sect2>
<Sect2>
<title>Where to report bugs</title>
<para>
In general, send bug reports to &lt;pgsql-bugs@postgresql.org&gt;. You are
invited to find a descriptive subject for your email message, perhaps parts
of the error message.
</para>
<para>
Do not send bug reports to any of the user mailing lists, such as
pgsql-sql or pgsql-general. These mailing lists are for answering
user questions, their subscribers normally do not wish to receive
bug reports. More importantly, they are unlikely to fix them.
</para>
<para>
Also, please do <emphasis>not</emphasis> send reports to
&lt;pgsql-hackers@postgresql.org&gt;. This list is for discussing the
development of <productname>PostgreSQL</productname>, it would be nice
if we could keep the bug reports separate. We might choose take up a
discussion
about your bug report on it, if the bug needs more review.
</para>
<para>
If you have a problem with the documentation, send email to
&lt;pgsql-docs@postgresql.org&gt;. Refer to the document, chapter, and sections.
</para>
<para>
If your bug is a portability problem on a non-supported platform, send
mail to &lt;pgsql-ports@postgresql.org&gt;, so we (and you) can work on
porting <productname>PostgreSQL</productname> to your platform.
</para>
<note>
<para>
Due to the unfortunate amount of spam going around, all of the above
email addresses are closed mailing lists. That is, you need to be
subscribed to them in order to be allowed to post. If you simply
want to send mail but do not want to receive list traffic, you can
subscribe to the special pgsql-loophole <quote>list</quote>, which
allows you to post to all <productname>PostgreSQL</productname>
mailing lists without receiving any messages. Send email to
&lt;pgsql-loophole-request@postgresql.org&gt; to subscribe.
</para>
</note>
</Sect2>
</Sect1>
doc/src/sgml/ecpg.sgml
View file @ f75bf187
<Chapter Id="ecpg">
<DocInfo>
<AuthorGroup>
<Author>
<FirstName>Linus</FirstName>
<Surname>Tolke</Surname>
</Author>
<Author>
<FirstName>Michael</FirstName>
<Surname>Meskes</Surname>
</Author>
</AuthorGroup>
<Copyright>
<Year>1996-1997</Year>
<Holder>Linus Tolke</Holder>
</Copyright>
<Copyright>
<Year>1998</Year>
<Holder>Michael Meskes</Holder>
</Copyright>
<Date>Transcribed 1998-02-12</Date>
</DocInfo>
<Title><Application>ecpg</Application> - Embedded <Acronym>SQL</Acronym>
in <Acronym>C</Acronym></Title>
<Para>
This describes an embedded <Acronym>SQL</Acronym> in <Acronym>C</Acronym>
package for <ProductName>Postgres</ProductName>.
It is written by <ULink url="mailto:linus@epact.se">Linus Tolke</ULink>
and <ULink url="mailto:meskes@postgresql.org">Michael Meskes</ULink>.
<Note>
<Para>
Permission is granted to copy and use in the same way as you are allowed
to copy and use the rest of the <ProductName>PostgreSQL</ProductName>.
</Para>
</Note>
</para>
<Sect1>
<Title>Why Embedded <Acronym>SQL</Acronym>?</Title>
<Para>
Embedded <Acronym>SQL</Acronym> has some small advantages over other ways
to handle <Acronym>SQL</Acronym>
queries. It takes care of all the tedious moving of information to and
from variables in your <Acronym>C</Acronym> program.
Many <Acronym>RDBMS</Acronym> packages
support this embedded language.
</Para>
<Para> There is an ANSI-standard describing how the embedded language should
work. <Application>ecpg</Application> was designed to meet this standard
as much as possible. So it is
possible to port programs with embedded <Acronym>SQL</Acronym> written for
other <Acronym>RDBMS</Acronym> packages to
<ProductName>Postgres</ProductName> and thus promoting the spirit of free
software.
</Para>
</sect1>
<Sect1>
<Title>The Concept</Title>
<Para>
You write your program in <Acronym>C</Acronym> with some
special <Acronym>SQL</Acronym> things.
For declaring variables that can be used in
<Acronym>SQL</Acronym> statements you need to
put them in a special declare section.
You use a special syntax for the <Acronym>SQL</Acronym> queries.
</Para>
<Para>
Before compiling you run the file through
the embedded <Acronym>SQL</Acronym> <Acronym>C</Acronym>
preprocessor and it converts the <Acronym>SQL</Acronym> statements you used
to function
calls with the variables used as arguments. Both variables that are used
as input to the <Acronym>SQL</Acronym> statements and variables that will
contain the
result are passed.
</Para>
<Para>
Then you compile and at link time you link with a special library that
contains the functions used. These functions (actually it is mostly one
single function) fetches the information from the arguments, performs
the <Acronym>SQL</Acronym> query using the ordinary interface
(<FileName>libpq</FileName>) and puts back
the result in the arguments dedicated for output.
</Para>
<Para>
Then you run your program and when the control arrives to
the <Acronym>SQL</Acronym>
statement the <Acronym>SQL</Acronym> statement is performed against
the database and you
can continue with the result.
</Para>
</sect1>
<Sect1>
<Title>How To Use <Application>egpc</Application></Title>
<Para>
This section describes how to use the <Application>egpc</Application> tool.
</Para>
<Sect2>
<Title>Preprocessor</title>
<Para>
The preprocessor is called <Application>ecpg</Application>.
After installation it resides in
the <ProductName>Postgres</ProductName> <FileName>bin/</FileName> directory.
</Para>
</sect2>
<Sect2>
<Title>Library</title>
<Para>
The <Application>ecpg</Application> library is called
<FileName>libecpg.a</FileName> or
<FileName>libecpg.so</FileName>. Additionally, the library
uses the <FileName>libpq</FileName> library for communication to the
<ProductName>Postgres</ProductName> server so you will
have to link your program with <Parameter>-lecpg -lpq</Parameter>.
</Para>
<Para>
The library has some methods that are "hidden" but that could prove very
useful sometime.
<itemizedlist>
<listitem>
<para>
<function>ECPGdebug(int <replaceable class="parameter">on</replaceable>, FILE *<replaceable class="parameter">stream</replaceable>)</function>
turns on debug logging if called with the first argument non-zero.
Debug logging is done on <replaceable class="parameter">stream</replaceable>.
Most <Acronym>SQL</Acronym> statement logs its arguments and result.
</Para>
<Para>
The most important one (<Function>ECPGdo</Function>)
that is called on almost all <Acronym>SQL</Acronym>
statements logs both its expanded string,
i.e. the string
with all the input variables inserted, and the result from the
<ProductName>Postgres</ProductName> server.
This can be very useful when searching for errors
in your <Acronym>SQL</Acronym> statements.
</Para>
</ListItem>
<listitem>
<para>
<function>ECPGstatus()</function>
This method returns TRUE if we are connected to a database and FALSE if not.
</Para>
</ListItem>
</itemizedlist>
</Para>
</sect2>
<Sect2>
<Title>Error handling</title>
<Para>
To be able to detect errors from the <ProductName>Postgres</ProductName>
server you include a line like
<ProgramListing>
exec sql include sqlca;
</ProgramListing>
in the include section of your file. This will define a struct and a
variable with the name <Parameter>sqlca</Parameter> as following:
<ProgramListing>
<chapter>
<docinfo>
<authorgroup>
<author>
<firstname>Linus</firstname>
<surname>Tolke</surname>
</author>
<author>
<firstname>Michael</firstname>
<surname>Meskes</surname>
</author>
</authorgroup>
<copyright>
<year>1996-1997</year>
<holder>Linus Tolke</holder>
</copyright>
<copyright>
<year>1998</year>
<holder>Michael Meskes</holder>
</copyright>
<date>Transcribed 1998-02-12</date>
</docinfo>
<title><application>ecpg</application> - Embedded <acronym>SQL</acronym>
in <acronym>C</acronym></title>
<para>
This describes an embedded <acronym>SQL</acronym> in <acronym>C</acronym>
package for <productname>Postgres</productname>.
It is written by <ulink url="">Linus Tolke</ulink>
and <ulink url="">Michael Meskes</ulink>.
<note>
<para>
Permission is granted to copy and use in the same way as you are allowed
to copy and use the rest of the <productname>PostgreSQL</productname>.
</para>
</note>
</para>
<sect1>
<title>Why Embedded <acronym>SQL</acronym>?</title>
<para>
Embedded <acronym>SQL</acronym> has some small advantages over other ways
to handle <acronym>SQL</acronym>
queries. It takes care of all the tedious moving of information to and
from variables in your <acronym>C</acronym> program.
Many <acronym>RDBMS</acronym> packages
support this embedded language.
</para>
<para> There is an ANSI-standard describing how the embedded language should
work. <application>ecpg</application> was designed to meet this standard
as much as possible. So it is
possible to port programs with embedded <acronym>SQL</acronym> written for
other <acronym>RDBMS</acronym> packages to
<productname>Postgres</productname> and thus promoting the spirit of free
software.
</para>
</sect1>
<sect1>
<title>The Concept</title>
<para>
You write your program in <acronym>C</acronym> with some
special <acronym>SQL</acronym> things.
For declaring variables that can be used in
<acronym>SQL</acronym> statements you need to
put them in a special declare section.
You use a special syntax for the <acronym>SQL</acronym> queries.
</para>
<para>
Before compiling you run the file through
the embedded <acronym>SQL</acronym> <acronym>C</acronym>
preprocessor and it converts the <acronym>SQL</acronym> statements you used
to function
calls with the variables used as arguments. Both variables that are used
as input to the <acronym>SQL</acronym> statements and variables that will
contain the
result are passed.
</para>
<para>
Then you compile and at link time you link with a special library that
contains the functions used. These functions (actually it is mostly one
single function) fetches the information from the arguments, performs
the <acronym>SQL</acronym> query using the ordinary interface
(<filename>libpq</filename>) and puts back
the result in the arguments dedicated for output.
</para>
<para>
Then you run your program and when the control arrives to
the <acronym>SQL</acronym>
statement the <acronym>SQL</acronym> statement is performed against
the database and you
can continue with the result.
</para>
</sect1>
<sect1>
<title>How To Use <application>ecpg</application></title>
<para>
This section describes how to use the <application>ecpg</application> tool.
</para>
<sect2>
<title>Preprocessor</title>
<para>
The preprocessor is called <application>ecpg</application>.
After installation it resides in
the <productname>Postgres</productname> <filename>bin/</filename> directory.
</para>
</sect2>
<sect2>
<title>Library</title>
<para>
The <application>ecpg</application> library is called
<filename>libecpg.a</filename> or
<filename>libecpg.so</filename>. Additionally, the library
uses the <filename>libpq</filename> library for communication to the
<productname>Postgres</productname> server so you will
have to link your program with <parameter>-lecpg -lpq</parameter>.
</para>
<para>
The library has some methods that are "hidden" but that could prove very
useful sometime.
<itemizedlist>
<listitem>
<para>
<function>ECPGdebug(int <replaceable>on</replaceable>, FILE
*<replaceable>stream</replaceable>)</function>
turns on debug logging if called with the first argument non-zero.
Debug logging is done on <replaceable>stream</replaceable>.
Most <acronym>SQL</acronym> statement logs its arguments and result.
</para>
<para>
The most important one (<function>ECPGdo</function>)
that is called on almost all <acronym>SQL</acronym>
statements logs both its expanded string,
i.e. the string
with all the input variables inserted, and the result from the
<productname>Postgres</productname> server.
This can be very useful when searching for errors
in your <acronym>SQL</acronym> statements.
</para>
</listitem>
<listitem>
<para>
<function>ECPGstatus()</function>
This method returns TRUE if we are connected to a database and FALSE if not.
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
<sect2>
<title>Error handling</title>
<para>
To be able to detect errors from the <productname>Postgres</productname>
server you include a line like
<programlisting>
exec sql include sqlca;
</programlisting>
in the include section of your file. This will define a struct and a
variable with the name <parameter>sqlca</parameter> as following:
<programlisting>
struct sqlca
{
char sqlcaid[8];
......@@ -207,702 +209,712 @@ struct sqlca
/* 7: empty */
char sqlext[8];
} sqlca;
</ProgramListing>
</Para>
<Para>
If an error occured in the last <Acronym>SQL</Acronym> statement
then <Parameter>sqlca.sqlcode</Parameter>
will be non-zero. If <Parameter>sqlca.sqlcode</Parameter> is less that 0
then this is
some kind of serious error, like the database definition does not match
the query given. If it is bigger than 0 then this is a normal error like
the table did not contain the requested row.
</Para>
<Para>
sqlca.sqlerrm.sqlerrmc will contain a string that describes the error.
The string ends with the line number
in the source file.
</Para>
<Para>
List of errors that can occur:
<VariableList>
<VarListEntry>
<Term>-12, Out of memory in line %d.</Term>
<ListItem>
<Para>
Does not normally occur. This is a sign that your virtual memory is
exhausted.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-200, Unsupported type %s on line %d.</Term>
<ListItem>
<Para>
Does not normally occur. This is a sign that the preprocessor has
generated something that the library does not know about. Perhaps you
are running incompatible versions of the preprocessor and the library.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-201, Too many arguments line %d.</Term>
<ListItem>
<Para>
This means that <ProductName>Postgres</ProductName> has returned more
arguments than we have
matching variables. Perhaps you have forgotten a couple of the host
variables in the <Command>INTO :var1,:var2</Command>-list.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-202, Too few arguments line %d.</Term>
<ListItem>
<Para>
This means that <ProductName>Postgres</ProductName> has returned fewer
arguments than we have
host variables. Perhaps you have too many host variables in the
<Command>INTO :var1,:var2</Command>-list.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-203, Too many matches line %d.</Term>
<ListItem>
<Para>
This means that the query has returned several lines but the
variables specified are no arrays. The <Command>SELECT</Command> you made
probably was not unique.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-204, Not correctly formatted int type: %s line %d.</Term>
<ListItem>
<Para>
This means that the host variable is of an <Type>int</Type> type and the field
in the <ProductName>Postgres</ProductName> database is of another type and
contains a value that cannot be interpreted as an <Type>int</Type>.
The library uses <Function>strtol</Function>
for this conversion.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-205, Not correctly formatted unsigned type: %s line %d.</Term>
<ListItem>
<Para>
This means that the host variable is of an <Type>unsigned int</Type> type and
the field in the <ProductName>Postgres</ProductName> database is of another
type and contains a
value that cannot be interpreted as an <Type>unsigned int</Type>. The library
uses <Function>strtoul</Function> for this conversion.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-206, Not correctly formatted floating point type: %s line %d.</Term>
<ListItem>
<Para>
This means that the host variable is of a <Type>float</Type> type and
the field in the <ProductName>Postgres</ProductName> database is of another
type and contains a
value that cannot be interpreted as an <Type>float</Type>. The library
uses <Function>strtod</Function> for this conversion.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-207, Unable to convert %s to bool on line %d.</Term>
<ListItem>
<Para>
This means that the host variable is of a <Type>bool</Type> type and
the field in the <ProductName>Postgres</ProductName> database is neither 't'
nor 'f'.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-208, Empty query line %d.</Term>
<ListItem>
<Para>
<ProductName>Postgres</ProductName> returned PGRES_EMPTY_QUERY, probably
because the query indeed was empty.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-220, No such connection %s in line %d.</Term>
<ListItem>
<Para>
The program tries to access a connection that does not exist.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-221, Not connected in line %d.</Term>
<ListItem>
<Para>
The program tries to access a connection that does exist but is not open.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-230, Invalid statement name %s in line %d.</Term>
<ListItem>
<Para>
The statement you are trying to use has not been prepared.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-400, Postgres error: %s line %d.</Term>
<ListItem>
<Para>
Some <ProductName>Postgres</ProductName> error.
The message contains the error message from the
<ProductName>Postgres</ProductName> backend.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-401, Error in transaction processing line %d. </Term>
<ListItem>
<Para>
<ProductName>Postgres</ProductName> signalled to us that we cannot start,
commit or rollback the transaction.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>-402, connect: could not open database %s.</Term>
<ListItem>
<Para>
The connect to the database did not work.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>100, Data not found line %d.</Term>
<ListItem>
<Para>
This is a "normal" error that tells you that what you are quering cannot
be found or we have gone through the cursor.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</Sect2>
</sect1>
<Sect1>
<Title>Limitations</Title>
<Para>
What will never be included and why or what cannot be done with this
concept.
<VariableList>
<VarListEntry>
<Term>oracles single tasking possibility</Term>
<ListItem>
<Para>
Oracle version 7.0 on AIX 3 uses the OS-supported locks on the shared
memory segments and allows the application designer to link an
application in a so called single tasking way. Instead of starting one
client process per application process both the database part and the
application part is run in the same process. In later versions of oracle
this is no longer supported.
</Para>
<Para>
This would require a total redesign of the <ProductName>Postgres</ProductName> access model and
that effort can not justify the performance gained.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</sect1>
<Sect1>
<Title>Porting From Other <Acronym>RDBMS</Acronym> Packages</Title>
<Para>
The design of <Application>ecpg</Application> follows SQL standard. So
porting from a standard RDBMS should not be a problem. Unfortunately there
is no such thing as a standard RDBMS. So <Application>ecpg</Application>
also tries to understand syntax additions as long as they do not create
conflicts with the standard.
</Para>
<Para>
The following list shows all the known incompatibilities. If you find one
not listed please notify <ULink url="mailto:meskes@postgresql.org">Michael
Meskes</ULink>. Note, however, that we list only incompatibilities from
a precompiler of another RDBMS to <Application>ecpg</Application> and not
additional <Application>ecpg</Application> features that these RDBMS do not
have.
</Para>
<Para>
<VariableList>
<VarListEntry>
<Term>Syntax of FETCH command</Term>
<ListItem>
<Para>
The standard syntax of the FETCH command is:
</para>
<Para>
FETCH [direction] [amount] IN|FROM <Replaceable>cursor name</Replaceable>.
</Para>
<para>
<Application>ORACLE</Application>, however, does not use the keywords IN
resp. FROM. This feature cannot be added since it would create parsing
conflicts.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</sect1>
<Sect1>
<Title>Installation</Title>
<Para>
Since version 0.5 <Application>ecpg</Application> is distributed
together with <ProductName>Postgres</ProductName>. So you
should get your precompiler, libraries and header files compiled and
installed by default as a part of your installation.
</Para>
</sect1>
<Sect1>
<Title>For the Developer</Title>
<Para>
This section is for those who want to develop the
<Application>ecpg</Application> interface. It
describes how the things work. The ambition is to make this section
contain things for those that want to have a look inside and the section
on How to use it should be enough for all normal questions.
So, read this before looking at the internals of the
<Application>ecpg</Application>. If
you are not interested in how it really works, skip this section.
</Para>
<Sect2>
<Title>ToDo List</Title>
<Para>
This version the preprocessor has some flaws:
<VariableList>
<VarListEntry>
<Term>Library functions</Term>
<ListItem>
<Para>
to_date et al. do not exists. But then <ProductName>Postgres</ProductName>
has some good conversion routines itself. So you probably won't miss these.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Structures ans unions</Term>
<ListItem>
<Para>
Structures and unions have to be defined in the declare section.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Missing statements</Term>
<ListItem>
<Para>
The following statements are not implemented thus far:
<VariableList>
<VarListEntry>
<Term> exec sql allocate</Term>
<ListItem>
<Para>
</Para>
</listitem>
</VarListEntry>
<VarListEntry>
<Term> exec sql deallocate</Term>
<ListItem>
<Para>
</Para>
</listitem>
</VarListEntry>
<VarListEntry>
<Term> SQLSTATE</Term>
<ListItem>
<Para>
</Para>
</listitem>
</VarListEntry>
</VariableList>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>message 'no data found'</Term>
<ListItem>
<Para>
The error message for "no data" in an exec sql insert select from statement
has to be 100.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>sqlwarn[6]</Term>
<ListItem>
<Para>
sqlwarn[6] should be 'W' if the PRECISION or SCALE value specified in a SET
DESCRIPTOR statement will be ignored.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</sect2>
<Sect2>
<Title>The Preprocessor</Title>
<Para>
The first four lines written to the output are constant additions by ecpg.
These are two comments and two include lines necessary for the interface to the
library.
</Para>
<Para>
Then the preprocessor works in one pass only, reading the input file and
writing to the output as it goes along. Normally it just echoes
everything to the output without looking at it further.
</Para>
<Para>
When it comes to an <Command>EXEC SQL</Command> statements it intervenes and
changes them depending on what it is.
The <Command>EXEC SQL</Command> statement can be one of these:
<VariableList>
<VarListEntry>
<Term>Declare sections</Term>
<ListItem>
<Para>
Declare sections begins with
<ProgramListing>
</programlisting>
</para>
<para>
If an error occured in the last <acronym>SQL</acronym> statement
then <parameter>sqlca.sqlcode</parameter>
will be non-zero. If <parameter>sqlca.sqlcode</parameter> is less that 0
then this is
some kind of serious error, like the database definition does not match
the query given. If it is bigger than 0 then this is a normal error like
the table did not contain the requested row.
</para>
<para>
sqlca.sqlerrm.sqlerrmc will contain a string that describes the error.
The string ends with the line number
in the source file.
</para>
<para>
List of errors that can occur:
<variablelist>
<varlistentry>
<term>-12, Out of memory in line %d.</term>
<listitem>
<para>
Does not normally occur. This is a sign that your virtual memory is
exhausted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-200, Unsupported type %s on line %d.</term>
<listitem>
<para>
Does not normally occur. This is a sign that the preprocessor has
generated something that the library does not know about. Perhaps you
are running incompatible versions of the preprocessor and the library.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-201, Too many arguments line %d.</term>
<listitem>
<para>
This means that <productname>Postgres</productname> has returned more
arguments than we have
matching variables. Perhaps you have forgotten a couple of the host
variables in the <command>INTO :var1,:var2</command>-list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-202, Too few arguments line %d.</term>
<listitem>
<para>
This means that <productname>Postgres</productname> has returned fewer
arguments than we have
host variables. Perhaps you have too many host variables in the
<command>INTO :var1,:var2</command>-list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-203, Too many matches line %d.</term>
<listitem>
<para>
This means that the query has returned several lines but the
variables specified are no arrays. The <command>SELECT</command> you made
probably was not unique.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-204, Not correctly formatted int type: %s line %d.</term>
<listitem>
<para>
This means that the host variable is of an <type>int</type> type and the field
in the <productname>Postgres</productname> database is of another type and
contains a value that cannot be interpreted as an <type>int</type>.
The library uses <function>strtol</function>
for this conversion.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-205, Not correctly formatted unsigned type: %s line %d.</term>
<listitem>
<para>
This means that the host variable is of an <type>unsigned int</type> type and
the field in the <productname>Postgres</productname> database is of another
type and contains a
value that cannot be interpreted as an <type>unsigned int</type>. The library
uses <function>strtoul</function> for this conversion.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-206, Not correctly formatted floating point type: %s line %d.</term>
<listitem>
<para>
This means that the host variable is of a <type>float</type> type and
the field in the <productname>Postgres</productname> database is of another
type and contains a
value that cannot be interpreted as an <type>float</type>. The library
uses <function>strtod</function> for this conversion.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-207, Unable to convert %s to bool on line %d.</term>
<listitem>
<para>
This means that the host variable is of a <type>bool</type> type and
the field in the <productname>Postgres</productname> database is neither 't'
nor 'f'.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-208, Empty query line %d.</term>
<listitem>
<para>
<productname>Postgres</productname> returned PGRES_EMPTY_QUERY, probably
because the query indeed was empty.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-220, No such connection %s in line %d.</term>
<listitem>
<para>
The program tries to access a connection that does not exist.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-221, Not connected in line %d.</term>
<listitem>
<para>
The program tries to access a connection that does exist but is not open.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-230, Invalid statement name %s in line %d.</term>
<listitem>
<para>
The statement you are trying to use has not been prepared.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-400, Postgres error: %s line %d.</term>
<listitem>
<para>
Some <productname>Postgres</productname> error.
The message contains the error message from the
<productname>Postgres</productname> backend.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-401, Error in transaction processing line %d. </term>
<listitem>
<para>
<productname>Postgres</productname> signalled to us that we cannot start,
commit or rollback the transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-402, connect: could not open database %s.</term>
<listitem>
<para>
The connect to the database did not work.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>100, Data not found line %d.</term>
<listitem>
<para>
This is a "normal" error that tells you that what you are quering cannot
be found or we have gone through the cursor.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
</sect1>
<sect1>
<title>Limitations</title>
<abstract>
<para>
What will never be included and why or what cannot be done with this
concept.
</para>
</abstract>
<para>
<variablelist>
<varlistentry>
<term>Oracle's single tasking possibility</term>
<listitem>
<para>
Oracle version 7.0 on AIX 3 uses the OS-supported locks on the shared
memory segments and allows the application designer to link an
application in a so called single tasking way. Instead of starting one
client process per application process both the database part and the
application part is run in the same process. In later versions of Oracle
this is no longer supported.
</para>
<para>
This would require a total redesign of the
<productname>Postgres</productname> access model and
that effort can not justify the performance gained.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1>
<title>Porting From Other <acronym>RDBMS</acronym> Packages</title>
<para>
The design of <application>ecpg</application> follows SQL standard. So
porting from a standard RDBMS should not be a problem. Unfortunately there
is no such thing as a standard RDBMS. So <application>ecpg</application>
also tries to understand syntax additions as long as they do not create
conflicts with the standard.
</para>
<para>
The following list shows all the known incompatibilities. If you find one
not listed please notify <ulink url="">Michael
Meskes</ulink>. Note, however, that we list only incompatibilities from
a precompiler of another RDBMS to <application>ecpg</application> and not
additional <application>ecpg</application> features that these RDBMS do not
have.
</para>
<para>
<variablelist>
<varlistentry>
<term>Syntax of FETCH command</term>
<listitem>
<para>
The standard syntax of the FETCH command is:
</para>
<para>
FETCH [direction] [amount] IN|FROM <replaceable>cursor name</replaceable>.
</para>
<para>
<application>ORACLE</application>, however, does not use the keywords IN
resp. FROM. This feature cannot be added since it would create parsing
conflicts.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1>
<title>Installation</title>
<para>
Since version 0.5 <application>ecpg</application> is distributed
together with <productname>Postgres</productname>. So you
should get your precompiler, libraries and header files compiled and
installed by default as a part of your installation.
</para>
</sect1>
<sect1>
<title>For the Developer</title>
<para>
This section is for those who want to develop the
<application>ecpg</application> interface. It
describes how the things work. The ambition is to make this section
contain things for those that want to have a look inside and the section
on How to use it should be enough for all normal questions.
So, read this before looking at the internals of the
<application>ecpg</application>. If
you are not interested in how it really works, skip this section.
</para>
<sect2>
<title>ToDo List</title>
<para>
This version the preprocessor has some flaws:
<variablelist>
<varlistentry>
<term>Library functions</term>
<listitem>
<para>
to_date et al. do not exists. But then <productname>Postgres</productname>
has some good conversion routines itself. So you probably won't miss these.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Structures ans unions</term>
<listitem>
<para>
Structures and unions have to be defined in the declare section.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Missing statements</term>
<listitem>
<para>
The following statements are not implemented thus far:
<variablelist>
<varlistentry>
<term> exec sql allocate</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term> exec sql deallocate</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term> SQLSTATE</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>message 'no data found'</term>
<listitem>
<para>
The error message for "no data" in an exec sql insert select from statement
has to be 100.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>sqlwarn[6]</term>
<listitem>
<para>
sqlwarn[6] should be 'W' if the PRECISION or SCALE value specified in a SET
DESCRIPTOR statement will be ignored.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2>
<title>The Preprocessor</title>
<para>
The first four lines written to the output are constant additions by ecpg.
These are two comments and two include lines necessary for the interface to the
library.
</para>
<para>
Then the preprocessor works in one pass only, reading the input file and
writing to the output as it goes along. Normally it just echoes
everything to the output without looking at it further.
</para>
<para>
When it comes to an <command>EXEC SQL</command> statements it intervenes and
changes them depending on what it is.
The <command>EXEC SQL</command> statement can be one of these:
<variablelist>
<varlistentry>
<term>Declare sections</term>
<listitem>
<para>
Declare sections begins with
<programlisting>
exec sql begin declare section;
</ProgramListing>
and ends with
<ProgramListing>
</programlisting>
and ends with
<programlisting>
exec sql end declare section;
</ProgramListing>
In the section only variable declarations are allowed. Every variable
declare within this section is also entered in a list of variables
indexed on their name together with the corresponding type.
</Para>
<Para>
In particular the definition of a structure or union also has to be listed
inside a declare section. Otherwise <Application>ecpg</Application> cannot
handle these types since it simply does not know the definition.
</Para>
<Para>
The declaration is echoed to the file to make the variable a normal
C-variable also.
</Para>
<Para>
The special types VARCHAR and VARCHAR2 are converted into a named struct
for every variable. A declaration like:
<ProgramListing>
</programlisting>
In the section only variable declarations are allowed. Every variable
declare within this section is also entered in a list of variables
indexed on their name together with the corresponding type.
</para>
<para>
In particular the definition of a structure or union also has to be listed
inside a declare section. Otherwise <application>ecpg</application> cannot
handle these types since it simply does not know the definition.
</para>
<para>
The declaration is echoed to the file to make the variable a normal
C-variable also.
</para>
<para>
The special types VARCHAR and VARCHAR2 are converted into a named struct
for every variable. A declaration like:
<programlisting>
VARCHAR var[180];
</ProgramListing>
is converted into
<ProgramListing>
</programlisting>
is converted into
<programlisting>
struct varchar_var { int len; char arr[180]; } var;
</ProgramListing>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Include statements</Term>
<ListItem>
<Para>
An include statement looks like:
<ProgramListing>
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Include statements</term>
<listitem>
<para>
An include statement looks like:
<programlisting>
exec sql include filename;
</ProgramListing>
Not that this is NOT the same as
<ProgramListing>
</programlisting>
Note that this is NOT the same as
<programlisting>
#include &lt;filename.h&gt;
</ProgramListing>
</Para>
<Para>
Instead the file specified is parsed by <Application>ecpg</Application>
itself. So the contents of the specified file is included in the resulting C
code. This way you are able to specify EXEC SQL commands in an include file.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Connect statement</Term>
<ListItem>
<Para>
A connect statement looks like:
<ProgramListing>
exec sql connect to <Replaceable>connection target</Replaceable>;
</ProgramListing>
It creates a connection to the specified database.
</Para>
<Para>
The <Replaceable>connection target</Replaceable> can be specified in the
following ways:
<VariableList>
<VarListEntry>
<Term>dbname[@server][:port][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term>tcp:postgresql://server[:port][/dbname][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term>unix:postgresql://server[:port][/dbname][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term><Replaceable>character variable</Replaceable>[as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term><Replaceable>character string</Replaceable>[as <Replaceable>connection name</Replaceable>][<Replaceable>user</Replaceable>]</Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term>default</Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term>user</Term>
<listitem><para></para></listitem>
</VarListEntry>
</VariableList>
</Para>
<Para>
There are also different ways to specify the user name:
<VariableList>
<VarListEntry>
<Term><Replaceable>userid</Replaceable></Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term><Replaceable>userid</Replaceable>/<Replaceable>password</Replaceable></Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term><Replaceable>userid</Replaceable> identified by <Replaceable>password</Replaceable></Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term><Replaceable>userid</Replaceable> using <Replaceable>password</Replaceable></Term>
<listitem><para></para></listitem>
</VarListEntry>
</VariableList>
</Para>
<Para> Finally the userid and the password. Each may be a constant text, a
character variable or a chararcter string.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Disconnect statements</Term>
<ListItem>
<Para>
A disconnect statement looks loke:
<ProgramListing>
exec sql disconnect [<Replaceable>connection target</Replaceable>];
</ProgramListing>
It closes the connection to the specified database.
</Para>
<Para>
The <Replaceable>connection target</Replaceable> can be specified in the
following ways:
<VariableList>
<VarListEntry>
<Term><Replaceable>connection name</Replaceable></Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term>default</Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term>current</Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term>all</Term>
<listitem><para></para></listitem>
</VarListEntry>
</VariableList>
</Para>
</ListItem>
</VarListEntry>
<!--WARNING: FROM HERE ON THE TEXT IS OUTDATED!-->
<VarListEntry>
<Term>Open cursor statement</Term>
<ListItem>
<Para>
An open cursor statement looks like:
<ProgramListing>
exec sql open <Replaceable>cursor</Replaceable>;
</ProgramListing>
and is ignore and not copied from the output.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Commit statement</Term>
<ListItem>
<Para>
A commit statement looks like
<ProgramListing>
</programlisting>
</para>
<para>
Instead the file specified is parsed by <application>ecpg</application>
itself. So the contents of the specified file is included in the resulting C
code. This way you are able to specify EXEC SQL commands in an include file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Connect statement</term>
<listitem>
<para>
A connect statement looks like:
<programlisting>
exec sql connect to <replaceable>connection target</replaceable>;
</programlisting>
It creates a connection to the specified database.
</para>
<para>
The <replaceable>connection target</replaceable> can be specified in the
following ways:
<variablelist>
<varlistentry>
<term>dbname[@server][:port][as <replaceable>connection
name</replaceable>][user <replaceable>user name</replaceable>]</term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term>tcp:postgresql://server[:port][/dbname][as
<replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term>unix:postgresql://server[:port][/dbname][as
<replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>character variable</replaceable>[as
<replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>character string</replaceable>[as
<replaceable>connection name</replaceable>][<replaceable>user</replaceable>]</term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term>default</term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term>user</term>
<listitem><para></para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
There are also different ways to specify the user name:
<variablelist>
<varlistentry>
<term><replaceable>userid</replaceable></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>userid</replaceable>/<replaceable>password</replaceable></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>userid</replaceable> identified by <replaceable>password</replaceable></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>userid</replaceable> using <replaceable>password</replaceable></term>
<listitem><para></para></listitem>
</varlistentry>
</variablelist>
</para>
<para> Finally the userid and the password. Each may be a constant text, a
character variable or a chararcter string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Disconnect statements</term>
<listitem>
<para>
A disconnect statement looks loke:
<programlisting>
exec sql disconnect [<replaceable>connection target</replaceable>];
</programlisting>
It closes the connection to the specified database.
</para>
<para>
The <replaceable>connection target</replaceable> can be specified in the
following ways:
<variablelist>
<varlistentry>
<term><replaceable>connection name</replaceable></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term>default</term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term>current</term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term>all</term>
<listitem><para></para></listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
<!--WARNING: FROM HERE ON THE TEXT IS OUTDATED!-->
<varlistentry>
<term>Open cursor statement</term>
<listitem>
<para>
An open cursor statement looks like:
<programlisting>
exec sql open <replaceable>cursor</replaceable>;
</programlisting>
and is ignore and not copied from the output.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Commit statement</term>
<listitem>
<para>
A commit statement looks like
<programlisting>
exec sql commit;
</ProgramListing>
and is translated on the output to
<ProgramListing>
</programlisting>
and is translated on the output to
<programlisting>
ECPGcommit(__LINE__);
</ProgramListing>
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Rollback statement</Term>
<ListItem>
<Para>
A rollback statement looks like
<ProgramListing>
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Rollback statement</term>
<listitem>
<para>
A rollback statement looks like
<programlisting>
exec sql rollback;
</ProgramListing>
and is translated on the output to
<ProgramListing>
</programlisting>
and is translated on the output to
<programlisting>
ECPGrollback(__LINE__);
</ProgramListing>
</Para>
</ListItem>
</VarListEntry>
<!--STARTING HERE IT IS OKAY AGAIN!-->
<VarListEntry>
<Term>Other statements</Term>
<ListItem>
<Para>
Other <Acronym>SQL</Acronym> statements are other statements that start with
<Command>exec sql</Command> and ends with <Command>;</Command>.
Everything inbetween is treated
as an <Acronym>SQL</Acronym> statement and parsed for variable substitution.
</Para>
<Para>
Variable substitution occur when a symbol starts with a colon
(<Command>:</Command>). Then a variable with that name is looked for among
the variables that were previously declared within a declare section and
depending on the variable being for input or output the pointers to the
variables are written to the output to allow for access by the function.
</Para>
<Para>
For every variable that is part of the <Acronym>SQL</Acronym> request
the function gets another ten arguments:
<SimpleList>
<Member>The type as a special symbol.</Member>
<Member>A pointer to the value or a pointer to the pointer.</Member>
<Member>The size of the variable if it is a char or varchar.</Member>
<Member>Number of elements in the array (for array fetches).</Member>
<Member>The offset to the next element in the array (for array fetches)</Member>
<Member>The type of the indicator variable as a special symbol.</Member>
<Member>A pointer to the value of the indicator variable or a pointer to the pointer of the indicator variable.</Member>
<Member>0.</Member>
<Member>Number of elements in the indicator array (for array fetches).</Member>
<Member>The offset to the next element in the indicator array (for array fetches)</Member>
</SimpleList>
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</Sect2>
<Sect2>
<Title>A Complete Example</Title>
<Para>
Here is a complete example describing the output of the preprocessor of a
file foo.pgc:
<ProgramListing>
</programlisting>
</para>
</listitem>
</varlistentry>
<!--STARTING HERE IT IS OKAY AGAIN!-->
<varlistentry>
<term>Other statements</term>
<listitem>
<para>
Other <acronym>SQL</acronym> statements are other statements that start with
<command>exec sql</command> and ends with <command>;</command>.
Everything inbetween is treated
as an <acronym>SQL</acronym> statement and parsed for variable substitution.
</para>
<para>
Variable substitution occur when a symbol starts with a colon
(<command>:</command>). Then a variable with that name is looked for among
the variables that were previously declared within a declare section and
depending on the variable being for input or output the pointers to the
variables are written to the output to allow for access by the function.
</para>
<para>
For every variable that is part of the <acronym>SQL</acronym> request
the function gets another ten arguments:
<simplelist>
<member>The type as a special symbol.</member>
<member>A pointer to the value or a pointer to the pointer.</member>
<member>The size of the variable if it is a char or varchar.</member>
<member>Number of elements in the array (for array fetches).</member>
<member>The offset to the next element in the array (for array fetches)</member>
<member>The type of the indicator variable as a special symbol.</member>
<member>A pointer to the value of the indicator variable or a pointer to the pointer of the indicator variable.</member>
<member>0.</member>
<member>Number of elements in the indicator array (for array fetches).</member>
<member>The offset to the next element in the indicator array (for array fetches)</member>
</simplelist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2>
<title>A Complete Example</title>
<para>
Here is a complete example describing the output of the preprocessor of a
file foo.pgc:
<programlisting>
exec sql begin declare section;
int index;
int result;
exec sql end declare section;
...
exec sql select res into :result from mytable where index = :index;
</ProgramListing>
is translated into:
<ProgramListing>
</programlisting>
is translated into:
<programlisting>
/* Processed by ecpg (2.6.0) */
/* These two include files are added by the preprocessor */
#include &lt;ecpgtype.h&gt;;
......@@ -923,100 +935,117 @@ ECPGdo(__LINE__, NULL, "select res from mytable where index = ? ",
ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
#line 147 "foo.pgc"
</ProgramListing>
(the indentation in this manual is added for readability and not
something that the preprocessor can do.)
</Para>
</sect2>
<Sect2>
<Title>The Library</Title>
<Para>
The most important function in the library is the <Function>ECPGdo</Function>
function. It takes a variable amount of arguments. Hopefully we will not run
into machines with limits on the amount of variables that can be
accepted by a vararg function. This could easily add up to 50 or so
arguments.
</Para>
<Para>
The arguments are:
<VariableList>
<VarListEntry>
<Term>A line number</Term>
<ListItem>
<Para>
This is a line number for the original line used in error messages only.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>A string</Term>
<ListItem>
<Para>
This is the <Acronym>SQL</Acronym> request that is to be issued.
This request is modified
by the input variables, i.e. the variables that where not known at
compile time but are to be entered in the request. Where the variables
should go the string contains <Quote>;</Quote>.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Input variables</Term>
<ListItem>
<Para>
As described in the section about the preprocessor every input variable
gets ten arguments.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>ECPGt_EOIT</Term>
<ListItem>
<Para>
An enum telling that there are no more input variables.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>Output variables</Term>
<ListItem>
<Para>
As described in the section about the preprocessor every input variable
gets ten arguments. These variables are filled by the function.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>ECPGt_EORT</Term>
<ListItem>
<Para>
An enum telling that there are no more variables.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
<Para>
All the <Acronym>SQL</Acronym> statements are performed in one transaction
unless you issue a commit transaction. To get this auto-transaction going
the first statement or the first after statement after a commit or rollback
always begins a transaction. To disable this feature per default use the
'-t' option on the commandline
</Para>
<Para>
To be completed: entries describing the other entries.
</Para>
</sect2>
</sect1>
</Chapter>
</programlisting>
(the indentation in this manual is added for readability and not
something that the preprocessor can do.)
</para>
</sect2>
<sect2>
<title>The Library</title>
<para>
The most important function in the library is the <function>ECPGdo</function>
function. It takes a variable amount of arguments. Hopefully we will not run
into machines with limits on the amount of variables that can be
accepted by a vararg function. This could easily add up to 50 or so
arguments.
</para>
<para>
The arguments are:
<variablelist>
<varlistentry>
<term>A line number</term>
<listitem>
<para>
This is a line number for the original line used in error messages only.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A string</term>
<listitem>
<para>
This is the <acronym>SQL</acronym> request that is to be issued.
This request is modified
by the input variables, i.e. the variables that where not known at
compile time but are to be entered in the request. Where the variables
should go the string contains <quote>;</quote>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Input variables</term>
<listitem>
<para>
As described in the section about the preprocessor every input variable
gets ten arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ECPGt_EOIT</term>
<listitem>
<para>
An enum telling that there are no more input variables.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Output variables</term>
<listitem>
<para>
As described in the section about the preprocessor every input variable
gets ten arguments. These variables are filled by the function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ECPGt_EORT</term>
<listitem>
<para>
An enum telling that there are no more variables.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
All the <acronym>SQL</acronym> statements are performed in one transaction
unless you issue a commit transaction. To get this auto-transaction going
the first statement or the first after statement after a commit or rollback
always begins a transaction. To disable this feature per default use the
<option>-t</option> option on the commandline.
</para>
<para>
To be completed: entries describing the other entries.
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/CATALOG")
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/func.sgml
View file @ f75bf187
......@@ -1404,7 +1404,7 @@ Not defined by this name. Implements the intersection operator '#'
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
......@@ -1414,7 +1414,7 @@ sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/indices.sgml
View file @ f75bf187
......@@ -394,7 +394,7 @@ CREATE MEMSTORE ON &lt;table&gt; COLUMNS &lt;cols&gt;
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
......@@ -404,7 +404,7 @@ sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/installation.sgml
View file @ f75bf187
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.7 1999/12/06 16:37:11 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.8 2000/03/30 22:22:40 thomas Exp $
Postgres quick Installation Guide.
- thomas 1998-10-26
$Log: installation.sgml,v $
Revision 1.8 2000/03/30 22:22:40 thomas
Accumulated fixups.
Add some chapters on new topics.
Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0
Grepped for and fixed apparent tag mangling from emacs
"Normalize" operation. Should be the last of those.
Revision 1.7 1999/12/06 16:37:11 thomas
Remove references to PostgreSQL as "public-domain" since that has a
specific meaning wrt copyright (or lack thereof).
......@@ -39,7 +46,7 @@ First cut at standalone installation guide to replace INSTALL text source.
-->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!entity about SYSTEM "about.sgml">
<!entity history SYSTEM "history.sgml">
......
doc/src/sgml/intro-ag.sgml
View file @ f75bf187
......@@ -19,6 +19,7 @@
&info;
&notation;
&problems;
&y2k;
&legal;
......@@ -26,7 +27,7 @@
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
......@@ -36,7 +37,7 @@ sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-catalogs:("/usr/lib/sgml/CATALOG")
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/intro-pg.sgml
View file @ f75bf187
......@@ -39,6 +39,7 @@
&info;
&notation;
&problems;
&y2k;
&legal;
......@@ -46,7 +47,7 @@
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
......@@ -56,7 +57,7 @@ sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-catalogs:("/usr/lib/sgml/CATALOG")
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/intro.sgml
View file @ f75bf187
......@@ -73,7 +73,7 @@
&about;
&info;
&notation;
&bug-reporting;
&problems;
&y2k;
&legal;
......
doc/src/sgml/jdbc.sgml
View file @ f75bf187
......@@ -233,13 +233,13 @@ Class.forName("postgresql.Driver");
<listitem>
<para>
jdbc:postgresql://<replaceable class="parameter">>hos</replaceable>>/<replaceable class="parameter">database</replaceable>
jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable>
</para>
</listitem>
<listitem>
<para>
jdbc:postgresql://<replaceable class="parameter">>hos</replaceable>><replaceable class="parameter">">po</replaceable>e>/<replaceable class="parameter">database</replaceable>
jdbc:postgresql://<replaceable class="parameter">host</replaceable><replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable>
</para>
</listitem>
</itemizedlist>
......
doc/src/sgml/libpgtcl.sgml
View file @ f75bf187
......@@ -671,6 +671,16 @@ the number of attributes in each tuple.
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-list VarName
</TERM>
<LISTITEM>
<PARA>
assign the results to a list of lists.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-assign arrayName
</TERM>
<LISTITEM>
......
doc/src/sgml/plan.sgml 0 → 100644
View file @ f75bf187
<chapter>
<title>Understanding Performance</title>
<para>
Query performance can be affected by many things. Some of these can
be manipulated by the user, while others are fundamental to the underlying
design of the system.
</para>
<para>
Some performance issues, such as index creation and bulk data
loading, are covered elsewhere. This chapter will discuss the
<command>EXPLAIN</command> command, and will show how the details
of a query can affect the query plan, and hence overall
performance.
</para>
<sect1>
<title>Using <command>EXPLAIN</command></title>
<note>
<title>Author</title>
<para>
Written by Tom Lane, from e-mail dated 2000-03-27.
</para>
</note>
<para>
Plan-reading is an art that deserves a tutorial, and I haven't
had time to write one. Here is some quick & dirty explanation.
</para>
<para>
The numbers that are currently quoted by EXPLAIN are:
<itemizedlist>
<listitem>
<para>
Estimated startup cost (time expended before output scan can start,
eg, time to do the sorting in a SORT node).
</para>
</listitem>
<listitem>
<para>
Estimated total cost (if all tuples are retrieved, which they may not
be --- LIMIT will stop short of paying the total cost, for
example).
</para>
</listitem>
<listitem>
<para>
Estimated number of rows output by this plan node.
</para>
</listitem>
<listitem>
<para>
Estimated average width (in bytes) of rows output by this plan
node.
</para>
</listitem>
</itemizedlist>
</para>
<para>
The costs are measured in units of disk page fetches. (There are some
fairly bogus fudge-factors for converting CPU effort estimates into
disk-fetch units; see the SET ref page if you want to play with these.)
It's important to note that the cost of an upper-level node includes
the cost of all its child nodes. It's also important to realize that
the cost only reflects things that the planner/optimizer cares about.
In particular, the cost does not consider the time spent transmitting
result tuples to the frontend --- which could be a pretty dominant
factor in the true elapsed time, but the planner ignores it because
it cannot change it by altering the plan. (Every correct plan will
output the same tuple set, we trust.)
</para>
<para>
Rows output is a little tricky because it is *not* the number of rows
processed/scanned by the query --- it is usually less, reflecting the
estimated selectivity of any WHERE-clause constraints that are being
applied at this node.
</para>
<para>
Average width is pretty bogus because the thing really doesn't have
any idea of the average length of variable-length columns. I'm thinking
about improving that in the future, but it may not be worth the trouble,
because the width isn't used for very much.
</para>
<para>
Here are some examples (using the regress test database after a
vacuum analyze, and current sources):
<programlisting>
regression=# explain select * from tenk1;
NOTICE: QUERY PLAN:
Seq Scan on tenk1 (cost=0.00..333.00 rows=10000 width=148)
</programlisting>
</para>
<para>
About as straightforward as it gets. If you do
<programlisting>
select * from pg_class where relname = 'tenk1';
</programlisting>
you'll find out that tenk1 has 233 disk
pages and 10000 tuples. So the cost is estimated at 233 block
reads, defined as 1.0 apiece, plus 10000 * cpu_tuple_cost which is
currently 0.01 (try <command>show cpu_tuple_cost</command>).
</para>
<para>
Now let's modify the query to add a qualification clause:
<programlisting>
regression=# explain select * from tenk1 where unique1 &lt; 1000;
NOTICE: QUERY PLAN:
Seq Scan on tenk1 (cost=0.00..358.00 rows=1000 width=148)
</programlisting>
Estimated output rows has gone down because of the WHERE clause.
(The uncannily accurate estimate is just because tenk1 is a particularly
simple case --- the unique1 column has 10000 distinct values ranging
from 0 to 9999, so the estimator's linear interpolation between min and
max column values is dead-on.) However, the scan will still have to
visit all 10000 rows, so the cost hasn't decreased; in fact it has gone
up a bit to reflect the extra CPU time spent checking the WHERE
condition.
</para>
<para>
Modify the query to restrict the qualification even more:
<programlisting>
regression=# explain select * from tenk1 where unique1 &lt; 100;
NOTICE: QUERY PLAN:
Index Scan using tenk1_unique1 on tenk1 (cost=0.00..89.35 rows=100 width=148)
</programlisting>
and you will see that if we make the WHERE condition selective
enough, the planner will
eventually decide that an indexscan is cheaper than a sequential scan.
This plan will only have to visit 100 tuples because of the index,
so it wins despite the fact that each individual fetch is expensive.
</para>
<para>
Add another condition to the qualification:
<programlisting>
regression=# explain select * from tenk1 where unique1 &lt; 100 and
regression-# stringu1 = 'xxx';
NOTICE: QUERY PLAN:
Index Scan using tenk1_unique1 on tenk1 (cost=0.00..89.60 rows=1 width=148)
</programlisting>
The added clause "stringu1 = 'xxx'" reduces the output-rows estimate,
but not the cost because we still have to visit the same set of tuples.
</para>
<para>
Let's try joining two tables, using the fields we have been discussing:
<programlisting>
regression=# explain select * from tenk1 t1, tenk2 t2 where t1.unique1 &lt; 100
regression-# and t1.unique2 = t2.unique2;
NOTICE: QUERY PLAN:
Nested Loop (cost=0.00..144.07 rows=100 width=296)
-&gt; Index Scan using tenk1_unique1 on tenk1 t1
(cost=0.00..89.35 rows=100 width=148)
-&gt; Index Scan using tenk2_unique2 on tenk2 t2
(cost=0.00..0.53 rows=1 width=148)
</programlisting>
</para>
<para>
In this nested-loop join, the outer scan is the same indexscan we had
in the example before last, and the cost and row count are the same
because we are applying the "unique1 &lt; 100" WHERE clause at this node.
The "t1.unique2 = t2.unique2" clause isn't relevant yet, so it doesn't
affect the row count. For the inner scan, we assume that the current
outer-scan tuple's unique2 value is plugged into the inner indexscan
to produce an indexqual like
"t2.unique2 = <replaceable>constant</replaceable>". So we get the
same inner-scan plan and costs that we'd get from, say, "explain select
* from tenk2 where unique2 = 42". The loop node's costs are then set
on the basis of the outer scan's cost, plus one repetition of the
inner scan for each outer tuple (100 * 0.53, here), plus a little CPU
time for join processing.
</para>
<para>
In this example the loop's output row count is the same as the product
of the two scans' row counts, but that's not true in general, because
in general you can have WHERE clauses that mention both relations and
so can only be applied at the join point, not to either input scan.
For example, if we added "WHERE ... AND t1.hundred &lt; t2.hundred",
that'd decrease the output row count of the join node, but not change
either input scan.
</para>
<para>
We can look at variant plans by forcing the planner to disregard
whatever strategy it thought was the winner (a pretty crude tool,
but it's what we've got at the moment):
<programlisting>
regression=# set enable_nestloop = 'off';
SET VARIABLE
regression=# explain select * from tenk1 t1, tenk2 t2 where t1.unique1 < 100
regression-# and t1.unique2 = t2.unique2;
NOTICE: QUERY PLAN:
Hash Join (cost=89.60..574.10 rows=100 width=296)
-&gt; Seq Scan on tenk2 t2
(cost=0.00..333.00 rows=10000 width=148)
-&gt; Hash (cost=89.35..89.35 rows=100 width=148)
-&gt; Index Scan using tenk1_unique1 on tenk1 t1
(cost=0.00..89.35 rows=100 width=148)
</programlisting>
This plan proposes to extract the 100 interesting rows of tenk1
using ye same olde indexscan, stash them into an in-memory hash table,
and then do a sequential scan of tenk2, probing into the hash table
for possible matches of "t1.unique2 = t2.unique2" at each tenk2 tuple.
The cost to read tenk1 and set up the hash table is entirely startup
cost for the hash join, since we won't get any tuples out until we can
start reading tenk2. The total time estimate for the join also
includes a pretty hefty charge for CPU time to probe the hash table
10000 times. Note, however, that we are NOT charging 10000 times 89.35;
the hash table setup is only done once in this plan type.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/CATALOG")
sgml-local-ecat-files:nil
End:
-->
doc/src/sgml/postgres.sgml
View file @ f75bf187
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!entity about SYSTEM "about.sgml">
<!entity bug-reporting SYSTEM "bug-reporting.sgml">
<!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml">
<!entity legal SYSTEM "legal.sgml">
<!entity notation SYSTEM "notation.sgml">
<!entity y2k SYSTEM "y2k.sgml">
<!entity about SYSTEM "about.sgml">
<!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml">
<!entity legal SYSTEM "legal.sgml">
<!entity notation SYSTEM "notation.sgml">
<!entity problems SYSTEM "problems.sgml">
<!entity y2k SYSTEM "y2k.sgml">
<!-- tutorial -->
<!entity arch SYSTEM "arch.sgml">
<!entity intro SYSTEM "intro.sgml">
<!entity query SYSTEM "query.sgml">
<!entity sql SYSTEM "sql.sgml">
<!entity start SYSTEM "start.sgml">
<!entity arch SYSTEM "arch.sgml">
<!entity intro SYSTEM "intro.sgml">
<!entity query SYSTEM "query.sgml">
<!entity sql SYSTEM "sql.sgml">
<!entity start SYSTEM "start.sgml">
<!-- user's guide -->
<!entity advanced SYSTEM "advanced.sgml">
<!entity array SYSTEM "array.sgml">
<!entity datatype SYSTEM "datatype.sgml">
<!entity datetime SYSTEM "datetime.sgml">
<!entity environ SYSTEM "environ.sgml">
<!entity func SYSTEM "func.sgml">
<!entity indices SYSTEM "indices.sgml">
<!entity inherit SYSTEM "inherit.sgml">
<!entity manage SYSTEM "manage.sgml">
<!entity mvcc SYSTEM "mvcc.sgml">
<!entity oper SYSTEM "oper.sgml">
<!entity pgaccess SYSTEM "pgaccess.sgml">
<!entity psql SYSTEM "psql.sgml">
<!entity query-ug SYSTEM "query-ug.sgml">
<!entity storage SYSTEM "storage.sgml">
<!entity syntax SYSTEM "syntax.sgml">
<!entity typeconv SYSTEM "typeconv.sgml">
<!entity advanced SYSTEM "advanced.sgml">
<!entity array SYSTEM "array.sgml">
<!entity datatype SYSTEM "datatype.sgml">
<!entity datetime SYSTEM "datetime.sgml">
<!entity environ SYSTEM "environ.sgml">
<!entity func SYSTEM "func.sgml">
<!entity indices SYSTEM "indices.sgml">
<!entity inherit SYSTEM "inherit.sgml">
<!entity manage SYSTEM "manage.sgml">
<!entity mvcc SYSTEM "mvcc.sgml">
<!entity oper SYSTEM "oper.sgml">
<!entity plan SYSTEM "plan.sgml">
<!entity plperl SYSTEM "plperl.sgml">
<!entity plsql SYSTEM "plsql.sgml">
<!entity pltcl SYSTEM "pltcl.sgml">
<!entity populate SYSTEM "populate.sgml">
<!entity psql SYSTEM "psql.sgml">
<!entity query-ug SYSTEM "query-ug.sgml">
<!entity storage SYSTEM "storage.sgml">
<!entity syntax SYSTEM "syntax.sgml">
<!entity typeconv SYSTEM "typeconv.sgml">
<!-- reference pages -->
<!entity % allfiles SYSTEM "ref/allfiles.sgml">
<!entity % allfiles SYSTEM "ref/allfiles.sgml">
%allfiles;
<!-- administrator's guide -->
<!entity config SYSTEM "config.sgml">
<!entity intro-ag SYSTEM "intro-ag.sgml">
<!entity install SYSTEM "install.sgml">
<!entity installw SYSTEM "install-win32.sgml">
<!entity layout SYSTEM "layout.sgml">
<!entity manage-ag SYSTEM "manage-ag.sgml">
<!entity ports SYSTEM "ports.sgml">
<!entity recovery SYSTEM "recovery.sgml">
<!entity regress SYSTEM "regress.sgml">
<!entity release SYSTEM "release.sgml">
<!entity runtime SYSTEM "runtime.sgml">
<!entity security SYSTEM "security.sgml">
<!entity start-ag SYSTEM "start-ag.sgml">
<!entity trouble SYSTEM "trouble.sgml">
<!entity config SYSTEM "config.sgml">
<!entity intro-ag SYSTEM "intro-ag.sgml">
<!entity install SYSTEM "install.sgml">
<!entity installw SYSTEM "install-win32.sgml">
<!entity layout SYSTEM "layout.sgml">
<!entity manage-ag SYSTEM "manage-ag.sgml">
<!entity ports SYSTEM "ports.sgml">
<!entity recovery SYSTEM "recovery.sgml">
<!entity regress SYSTEM "regress.sgml">
<!entity release SYSTEM "release.sgml">
<!entity runtime SYSTEM "runtime.sgml">
<!entity security SYSTEM "security.sgml">
<!entity start-ag SYSTEM "start-ag.sgml">
<!entity trouble SYSTEM "trouble.sgml">
<!-- programmer's guide -->
<!entity arch-pg SYSTEM "arch-pg.sgml">
<!entity dfunc SYSTEM "dfunc.sgml">
<!entity ecpg SYSTEM "ecpg.sgml">
<!entity extend SYSTEM "extend.sgml">
<!entity func-ref SYSTEM "func-ref.sgml">
<!entity gist SYSTEM "gist.sgml">
<!entity intro-pg SYSTEM "intro-pg.sgml">
<!entity jdbc SYSTEM "jdbc.sgml">
<!entity libpq SYSTEM "libpq.sgml">
<!entity libpqpp SYSTEM "libpq++.sgml">
<!entity libpgtcl SYSTEM "libpgtcl.sgml">
<!entity lisp SYSTEM "lisp.sgml">
<!entity lobj SYSTEM "lobj.sgml">
<!entity odbc SYSTEM "odbc.sgml">
<!entity rules SYSTEM "rules.sgml">
<!entity spi SYSTEM "spi.sgml">
<!entity trigger SYSTEM "trigger.sgml">
<!entity xaggr SYSTEM "xaggr.sgml">
<!entity xfunc SYSTEM "xfunc.sgml">
<!entity xindex SYSTEM "xindex.sgml">
<!entity xplang SYSTEM "xplang.sgml">
<!entity xoper SYSTEM "xoper.sgml">
<!entity xtypes SYSTEM "xtypes.sgml">
<!entity arch-pg SYSTEM "arch-pg.sgml">
<!entity dfunc SYSTEM "dfunc.sgml">
<!entity ecpg SYSTEM "ecpg.sgml">
<!entity extend SYSTEM "extend.sgml">
<!entity func-ref SYSTEM "func-ref.sgml">
<!entity gist SYSTEM "gist.sgml">
<!entity intro-pg SYSTEM "intro-pg.sgml">
<!entity indexcost SYSTEM "indexcost.sgml">
<!entity jdbc SYSTEM "jdbc.sgml">
<!entity libpq SYSTEM "libpq.sgml">
<!entity libpqpp SYSTEM "libpq++.sgml">
<!entity libpgtcl SYSTEM "libpgtcl.sgml">
<!entity lisp SYSTEM "lisp.sgml">
<!entity lobj SYSTEM "lobj.sgml">
<!entity odbc SYSTEM "odbc.sgml">
<!entity rules SYSTEM "rules.sgml">
<!entity spi SYSTEM "spi.sgml">
<!entity trigger SYSTEM "trigger.sgml">
<!entity xaggr SYSTEM "xaggr.sgml">
<!entity xfunc SYSTEM "xfunc.sgml">
<!entity xindex SYSTEM "xindex.sgml">
<!entity xplang SYSTEM "xplang.sgml">
<!entity xoper SYSTEM "xoper.sgml">
<!entity xtypes SYSTEM "xtypes.sgml">
<!-- developer's guide -->
<!entity arch-dev SYSTEM "arch-dev.sgml">
<!entity biblio SYSTEM "biblio.sgml">
<!entity bki SYSTEM "bki.sgml">
<!entity compiler SYSTEM "compiler.sgml">
<!entity contacts SYSTEM "contacts.sgml">
<!entity cvs SYSTEM "cvs.sgml">
<!entity docguide SYSTEM "docguide.sgml">
<!entity geqo SYSTEM "geqo.sgml">
<!entity options SYSTEM "pg_options.sgml">
<!entity page SYSTEM "page.sgml">
<!entity protocol SYSTEM "protocol.sgml">
<!entity signals SYSTEM "signals.sgml">
<!entity sources SYSTEM "sources.sgml">
<!entity arch-dev SYSTEM "arch-dev.sgml">
<!entity biblio SYSTEM "biblio.sgml">
<!entity bki SYSTEM "bki.sgml">
<!entity compiler SYSTEM "compiler.sgml">
<!entity contacts SYSTEM "contacts.sgml">
<!entity cvs SYSTEM "cvs.sgml">
<!entity docguide SYSTEM "docguide.sgml">
<!entity geqo SYSTEM "geqo.sgml">
<!entity index SYSTEM "index.sgml">
<!entity options SYSTEM "pg_options.sgml">
<!entity page SYSTEM "page.sgml">
<!entity protocol SYSTEM "protocol.sgml">
<!entity signals SYSTEM "signals.sgml">
<!entity sources SYSTEM "sources.sgml">
]>
<!-- entity manpages SYSTEM "man/manpages.sgml" subdoc -->
<Book Id="postgres">
......@@ -181,10 +187,15 @@ Your name here...
&indices;
&array;
&inherit;
&plsql;
&pltcl;
&plperl;
&mvcc;
&environ;
&manage;
&storage;
&plan;
&populate;
&commands;
</Part>
......@@ -237,6 +248,7 @@ Your name here...
&xaggr;
&rules;
&xindex;
&indexcost;
&gist;
&dfunc;
&trigger;
......
doc/src/sgml/programmer.sgml
View file @ f75bf187
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.22 2000/03/28 14:16:06 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.23 2000/03/30 22:22:41 thomas Exp $
Postgres Programmer's Guide.
$Log: programmer.sgml,v $
Revision 1.23 2000/03/30 22:22:41 thomas
Accumulated fixups.
Add some chapters on new topics.
Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0
Grepped for and fixed apparent tag mangling from emacs
"Normalize" operation. Should be the last of those.
Revision 1.22 2000/03/28 14:16:06 thomas
Update SGML catalog references to DocBook 3.1 on FreeBSD.
Matches postgresql.org/hub.org environment.
......@@ -49,46 +56,49 @@ Make new file current.sgml to hold release info for the current release.
<!entity info SYSTEM "info.sgml">
<!entity legal SYSTEM "legal.sgml">
<!entity notation SYSTEM "notation.sgml">
<!entity problems SYSTEM "problems.sgml">
<!entity y2k SYSTEM "y2k.sgml">
<!entity arch-pg SYSTEM "arch-pg.sgml">
<!entity dfunc SYSTEM "dfunc.sgml">
<!entity ecpg SYSTEM "ecpg.sgml">
<!entity extend SYSTEM "extend.sgml">
<!entity func-ref SYSTEM "func-ref.sgml">
<!entity gist SYSTEM "gist.sgml">
<!entity intro-pg SYSTEM "intro-pg.sgml">
<!entity jdbc SYSTEM "jdbc.sgml">
<!entity libpq SYSTEM "libpq.sgml">
<!entity libpqpp SYSTEM "libpq++.sgml">
<!entity libpgtcl SYSTEM "libpgtcl.sgml">
<!entity lisp SYSTEM "lisp.sgml">
<!entity lobj SYSTEM "lobj.sgml">
<!entity odbc SYSTEM "odbc.sgml">
<!entity rules SYSTEM "rules.sgml">
<!entity spi SYSTEM "spi.sgml">
<!entity trigger SYSTEM "trigger.sgml">
<!entity xaggr SYSTEM "xaggr.sgml">
<!entity xfunc SYSTEM "xfunc.sgml">
<!entity xindex SYSTEM "xindex.sgml">
<!entity xplang SYSTEM "xplang.sgml">
<!entity xoper SYSTEM "xoper.sgml">
<!entity xtypes SYSTEM "xtypes.sgml">
<!entity arch-pg SYSTEM "arch-pg.sgml">
<!entity dfunc SYSTEM "dfunc.sgml">
<!entity ecpg SYSTEM "ecpg.sgml">
<!entity extend SYSTEM "extend.sgml">
<!entity func-ref SYSTEM "func-ref.sgml">
<!entity gist SYSTEM "gist.sgml">
<!entity intro-pg SYSTEM "intro-pg.sgml">
<!entity indexcost SYSTEM "indexcost.sgml">
<!entity jdbc SYSTEM "jdbc.sgml">
<!entity libpq SYSTEM "libpq.sgml">
<!entity libpqpp SYSTEM "libpq++.sgml">
<!entity libpgtcl SYSTEM "libpgtcl.sgml">
<!entity lisp SYSTEM "lisp.sgml">
<!entity lobj SYSTEM "lobj.sgml">
<!entity odbc SYSTEM "odbc.sgml">
<!entity plperl SYSTEM "plperl.sgml">
<!entity rules SYSTEM "rules.sgml">
<!entity spi SYSTEM "spi.sgml">
<!entity trigger SYSTEM "trigger.sgml">
<!entity xaggr SYSTEM "xaggr.sgml">
<!entity xfunc SYSTEM "xfunc.sgml">
<!entity xindex SYSTEM "xindex.sgml">
<!entity xplang SYSTEM "xplang.sgml">
<!entity xoper SYSTEM "xoper.sgml">
<!entity xtypes SYSTEM "xtypes.sgml">
<!-- developer's guide -->
<!entity arch-dev SYSTEM "arch-dev.sgml">
<!entity biblio SYSTEM "biblio.sgml">
<!entity bki SYSTEM "bki.sgml">
<!entity compiler SYSTEM "compiler.sgml">
<!entity contacts SYSTEM "contacts.sgml">
<!entity cvs SYSTEM "cvs.sgml">
<!entity docguide SYSTEM "docguide.sgml">
<!entity geqo SYSTEM "geqo.sgml">
<!entity options SYSTEM "pg_options.sgml">
<!entity page SYSTEM "page.sgml">
<!entity protocol SYSTEM "protocol.sgml">
<!entity signals SYSTEM "signals.sgml">
<!entity sources SYSTEM "sources.sgml">
<!entity arch-dev SYSTEM "arch-dev.sgml">
<!entity biblio SYSTEM "biblio.sgml">
<!entity bki SYSTEM "bki.sgml">
<!entity compiler SYSTEM "compiler.sgml">
<!entity contacts SYSTEM "contacts.sgml">
<!entity cvs SYSTEM "cvs.sgml">
<!entity docguide SYSTEM "docguide.sgml">
<!entity geqo SYSTEM "geqo.sgml">
<!entity options SYSTEM "pg_options.sgml">
<!entity page SYSTEM "page.sgml">
<!entity protocol SYSTEM "protocol.sgml">
<!entity signals SYSTEM "signals.sgml">
<!entity sources SYSTEM "sources.sgml">
]>
<book id="programmer">
......@@ -169,8 +179,10 @@ Your name here...
&xaggr;
&rules;
&xindex;
&indexcost;
&gist;
&xplang;
&plperl;
&dfunc;
<!-- reference -->
......
doc/src/sgml/refentry.sgml
View file @ f75bf187
<!doctype refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
doc/src/sgml/reference.sgml
View file @ f75bf187
<!-- reference.sgml
$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.6 1999/05/26 17:30:30 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.7 2000/03/30 22:22:41 thomas Exp $
Postgres User's Reference documentation.
- thomas 1998-08-31
$Log: reference.sgml,v $
Revision 1.7 2000/03/30 22:22:41 thomas
Accumulated fixups.
Add some chapters on new topics.
Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0
Grepped for and fixed apparent tag mangling from emacs
"Normalize" operation. Should be the last of those.
Revision 1.6 1999/05/26 17:30:30 thomas
Add chapters on CVS access, MVCC, SQL theory to the docs.
Add an appendix with more details on date/time attributes and handling.
......@@ -24,7 +31,7 @@ Bigger updates to the installation instructions (install and config).
-->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!entity intro SYSTEM "intro.sgml">
<!entity % allfiles SYSTEM "ref/allfiles.sgml">
......
doc/src/sgml/tutorial.sgml
View file @ f75bf187
......@@ -11,6 +11,7 @@
<!entity info SYSTEM "info.sgml">
<!entity legal SYSTEM "legal.sgml">
<!entity notation SYSTEM "notation.sgml">
<!entity problems SYSTEM "problems.sgml">
<!entity y2k SYSTEM "y2k.sgml">
<!entity advanced SYSTEM "advanced.sgml">
......
doc/src/sgml/user.sgml
View file @ f75bf187
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!entity about SYSTEM "about.sgml">
<!entity bug-reporting SYSTEM "bug-reporting.sgml">
<!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml">
<!entity legal SYSTEM "legal.sgml">
<!entity notation SYSTEM "notation.sgml">
<!entity y2k SYSTEM "y2k.sgml">
<!entity advanced SYSTEM "advanced.sgml">
<!entity array SYSTEM "array.sgml">
<!entity biblio SYSTEM "biblio.sgml">
<!entity datatype SYSTEM "datatype.sgml">
<!entity datetime SYSTEM "datetime.sgml">
<!entity environ SYSTEM "environ.sgml">
<!entity func SYSTEM "func.sgml">
<!entity indices SYSTEM "indices.sgml">
<!entity inherit SYSTEM "inherit.sgml">
<!entity intro SYSTEM "intro.sgml">
<!entity manage SYSTEM "manage.sgml">
<!entity mvcc SYSTEM "mvcc.sgml">
<!entity oper SYSTEM "oper.sgml">
<!entity storage SYSTEM "storage.sgml">
<!entity syntax SYSTEM "syntax.sgml">
<!entity typeconv SYSTEM "typeconv.sgml">
<!entity about SYSTEM "about.sgml">
<!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml">
<!entity legal SYSTEM "legal.sgml">
<!entity notation SYSTEM "notation.sgml">
<!entity problems SYSTEM "problems.sgml">
<!entity y2k SYSTEM "y2k.sgml">
<!entity advanced SYSTEM "advanced.sgml">
<!entity array SYSTEM "array.sgml">
<!entity biblio SYSTEM "biblio.sgml">
<!entity datatype SYSTEM "datatype.sgml">
<!entity datetime SYSTEM "datetime.sgml">
<!entity environ SYSTEM "environ.sgml">
<!entity func SYSTEM "func.sgml">
<!entity indices SYSTEM "indices.sgml">
<!entity inherit SYSTEM "inherit.sgml">
<!entity intro SYSTEM "intro.sgml">
<!entity manage SYSTEM "manage.sgml">
<!entity mvcc SYSTEM "mvcc.sgml">
<!entity oper SYSTEM "oper.sgml">
<!entity plan SYSTEM "plan.sgml">
<!entity plperl SYSTEM "plperl.sgml">
<!entity plsql SYSTEM "plsql.sgml">
<!entity pltcl SYSTEM "pltcl.sgml">
<!entity populate SYSTEM "populate.sgml">
<!entity storage SYSTEM "storage.sgml">
<!entity syntax SYSTEM "syntax.sgml">
<!entity typeconv SYSTEM "typeconv.sgml">
<!-- reference pages -->
<!entity % allfiles SYSTEM "allfiles.sgml">
......@@ -108,10 +113,15 @@ Your name here...
&indices;
&array;
&inherit;
&plsql;
&pltcl;
&plperl;
&mvcc;
&environ;
&manage;
&storage;
&plan;
&populate
&commands;
<!-- appendices -->
......
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