Skip to content

P
Postgres FD Implementation
Commit d1b4327d authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Last round of reference page editing.

parent ac5fdea6
Show whitespace changes
Inline Side-by-side
Showing with 3240 additions and 4452 deletions
doc/src/sgml/ref/declare.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.23 2003/04/29 03:21:28 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.24 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,140 +8,162 @@ PostgreSQL documentation
<refentrytitle id="SQL-DECLARE-TITLE">DECLARE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DECLARE
</refname>
<refpurpose>
define a cursor
</refpurpose>
<refname>DECLARE</refname>
<refpurpose>define a cursor</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ]
CURSOR [ { WITH | WITHOUT } HOLD ] FOR <replaceable class="parameter">query</replaceable>
[ FOR { READ ONLY | UPDATE [ OF <replaceable class="parameter">column</replaceable> [, ...] ] ]
</synopsis>
<refsect2 id="R2-SQL-DECLARE-1">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Inputs
</title>
[ FOR { READ ONLY | UPDATE [ OF <replaceable class="parameter">column</replaceable> [, ...] ] } ]
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">cursorname</replaceable></term>
<listitem>
<command>DECLARE</command> allows a user to create cursors, which
can be used to retrieve
a small number of rows at a time out of a larger query. Cursors can
return data either in text or in binary format using
<xref linkend="sql-fetch" endterm="sql-fetch-title">.
</para>
<para>
The name of the cursor to be used in subsequent
<command>FETCH</command> operations.
Normal cursors return data in text format, the same as a
<command>SELECT</> would produce. Since data is stored natively in
binary format, the system must do a conversion to produce the text
format. Once the information comes back in text form, the client
application may need to convert it to a binary format to manipulate
it. In addition, data in the text format is often larger in size
than in the binary format. Binary cursors return the data in the
native binary representation. Nevertheless, if you intend to
display the data as text anyway, retrieving it in text form will
save you some effort on the client side.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BINARY</term>
<listitem>
<para>
Causes the cursor to return data in binary rather than in text format.
As an example, if a query returns a value of one from an integer column,
you would get a string of <literal>1</> with a default cursor
whereas with a binary cursor you would get
a 4-byte value containing the internal representation of the value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>INSENSITIVE</term>
<listitem>
<para>
<acronym>SQL92</acronym> keyword indicating that data retrieved
from the cursor should be unaffected by updates from other
processes or cursors. By default, all cursors are insensitive.
This keyword currently has no effect and is present for
compatibility with the SQL standard.
Binary cursors should be used carefully. Many applications,
including <application>psql</application>, are not prepared to
handle binary cursors and expect data to come back in the text
format.
</para>
</listitem>
</varlistentry>
<para>
The string representation is architecture-neutral whereas binary
representation can differ between different machine architectures.
<emphasis><productname>PostgreSQL</productname> does not resolve
byte ordering or representation issues for binary
cursors.</emphasis> Therefore, if your client machine and server
machine use different representations (e.g.,
<quote>big-endian</quote> versus <quote>little-endian</quote>), you
will probably not want your data returned in binary format.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>NO SCROLL</term>
<term><replaceable class="parameter">cursorname</replaceable></term>
<listitem>
<para>
Specifies that the cursor cannot be used to retrieve rows in a
nonsequential fashion (e.g., backward).
The name of the cursor to be used in subsequent
<command>FETCH</command> operations.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SCROLL</term>
<term><literal>BINARY</literal></term>
<listitem>
<para>
Specifies that the cursor may be used to retrieve rows in a
nonsequential fashion (e.g., backward). Depending upon the
complexity of the query's execution plan, specifying
<literal>SCROLL</literal> may impose a performance penalty
on the query's execution time.
Causes the cursor to return data in binary rather than in text format.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>WITHOUT HOLD</term>
<term><literal>INSENSITIVE</literal></term>
<listitem>
<para>
Specifies that the cursor cannot be used outside of the
transaction that created it. If neither <literal>WITHOUT
HOLD</literal> nor <literal>WITH HOLD</literal> is specified,
<literal>WITHOUT HOLD</literal> is the default.
Indicates that data retrieved from the cursor should be
unaffected by updates to the tables underlying the cursor while
the cursor exists. In PostgreSQL, all cursors are insensitive;
this key word currently has no effect and is present for
compatibility with the SQL standard.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>WITH HOLD</term>
<term><literal>SCROLL</literal></term>
<term><literal>NO SCROLL</literal></term>
<listitem>
<para>
Specifies that the cursor may continue to be used after the
transaction that creates it successfully commits.
<literal>SCROLL</literal> specifies that the cursor may be used
to retrieve rows in a nonsequential fashion (e.g.,
backward). Depending upon the complexity of the query's
execution plan, specifying <literal>SCROLL</literal> may impose
a performance penalty on the query's execution time.
<literal>NO SCROLL</literal> specifies that the cursor cannot be
used to retrieve rows in a nonsequential fashion.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">query</replaceable></term>
<term><literal>WITH HOLD</literal></term>
<term><literal>WITHOUT HOLD</literal></term>
<listitem>
<para>
A <command>SELECT</> query which will provide the rows to be
returned by the cursor.
Refer to <xref linkend="sql-select" endterm="sql-select-title">
for further information about valid arguments.
<literal>WITH HOLD</literal> specifies that the cursor may
continue to be used after the transaction that created it
successfully commits. <literal>WITHOUT HOLD</literal> specifies
that the cursor cannot be used outside of the transaction that
created it. If neither <literal>WITHOUT HOLD</literal> nor
<literal>WITH HOLD</literal> is specified, <literal>WITHOUT
HOLD</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>READ ONLY</term>
<term><replaceable class="parameter">query</replaceable></term>
<listitem>
<para>
<acronym>SQL92</acronym> keyword indicating that the cursor will be used
in a read only mode. Since this is the only cursor access mode
available in <productname>PostgreSQL</productname> this keyword has no effect.
A <command>SELECT</> command that will provide the rows to be
returned by the cursor. Refer to <xref linkend="sql-select"
endterm="sql-select-title"> for further information about valid
queries.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>UPDATE</term>
<term><literal>FOR READ ONLY</literal></term>
<term><literal>FOR UPDATE</literal></term>
<listitem>
<para>
<acronym>SQL92</acronym> keyword indicating that the cursor will be used
to update tables. Since cursor updates are not currently
supported in <productname>PostgreSQL</productname> this keyword
provokes an informational error message.
<literal>FOR READ ONLY</literal> indicates that the cursor will
be used in a read-only mode. <literal>FOR UPDATE</literal>
indicates that the cursor will be used to update tables. Since
cursor updates are not currently supported in
<productname>PostgreSQL</productname>, specifying <literal>FOR
UPDATE</literal> will cause an error message and specifying
<literal>FOR READ ONLY</literal> has no effect.
</para>
</listitem>
</varlistentry>
......@@ -150,48 +172,37 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
<term><replaceable class="parameter">column</replaceable></term>
<listitem>
<para>
Column(s) to be updated.
Since cursor updates are not currently
supported in <productname>PostgreSQL</productname> the UPDATE clause
provokes an informational error message.
Column(s) to be updated by the cursor. Since cursor updates are
not currently supported in
<productname>PostgreSQL</productname>, the <literal>FOR
UPDATE</literal> clause provokes an error message.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The <literal>BINARY</literal>, <literal>INSENSITIVE</literal>,
and <literal>SCROLL</literal> keywords may appear in any order.
The key words <literal>BINARY</literal>,
<literal>INSENSITIVE</literal>, and <literal>SCROLL</literal> may
appear in any order.
</para>
</refsect2>
<refsect2 id="R2-SQL-DECLARE-2">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DECLARE CURSOR
</computeroutput></term>
<term><computeroutput>DECLARE CURSOR</computeroutput></term>
<listitem>
<para>
The message returned if the <command>SELECT</command> is run successfully.
The message returned if the cursor was successfully defined.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
WARNING: Closing pre-existing portal "<replaceable class="parameter">cursorname</replaceable>"
</computeroutput></term>
<term><computeroutput>WARNING: Closing pre-existing portal "<replaceable class="parameter">cursorname</replaceable>"</computeroutput></term>
<listitem>
<para>
This message is reported if a cursor with the same name already
......@@ -201,9 +212,7 @@ WARNING: Closing pre-existing portal "<replaceable class="parameter">cursorname
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: DECLARE CURSOR may only be used in begin/end transaction blocks
</computeroutput></term>
<term><computeroutput>ERROR: DECLARE CURSOR may only be used in begin/end transaction blocks</computeroutput></term>
<listitem>
<para>
This error occurs if the cursor is not declared within a
......@@ -213,74 +222,10 @@ ERROR: DECLARE CURSOR may only be used in begin/end transaction blocks
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DECLARE-1">
<refsect1info>
<date>1998-09-04</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DECLARE</command> allows a user to create cursors, which
can be used to retrieve
a small number of rows at a time out of a larger query. Cursors can
return data either in text or in binary format using
<xref linkend="sql-fetch" endterm="sql-fetch-title">.
</para>
<para>
Normal cursors return data in text format, the same as a
<command>SELECT</> would produce. Since data is stored natively in
binary format, the system must do a conversion to produce the text
format. In addition, text formats are often larger in size than the
corresponding binary format. Once the information comes back in
text form, the client application may need to convert it to a
binary format to manipulate it. BINARY cursors give you back the
data in the native binary representation.
</para>
<para>
As an example, if a query returns a value of one from an integer column,
you would get a string of <literal>1</> with a default cursor
whereas with a binary cursor you would get
a 4-byte value equal to control-A (<literal>^A</literal>).
</para>
<para>
BINARY cursors should be used carefully. User applications such
as <application>psql</application> are not aware of binary cursors
and expect data to come back in a text format.
</para>
<para>
String representation is architecture-neutral whereas binary
representation can differ between different machine architectures.
<emphasis><productname>PostgreSQL</productname> does not resolve
byte ordering or representation issues for binary cursors</emphasis>.
Therefore, if your client machine and server machine use different
representations (e.g., <quote>big-endian</quote> versus <quote>little-endian</quote>),
you will probably not want your data returned in
binary format.
<tip>
<para>
If you intend to display the data as text, retrieving it in text form
will save you some effort on the client side.
</para>
</tip>
</para>
</refsect1>
<refsect2 id="R2-SQL-DECLARE-3">
<refsect2info>
<date>1998-09-04</date>
</refsect2info>
<title>
Notes
</title>
<refsect1>
<title>Notes</title>
<para>
If <literal>WITH HOLD</literal> is not specified, the cursor
......@@ -295,87 +240,73 @@ ERROR: DECLARE CURSOR may only be used in begin/end transaction blocks
<para>
If <literal>WITH HOLD</literal> is specified and the transaction
that created the cursor successfully commits, the cursor can be
continue to be accessed by subsequent transactions in the same session.
(But if the creating
transaction is aborted, the cursor is removed.) A cursor created
with <literal>WITH HOLD</literal> is closed when an explicit
<command>CLOSE</command> command is issued on it, or when the client
connection is terminated. In the current implementation, the rows
represented by a held cursor are copied into a temporary file or
memory area so that they remain available for subsequent transactions.
that created the cursor successfully commits, the cursor can
continue to be accessed by subsequent transactions in the same
session. (But if the creating transaction is aborted, the cursor
is removed.) A cursor created with <literal>WITH HOLD</literal>
is closed when an explicit <command>CLOSE</command> command is
issued on it, or the session ends. In the current implementation,
the rows represented by a held cursor are copied into a temporary
file or memory area so that they remain available for subsequent
transactions.
</para>
<para>
The <literal>SCROLL</> option should be specified when defining a
cursor that will be used to fetch backwards. This is required by
<acronym>SQL92</acronym>. However, for compatibility with earlier
the SQL standard. However, for compatibility with earlier
versions, <productname>PostgreSQL</productname> will allow
backward fetches without <literal>SCROLL</>, if the cursor's query
plan is simple enough that no extra overhead is needed to support
it. However, application developers are advised not to rely on
using backward fetches from a cursor that has not been created
with <literal>SCROLL</literal>. If <literal>NO SCROLL</> is specified,
then backward fetches are disallowed in any case.
with <literal>SCROLL</literal>. If <literal>NO SCROLL</> is
specified, then backward fetches are disallowed in any case.
</para>
<para>
In <acronym>SQL92</acronym> cursors are only available in
embedded <acronym>SQL</acronym> (<acronym>ESQL</acronym>) applications.
The <productname>PostgreSQL</productname> backend
does not implement an explicit <command>OPEN cursor</command>
statement; a cursor is considered to be open when it is declared.
However, <application>ecpg</application>, the
embedded SQL preprocessor for <productname>PostgreSQL</productname>,
supports the <acronym>SQL92</acronym> cursor conventions, including those
involving <command>DECLARE</command> and <command>OPEN</command> statements.
The SQL standard only makes provisions for cursors in embedded
<acronym>SQL</acronym>. The <productname>PostgreSQL</productname>
server does not implement an <command>OPEN</command> statement for
cursors; a cursor is considered to be open when it is declared.
However, <application>ECPG</application>, the embedded SQL
preprocessor for <productname>PostgreSQL</productname>, supports
the standard SQL cursor conventions, including those involving
<command>DECLARE</command> and <command>OPEN</command> statements.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DECLARESTATEMENT-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
To declare a cursor:
<programlisting>
DECLARE liahona CURSOR
FOR SELECT * FROM films;
</programlisting>
<programlisting>
DECLARE liahona CURSOR FOR SELECT * FROM films;
</programlisting>
See <xref linkend="sql-fetch" endterm="sql-fetch-title"> for more
examples of cursor usage.
</para>
</refsect1>
<refsect1 id="R1-SQL-DECLARESTATEMENT-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DECLARESTATEMENT-4">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
<acronym>SQL92</acronym> allows cursors only in embedded
The SQL standard allows cursors only in embedded
<acronym>SQL</acronym> and in modules. <productname>PostgreSQL</>
permits cursors to be used interactively.
</para>
<para>
<acronym>SQL92</acronym> allows embedded or modular cursors to
update database information. All <productname>PostgreSQL</>
cursors are read only.
The SQL standard allows cursors to update table data. All
<productname>PostgreSQL</> cursors are read only.
</para>
<para>
The <literal>BINARY</literal> keyword is a
<productname>PostgreSQL</productname> extension.
Binary cursors are a <productname>PostgreSQL</productname>
extension.
</para>
</refsect2>
</refsect1>
</refentry>
......
doc/src/sgml/ref/drop_aggregate.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_aggregate.sgml,v 1.21 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_aggregate.sgml,v 1.22 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,30 +8,31 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPAGGREGATE-TITLE">DROP AGGREGATE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP AGGREGATE
</refname>
<refpurpose>
remove a user-defined aggregate function
</refpurpose>
<refname>DROP AGGREGATE</refname>
<refpurpose>remove a user-defined aggregate function</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( <replaceable class="PARAMETER">type</replaceable> ) [ CASCADE | RESTRICT ]
</synopsis>
<refsect2 id="R2-SQL-DROPAGGREGATE-1">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Inputs
</title>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP AGGREGATE</command> will delete an existing
aggregate function. To execute this command the current
user must be the owner of the aggregate function.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
......@@ -41,134 +42,92 @@ DROP AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( <replaceable
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">type</replaceable></term>
<listitem>
<para>
The input data type of the aggregate function,
or <literal>*</literal> if the function accepts any input type.
The argument data type of the aggregate function, or
<literal>*</literal> if the function accepts any data type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the aggregate.
Automatically drop objects that depend on the aggregate function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the aggregate if there are any dependent objects.
This is the default.
Refuse to drop the aggregate function if any objects depend on
it. This is the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPAGGREGATE-2">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP AGGREGATE
</computeroutput></term>
<term><computeroutput>DROP AGGREGATE</computeroutput></term>
<listitem>
<para>
Message returned if the command is successful.
Message returned if the command was successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: RemoveAggregate: aggregate '<replaceable class="parameter">name</replaceable>' for type <replaceable class="parameter">type</replaceable> does not exist
</computeroutput></term>
<term><computeroutput>ERROR: RemoveAggregate: aggregate '<replaceable class="parameter">name</replaceable>' for type <replaceable class="parameter">type</replaceable> does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if the aggregate function specified does not
exist in the database.
This message is returned if the specified aggregate function
does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPAGGREGATE-1">
<refsect1info>
<date>1998-04-15</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP AGGREGATE</command> will delete an existing
aggregate definition. To execute this command the current
user must be the owner of the aggregate.
</para>
</refsect1>
<refsect2 id="R2-SQL-DROPAGGREGATE-3">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Notes
</title>
<refsect1>
<title>Examples</title>
<para>
Use
<xref linkend="sql-createaggregate" endterm="sql-createaggregate-title">
to create aggregate functions.
To remove the aggregate function <literal>myavg</literal> for type
<type>integer</type>:
<programlisting>
DROP AGGREGATE myavg(integer);
</programlisting>
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DROPAGGREGATE-2">
<title>
Usage
</title>
<refsect1>
<title>Compatibility</title>
<para>
To remove the <literal>myavg</literal> aggregate for type
<literal>int4</literal>:
There is no <command>DROP AGGREGATE</command> statement in the SQL
standard.
</para>
<programlisting>
DROP AGGREGATE myavg(int4);
</programlisting>
</refsect1>
<refsect1 id="R1-SQL-DROPAGGREGATE-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DROPAGGREGATE-4">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>See Also</title>
<para>
There is no <command>DROP AGGREGATE</command> statement
in <acronym>SQL92</acronym>; the statement is a
<productname>PostgreSQL</productname>
language extension.
</para>
</refsect2>
<simplelist type="inline">
<member><xref linkend="sql-createaggregate" endterm="sql-createaggregate-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_cast.sgml
View file @ d1b4327d
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_cast.sgml,v 1.2 2002/08/11 17:44:12 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_cast.sgml,v 1.3 2003/05/04 02:23:16 petere Exp $ -->
<refentry id="SQL-DROPCAST">
<refmeta>
......@@ -13,8 +13,7 @@
<refsynopsisdiv>
<synopsis>
DROP CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</replaceable>)
[ CASCADE | RESTRICT ]
DROP CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</replaceable>) [ CASCADE | RESTRICT ]
</synopsis>
</refsynopsisdiv>
......@@ -30,10 +29,12 @@ DROP CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</rep
data type. These are the same privileges that are required to
create a cast.
</para>
</refsect1>
<variablelist>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable>sourcetype</replaceable></term>
......@@ -66,45 +67,33 @@ DROP CAST (<replaceable>sourcetype</replaceable> AS <replaceable>targettype</rep
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="sql-dropcast-notes">
<title>Notes</title>
<para>
Use <command>CREATE CAST</command> to create user-defined casts.
</para>
</refsect1>
<refsect1 id="sql-dropcast-examples">
<title>Examples</title>
<para>
To drop the cast from type <type>text</type> to type <type>int</type>:
<programlisting>
DROP CAST (text AS int4);
DROP CAST (text AS int);
</programlisting>
</para>
</refsect1>
<refsect1 id="sql-dropcast-compat">
<title>Compatibility</title>
<para>
The <command>DROP CAST</command> command conforms to SQL99.
The <command>DROP CAST</command> command conforms to the SQL standard.
</para>
</refsect1>
<refsect1 id="sql-dropcast-seealso">
<refsect1>
<title>See Also</title>
<para>
<xref linkend="sql-createcast" endterm="sql-createcast-title">
</para>
<simplelist type="inline">
<member><xref linkend="sql-createcast" endterm="sql-createcast-title"></member>
</simplelist>
</refsect1>
</refentry>
......
doc/src/sgml/ref/drop_conversion.sgml
View file @ d1b4327d
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_conversion.sgml,v 1.3 2002/09/21 18:32:54 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_conversion.sgml,v 1.4 2003/05/04 02:23:16 petere Exp $ -->
<refentry id="SQL-DROPCONVERSION">
<refmeta>
......@@ -13,8 +13,7 @@
<refsynopsisdiv>
<synopsis>
DROP CONVERSION <replaceable>conversion_name</replaceable>
[ CASCADE | RESTRICT ]
DROP CONVERSION <replaceable>conversion_name</replaceable> [ CASCADE | RESTRICT ]
</synopsis>
</refsynopsisdiv>
......@@ -23,15 +22,14 @@ DROP CONVERSION <replaceable>conversion_name</replaceable>
<para>
<command>DROP CONVERSION</command> removes a previously defined conversion.
</para>
<para>
To be able to drop a conversion, you must own the conversion.
</para>
</refsect1>
<variablelist>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable>conversion_name</replaceable></term>
......@@ -55,23 +53,8 @@ DROP CONVERSION <replaceable>conversion_name</replaceable>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="sql-dropconversion-notes">
<title>Notes</title>
<para>
Use <command>CREATE CONVERSION</command> to create user-defined conversions.
</para>
<para>
The privileges required to drop a conversion may be changed in a future
release.
</para>
</refsect1>
<refsect1 id="sql-dropconversion-examples">
<title>Examples</title>
......@@ -83,25 +66,21 @@ DROP CONVERSION myname;
</para>
</refsect1>
<refsect1 id="sql-dropconversion-compat">
<title>Compatibility</title>
<para>
<command>DROP CONVERSION</command>
is a <productname>PostgreSQL</productname> extension.
There is no <command>DROP CONVERSION</command>
statement in <acronym>SQL99</acronym>.
There is no <command>DROP CONVERSION</command> statement in the SQL
standard.
</para>
</refsect1>
<refsect1 id="sql-dropconversion-seealso">
<refsect1>
<title>See Also</title>
<para>
<xref linkend="sql-createconversion" endterm="sql-createconversion-title">
</para>
<simplelist type="inline">
<member><xref linkend="sql-createconversion" endterm="sql-createconversion-title"></member>
</simplelist>
</refsect1>
</refentry>
......
doc/src/sgml/ref/drop_database.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.15 2002/04/21 19:02:39 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.16 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,59 +8,56 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPDATABASE-TITLE">DROP DATABASE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP DATABASE
</refname>
<refpurpose>
remove a database
</refpurpose>
<refname>DROP DATABASE</refname>
<refpurpose>remove a database</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-12-11</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
</synopsis>
<refsect2 id="R2-SQL-DROPDATABASE-1">
<refsect2info>
<date>1999-12-11</date>
</refsect2info>
<title>
Inputs
</title>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP DATABASE</command> drops a database. It removes the
catalog entries for the database and deletes the directory
containing the data. It can only be executed by the database owner.
</para>
<para>
<command>DROP DATABASE</command> cannot be undone. Use it with care!
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of an existing database to remove.
The name of the database to remove.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPDATABASE-2">
<refsect2info>
<date>1999-12-11</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<variablelist>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>DROP DATABASE</computeroutput></term>
<listitem>
<para>
This message is returned if the command is successful.
This message is returned if the command was successful.
</para>
</listitem>
</varlistentry>
......@@ -84,72 +81,34 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPDATABASE-1">
<refsect1info>
<date>1999-12-11</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP DATABASE</command> removes the catalog entries for an existing
database and deletes the directory containing the data.
It can only be executed by the database owner (usually the user that created
it).
</para>
<para>
<command>DROP DATABASE</command> cannot be undone. Use it with care!
</para>
</refsect1>
<refsect2 id="R2-SQL-DROPDATABASE-3">
<refsect2info>
<date>1999-12-11</date>
</refsect2info>
<title>
Notes
</title>
<refsect1>
<title>Notes</title>
<para>
This command cannot be executed while connected to the target
database. Thus, it might be more convenient to use the shell
script <xref linkend="app-dropdb" endterm="app-dropdb-title">,
which is a wrapper around this command, instead.
database. Thus, it might be more convenient to use the program
<xref linkend="app-dropdb" endterm="app-dropdb-title"> instead,
which is a wrapper around this command.
</para>
</refsect1>
<refsect1>
<title>Compatibility</title>
<para>
Refer to
<xref linkend="sql-createdatabase" endterm="sql-createdatabase-title">
for information on how to create a database.
The is no <command>DROP DATABASE</command> statement in the SQL standard.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DROPDATABASE-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DROPDATABASE-4">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>See Also</title>
<para>
<command>DROP DATABASE</command> statement is a
<productname>PostgreSQL</productname> language extension;
there is no such command in <acronym>SQL92</acronym>.
</para>
</refsect2>
<simplelist type="inline">
<member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member>
</simplelist>
</refsect1>
</refentry>
......
doc/src/sgml/ref/drop_domain.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_domain.sgml,v 1.9 2002/11/21 23:34:43 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_domain.sgml,v 1.10 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
<refentry id="SQL-DROPDOMAIN">
<refmeta>
<refentrytitle id="SQL-DROPDOMAIN-TITLE">
DROP DOMAIN
</refentrytitle>
<refentrytitle id="SQL-DROPDOMAIN-TITLE">DROP DOMAIN</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP DOMAIN
</refname>
<refpurpose>
remove a user-defined domain
</refpurpose>
<refname>DROP DOMAIN</refname>
<refpurpose>remove a domain</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP DOMAIN <replaceable class="PARAMETER">domainname</replaceable> [, ...] [ CASCADE | RESTRICT ]
</synopsis>
<refsect2 id="R2-SQL-DROPDOMAIN-1">
<refsect2info>
<date>2002-02-24</date>
</refsect2info>
<title>
Inputs
</title>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP DOMAIN</command> will remove a domain. Only the
owner of a domain can remove it.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">domainname</replaceable></term>
......@@ -48,8 +46,8 @@ DROP DOMAIN <replaceable class="PARAMETER">domainname</replaceable> [, ...] [ C
<term><literal>CASCADE</></term>
<listitem>
<para>
Automatically drop objects that depend on the domain
(such as table columns).
Automatically drop objects that depend on the domain (such as
table columns).
</para>
</listitem>
</varlistentry>
......@@ -58,69 +56,43 @@ DROP DOMAIN <replaceable class="PARAMETER">domainname</replaceable> [, ...] [ C
<term><literal>RESTRICT</></term>
<listitem>
<para>
Refuse to drop the domain if there are any dependent objects.
This is the default.
Refuse to drop the domain if any objects depend on it. This is
the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPDOMAIN-2">
<refsect2info>
<date>2002-02-24</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP DOMAIN
</computeroutput></term>
<term><computeroutput>DROP DOMAIN</computeroutput></term>
<listitem>
<para>
The message returned if the command is successful.
Message returned if the command was successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: RemoveDomain: type '<replaceable class="parameter">domainname</replaceable>' does not exist
</computeroutput></term>
<term><computeroutput>ERROR: RemoveDomain: type '<replaceable class="parameter">domainname</replaceable>' does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if the specified domain (or type) is not found.
This message occurs if the specified domain does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPDOMAIN-1">
<refsect1info>
<date>2002-02-24</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP DOMAIN</command> will remove a user domain from the
system catalogs.
</para>
<para>
Only the owner of a domain can remove it.
</para>
</refsect1>
<refsect1 id="SQL-DROPDOMAIN-examples">
<title>Examples</title>
<para>
To remove the <type>box</type> domain:
To remove the domain <type>box</type>:
<programlisting>
DROP DOMAIN box;
......@@ -131,13 +103,9 @@ DROP DOMAIN box;
<refsect1 id="SQL-DROPDOMAIN-compatibility">
<title>Compatibility</title>
<refsect2 id="R2-SQL-DROPDOMAIN-sql92">
<title>
SQL92
</title>
<para></para>
</refsect2>
<para>
This command conforms to the SQL standard.
</para>
</refsect1>
<refsect1 id="SQL-DROPDOMAIN-see-also">
......
doc/src/sgml/ref/drop_function.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_function.sgml,v 1.23 2002/11/21 23:34:43 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_function.sgml,v 1.24 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,30 +8,33 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPFUNCTION-TITLE">DROP FUNCTION</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP FUNCTION
</refname>
<refpurpose>
remove a user-defined function
</refpurpose>
<refname>DROP FUNCTION</refname>
<refpurpose>remove a user-defined function</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">type</replaceable> [, ...] ] ) [ CASCADE | RESTRICT ]
</synopsis>
<refsect2 id="R2-SQL-DROPFUNCTION-1">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Inputs
</title>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP FUNCTION</command> removes the definition of an existing
function. To execute this command the user must be the
owner of the function. The argument types to the
function must be specified, since several different functions
may exist with the same name and different argument lists.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
......@@ -41,96 +44,60 @@ DROP FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">type</replaceable></term>
<listitem>
<para>
The type of a parameter of the function.
The data type of an argument of the function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the function
(such as operators or triggers).
Automatically drop objects that depend on the function (such as
operators or triggers).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the function if there are any dependent objects.
This is the default.
Refuse to drop the function if any objects depend on it. This
is the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPFUNCTION-2">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP FUNCTION
</computeroutput></term>
<term><computeroutput>DROP FUNCTION</computeroutput></term>
<listitem>
<para>
Message returned if the command completes successfully.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
WARNING: RemoveFunction: Function "<replaceable class="parameter">name</replaceable>" ("<replaceable class="parameter">types</replaceable>") does not exist
</computeroutput></term>
<term><computeroutput>WARNING: RemoveFunction: Function <replaceable class="parameter">name</replaceable> (<replaceable class="parameter">types</replaceable>) does not exist</computeroutput></term>
<listitem>
<para>
This message is given if the function specified does not
exist in the current database.
This message is output if the function specified does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPFUNCTION-1">
<refsect1info>
<date>1998-04-15</date>
</refsect1info>
<title>
Description
</title>
<para>
DROP FUNCTION will remove the definition of an existing
function. To execute this command the user must be the
owner of the function. The input argument types to the
function must be specified, since several different functions
may exist with the same name and different argument lists.
</para>
</refsect1>
<refsect1 id="SQL-DROPFUNCTION-notes">
<title>Notes</title>
<para>
Refer to
<xref linkend="sql-createfunction" endterm="sql-createfunction-title">
for information on creating functions.
</para>
</refsect1>
<refsect1 id="SQL-DROPFUNCTION-examples">
......@@ -149,8 +116,8 @@ DROP FUNCTION sqrt(integer);
<title>Compatibility</title>
<para>
A <command>DROP FUNCTION</command> statement is defined in SQL99. One of
its syntax forms is similar to PostgreSQL's.
A <command>DROP FUNCTION</command> statement is defined in the SQL
standard, but it is not compatible with this command.
</para>
</refsect1>
......@@ -161,6 +128,7 @@ DROP FUNCTION sqrt(integer);
<member><xref linkend="sql-createfunction" endterm="sql-createfunction-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_group.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_group.sgml,v 1.4 2002/04/21 19:02:39 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_group.sgml,v 1.5 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,30 +8,29 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPGROUP-TITLE">DROP GROUP</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP GROUP
</refname>
<refpurpose>
remove a user group
</refpurpose>
<refname>DROP GROUP</refname>
<refpurpose>remove a user group</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2000-01-14</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP GROUP <replaceable class="PARAMETER">name</replaceable>
</synopsis>
<refsect2 id="R2-SQL-DROPGROUP-1">
<refsect2info>
<date>2000-01-14</date>
</refsect2info>
<title>
Inputs
</title>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP GROUP</command> removes the specified group. The
users in the group are not deleted.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
......@@ -43,54 +42,26 @@ DROP GROUP <replaceable class="PARAMETER">name</replaceable>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPGROUP-2">
<refsect2info>
<date>2000-01-14</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>DROP GROUP</computeroutput></term>
<listitem>
<para>
The message returned if the group is successfully deleted.
Message returned if the group was successfully removed.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPGROUP-1">
<refsect1info>
<date>2000-01-14</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP GROUP</command> removes the specified group from the database.
The users in the group are not deleted.
</para>
<para>
Use <xref linkend="SQL-CREATEGROUP" endterm="SQL-CREATEGROUP-title">
to add new groups, and <xref linkend="SQL-ALTERGROUP"
endterm="SQL-ALTERGROUP-title"> to change a group's membership.
</para>
</refsect1>
<refsect1 id="R1-SQL-DROPGROUP-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
To drop a group:
<programlisting>
......@@ -99,23 +70,23 @@ DROP GROUP staff;
</para>
</refsect1>
<refsect1 id="R1-SQL-DROPGROUP-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DROPGROUP-4">
<refsect2info>
<date>2000-01-14</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
There is no <command>DROP GROUP</command> in <acronym>SQL92</acronym>.
There is no <command>DROP GROUP</command> statement in the SQL standard.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-altergroup" endterm="sql-altergroup-title"></member>
<member><xref linkend="sql-creategroup" endterm="sql-creategroup-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_index.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_index.sgml,v 1.16 2002/07/12 18:43:13 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_index.sgml,v 1.17 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,30 +8,31 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPINDEX-TITLE">DROP INDEX</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP INDEX
</refname>
<refpurpose>
remove an index
</refpurpose>
<refname>DROP INDEX</refname>
<refpurpose>remove an index</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP INDEX <replaceable class="PARAMETER">index_name</replaceable> [, ...] [ CASCADE | RESTRICT ]
</synopsis>
<refsect2 id="R2-SQL-DROPINDEX-1">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Inputs
</title>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP INDEX</command> drops an existing index from the database
system. To execute this command you must be the owner of
the index.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">index_name</replaceable></term>
......@@ -41,128 +42,84 @@ DROP INDEX <replaceable class="PARAMETER">index_name</replaceable> [, ...] [ CAS
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the index.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the index if there are any dependent objects.
This is the default.
Refuse to drop the index if any objects depend on it. This is
the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPINDEX-2">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP INDEX
</computeroutput></term>
<term><computeroutput>DROP INDEX</computeroutput></term>
<listitem>
<para>
The message returned if the command completes successfully.
Message returned if the command completes successfully.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: index "<replaceable class="PARAMETER">index_name</replaceable>" does not exist
</computeroutput></term>
<term><computeroutput>ERROR: index "<replaceable class="PARAMETER">index_name</replaceable>" does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if <replaceable class="PARAMETER">index_name</replaceable>
is not an index in the database.
This message is returned if <replaceable
class="PARAMETER">index_name</replaceable> is not an existing
index.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
</refsect1>
<refsect1 id="R1-SQL-DROPINDEX-1">
<refsect1info>
<date>1998-04-15</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP INDEX</command> drops an existing index from the database
system. To execute this command you must be the owner of
the index.
</para>
<refsect1>
<title>Examples</title>
<refsect2 id="R2-SQL-DROPINDEX-3">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Notes
</title>
<para>
<command>DROP INDEX</command> is a <productname>PostgreSQL</productname>
language extension.
</para>
<para>
Refer to
<xref linkend="sql-createindex" endterm="sql-createindex-title">
for information on how to create indexes.
This command will remove the index <literal>title_idx</literal>:
<programlisting>
DROP INDEX title_idx;
</programlisting>
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DROPINDEX-2">
<title>
Usage
</title>
<para>
This command will remove the <literal>title_idx</literal> index:
<refsect1>
<title>Compatibility</title>
<programlisting>
DROP INDEX title_idx;
</programlisting>
<para>
<command>DROP INDEX</command> is a
<productname>PostgreSQL</productname> language extension. There
are no provisions for indexes in the SQL standard.
</para>
</refsect1>
<refsect1 id="R1-SQL-DROPINDEX-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DROPINDEX-4">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
SQL92
</title>
<para>
<acronym>SQL92</acronym> defines commands by which to access
a generic relational database.
Indexes are an implementation-dependent feature and hence
there are no index-specific commands or definitions in the
<acronym>SQL92</acronym> language.
</para>
</refsect2>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createindex" endterm="sql-createindex-title"></member>
</simplelist>
</refsect1>
</refentry>
......
doc/src/sgml/ref/drop_language.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_language.sgml,v 1.15 2002/07/12 18:43:13 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_language.sgml,v 1.16 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,30 +8,30 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPLANGUAGE-TITLE">DROP LANGUAGE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP LANGUAGE
</refname>
<refpurpose>
remove a user-defined procedural language
</refpurpose>
<refname>DROP LANGUAGE</refname>
<refpurpose>remove a user-defined procedural language</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">name</replaceable> [ CASCADE | RESTRICT ]
</synopsis>
<refsect2 id="R2-SQL-DROPLANGUAGE-1">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Inputs
</title>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP LANGUAGE</command> will remove the definition
of the previously registered procedural language called
<replaceable class="parameter">name</replaceable>.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
......@@ -43,128 +43,85 @@ DROP [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">name</replaceable> [
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the language
(such as functions in the language).
Automatically drop objects that depend on the language (such as
functions in the language).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the language if there are any dependent objects.
This is the default.
Refuse to drop the language if any objects depend on it. This
is the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPLANGUAGE-2">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP LANGUAGE
</computeroutput></term>
<term><computeroutput>DROP LANGUAGE</computeroutput></term>
<listitem>
<para>
This message is returned if the language is successfully dropped.
This message is returned if the language was successfully dropped.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: Language "<replaceable class="parameter">name</replaceable>" doesn't exist
</computeroutput></term>
<term><computeroutput>ERROR: Language "<replaceable class="parameter">name</replaceable>" doesn't exist</computeroutput></term>
<listitem>
<para>
This message occurs if a language called
<replaceable class="parameter">name</replaceable> is
not found in the database.
This message is returned if a language called <replaceable
class="parameter">name</replaceable> is not found in the
database.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPLANGUAGE-1">
<refsect1info>
<date>1998-04-15</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP PROCEDURAL LANGUAGE</command> will remove the definition
of the previously registered procedural language called
<replaceable class="parameter">name</replaceable>.
</para>
<refsect2 id="R2-SQL-DROPLANGUAGE-3">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Notes
</title>
<para>
The <command>DROP PROCEDURAL LANGUAGE</command> statement is
a <productname>PostgreSQL</productname> language extension.
</para>
<para>
Refer to
<xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
for information on how to create procedural languages.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DROPLANGUAGE-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
This command removes the PL/Sample language:
This command removes the procedural language
<literal>plsample</literal>:
<programlisting>
<programlisting>
DROP LANGUAGE plsample;
</programlisting>
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-DROPLANGUAGE-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DROPLANGUAGE-5">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
There is no <command>DROP PROCEDURAL LANGUAGE</command> in
<acronym>SQL92</acronym>.
There is no <command>DROP LANGUAGE</command> statement in the SQL
standard.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_opclass.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_opclass.sgml,v 1.2 2002/09/21 18:32:54 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_opclass.sgml,v 1.3 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,31 +8,30 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPOPCLASS-TITLE">DROP OPERATOR CLASS</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP OPERATOR CLASS
</refname>
<refpurpose>
remove a user-defined operator class
</refpurpose>
<refname>DROP OPERATOR CLASS</refname>
<refpurpose>remove a user-defined operator class</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2002-07-28</date>
</refsynopsisdivinfo>
<synopsis>
DROP OPERATOR CLASS <replaceable class="PARAMETER">name</replaceable> USING <replaceable class="PARAMETER">access_method</replaceable> [ CASCADE | RESTRICT ]
</synopsis>
<refsect2 id="R2-SQL-DROPOPCLASS-1">
<refsect2info>
<date>2002-07-28</date>
</refsect2info>
<title>
Inputs
</title>
<synopsis>
DROP OPERATOR CLASS <replaceable class="PARAMETER">name</replaceable> USING <replaceable class="PARAMETER">index_method</replaceable> [ CASCADE | RESTRICT ]
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP OPERATOR CLASS</command> drops an existing operator class.
To execute this command you must be the owner of the operator class.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
......@@ -42,128 +41,85 @@ DROP OPERATOR CLASS <replaceable class="PARAMETER">name</replaceable> USING <rep
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">access_method</replaceable></term>
<term><replaceable class="parameter">index_method</replaceable></term>
<listitem>
<para>
The name of the index access method the operator class is for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the operator class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the operator class if there are any dependent objects.
Refuse to drop the operator class if any objects depend on it.
This is the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPOPCLASS-2">
<refsect2info>
<date>2002-07-28</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP OPERATOR CLASS
</computeroutput></term>
<term><computeroutput>DROP OPERATOR CLASS</computeroutput></term>
<listitem>
<para>
The message returned if the command is successful.
Message returned if the command was successful.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPOPCLASS-1">
<refsect1info>
<date>2002-07-28</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP OPERATOR CLASS</command> drops an existing operator class
from the database.
To execute this command you must be the owner of the operator class.
</para>
<refsect2 id="R2-SQL-DROPOPCLASS-3">
<refsect2info>
<date>2002-07-28</date>
</refsect2info>
<title>
Notes
</title>
<para>
The <command>DROP OPERATOR CLASS</command> statement is a
<productname>PostgreSQL</productname>
language extension.
</para>
<para>
Refer to
<xref linkend="sql-createopclass" endterm="sql-createopclass-title">
for information on how to create operator classes.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DROPOPCLASS-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
Remove B-tree operator class <literal>widget_ops</literal>:
Remove the B-tree operator class <literal>widget_ops</literal>:
<programlisting>
<programlisting>
DROP OPERATOR CLASS widget_ops USING btree;
</programlisting>
</programlisting>
This command will not execute if there are any existing indexes
This command will not succeed if there are any existing indexes
that use the operator class. Add <literal>CASCADE</> to drop
such indexes along with the operator class.
</para>
</refsect1>
<refsect1 id="R1-SQL-DROPOPCLASS-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DROPOPCLASS-4">
<refsect2info>
<date>2002-07-28</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
There is no <command>DROP OPERATOR CLASS</command> in
<acronym>SQL92</acronym>.
There is no <command>DROP OPERATOR CLASS</command> statement in the
SQL standard.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createopclass" endterm="sql-createopclass-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_operator.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_operator.sgml,v 1.18 2002/07/29 22:14:10 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_operator.sgml,v 1.19 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,216 +8,169 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPOPERATOR-TITLE">DROP OPERATOR</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP OPERATOR
</refname>
<refpurpose>
remove a user-defined operator
</refpurpose>
<refname>DROP OPERATOR</refname>
<refpurpose>remove a user-defined operator</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
DROP OPERATOR <replaceable class="PARAMETER">id</replaceable> ( <replaceable class="PARAMETER">lefttype</replaceable> | NONE , <replaceable class="PARAMETER">righttype</replaceable> | NONE ) [ CASCADE | RESTRICT ]
</synopsis>
<refsect2 id="R2-SQL-DROPOPERATOR-1">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Inputs
</title>
<synopsis>
DROP OPERATOR <replaceable class="PARAMETER">name</replaceable> ( <replaceable class="PARAMETER">lefttype</replaceable> | NONE , <replaceable class="PARAMETER">righttype</replaceable> | NONE ) [ CASCADE | RESTRICT ]
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP OPERATOR</command> drops an existing operator from
the database system. To execute this command you must be the owner
of the operator.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">id</replaceable></term>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The identifier (optionally schema-qualified) of an existing operator.
The name (optionally schema-qualified) of an existing operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">lefttype</replaceable></term>
<listitem>
<para>
The type of the operator's left argument; write <literal>NONE</literal> if the
operator has no left argument.
The data type of the operator's left operand; write
<literal>NONE</literal> if the operator has no left operand.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">righttype</replaceable></term>
<listitem>
<para>
The type of the operator's right argument; write <literal>NONE</literal> if the
operator has no right argument.
The data type of the operator's right operand; write
<literal>NONE</literal> if the operator has no right operand.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the operator if there are any dependent objects.
This is the default.
Refuse to drop the operator if any objects depend on it. This
is the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPOPERATOR-2">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP OPERATOR
</computeroutput></term>
<term><computeroutput>DROP OPERATOR</computeroutput></term>
<listitem>
<para>
The message returned if the command is successful.
Message returned if the command was successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: RemoveOperator: binary operator '<replaceable class="PARAMETER">oper</replaceable>' taking '<replaceable class="PARAMETER">lefttype</replaceable>' and '<replaceable class="PARAMETER">righttype</replaceable>' does not exist
</computeroutput></term>
<term><computeroutput>ERROR: RemoveOperator: binary operator '<replaceable class="PARAMETER">name</replaceable>' taking '<replaceable class="PARAMETER">lefttype</replaceable>' and '<replaceable class="PARAMETER">righttype</replaceable>' does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if the specified binary operator does not exist.
This message is returned if the specified binary operator does not exist.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: RemoveOperator: left unary operator '<replaceable class="PARAMETER">oper</replaceable>' taking '<replaceable class="PARAMETER">lefttype</replaceable>' does not exist
</computeroutput></term>
<term><computeroutput>ERROR: RemoveOperator: left unary operator '<replaceable class="PARAMETER">name</replaceable>' taking '<replaceable class="PARAMETER">lefttype</replaceable>' does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if the left unary operator
specified does not exist.
This message is returned if the specified left unary operator
does not exist.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: RemoveOperator: right unary operator '<replaceable class="PARAMETER">oper</replaceable>' taking '<replaceable class="PARAMETER">righttype</replaceable>' does not exist
</computeroutput></term>
<term><computeroutput>ERROR: RemoveOperator: right unary operator '<replaceable class="PARAMETER">name</replaceable>' taking '<replaceable class="PARAMETER">righttype</replaceable>' does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if the right unary operator
specified does not exist.
This message is returned if the specified right unary operator
does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
</refsect1>
<refsect1>
<title>Examples</title>
<refsect1 id="R1-SQL-DROPOPERATOR-1">
<refsect1info>
<date>1998-09-22</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP OPERATOR</command> drops an existing operator from the
database.
To execute this command you must be the owner of the operator.
</para>
<para>
The left or right type of a left or right unary
operator, respectively, must be specified as <literal>NONE</literal>.
Remove the power operator <literal>a^b</literal> for type <type>integer</type>:
<programlisting>
DROP OPERATOR ^ (integer, integer);
</programlisting>
</para>
<refsect2 id="R2-SQL-DROPOPERATOR-3">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Notes
</title>
<para>
The <command>DROP OPERATOR</command> statement is a
<productname>PostgreSQL</productname>
language extension.
Remove the left unary bitwise complement operator
<literal>~b</literal> for type <type>bit</type>:
<programlisting>
DROP OPERATOR ~ (none, bit);
</programlisting>
</para>
<para>
Refer to
<xref linkend="sql-createoperator" endterm="sql-createoperator-title">
for information on how to create operators.
Remove the right unary factorial operator <literal>x!</literal>
for type <type>integer</type>:
<programlisting>
DROP OPERATOR ! (integer, none);
</programlisting>
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DROPOPERATOR-2">
<title>
Usage
</title>
<para>
Remove power operator <literal>a^n</literal> for <literal>int4</literal>:
<refsect1>
<title>Compatibility</title>
<programlisting>
DROP OPERATOR ^ (int4, int4);
</programlisting>
</para>
<para>
Remove left unary negation operator (<literal>! b</literal>) for <type>boolean</type>:
<programlisting>
DROP OPERATOR ! (none, bool);
</programlisting>
</para>
<para>
Remove right unary factorial operator (<literal>i !</literal>) for
<literal>int4</literal>:
<programlisting>
DROP OPERATOR ! (int4, none);
</programlisting>
There is no <command>DROP OPERATOR</command> statement in the SQL standard.
</para>
</refsect1>
<refsect1 id="R1-SQL-DROPOPERATOR-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DROPOPERATOR-4">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>DROP OPERATOR</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createoperator" endterm="sql-createoperator-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_rule.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_rule.sgml,v 1.16 2002/07/12 18:43:13 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_rule.sgml,v 1.17 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,169 +8,122 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPRULE-TITLE">DROP RULE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP RULE
</refname>
<refpurpose>
remove a rewrite rule
</refpurpose>
<refname>DROP RULE</refname>
<refpurpose>remove a rewrite rule</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1998-09-22</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP RULE <replaceable class="PARAMETER">name</replaceable> ON <replaceable class="PARAMETER">relation</replaceable> [ CASCADE | RESTRICT ]
</synopsis>
<refsect2 id="R2-SQL-DROPRULE-1">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Inputs
</title>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP RULE</command> drops a rewrite rule.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of an existing rule to drop.
The name of the rule to drop.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">relation</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of the relation the rule
applies to.
The name (optionally schema-qualified) of the table or view that
the rule applies to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the rule.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the rule if there are any dependent objects.
This is the default.
Refuse to drop the rule if any objects depend on it. This is
the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPRULE-2">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP RULE
</computeroutput></term>
<term><computeroutput>DROP RULE</computeroutput></term>
<listitem>
<para>
Message returned if successful.
Message returned if the command was successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: Rule "<replaceable class="parameter">name</replaceable>" not found
</computeroutput></term>
<term><computeroutput>ERROR: Rule "<replaceable class="parameter">name</replaceable>" not found</computeroutput></term>
<listitem>
<para>
This message occurs if the specified rule does not exist.
Message if the specified rule does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPRULE-1">
<refsect1info>
<date>1998-09-22</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP RULE</command> drops a rule from the specified
<productname>PostgreSQL</productname> rule
system. <productname>PostgreSQL</productname>
will immediately cease enforcing it and
will purge its definition from the system catalogs.
</para>
<refsect2 id="R2-SQL-DROPRULE-3">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Notes
</title>
<para>
The <command>DROP RULE</command> statement is a
<productname>PostgreSQL</productname>
language extension.
</para>
<para>
Refer to <command>CREATE RULE</command> for
information on how to create rules.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DROPRULE-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
To drop the rewrite rule <literal>newrule</literal>:
<programlisting>
<programlisting>
DROP RULE newrule ON mytable;
</programlisting>
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-DROPRULE-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DROPRULE-5">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
There is no <command>DROP RULE</command> in SQL92.
There is no <command>DROP RULE</command> statement in the SQL standard.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createrule" endterm="sql-createrule-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_schema.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_schema.sgml,v 1.1 2002/07/18 16:47:22 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_schema.sgml,v 1.2 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,31 +8,35 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPSCHEMA-TITLE">DROP SCHEMA</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP SCHEMA
</refname>
<refpurpose>
remove a schema
</refpurpose>
<refname>DROP SCHEMA</refname>
<refpurpose>remove a schema</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2002-07-18</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP SCHEMA <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCADE | RESTRICT ]
</synopsis>
</refsynopsisdiv>
</synopsis>
<refsect1>
<title>Description</title>
<para>
<command>DROP SCHEMA</command> removes schemas from the database.
</para>
<refsect2 id="R2-SQL-DROPSCHEMA-1">
<refsect2info>
<date>2002-07-18</date>
</refsect2info>
<title>
Inputs
</title>
<para>
A schema can only be dropped by its owner or a superuser. Note that
the owner can drop the schema (and thereby all contained objects)
even if he does not own some of the objects within the schema.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
......@@ -42,128 +46,84 @@ DROP SCHEMA <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCADE
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects (tables, functions, etc) that are contained
in the schema.
Automatically drop objects (tables, functions, etc.) that are
contained in the schema.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the schema if it contains any objects.
This is the default.
Refuse to drop the schema if it contains any objects. This is
the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPSCHEMA-2">
<refsect2info>
<date>2002-07-18</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP SCHEMA
</computeroutput></term>
<term><computeroutput>DROP SCHEMA</computeroutput></term>
<listitem>
<para>
The message returned if the schema is successfully dropped.
Message returned if the schema was successfully dropped.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: Schema "<replaceable class="parameter">name</replaceable>" does not exist
</computeroutput></term>
<term><computeroutput>ERROR: Schema "<replaceable class="parameter">name</replaceable>" does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if the specified schema does not exist.
This message is returned if the specified schema does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPSCHEMA-1">
<refsect1info>
<date>2002-07-18</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP SCHEMA</command> removes schemas from the data base.
</para>
<para>
A schema can only be dropped by its owner or a superuser. Note that
the owner can drop the schema (and thereby all contained objects)
even if he does not own some of the objects within the schema.
</para>
<refsect2 id="R2-SQL-DROPSCHEMA-3">
<refsect2info>
<date>2002-07-18</date>
</refsect2info>
<title>
Notes
</title>
<para>
Refer to the <command>CREATE SCHEMA</command> statement for
information on how to create a schema.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DROPSCHEMA-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
To remove schema <literal>mystuff</literal> from the database,
along with everything it contains:
<programlisting>
<programlisting>
DROP SCHEMA mystuff CASCADE;
</programlisting>
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-DROPSCHEMA-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DROPSCHEMA-4">
<refsect2info>
<date>2002-07-18</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
<command>DROP SCHEMA</command> is fully compatible with
<acronym>SQL92</acronym>, except that the standard only allows
one schema to be dropped per command.
<command>DROP SCHEMA</command> is fully conforming with the SQL
standard, except that the standard only allows one schema to be
dropped per command.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createschema" endterm="sql-createschema-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_sequence.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_sequence.sgml,v 1.16 2002/07/18 15:49:08 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_sequence.sgml,v 1.17 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,31 +8,29 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPSEQUENCE-TITLE">DROP SEQUENCE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP SEQUENCE
</refname>
<refpurpose>
remove a sequence
</refpurpose>
<refname>DROP SEQUENCE</refname>
<refpurpose>remove a sequence</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP SEQUENCE <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCADE | RESTRICT ]
</synopsis>
</refsynopsisdiv>
</synopsis>
<refsect1>
<title>Description</title>
<refsect2 id="R2-SQL-DROPSEQUENCE-1">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<command>DROP SEQUENCE</command> removes sequence number generators.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
......@@ -42,126 +40,80 @@ DROP SEQUENCE <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCAD
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the sequence.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the sequence if there are any dependent objects.
This is the default.
Refuse to drop the sequence if any objects depend on it. This
is the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPSEQUENCE-2">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP SEQUENCE
</computeroutput></term>
<term><computeroutput>DROP SEQUENCE</computeroutput></term>
<listitem>
<para>
The message returned if the sequence is successfully dropped.
Message returned if the sequence was successfully dropped.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: sequence "<replaceable class="parameter">name</replaceable>" does not exist
</computeroutput></term>
<term><computeroutput>ERROR: sequence "<replaceable class="parameter">name</replaceable>" does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if the specified sequence does not exist.
Message returned if the specified sequence does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1>
<title>Examples</title>
<refsect1 id="R1-SQL-DROPSEQUENCE-1">
<refsect1info>
<date>1998-09-22</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP SEQUENCE</command> removes sequence number generators from the
data base. With the current implementation of sequences as
special tables it works just like the <command>DROP TABLE</command>
statement.
</para>
To remove the sequence <literal>serial</literal>:
<refsect2 id="R2-SQL-DROPSEQUENCE-3">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Notes
</title>
<para>
The <command>DROP SEQUENCE</command> statement is a
<productname>PostgreSQL</productname>
language extension.
</para>
<para>
Refer to the <command>CREATE SEQUENCE</command> statement for
information on how to create a sequence.
<programlisting>
DROP SEQUENCE serial;
</programlisting>
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DROPSEQUENCE-2">
<title>
Usage
</title>
<para>
To remove sequence <literal>serial</literal> from database:
<refsect1>
<title>Compatibility</title>
<programlisting>
DROP SEQUENCE serial;
</programlisting>
<para>
There is no <command>DROP SEQUENCE</command> statement in the SQL standard.
</para>
</refsect1>
<refsect1 id="R1-SQL-DROPSEQUENCE-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DROPSEQUENCE-4">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>DROP SEQUENCE</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createsequence" endterm="sql-createsequence-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_table.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_table.sgml,v 1.17 2002/07/14 22:47:56 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_table.sgml,v 1.18 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,158 +8,126 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPTABLE-TITLE">DROP TABLE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP TABLE
</refname>
<refpurpose>
remove a table
</refpurpose>
<refname>DROP TABLE</refname>
<refpurpose>remove a table</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP TABLE <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCADE | RESTRICT ]
</synopsis>
</refsynopsisdiv>
</synopsis>
<refsect1>
<title>Description</title>
<para>
<command>DROP TABLE</command> removes tables from the database.
Only its owner may destroy a table. To empty a table of rows,
without destroying the table, use <command>DELETE</command>.
</para>
<refsect2 id="R2-SQL-DROPTABLE-1">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<command>DROP TABLE</command> always removes any indexes, rules,
triggers, and constraints that exist for the target table.
However, to drop a table that is referenced by a foreign-key
constraint of another table, <literal>CASCADE</> must be
specified. (<literal>CASCADE</> will remove the foreign-key
constraint, not the other table entirely.)
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an existing table to drop.
The name (optionally schema-qualified) of the table to drop.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the table
(such as views).
Automatically drop objects that depend on the table (such as
views).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the table if there are any dependent objects.
This is the default.
Refuse to drop the table if any objects depend on it. This is
the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPTABLE-2">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP TABLE
</computeroutput></term>
<term><computeroutput>DROP TABLE</computeroutput></term>
<listitem>
<para>
The message returned if the command completes successfully.
Message returned if the command completes successfully.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: table "<replaceable class="parameter">name</replaceable>" does not exist
</computeroutput></term>
<term><computeroutput>ERROR: table "<replaceable class="parameter">name</replaceable>" does not exist</computeroutput></term>
<listitem>
<para>
If the specified table does not exist in the database.
Message returned if the specified table does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPTABLE-1">
<refsect1info>
<date>1998-09-22</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP TABLE</command> removes tables from the database.
Only its owner may destroy a table. A table may be emptied of rows, but not
destroyed, by using <command>DELETE</command>.
</para>
<para>
<command>DROP TABLE</command> always removes any indexes, rules,
triggers, and constraints that exist for the target table. However,
to drop a table that is referenced by a foreign-key constraint of another
table, CASCADE must be specified. (CASCADE will remove the foreign-key
constraint, not the other table itself.)
</para>
<refsect2 id="R2-SQL-DROPTABLE-3">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Notes
</title>
<para>
Refer to <command>CREATE TABLE</command> and
<command>ALTER TABLE</command> for information on
how to create or modify tables.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DROPTABLE-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
To destroy two tables, <literal>films</literal> and
<literal>distributors</literal>:
<programlisting>
<programlisting>
DROP TABLE films, distributors;
</programlisting>
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-DROPTABLE-3">
<title>
Compatibility
</title>
<refsect1>
<title>Compatibility</title>
<refsect2 id="R2-SQL-DROPTABLE-4">
<title>
SQL92
</title>
<para>
This command conforms to the SQL standard.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-altertable" endterm="sql-altertable-title"></member>
<member><xref linkend="sql-createtable" endterm="sql-createtable-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_trigger.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_trigger.sgml,v 1.14 2002/11/21 23:34:43 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_trigger.sgml,v 1.15 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,124 +8,102 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPTRIGGER-TITLE">DROP TRIGGER</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP TRIGGER
</refname>
<refpurpose>
remove a trigger
</refpurpose>
<refname>DROP TRIGGER</refname>
<refpurpose>remove a trigger</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1998-09-22</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP TRIGGER <replaceable class="PARAMETER">name</replaceable> ON <replaceable class="PARAMETER">table</replaceable> [ CASCADE | RESTRICT ]
</synopsis>
<refsect2 id="R2-SQL-DROPTRIGGER-1">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Inputs
</title>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP TRIGGER</command> will remove an existing
trigger definition. To execute this command, the current
user must be the owner of the table for which the trigger is defined.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of an existing trigger.
The name of the trigger to remove.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of a table.
The name (optionally schema-qualified) of a table for which the
trigger is defined.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the trigger.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the trigger if there are any dependent objects.
This is the default.
Refuse to drop the trigger if any objects depend on it. This is
the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPTRIGGER-2">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP TRIGGER
</computeroutput></term>
<term><computeroutput>DROP TRIGGER</computeroutput></term>
<listitem>
<para>
The message returned if the trigger is successfully dropped.
Message returned if the trigger was successfully dropped.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: DropTrigger: there is no trigger <replaceable class="PARAMETER">name</replaceable> on relation "<replaceable class="parameter">table</replaceable>"
</computeroutput></term>
<term><computeroutput>ERROR: DropTrigger: there is no trigger <replaceable class="PARAMETER">name</replaceable> on relation "<replaceable class="parameter">table</replaceable>"</computeroutput></term>
<listitem>
<para>
This message occurs if the trigger specified does not exist.
Message returned if the specified trigger does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPTRIGGER-1">
<refsect1info>
<date>1998-09-22</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP TRIGGER</command> will remove an existing
trigger definition. To execute this command the current
user must be the owner of the table for which the trigger is defined.
</para>
</refsect1>
<refsect1 id="SQL-DROPTRIGGER-examples">
<title>Examples</title>
<para>
Destroy the <literal>if_dist_exists</literal> trigger
on table <literal>films</literal>:
Destroy the trigger <literal>if_dist_exists</literal> on the table
<literal>films</literal>:
<programlisting>
DROP TRIGGER if_dist_exists ON films;
......@@ -136,30 +114,13 @@ DROP TRIGGER if_dist_exists ON films;
<refsect1 id="SQL-DROPTRIGGER-compatibility">
<title>Compatibility</title>
<variablelist>
<varlistentry>
<term>SQL92</term>
<listitem>
<para>
There is no <command>DROP TRIGGER</command> statement in
<acronym>SQL92</acronym>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SQL99</term>
<listitem>
<para>
The <command>DROP TRIGGER</command> statement in
<productname>PostgreSQL</productname> is incompatible with
SQL99. In SQL99, trigger names are not local to tables, so the
command is simply <literal>DROP TRIGGER
<productname>PostgreSQL</productname> is incompatible with the SQL
standard. In the SQL standard, trigger names are not local to
tables, so the command is simply <literal>DROP TRIGGER
<replaceable>name</replaceable></literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
......@@ -169,6 +130,7 @@ DROP TRIGGER if_dist_exists ON films;
<member><xref linkend="sql-createtrigger" endterm="sql-createtrigger-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_type.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_type.sgml,v 1.20 2002/11/21 23:34:43 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_type.sgml,v 1.21 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,118 +8,91 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPTYPE-TITLE">DROP TYPE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP TYPE
</refname>
<refpurpose>
remove a user-defined data type
</refpurpose>
<refname>DROP TYPE</refname>
<refpurpose>remove a user-defined data type</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP TYPE <replaceable class="PARAMETER">typename</replaceable> [, ...] [ CASCADE | RESTRICT ]
</synopsis>
</refsynopsisdiv>
</synopsis>
<refsect1>
<title>Description</title>
<refsect2 id="R2-SQL-DROPTYPE-1">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<command>DROP TYPE</command> will remove a user-defined data type.
Only the owner of a type can remove it.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">typename</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an existing type.
The name (optionally schema-qualified) of the data type to remove.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the type
(such as table columns, functions, operators, etc).
Automatically drop objects that depend on the type (such as
table columns, functions, operators).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the type if there are any dependent objects.
This is the default.
Refuse to drop the type if any objects depend on it. This is
the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPTYPE-2">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Outputs
</title>
<para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP TYPE
</computeroutput></term>
<term><computeroutput>DROP TYPE</computeroutput></term>
<listitem>
<para>
The message returned if the command is successful.
Message returned if the command was successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: RemoveType: type '<replaceable class="parameter">typename</replaceable>' does not exist
</computeroutput></term>
<term><computeroutput>ERROR: RemoveType: type '<replaceable class="parameter">typename</replaceable>' does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if the specified type is not found.
Message returned if the specified type does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-DROPTYPE-1">
<refsect1info>
<date>1998-09-22</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP TYPE</command> will remove a user type from the
system catalogs.
</para>
<para>
Only the owner of a type can remove it.
</para>
</refsect1>
<refsect1 id="SQL-DROPTYPE-examples">
<title>Examples</title>
<para>
To remove the <type>box</type> type:
<para>
To remove the data type <type>box</type>:
<programlisting>
DROP TYPE box;
</programlisting>
......@@ -130,9 +103,10 @@ DROP TYPE box;
<title>Compatibility</title>
<para>
Note that the <command>CREATE TYPE</command> command and the data
type extension mechanisms in <productname>PostgreSQL</productname>
differ from SQL99.
This command is similar to the corresponding command in the SQL
standard, but note that the <command>CREATE TYPE</command> command
and the data type extension mechanisms in
<productname>PostgreSQL</productname> differ from the SQL standard.
</para>
</refsect1>
......@@ -143,6 +117,7 @@ DROP TYPE box;
<member><xref linkend="sql-createtype" endterm="sql-createtype-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/drop_user.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.15 2002/02/27 21:14:54 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.16 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,6 +8,7 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPUSER-TITLE">DROP USER</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>DROP USER</refname>
<refpurpose>remove a database user account</refpurpose>
......@@ -23,40 +24,36 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
<title>Description</title>
<para>
<command>DROP USER</command> removes the specified user from the database.
<command>DROP USER</command> removes the specified user.
It does not remove tables, views, or other objects owned by the user. If the
user owns any database, an error is raised.
</para>
</refsect1>
<refsect2>
<refsect1>
<title>Parameters</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of an existing user.
The name of the user to remove.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>DROP USER</computeroutput></term>
<listitem>
<para>
The message returned if the user is successfully deleted.
Message returned if the user was successfully deleted.
</para>
</listitem>
</varlistentry>
......@@ -65,7 +62,7 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
<term><computeroutput>ERROR: DROP USER: user "<replaceable class="parameter">name</replaceable>" does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if the user name is not found.
Message returned if the specified user does not exist.
</para>
</listitem>
</varlistentry>
......@@ -78,18 +75,13 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
Use <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
to add new users, and <xref linkend="SQL-ALTERUSER"
endterm="SQL-ALTERUSER-title"> to change a user's attributes.
<productname>PostgreSQL</productname> includes a program <xref
linkend="APP-DROPUSER" endterm="APP-DROPUSER-title"> that has the
same functionality as this command (in fact, it calls this command)
......@@ -122,9 +114,8 @@ DROP USER jonathan;
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
<member><xref linkend="sql-alteruser" endterm="sql-alteruser-title"></member>
<member><xref linkend="app-dropuser"></member>
<member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
</simplelist>
</refsect1>
......
doc/src/sgml/ref/drop_view.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_view.sgml,v 1.16 2002/11/21 23:34:43 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_view.sgml,v 1.17 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,154 +8,113 @@ PostgreSQL documentation
<refentrytitle id="SQL-DROPVIEW-TITLE">DROP VIEW</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP VIEW
</refname>
<refpurpose>
remove a view
</refpurpose>
<refname>DROP VIEW</refname>
<refpurpose>remove a view</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP VIEW <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCADE | RESTRICT ]
</synopsis>
<refsect2 id="R2-SQL-DROPVIEW-1">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Inputs
</title>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP VIEW</command> drops an existing view. To execute
this command you must be the owner of the view.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an existing view.
The name (optionally schema-qualified) of the view to remove.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the view
(such as other views).
Automatically drop objects that depend on the view (such as
other views).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the view if there are any dependent objects.
This is the default.
Refuse to drop the view if any objects depend on it. This is
the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPVIEW-2">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
DROP VIEW
</computeroutput></term>
<term><computeroutput>DROP VIEW</computeroutput></term>
<listitem>
<para>
The message returned if the command is successful.
Message returned if the command was successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: view <replaceable class="parameter">name</replaceable> does not exist
</computeroutput></term>
<term><computeroutput>ERROR: view <replaceable class="parameter">name</replaceable> does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if the specified view does not exist in
the database.
Message returned if the specified view does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
</refsect1>
<refsect1 id="R1-SQL-DROPVIEW-1">
<refsect1info>
<date>1998-09-22</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP VIEW</command> drops an existing view from the database.
To execute this command you must be the owner of the
view.
</para>
<refsect1>
<title>Examples</title>
<refsect2 id="R2-SQL-DROPVIEW-3">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Notes
</title>
<para>
Refer to <xref linkend="sql-createview" endterm="sql-createview-title">
for information on how to create views.
This command will remove the view called <literal>kinds</literal>:
<programlisting>
DROP VIEW kinds;
</programlisting>
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-DROPVIEW-2">
<title>
Usage
</title>
<refsect1>
<title>Compatibility</title>
<para>
This command will remove the view called <literal>kinds</literal>:
This command conforms to the SQL standard.
</para>
<programlisting>
DROP VIEW kinds;
</programlisting>
</refsect1>
<refsect1 id="R1-SQL-DROPVIEW-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-DROPVIEW-4">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
SQL92
</title>
<para>
</para>
</refsect2>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createview" endterm="sql-createview-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/fetch.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/fetch.sgml,v 1.28 2003/03/27 16:51:27 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/fetch.sgml,v 1.29 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,19 +8,14 @@ PostgreSQL documentation
<refentrytitle id="SQL-FETCH-TITLE">FETCH</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
FETCH
</refname>
<refpurpose>
retrieve rows from a query using a cursor
</refpurpose>
<refname>FETCH</refname>
<refpurpose>retrieve rows from a query using a cursor</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2003-03-11</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
FETCH [ <replaceable class="PARAMETER">direction</replaceable> { FROM | IN } ] <replaceable class="PARAMETER">cursor</replaceable>
where <replaceable class="PARAMETER">direction</replaceable> can be empty or one of:
......@@ -39,89 +34,135 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one
BACKWARD
BACKWARD <replaceable class="PARAMETER">count</replaceable>
BACKWARD ALL
</synopsis>
<refsect2 id="R2-SQL-FETCH-1">
<refsect2info>
<date>2003-03-11</date>
</refsect2info>
<title>
Inputs
</title>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>FETCH</command> retrieves rows using a cursor.
</para>
<para>
A cursor has an associated position, which is used by
<command>FETCH</>. The cursor position can be before the first row of the
query result, on any particular row of the result, or after the last row
of the result. When created, a cursor is positioned before the first row.
After fetching some rows, the cursor is positioned on the row most recently
retrieved. If <command>FETCH</> runs off the end of the available rows
then the cursor is left positioned after the last row, or before the first
row if fetching backward. <command>FETCH ALL</> or <command>FETCH BACKWARD
ALL</> will always leave the cursor positioned after the last row or before
the first row.
</para>
<para>
The forms <literal>NEXT</>, <literal>PRIOR</>, <literal>FIRST</>,
<literal>LAST</>, <literal>ABSOLUTE</>, <literal>RELATIVE</> fetch
a single row after moving the cursor appropriately. If there is no
such row, an empty result is returned, and the cursor is left
positioned before the first row or after the last row as
appropriate.
</para>
<para>
The forms using <literal>FORWARD</> and <literal>BACKWARD</>
retrieve the indicated number of rows moving in the forward or
backward direction, leaving the cursor positioned on the
last-returned row (or after/before all rows, if the <replaceable
class="PARAMETER">count</replaceable> exceeds the number of rows
available).
</para>
<para>
<literal>RELATIVE 0</>, <literal>FORWARD 0</>, and
<literal>BACKWARD 0</> all request fetching the current row without
moving the cursor, that is, re-fetching the most recently fetched
row. This will succeed unless the cursor is positioned before the
first row or after the last row; in which case, no row is returned.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">direction</replaceable></term>
<listitem>
<para>
<replaceable class="PARAMETER">direction</replaceable>
defines the fetch direction and number of rows to fetch.
It can be one of the following:
<replaceable class="PARAMETER">direction</replaceable> defines
the fetch direction and number of rows to fetch. It can be one
of the following:
<variablelist>
<varlistentry>
<term>NEXT</term>
<term><literal>NEXT</literal></term>
<listitem>
<para>
fetch next row. This is the default
if <replaceable class="PARAMETER">direction</replaceable> is omitted.
Fetch the next row. This is the default if <replaceable
class="PARAMETER">direction</replaceable> is omitted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PRIOR</term>
<term><literal>PRIOR</literal></term>
<listitem>
<para>
fetch prior row.
Fetch the prior row.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FIRST</term>
<term><literal>FIRST</literal></term>
<listitem>
<para>
fetch first row of query (same as ABSOLUTE 1).
Fetch the first row of the query (same as <literal>ABSOLUTE 1</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LAST</term>
<term><literal>LAST</literal></term>
<listitem>
<para>
fetch last row of query (same as ABSOLUTE -1).
Fetch the last row of the query (same as <literal>ABSOLUTE -1</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ABSOLUTE <replaceable class="PARAMETER">count</replaceable></term>
<term><literal>ABSOLUTE <replaceable class="PARAMETER">count</replaceable></literal></term>
<listitem>
<para>
fetch the <replaceable class="PARAMETER">count</replaceable>'th
row of query, or the
abs(<replaceable class="PARAMETER">count</replaceable>)'th row
from the end if
<replaceable class="PARAMETER">count</replaceable> &lt; 0.
Position before first row or after last row
if <replaceable class="PARAMETER">count</replaceable> is out of
range; in particular, ABSOLUTE 0 positions before first row.
Fetch the <replaceable
class="PARAMETER">count</replaceable>'th row of the query,
or the <literal>abs(<replaceable
class="PARAMETER">count</replaceable>)</literal>'th row from
the end if <replaceable
class="PARAMETER">count</replaceable> is negative. Position
before first row or after last row if <replaceable
class="PARAMETER">count</replaceable> is out of range; in
particular, <literal>ABSOLUTE 0</literal> positions before
the first row.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RELATIVE <replaceable class="PARAMETER">count</replaceable></term>
<term><literal>RELATIVE <replaceable class="PARAMETER">count</replaceable></literal></term>
<listitem>
<para>
fetch the <replaceable class="PARAMETER">count</replaceable>'th
succeeding row, or the
abs(<replaceable class="PARAMETER">count</replaceable>)'th prior
row if <replaceable class="PARAMETER">count</replaceable> &lt; 0.
RELATIVE 0 re-fetches current row, if any.
Fetch the <replaceable
class="PARAMETER">count</replaceable>'th succeeding row, or
the <literal>abs(<replaceable
class="PARAMETER">count</replaceable>)</literal>'th prior
row if <replaceable class="PARAMETER">count</replaceable> is
negative. <literal>RELATIVE 0</literal> re-fetches the
current row, if any.
</para>
</listitem>
</varlistentry>
......@@ -130,77 +171,81 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one
<term><replaceable class="PARAMETER">count</replaceable></term>
<listitem>
<para>
fetch the next <replaceable class="PARAMETER">count</replaceable>
rows (same as FORWARD <replaceable class="PARAMETER">count</replaceable>).
Fetch the next <replaceable
class="PARAMETER">count</replaceable> rows (same as
<literal>FORWARD <replaceable
class="PARAMETER">count</replaceable></literal>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ALL</term>
<term><literal>ALL</literal></term>
<listitem>
<para>
fetch all remaining rows (same as FORWARD ALL).
Fetch all remaining rows (same as <literal>FORWARD ALL</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FORWARD</term>
<term><literal>FORWARD</literal></term>
<listitem>
<para>
fetch next row (same as NEXT).
Fetch the next row (same as <literal>NEXT</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FORWARD <replaceable class="PARAMETER">count</replaceable></term>
<term><literal>FORWARD <replaceable class="PARAMETER">count</replaceable></literal></term>
<listitem>
<para>
fetch next <replaceable class="PARAMETER">count</replaceable>
rows. FORWARD 0 re-fetches current row.
Fetch the next <replaceable
class="PARAMETER">count</replaceable> rows.
<literal>FORWARD 0</literal> re-fetches the current row.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FORWARD ALL</term>
<term><literal>FORWARD ALL</literal></term>
<listitem>
<para>
fetch all remaining rows.
Fetch all remaining rows.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BACKWARD</term>
<term><literal>BACKWARD</literal></term>
<listitem>
<para>
fetch prior row (same as PRIOR).
Fetch the prior row (same as <literal>PRIOR</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BACKWARD <replaceable class="PARAMETER">count</replaceable></term>
<term><literal>BACKWARD <replaceable class="PARAMETER">count</replaceable></literal></term>
<listitem>
<para>
fetch prior <replaceable class="PARAMETER">count</replaceable>
rows (scanning backwards). BACKWARD 0 re-fetches current row.
Fetch the prior <replaceable
class="PARAMETER">count</replaceable> rows (scanning
backwards). <literal>BACKWARD 0</literal> re-fetches the
current row.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BACKWARD ALL</term>
<term><literal>BACKWARD ALL</literal></term>
<listitem>
<para>
fetch all prior rows (scanning backwards).
Fetch all prior rows (scanning backwards).
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
......@@ -210,12 +255,12 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one
<term><replaceable class="PARAMETER">count</replaceable></term>
<listitem>
<para>
<replaceable class="PARAMETER">count</replaceable>
is a possibly-signed integer constant, determining the location
or number of rows to fetch. For FORWARD and BACKWARD cases,
specifying a negative <replaceable
class="PARAMETER">count</replaceable>
is equivalent to changing the sense of FORWARD and BACKWARD.
<replaceable class="PARAMETER">count</replaceable> is a
possibly-signed integer constant, determining the location or
number of rows to fetch. For <literal>FORWARD</> and
<literal>BACKWARD</> cases, specifying a negative <replaceable
class="PARAMETER">count</replaceable> is equivalent to changing
the sense of <literal>FORWARD</> and <literal>BACKWARD</>.
</para>
</listitem>
</varlistentry>
......@@ -229,26 +274,14 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-FETCH-2">
<refsect2info>
<date>2003-03-11</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<command>FETCH</command> returns rows from the result of the query defined
by the specified cursor.
The following messages will be returned if the query fails:
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
WARNING: PerformPortalFetch: portal "<replaceable class="PARAMETER">cursor</replaceable>" not found
</computeroutput></term>
<term><computeroutput>WARNING: PerformPortalFetch: portal "<replaceable class="PARAMETER">cursor</replaceable>" not found</computeroutput></term>
<listitem>
<para>
There is no cursor with the specified name.
......@@ -256,125 +289,60 @@ WARNING: PerformPortalFetch: portal "<replaceable class="PARAMETER">cursor</rep
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-FETCH-1">
<refsect1info>
<date>2003-03-11</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>FETCH</command> retrieves rows using a cursor.
</para>
<para>
A cursor has an associated <firstterm>position</> that is used by
<command>FETCH</>. The cursor position can be before the first row of the
query result, or on any particular row of the result, or after the last row
of the result. When created, a cursor is positioned before the first row.
After fetching some rows, the cursor is positioned on the row most recently
retrieved. If <command>FETCH</> runs off the end of the available rows
then the cursor is left positioned after the last row, or before the first
row if fetching backward. <command>FETCH ALL</> or <command>FETCH BACKWARD
ALL</> will always leave the cursor positioned after the last row or before
the first row.
</para>
<para>
The SQL-compatible forms (NEXT, PRIOR, FIRST, LAST, ABSOLUTE, RELATIVE)
fetch a single row after moving the cursor appropriately. If there is
no such row, an empty result is returned, and the cursor is left positioned
before the first row or after the last row as appropriate.
</para>
<para>
The forms using FORWARD and BACKWARD are not in the SQL standard, but
are <productname>PostgreSQL</productname> extensions. These forms
retrieve the indicated number of rows moving in the forward or backward
direction, leaving the cursor positioned on the last-returned row
(or after/before all rows, if the <replaceable
class="PARAMETER">count</replaceable> exceeds the number of rows
available).
</para>
<tip>
<para>
RELATIVE 0, FORWARD 0, and BACKWARD 0 all request
fetching the current row without moving the
cursor --- that is, re-fetching the most recently fetched row.
This will succeed unless the cursor is positioned before the
first row or after the last row; in which case, no row is returned.
</para>
</tip>
</refsect1>
<refsect2 id="R2-SQL-FETCH-3">
<refsect2info>
<date>2003-03-11</date>
</refsect2info>
<title>
Notes
</title>
<refsect1>
<title>Notes</title>
<para>
The cursor should be declared with the SCROLL option if one intends to
use any variants of <command>FETCH</> other than <command>FETCH NEXT</>
or <command>FETCH FORWARD</> with a positive count. For simple queries
<productname>PostgreSQL</productname> will allow backwards fetch from
cursors not declared with SCROLL, but this behavior is best not
relied on. If the cursor is declared with NO SCROLL, no backward
fetches are allowed.
The cursor should be declared with the <literal>SCROLL</literal>
option if one intends to use any variants of <command>FETCH</>
other than <command>FETCH NEXT</> or <command>FETCH FORWARD</> with
a positive count. For simple queries
<productname>PostgreSQL</productname> will allow backwards fetch
from cursors not declared with <literal>SCROLL</literal>, but this
behavior is best not relied on. If the cursor is declared with
<literal>NO SCROLL</literal>, no backward fetches are allowed.
</para>
<para>
ABSOLUTE fetches are not any faster than navigating to the desired row
with a relative move: the underlying implementation must traverse all
the intermediate rows anyway. Negative absolute fetches are even worse:
the query must be read to the end to find the last row, and then
traversed backward from there. However, rewinding to the start of the
query (as with FETCH ABSOLUTE 0) is fast.
<literal>ABSOLUTE</literal> fetches are not any faster than
navigating to the desired row with a relative move: the underlying
implementation must traverse all the intermediate rows anyway.
Negative absolute fetches are even worse: the query must be read to
the end to find the last row, and then traversed backward from
there. However, rewinding to the start of the query (as with
<literal>FETCH ABSOLUTE 0</literal>) is fast.
</para>
<para>
Updating data via a cursor is not supported by
<productname>PostgreSQL</productname>, because mapping cursor
updates back to base tables is not generally possible, as is also
the case with view updates. Consequently, users must issue
explicit <command>UPDATE</command> commands to replace data.
Updating data via a cursor is currently not supported by
<productname>PostgreSQL</productname>.
</para>
<para>
<xref linkend="sql-declare" endterm="sql-declare-title">
is used to define a cursor.
Use
is used to define a cursor. Use
<xref linkend="sql-move" endterm="sql-move-title">
to change cursor position without retrieving data.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-FETCH-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
The following example traverses a table using a cursor.
<programlisting>
-- Set up and use a cursor:
BEGIN WORK;
-- Set up a cursor:
DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films;
-- Fetch first 5 rows in the cursor liahona:
FETCH FORWARD 5 IN liahona;
-- Fetch the first 5 rows in the cursor liahona:
FETCH FORWARD 5 FROM liahona;
<computeroutput>
code | title | did | date_prod | kind | len
-------+-------------------------+-----+------------+----------+-------
BL101 | The Third Man | 101 | 1949-12-23 | Drama | 01:44
......@@ -382,70 +350,46 @@ FETCH FORWARD 5 IN liahona;
JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romantic | 01:25
P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08
P_302 | Becket | 103 | 1964-02-03 | Drama | 02:28
</computeroutput>
-- Fetch previous row:
-- Fetch the previous row:
FETCH PRIOR FROM liahona;
<computeroutput>
code | title | did | date_prod | kind | len
-------+---------+-----+------------+--------+-------
P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08
</computeroutput>
-- close the cursor and commit work:
-- Close the cursor and end the transaction:
CLOSE liahona;
COMMIT WORK;
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-FETCH-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-FETCH-4">
<refsect2info>
<date>2003-03-11</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
<acronym>SQL92</acronym> defines <command>FETCH</command> for use
in embedded contexts only. Therefore, it describes placing the
results into explicit variables using an <literal>INTO</> clause,
for example:
<synopsis>
FETCH ABSOLUTE <replaceable class="PARAMETER">n</replaceable>
FROM <replaceable class="PARAMETER">cursor</replaceable>
INTO :<replaceable class="PARAMETER">variable</replaceable> [, ...]
</synopsis>
<productname>PostgreSQL</productname>'s use of non-embedded
cursors is non-standard, and so is its practice of returning the
result data as if it were a <command>SELECT</command> result.
Other than this point, <command>FETCH</command> is fully
upward-compatible with <acronym>SQL92</acronym>.
The SQL standard defines <command>FETCH</command> for use in
embedded SQL only. This variant of <command>FETCH</command>
described here returns the data as if it were a
<command>SELECT</command> result rather than placing it in host
variables. Other than this point, <command>FETCH</command> is
fully upward-compatible with the SQL standard.
</para>
<para>
The <command>FETCH</command> forms involving FORWARD and BACKWARD
(including the forms FETCH <replaceable
class="PARAMETER">count</replaceable> and FETCH ALL, in which
FORWARD is implicit) are <productname>PostgreSQL</productname>
extensions.
The <command>FETCH</command> forms involving
<literal>FORWARD</literal> and <literal>BACKWARD</literal>, as well
as the forms <literal>FETCH <replaceable
class="PARAMETER">count</replaceable></literal> and <literal>FETCH
ALL</literal>, in which <literal>FORWARD</literal> is implicit, are
<productname>PostgreSQL</productname> extensions.
</para>
<para>
<acronym>SQL92</acronym> allows only <literal>FROM</> preceding the
cursor name; the option to use <literal>IN</> is an extension.
The SQL standard allows only <literal>FROM</> preceding the cursor
name; the option to use <literal>IN</> is an extension.
</para>
</refsect2>
</refsect1>
</refentry>
......
doc/src/sgml/ref/move.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/move.sgml,v 1.21 2003/03/27 16:51:27 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/move.sgml,v 1.22 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,112 +8,74 @@ PostgreSQL documentation
<refentrytitle id="SQL-MOVE-TITLE">MOVE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
MOVE
</refname>
<refpurpose>
reposition a cursor
</refpurpose>
<refname>MOVE</refname>
<refpurpose>reposition a cursor</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
MOVE [ <replaceable class="PARAMETER">direction</replaceable> { FROM | IN } ] <replaceable class="PARAMETER">cursor</replaceable>
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-MOVE-1">
<refsect1info>
<date>1998-09-24</date>
</refsect1info>
<title>
Description
</title>
<refsect1>
<title>Description</title>
<para>
<command>MOVE</command> repositions a cursor without retrieving any data.
<command>MOVE</command> works exactly like the <command>FETCH</command>
command, except it only repositions the cursor and does not return rows.
</para>
<para>
Refer to
<xref linkend="sql-fetch" endterm="sql-fetch-title">
for details on syntax and usage.
</para>
</refsect1>
<refsect2 id="R2-SQL-MOVE-3">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
Notes
</title>
<refsect1>
<title>Diagnostics</title>
<para>
The count returned in <command>MOVE</command>'s status string is the
count of the number of rows that would have been returned by the
equivalent <command>FETCH</command> command.
The count returned in <command>MOVE</command>'s status string is
the count of the number of rows that would have been returned by
the equivalent <command>FETCH</command> command.
</para>
<para>
Refer to
<xref linkend="sql-fetch" endterm="sql-fetch-title">
for a description of valid arguments.
Refer to
<xref linkend="sql-declare" endterm="sql-declare-title">
to define a cursor.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-MOVE-2">
<title>
Usage
</title>
<para>
Set up and use a cursor:
<refsect1>
<title>Examples</title>
<programlisting>
BEGIN WORK;
DECLARE liahona CURSOR FOR SELECT * FROM films;
-- Skip first 5 rows:
-- Skip the first 5 rows:
MOVE FORWARD 5 IN liahona;
<computeroutput>
MOVE 5
</computeroutput>
-- Fetch 6th row in the cursor liahona:
FETCH 1 IN liahona;
<computeroutput>
-- Fetch the 6th row from the cursor liahona:
FETCH 1 FROM liahona;
code | title | did | date_prod | kind | len
-------+--------+-----+-----------+--------+-------
P_303 | 48 Hrs | 103 | 1982-10-22| Action | 01:37
-------+--------+-----+------------+--------+-------
P_303 | 48 Hrs | 103 | 1982-10-22 | Action | 01:37
(1 row)
</computeroutput>
-- close the cursor liahona and commit work:
-- Close the cursor liahona and end the transaction:
CLOSE liahona;
COMMIT WORK;
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-MOVE-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-MOVE-4">
<refsect2info>
<date>1998-09-01</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
There is no <acronym>SQL92</acronym> <command>MOVE</command> statement.
There is no <command>MOVE</command> statement in the SQL standard.
</para>
</refsect2>
</refsect1>
</refentry>
......
doc/src/sgml/ref/reset.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/reset.sgml,v 1.19 2003/03/25 16:15:44 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/reset.sgml,v 1.20 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,33 +8,66 @@ PostgreSQL documentation
<refentrytitle id="SQL-RESET-TITLE">RESET</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>RESET</refname>
<refpurpose>restore the value of a run-time parameter to a default value</refpurpose>
<refpurpose>restore the value of a run-time parameter to the default value</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
RESET <replaceable class="PARAMETER">variable</replaceable>
</synopsis>
<synopsis>
<synopsis>
RESET <replaceable class="PARAMETER">parameter</replaceable>
</synopsis>
<synopsis>
RESET ALL
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<refsect2 id="R2-SQL-RESET-1">
<title>Inputs</title>
<para>
<command>RESET</command> restores run-time parameters to their
default values. <command>RESET</command> is an alternative
spelling for
<synopsis>
SET <replaceable class="parameter">parameter</replaceable> TO DEFAULT
</synopsis>
Refer to <xref linkend="sql-set" endterm="sql-set-title"> for
details.
</para>
<para>
The default value is defined as the value that the parameter would
have had, had no <command>SET</> ever been issued for it in the
current session. The actual source of this value might be a
compiled-in default, the configuration file, command-line options,
or per-database or per-user default settings. See <xref
linkend="runtime-config"> for details.
</para>
<para>
See the <command>SET</> reference page for details on the
transaction behavior of <command>RESET</>.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">variable</replaceable></term>
<term><replaceable class="PARAMETER">parameter</replaceable></term>
<listitem>
<para>
The name of a run-time parameter. See <xref
linkend="sql-set" endterm="sql-set-title"> for a list.
The name of a run-time parameter. See <xref linkend="sql-set"
endterm="sql-set-title"> for a list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ALL</term>
<term><literal>ALL</literal></term>
<listitem>
<para>
Resets all settable run-time parameters to default values.
......@@ -42,61 +75,30 @@ RESET ALL
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>RESET</command> restores run-time parameters to their
default values. Refer to
<xref linkend="sql-set" endterm="sql-set-title">
for details. <command>RESET</command> is an alternate spelling for
<synopsis>
SET <replaceable class="parameter">variable</replaceable> TO DEFAULT
</synopsis>
The default value is defined as the value that the variable would
have had, had no <command>SET</> ever been issued for it in the
current session. The actual source of this value might be a
compiled-in default, the postmaster's configuration file or command-line
switches, or per-database or per-user default settings. See
<xref linkend="runtime-config"> for details.
</para>
<para>
See the <command>SET</> manual page for details on the transaction
behavior of <command>RESET</>.
</para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<para>
See under the <xref linkend="sql-set"
endterm="sql-set-title"> command.
See under the <xref linkend="sql-set" endterm="sql-set-title">.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
Set <varname>DateStyle</> to its default value:
<para>
Set <varname>datestyle</> to its default value:
<screen>
RESET DateStyle;
RESET datestyle;
</screen>
</para>
<para>
Set <varname>geqo</> to its default value:
<screen>
RESET GEQO;
RESET geqo;
</screen>
</para>
</refsect1>
......
doc/src/sgml/ref/select.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.66 2003/03/25 16:15:44 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.67 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,667 +8,666 @@ PostgreSQL documentation
<refentrytitle id="sql-select-title">SELECT</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
SELECT
</refname>
<refpurpose>
retrieve rows from a table or view
</refpurpose></refnamediv>
<refname>SELECT</refname>
<refpurpose>retrieve rows from a table or view</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2000-12-11</date>
</refsynopsisdivinfo>
<synopsis>
SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) ] ]
* | <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">output_name</replaceable> ] [, ...]
[ FROM <replaceable class="PARAMETER">from_item</replaceable> [, ...] ]
[ WHERE <replaceable class="PARAMETER">condition</replaceable> ]
[ GROUP BY <replaceable class="PARAMETER">expression</replaceable> [, ...] ]
[ HAVING <replaceable class="PARAMETER">condition</replaceable> [, ...] ]
[ { UNION | INTERSECT | EXCEPT } [ ALL ] <replaceable class="PARAMETER">select</replaceable> ]
[ ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
[ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
[ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
[ FOR UPDATE [ OF <replaceable class="PARAMETER">tablename</replaceable> [, ...] ] ]
where <replaceable class="PARAMETER">from_item</replaceable> can be:
[ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ]
[ [ AS ] <replaceable class="PARAMETER">alias</replaceable> [ ( <replaceable class="PARAMETER">column_alias_list</replaceable> ) ] ]
|
( <replaceable class="PARAMETER">select</replaceable> )
[ AS ] <replaceable class="PARAMETER">alias</replaceable> [ ( <replaceable class="PARAMETER">column_alias_list</replaceable> ) ]
|
<replaceable class="PARAMETER">table_function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] )
[ AS ] <replaceable class="PARAMETER">alias</replaceable> [ ( <replaceable class="PARAMETER">column_alias_list</replaceable> | <replaceable class="PARAMETER">column_definition_list</replaceable> ) ]
|
<replaceable class="PARAMETER">table_function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] )
AS ( <replaceable class="PARAMETER">column_definition_list</replaceable> )
|
<!--
FIXME: this syntax is incorrect if the join type is an INNER or
OUTER join (in which case one of NATURAL, ON ..., or USING ... is
mandatory, not optional). What's the best way to fix this?
-->
<replaceable class="PARAMETER">from_item</replaceable> [ NATURAL ] <replaceable class="PARAMETER">join_type</replaceable> <replaceable class="PARAMETER">from_item</replaceable>
[ ON <replaceable class="PARAMETER">join_condition</replaceable> | USING ( <replaceable class="PARAMETER">join_column_list</replaceable> ) ]
</synopsis>
<synopsis>
SELECT [ ALL | DISTINCT [ ON ( <replaceable class="parameter">expression</replaceable> [, ...] ) ] ]
* | <replaceable class="parameter">expression</replaceable> [ AS <replaceable class="parameter">output_name</replaceable> ] [, ...]
[ FROM <replaceable class="parameter">from_item</replaceable> [, ...] ]
[ WHERE <replaceable class="parameter">condition</replaceable> ]
[ GROUP BY <replaceable class="parameter">expression</replaceable> [, ...] ]
[ HAVING <replaceable class="parameter">condition</replaceable> [, ...] ]
[ { UNION | INTERSECT | EXCEPT } [ ALL ] <replaceable class="parameter">select</replaceable> ]
[ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [, ...] ]
[ LIMIT { <replaceable class="parameter">count</replaceable> | ALL } ]
[ OFFSET <replaceable class="parameter">start</replaceable> ]
[ FOR UPDATE [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] ]
where <replaceable class="parameter">from_item</replaceable> can be one of:
[ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> [ ( <replaceable class="parameter">column_alias</replaceable> [, ...] ) ] ]
( <replaceable class="parameter">select</replaceable> ) [ AS ] <replaceable class="parameter">alias</replaceable> [ ( <replaceable class="parameter">column_alias</replaceable> [, ...] ) ]
<replaceable class="parameter">function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] ) [ AS ] <replaceable class="parameter">alias</replaceable> [ ( <replaceable class="parameter">column_alias</replaceable> [, ...] | <replaceable class="parameter">column_definition</replaceable> [, ...] ) ]
<replaceable class="parameter">function_name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> [, ...] ] ) AS ( <replaceable class="parameter">column_definition</replaceable> [, ...] )
<replaceable class="parameter">from_item</replaceable> [ NATURAL ] <replaceable class="parameter">join_type</replaceable> <replaceable class="parameter">from_item</replaceable> [ ON <replaceable class="parameter">join_condition</replaceable> | USING ( <replaceable class="parameter">join_column</replaceable> [, ...] ) ]
</synopsis>
<comment>FIXME: This last syntax is incorrect if the join type is an
INNER or OUTER join (in which case one of NATURAL, ON ..., or USING
... is mandatory, not optional). What's the best way to fix
this?</comment>
<refsect2 id="R2-SQL-SELECT-1">
<refsect2info>
<date>2000-12-11</date>
</refsect2info>
<title>
Inputs
</title>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">expression</replaceable></term>
<command>SELECT</command> retrieves rows from one or more tables.
The general processing of <command>SELECT</command> is as follows:
<orderedlist>
<listitem>
<para>
The name of a table's column or an expression.
All elements in the <literal>FROM</literal> list are computed.
(Each element in the <literal>FROM</literal> list is a real or
virtual table.) If more than one element is specified in the
<literal>FROM</literal> list, they are cross-joined together.
(See <xref linkend="sql-from" endterm="sql-from-title"> below.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">output_name</replaceable></term>
<listitem>
<para>
Specifies another name for an output column using
the AS clause. This name is primarily used to label the column
for display. It can also be used to refer to the column's value in
ORDER BY and GROUP BY clauses. But the
<replaceable class="PARAMETER">output_name</replaceable>
cannot be used in the WHERE or HAVING clauses; write out the
expression instead.
If the <literal>WHERE</literal> clause is specified, all rows
that do not satisfy the condition are eliminated from the
output. (See <xref linkend="sql-where"
endterm="sql-where-title"> below.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">from_item</replaceable></term>
<listitem>
<para>
A table reference, sub-SELECT, table function, or JOIN clause. See below for details.
If the <literal>GROUP BY</literal> clause is specified, the
output is divided into groups of rows that match on one or more
values. If the <literal>HAVING</literal> clause is present, it
eliminates groups that do not satisfy the given condition. (See
<xref linkend="sql-groupby" endterm="sql-groupby-title"> and
<xref linkend="sql-having" endterm="sql-having-title"> below.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">condition</replaceable></term>
<listitem>
<para>
A Boolean expression giving a result of true or false.
See the WHERE and HAVING clause descriptions below.
Using the operators <literal>UNION</literal>,
<literal>INTERSECT</literal>, and <literal>EXCEPT</literal>, the
output of more than one <command>SELECT</command> statement can
be combined to form a single result set. The
<literal>UNION</literal> operator returns all rows that are in
one or both of the result sets. The
<literal>INTERSECT</literal> operator returns all rows that are
strictly in both result sets. The <literal>EXCEPT</literal>
operator returns the rows that are in the first result set but
not in the second. In all three cases, duplicate rows are
eliminated unless <literal>ALL</literal> is specified. (See
<xref linkend="sql-union" endterm="sql-union-title">, <xref
linkend="sql-intersect" endterm="sql-intersect-title">, and
<xref linkend="sql-except" endterm="sql-except-title"> below.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">select</replaceable></term>
<listitem>
<para>
A select statement with all features except the ORDER BY,
LIMIT/OFFSET, and FOR UPDATE clauses (even those can be used when the
select is parenthesized).
The actual output rows are computed the
<command>SELECT</command> output expressions for each selected
row. (See
<xref linkend="sql-select-list" endterm="sql-select-list-title">
below.)
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
FROM items can contain:
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">table_name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an existing table or view.
If <literal>ONLY</> is specified, only that table is scanned. If
<literal>ONLY</> is not specified, the table and all its descendant
tables (if any) are scanned. <literal>*</> can be appended to the
table name to indicate that descendant tables are to be scanned, but
in the current version, this is the default behavior. (In releases
before 7.1, <literal>ONLY</> was the default behavior.) The
default behavior can be modified by changing the
<option>SQL_INHERITANCE</option> configuration option.
If the <literal>ORDER BY</literal> clause is specified, the
returned rows are sorted in the specified order. If
<literal>ORDER BY</literal> is not given, the rows are returned
in whatever order the system finds fastest to produce. (See
<xref linkend="sql-orderby" endterm="sql-orderby-title"> below.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">alias</replaceable></term>
<listitem>
<para>
A substitute name for the FROM item containing the alias.
An alias is used for brevity or to eliminate ambiguity for self-joins
(where the same table is scanned multiple times). When an alias
is provided, it completely hides the actual name of the table or
table function; for example given <literal>FROM foo AS f</>, the
remainder of the SELECT must refer to this FROM item as <literal>f</>
not <literal>foo</>.
If an alias is
written, a column alias list can also be written to provide
substitute names for one or more columns of the table.
If the <literal>LIMIT</literal> or <literal>OFFSET</literal>
clause is specified, the <command>SELECT</command> statement
only returns a subset of the result rows. (See <xref
linkend="sql-limit" endterm="sql-limit-title"> below.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">select</replaceable></term>
<listitem>
<para>
A sub-SELECT can appear in the FROM clause. This acts as though
its output were created as a temporary table for the duration of
this single SELECT command. Note that the sub-SELECT must be
surrounded by parentheses, and an alias <emphasis>must</emphasis>
be provided for it.
<literal>DISTINCT</literal> eliminates duplicate rows from the
result. <literal>DISTINCT ON</literal> eliminates rows that
match on all the specified expressions. <literal>ALL</literal>
(the default) will return all candidate rows, including
duplicates. (See <xref linkend="sql-distinct"
endterm="sql-distinct-title"> below.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">table function</replaceable></term>
<listitem>
<para>
A table function can appear in the FROM clause. This acts as though
its output were created as a temporary table for the duration of
this single SELECT command. An alias may also be used. If an alias is
written, a column alias list can also be written to provide substitute
names for one or more columns of the table function. If the table
function has been defined as returning the <type>record</> data type,
an alias, or the keyword <literal>AS</>, must be present, followed by
a column definition list in the form ( <replaceable
class="PARAMETER">column_name</replaceable> <replaceable
class="PARAMETER">data_type</replaceable> [, ... ] ).
The column definition list must match the actual number and types
of columns returned by the function.
The <literal>FOR UPDATE</literal> clause causes the
<command>SELECT</command> statement to lock the selected rows
against concurrent updates. (See <xref linkend="sql-for-update"
endterm="sql-for-update-title"> below.)
</para>
</listitem>
</varlistentry>
</orderedlist>
</para>
<para>
You must have <literal>SELECT</literal> privilege on a table to
read its values. The use of <literal>FOR UPDATE</literal> requires
<literal>UPDATE</literal> privilege as well.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<refsect2 id="SQL-FROM">
<title id="sql-from-title"><literal>FROM</literal> Clause</title>
<para>
The <literal>FROM</literal> clause specifies one or more source
tables for the <command>SELECT</command>. If multiple sources are
specified, the result is the Cartesian product (cross join) of all
the sources. But usually qualification conditions
are added to restrict the returned rows to a small subset of the
Cartesian product.
</para>
<para>
<literal>FROM</literal>-clause elements can contain:
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">join_type</replaceable></term>
<term><replaceable class="parameter">table_name</replaceable></term>
<listitem>
<para>
One of
<command>[ INNER ] JOIN</command>,
<command>LEFT [ OUTER ] JOIN</command>,
<command>RIGHT [ OUTER ] JOIN</command>,
<command>FULL [ OUTER ] JOIN</command>, or
<command>CROSS JOIN</command>.
For INNER and OUTER join types, exactly one of NATURAL,
ON <replaceable class="PARAMETER">join_condition</replaceable>, or
USING ( <replaceable class="PARAMETER">join_column_list</replaceable> )
must appear. For CROSS JOIN, none of these items may appear.
The name (optionally schema-qualified) of an existing table or
view. If <literal>ONLY</> is specified, only that table is
scanned. If <literal>ONLY</> is not specified, the table and
all its descendant tables (if any) are scanned. <literal>*</>
can be appended to the table name to indicate that descendant
tables are to be scanned, but in the current version, this is
the default behavior. (In releases before 7.1,
<literal>ONLY</> was the default behavior.) The default
behavior can be modified by changing the
<varname>sql_interitance</varname> configuration option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">join_condition</replaceable></term>
<term><replaceable class="parameter">alias</replaceable></term>
<listitem>
<para>
A qualification condition. This is similar to the WHERE condition
except that it only applies to the two from_items being joined in
this JOIN clause.
A substitute name for the <literal>FROM</> item containing the
alias. An alias is used for brevity or to eliminate ambiguity
for self-joins (where the same table is scanned multiple
times). When an alias is provided, it completely hides the
actual name of the table or function; for example given
<literal>FROM foo AS f</>, the remainder of the
<command>SELECT</command> must refer to this <literal>FROM</>
item as <literal>f</> not <literal>foo</>. If an alias is
written, a column alias list can also be written to provide
substitute names for one or more columns of the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">join_column_list</replaceable></term>
<term><replaceable class="parameter">select</replaceable></term>
<listitem>
<para>
A USING column list ( a, b, ... ) is shorthand for the ON condition
left_table.a = right_table.a AND left_table.b = right_table.b ...
A sub-<command>SELECT</command> can appear in the
<literal>FROM</literal> clause. This acts as though its
output were created as a temporary table for the duration of
this single <command>SELECT</command> command. Note that the
sub-<command>SELECT</command> must be surrounded by
parentheses, and an alias <emphasis>must</emphasis> be
provided for it.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-SELECT-2">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term>Rows</term>
<term><replaceable class="parameter">function_name</replaceable></term>
<listitem>
<para>
The complete set of rows resulting from the query specification.
Function calls can appear in the <literal>FROM</literal>
clause. (This is especially useful for functions that return
result sets, but any function can be used.) This acts as
though its output were created as a temporary table for the
duration of this single <command>SELECT</command> command. An
alias may also be used. If an alias is written, a column alias
list can also be written to provide substitute names for one
or more attributes of the function's composite return type. If
the function has been defined as returning the <type>record</>
data type, then an alias or the key word <literal>AS</> must
be present, followed by a column definition list in the form
<literal>( <replaceable
class="parameter">column_name</replaceable> <replaceable
class="parameter">data_type</replaceable> <optional>, ... </>
)</literal>. The column definition list must match the actual
number and types of columns returned by the function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<returnvalue><replaceable>count</replaceable></returnvalue>
</term>
<term><replaceable class="parameter">join_type</replaceable></term>
<listitem>
<para>
The count of rows returned by the query.
</para>
One of
<itemizedlist>
<listitem>
<para><literal>[ INNER ] JOIN</literal></para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<listitem>
<para><literal>LEFT [ OUTER ] JOIN</literal></para>
</listitem>
<listitem>
<para><literal>RIGHT [ OUTER ] JOIN</literal></para>
</listitem>
<listitem>
<para><literal>FULL [ OUTER ] JOIN</literal></para>
</listitem>
<listitem>
<para><literal>CROSS JOIN</literal></para>
</listitem>
</itemizedlist>
<refsect1 id="R1-SQL-SELECT-1">
<refsect1info>
<date>2000-12-11</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>SELECT</command> will return rows from one or more tables.
Candidates for selection are rows which satisfy the WHERE condition;
if WHERE is omitted, all rows are candidates.
(See <xref linkend="sql-where" endterm="sql-where-title">.)
For the <literal>INNER</> and <literal>OUTER</> join types, a
join condition must be specified, namely exactly one of
<literal>NATURAL</>, <literal>ON <replaceable
class="parameter">join_condition</replaceable></literal>, or
<literal>USING (<replaceable
class="parameter">join_column</replaceable> [, ...])</literal>.
See below for the meaning. For <literal>CROSS JOIN</literal>,
none of these clauses may appear.
</para>
<para>
Actually, the returned rows are not directly the rows produced by the
FROM/WHERE/GROUP BY/HAVING clauses; rather, the output rows are formed
by computing the SELECT output expressions for each selected row.
<command>*</command> can be written in the output list as a shorthand
for all the columns of the selected rows. Also, one can write
<replaceable class="PARAMETER">table_name</replaceable><command>.*</command>
as a shorthand for the columns coming from just that table.
A <literal>JOIN</literal> clause, combines two
<literal>FROM</> items. (Use parentheses if necessary to
determine the order of nesting.)
</para>
<para>
DISTINCT will eliminate duplicate rows from the result. ALL (the
default) will return all candidate rows, including duplicates.
<literal>CROSS JOIN</> and <literal>INNER JOIN</literal>
produce a simple Cartesian product, the same as you get from
listing the two items at the top level of <literal>FROM</>.
<literal>CROSS JOIN</> is equivalent to <literal>INNER JOIN ON
(true)</>, that is, no rows are removed by qualification.
These join types are just a notational convenience, since they
do nothing you couldn't do with plain <literal>FROM</> and
<literal>WHERE</>.
</para>
<para>
DISTINCT ON eliminates rows that match on all the
specified expressions, keeping only the first row of each set of
duplicates. The DISTINCT ON expressions are interpreted using the
same rules as for ORDER BY items; see below.
Note that the <quote>first row</quote> of each set is unpredictable
unless ORDER BY is used to ensure that the desired
row appears first. For example,
<programlisting>
SELECT DISTINCT ON (location) location, time, report
FROM weatherReports
ORDER BY location, time DESC;
</programlisting>
retrieves the most recent weather report for each location. But if
we had not used ORDER BY to force descending order of time values
for each location, we'd have gotten a report of unpredictable age
for each location.
<literal>LEFT OUTER JOIN</> returns all rows in the qualified
Cartesian product (i.e., all combined rows that pass its join
condition), plus one copy of each row in the left-hand table
for which there was no right-hand row that passed the join
condition. This left-hand row is extended to the full width
of the joined table by inserting null values for the
right-hand columns. Note that only the <literal>JOIN</>
clauses own condition is considered while deciding which rows
have matches. Outer conditions are applied afterwards.
</para>
<para>
The GROUP BY clause allows a user to divide a table
into groups of rows that match on one or more values.
(See <xref linkend="sql-groupby" endterm="sql-groupby-title">.)
Conversely, <literal>RIGHT OUTER JOIN</> returns all the
joined rows, plus one row for each unmatched right-hand row
(extended with nulls on the left). This is just a notational
convenience, since you could convert it to a <literal>LEFT
OUTER JOIN</> by switching the left and right inputs.
</para>
<para>
The HAVING clause allows selection of only those groups of rows
meeting the specified condition.
(See <xref linkend="sql-having" endterm="sql-having-title">.)
<literal>FULL OUTER JOIN</> returns all the joined rows, plus
one row for each unmatched left-hand row (extended with nulls
on the right), plus one row for each unmatched right-hand row
(extended with nulls on the left).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ON <replaceable class="parameter">join_condition</replaceable></literal></term>
<listitem>
<para>
The ORDER BY clause causes the returned rows to be sorted in a specified
order. If ORDER BY is not given, the rows are returned in whatever order
the system finds cheapest to produce.
(See <xref linkend="sql-orderby" endterm="sql-orderby-title">.)
<replaceable class="parameter">join_condition</replaceable> is
an expression resulting in a value of type
<type>boolean</type> (similar to a <literal>WHERE</literal>
clause) that specifies which rows in a join are considered to
match.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>USING (<replaceable class="parameter">join_column</replaceable> [, ...])</literal></term>
<listitem>
<para>
<command>SELECT</command> queries can be combined using UNION,
INTERSECT, and EXCEPT operators. Use parentheses if necessary to
determine the ordering of these operators.
A clause of the form <literal>USING ( a, b, ... )</literal> is
shorthand for <literal>ON left_table.a = right_table.a AND
left_table.b = right_table.b ...</literal>. Also,
<literal>USING</> implies that only one of each pair of
equivalent columns will be included in the join output, not
both.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>NATURAL</literal></term>
<listitem>
<para>
The UNION operator computes the collection of rows
returned by the queries involved.
Duplicate rows are eliminated unless ALL is specified.
(See <xref linkend="sql-union" endterm="sql-union-title">.)
<literal>NATURAL</literal> is shorthand for a
<literal>USING</> list that mentions all columns in the two
tables that have the same names.
</para>
<para>
The INTERSECT operator computes the rows that are common to both queries.
Duplicate rows are eliminated unless ALL is specified.
(See <xref linkend="sql-intersect" endterm="sql-intersect-title">.)
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="SQL-WHERE">
<title id="sql-where-title"><literal>WHERE</literal> Clause</title>
<para>
The EXCEPT operator computes the rows returned by the first query but
not the second query.
Duplicate rows are eliminated unless ALL is specified.
(See <xref linkend="sql-except" endterm="sql-except-title">.)
The optional <literal>WHERE</literal> clause has the general form
<synopsis>
WHERE <replaceable class="parameter">condition</replaceable>
</synopsis>
where <replaceable class="parameter">condition</replaceable> is
any expression that evaluates to a result of type
<type>boolean</type>. Any row that does not satisfy this
condition will be eliminated from the output. A row satisfies the
condition if it returns true when the actual row values are
substituted for any variable references.
</para>
</refsect2>
<refsect2 id="SQL-GROUPBY">
<title id="sql-groupby-title"><literal>GROUP BY</literal> Clause</title>
<para>
The LIMIT clause allows a subset of the rows produced by the query
to be returned to the user.
(See <xref linkend="sql-limit" endterm="sql-limit-title">.)
The optional <literal>GROUP BY</literal> clause has the general form
<synopsis>
GROUP BY <replaceable class="parameter">expression</replaceable> [, ...]
</synopsis>
</para>
<para>
The FOR UPDATE clause causes the <command>SELECT</command>
statement to lock the selected rows against concurrent updates.
<literal>GROUP BY</literal> will condense into a single row all
selected rows that share the same values for the grouped
expressions. <replaceable
class="parameter">expression</replaceable> can be an input column
name, or the name or ordinal number of an output column
(<command>SELECT</command> list), or it can be an arbitrary
expression formed from input-column values. In case of ambiguity,
a <literal>GROUP BY</literal> name will be interpreted as an
input-column name rather than an output column name.
</para>
<para>
You must have SELECT privilege to a table to read its values
(See the <command>GRANT</command>/<command>REVOKE</command> statements).
Use of FOR UPDATE requires UPDATE privilege as well.
Aggregate functions, if any are used, are computed across all rows
making up each group, producing a separate value for each group
(whereas without <literal>GROUP BY</literal>, an aggregate
produces a single value computed across all the selected rows).
When <literal>GROUP BY</literal> is present, it is not valid for
the <command>SELECT</command> list expressions to refer to
ungrouped columns except within aggregate functions, since there
would be more than one possible value to return for an ungrouped
column.
</para>
</refsect2>
<refsect2 id="SQL-FROM">
<refsect2info>
<date>2000-12-11</date>
</refsect2info>
<title id="sql-from-title">
FROM Clause
</title>
<refsect2 id="SQL-HAVING">
<title id="sql-having-title"><literal>HAVING</literal> Clause</title>
<para>
The FROM clause specifies one or more source tables for the
<command>SELECT</command>. If multiple sources are specified, the
result is conceptually the Cartesian product of all the rows in
all the sources --- but usually qualification conditions are added
to restrict the returned rows to a small subset of the Cartesian
product.
The optional <literal>HAVING</literal> clause has the general form
<synopsis>
HAVING <replaceable class="parameter">condition</replaceable>
</synopsis>
where <replaceable class="parameter">condition</replaceable> is
the same as specified for the <literal>WHERE</literal> clause.
</para>
<para>
When a FROM item is a simple table name, it implicitly includes rows
from sub-tables (inheritance children) of the table.
<command>ONLY</command> will
suppress rows from sub-tables of the table. Before
<Productname>PostgreSQL</Productname> 7.1,
this was the default result, and adding sub-tables was done
by appending <command>*</command> to the table name.
This old behavior is available via the command
<command>SET SQL_Inheritance TO OFF</command>.
<literal>HAVING</literal> eliminates group rows that do not
satisfy the condition. <literal>HAVING</literal> is different
from <literal>WHERE</literal>: <literal>WHERE</literal> filters
individual rows before the application of <literal>GROUP
BY</literal>, while <literal>HAVING</literal> filters group rows
created by <literal>GROUP BY</literal>. Each column referenced in
<replaceable class="parameter">condition</replaceable> must
unambiguously reference a grouping column, unless the reference
appears within an aggregate function.
</para>
</refsect2>
<refsect2 id="SQL-UNION">
<title id="sql-union-title"><literal>UNION</literal> Clause</title>
<para>
A FROM item can also be a parenthesized
sub-<command>SELECT</command> (note that an alias clause is
required for a sub-<command>SELECT</command>!). This is an
extremely useful feature since it's the only way to get multiple
levels of grouping, aggregation, or sorting in a single query.
The <literal>UNION</literal> clause has this general form:
<synopsis>
<replaceable class="parameter">select_statement</replaceable> UNION [ ALL ] <replaceable class="parameter">select_statement</replaceable>
</synopsis>
<replaceable class="parameter">select_statement</replaceable> is
any <command>SELECT</command> statement without an <literal>ORDER
BY</>, <literal>LIMIT</>, or <literal>FOR UPDATE</literal> clause.
(<literal>ORDER BY</> and <literal>LIMIT</> can be attached to a
subexpression if it is enclosed in parentheses. Without
parentheses, these clauses will be taken to apply to the result of
the <literal>UNION</literal>, not to its right-hand input
expression.)
</para>
<para>
A FROM item can be a table function (typically, a function that returns
multiple rows and/or columns, though actually any function can be used).
The function is invoked with the given argument value(s), and then its
output is scanned as though it were a table.
The <literal>UNION</literal> operator computes the set union of
the rows returned by the involved <command>SELECT</command>
statements. A row is in the set union of two result sets if it
appears in at least one of the result sets. The two
<command>SELECT</command> statements that represent the direct
operands of the <literal>UNION</literal> must produce the same
number of columns, and corresponding columns must be of compatible
data types.
</para>
<para>
In some cases it is useful to define table functions that can return
different column sets depending on how they are invoked. To support this,
the table function can be declared as returning the pseudo-type
<type>record</>. When such a function is used in FROM, it must be
followed by an alias, or the keyword <literal>AS</> alone,
and then by a parenthesized list of column names and types. This provides
a query-time composite type definition. The composite type definition
must match the actual composite type returned from the function, or an
error will be reported at run-time.
The result of <literal>UNION</> does not contain any duplicate
rows unless the <literal>ALL</> option is specified.
<literal>ALL</> prevents elimination of duplicates.
</para>
<para>
Finally, a FROM item can be a JOIN clause, which combines two simpler
FROM items. (Use parentheses if necessary to determine the order
of nesting.)
Multiple <literal>UNION</> operators in the same
<command>SELECT</command> statement are evaluated left to right,
unless otherwise indicated by parentheses.
</para>
<para>
A CROSS JOIN or INNER JOIN is a simple Cartesian product,
the same as you get from listing the two items at the top level of FROM.
CROSS JOIN is equivalent to INNER JOIN ON (TRUE), that is, no rows are
removed by qualification. These join types are just a notational
convenience, since they do nothing you couldn't do with plain FROM and
WHERE.
Currently, <literal>FOR UPDATE</> may not be specified either for
a <literal>UNION</> result or for the inputs of <literal>UNION</>.
</para>
</refsect2>
<refsect2 id="SQL-INTERSECT">
<title id="sql-intersect-title"><literal>INTERSECT</literal> Clause</title>
<para>
LEFT OUTER JOIN returns all rows in the qualified Cartesian product
(i.e., all combined rows that pass its ON condition), plus one copy of each
row in the left-hand table for which there was no right-hand row that
passed the ON condition. This left-hand row is extended to the full
width of the joined table by inserting null values for the right-hand columns.
Note that only the <literal>JOIN</>'s own ON or USING condition is considered while
deciding which rows have matches. Outer ON or WHERE conditions are
applied afterwards.
The <literal>INTERSECT</literal> clause has this general form:
<synopsis>
<replaceable class="parameter">select_statement</replaceable> INTERSECT [ ALL ] <replaceable class="parameter">select_statement</replaceable>
</synopsis>
<replaceable class="parameter">select_statement</replaceable> is
any <command>SELECT</command> statement without an <literal>ORDER
BY</>, <literal>LIMIT</>, or <literal>FOR UPDATE</literal> clause.
</para>
<para>
Conversely, RIGHT OUTER JOIN returns all the joined rows, plus one row
for each unmatched right-hand row (extended with nulls on the left).
This is just a notational
convenience, since you could convert it to a LEFT OUTER JOIN by switching
the left and right inputs.
The <literal>INTERSECT</literal> operator computes the set
intersection of the rows returned by the involved
<command>SELECT</command> statements. A row is in the
intersection of two result sets if it appears in both result sets.
</para>
<para>
FULL OUTER JOIN returns all the joined rows, plus one row for each
unmatched left-hand row (extended with nulls on the right), plus one row
for each unmatched right-hand row (extended with nulls on the left).
The result of <literal>INTERSECT</literal> does not contain any
duplicate rows unless the <literal>ALL</> option is specified.
With <literal>ALL</>, a row that has m duplicates in the left
table and n duplicates in the right table will appear min(m,n)
times in the result set.
</para>
<para>
For all the JOIN types except CROSS JOIN, you must write exactly one of
ON <replaceable class="PARAMETER">join_condition</replaceable>,
USING ( <replaceable class="PARAMETER">join_column_list</replaceable> ),
or NATURAL. ON is the most general case: you can write any qualification
expression involving the two tables to be joined.
A USING column list ( a, b, ... ) is shorthand for the ON condition
left_table.a = right_table.a AND left_table.b = right_table.b ...
Also, USING implies that only one of each pair of equivalent columns will
be included in the JOIN output, not both. NATURAL is shorthand for
a USING list that mentions all similarly-named columns in the tables.
Multiple <literal>INTERSECT</literal> operators in the same
<command>SELECT</command> statement are evaluated left to right,
unless parentheses dictate otherwise.
<literal>INTERSECT</literal> binds more tightly than
<literal>UNION</literal>. That is, <literal>A UNION B INTERSECT
C</literal> will be read as <literal>A UNION (B INTERSECT
C)</literal>.
</para>
</refsect2>
<refsect2 id="SQL-WHERE">
<refsect2info>
<date>2000-03-15</date>
</refsect2info>
<title id="sql-where-title">
WHERE Clause
</title>
<refsect2 id="SQL-EXCEPT">
<title id="sql-except-title"><literal>EXCEPT</literal> Clause</title>
<para>
The optional WHERE condition has the general form:
<synopsis>
WHERE <replaceable class="PARAMETER">boolean_expr</replaceable>
</synopsis>
<replaceable class="PARAMETER">boolean_expr</replaceable>
can consist of any expression which evaluates to a Boolean value.
In many cases, this expression will be:
<synopsis>
<replaceable class="PARAMETER">expr</replaceable> <replaceable class="PARAMETER">cond_op</replaceable> <replaceable class="PARAMETER">expr</replaceable>
</synopsis>
or
<synopsis>
<replaceable class="PARAMETER">log_op</replaceable> <replaceable class="PARAMETER">expr</replaceable>
</synopsis>
where <replaceable class="PARAMETER">cond_op</replaceable>
can be one of: =, &lt;, &lt;=, &gt;, &gt;= or &lt;&gt;,
a conditional operator like ALL, ANY, IN, LIKE, or a
locally defined operator,
and <replaceable class="PARAMETER">log_op</replaceable> can be one
of: AND, OR, NOT.
SELECT will ignore all rows for which the WHERE condition does not return
TRUE.
The <literal>EXCEPT</literal> clause has this general form:
<synopsis>
<replaceable class="parameter">select_statement</replaceable> EXCEPT [ ALL ] <replaceable class="parameter">select_statement</replaceable>
</synopsis>
<replaceable class="parameter">select_statement</replaceable> is
any <command>SELECT</command> statement without an <literal>ORDER
BY</>, <literal>LIMIT</>, or <literal>FOR UPDATE</literal> clause.
</para>
</refsect2>
<refsect2 id="SQL-GROUPBY">
<refsect2info>
<date>2000-03-15</date>
</refsect2info>
<title id="sql-groupby-title">
GROUP BY Clause
</title>
<para>
GROUP BY specifies a grouped table derived by the application
of this clause:
<synopsis>
GROUP BY <replaceable class="PARAMETER">expression</replaceable> [, ...]
</synopsis>
</para>
<para>
GROUP BY will condense into a single row all selected rows that
share the same values for the grouped columns. Aggregate
functions, if any, are computed across all rows making up each
group, producing a separate value for each group (whereas without
GROUP BY, an aggregate produces a single value computed across all
the selected rows). When GROUP BY is present, it is not valid for
the <command>SELECT</command> output expression(s) to refer to
ungrouped columns except within aggregate functions, since there
would be more than one possible value to return for an ungrouped
column.
<para>
The <literal>EXCEPT</literal> operator computes the set of rows
that are in the result of the left <command>SELECT</command>
statement but not in the result of the right one.
</para>
<para>
A GROUP BY item can be an input column name, or the name or
ordinal number of an output column (<command>SELECT</command>
expression), or it can be an arbitrary expression formed from
input-column values. In case of ambiguity, a GROUP BY name will
be interpreted as an input-column name rather than an output
column name.
The result of <literal>EXCEPT</literal> does not contain any
duplicate rows unless the <literal>ALL</> option is specified.
With <literal>ALL</>, a row that has m duplicates in the left
table and n duplicates in the right table will appear max(m-n,0)
times in the result set.
</para>
</refsect2>
<refsect2 id="SQL-HAVING">
<refsect2info>
<date>2000-03-15</date>
</refsect2info>
<title id="sql-having-title">
HAVING Clause
</title>
<para>
The optional HAVING condition has the general form:
<synopsis>
HAVING <replaceable class="PARAMETER">boolean_expr</replaceable>
</synopsis>
where <replaceable class="PARAMETER">boolean_expr</replaceable> is the same
as specified for the WHERE clause.
Multiple <literal>EXCEPT</literal> operators in the same
<command>SELECT</command> statement are evaluated left to right,
unless parentheses dictate otherwise. <literal>EXCEPT</> binds at
the same level as <literal>UNION</>.
</para>
</refsect2>
<para>
HAVING specifies a grouped table derived by the elimination
of group rows that do not satisfy the
<replaceable class="PARAMETER">boolean_expr</replaceable>.
HAVING is different from WHERE:
WHERE filters individual rows before application of GROUP BY,
while HAVING filters group rows created by GROUP BY.
<refsect2 id="sql-select-list">
<title id="sql-select-list-title"><command>SELECT</command> List</title>
<para>
The <command>SELECT</command> list (between the key words
<literal>SELECT</> and <literal>FROM</>) specifies expressions
that form the output rows of the <command>SELECT</command>
statement. The expressions can (and usually do) refer to columns
computed in the <literal>FROM</> clause. Using the clause
<literal>AS <replaceable
class="parameter">output_name</replaceable></literal>, another
name can be specified for an output column. This name is
primarily used to label the column for display. It can also be
used to refer to the column's value in <literal>ORDER BY</> and
<literal>GROUP BY</> clauses, but not in the <literal>WHERE</> or
<literal>HAVING</> clauses; there you must write out the
expression instead.
</para>
<para>
Each column referenced in
<replaceable class="PARAMETER">boolean_expr</replaceable> shall unambiguously
reference a grouping column, unless the reference appears within an
aggregate function.
Instead of an expression, <literal>*</literal> can be written in
the output list as a shorthand for all the columns of the selected
rows. Also, one can write <literal><replaceable
class="parameter">table_name</replaceable>.*</literal> as a
shorthand for the columns coming from just that table.
</para>
</refsect2>
<refsect2 id="SQL-ORDERBY">
<refsect2info>
<date>2000-03-15</date>
</refsect2info>
<title id="sql-orderby-title">
ORDER BY Clause
</title>
<title id="sql-orderby-title"><literal>ORDER BY</literal> Clause</title>
<para>
<synopsis>
ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...]
</synopsis></para>
The optional <literal>ORDER BY</literal> clause has this general form:
<synopsis>
ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [, ...]
</synopsis>
<replaceable class="parameter">expression</replaceable> can be the
name or ordinal number of an output column
(<command>SELECT</command> list), or it can be an arbitrary
expression formed from input-column values.
</para>
<para>
An ORDER BY item can be the name or ordinal number of an output
column (<command>SELECT</command> expression), or it can be an
arbitrary expression formed from input-column values. In case of
ambiguity, an ORDER BY name will be interpreted as an
output-column name.
The <literal>ORDER BY</literal> clause causes the result rows to
be sorted according to the specified expressions. If two rows are
equal according to the leftmost expression, the are compared
according to the next expression and so on. If they are equal
according to all specified expressions, they are returned in
random order.
</para>
<para>
The ordinal number refers to the ordinal (left-to-right) position
of the result column. This feature makes it possible to define an ordering
on the basis of a column that does not have a unique name.
This is never absolutely necessary because it is always possible
to assign a name to a result column using the AS clause, e.g.:
<programlisting>
SELECT title, date_prod + 1 AS newlen FROM films ORDER BY newlen;
</programlisting></para>
<para>
It is also possible to ORDER BY
arbitrary expressions (an extension to SQL92),
including fields that do not appear in the
SELECT result list.
Thus the following statement is legal:
<programlisting>
of the result column. This feature makes it possible to define an
ordering on the basis of a column that does not have a unique
name. This is never absolutely necessary because it is always
possible to assign a name to a result column using the
<literal>AS</> clause.
</para>
<para>
It is also possible to use arbitrary expressions in the
<literal>ORDER BY</literal> clause, including columns that do not
appear in the <command>SELECT</command> result list. Thus the
following statement is valid:
<programlisting>
SELECT name FROM distributors ORDER BY code;
</programlisting>
A limitation of this feature is that an ORDER BY clause applying to the
result of a UNION, INTERSECT, or EXCEPT query may only specify an output
column name or number, not an expression.
</programlisting>
A limitation of this feature is that an <literal>ORDER BY</>
clause applying to the result of a <literal>UNION</>,
<literal>INTERSECT</>, or <literal>EXCEPT</> clause may only
specify an output column name or number, not an expression.
</para>
<para>
Note that if an ORDER BY item is a simple name that matches both
a result column name and an input column name, ORDER BY will interpret
it as the result column name. This is the opposite of the choice that
GROUP BY will make in the same situation. This inconsistency is
mandated by the SQL92 standard.
If an <literal>ORDER BY</> expression is a simple name that
matches both a result column name and an input column name,
<literal>ORDER BY</> will interpret it as the result column name.
This is the opposite of the choice that <literal>GROUP BY</> will
make in the same situation. This inconsistency is made to be
compatible with the SQL standard.
</para>
<para>
Optionally one may add the key word <literal>DESC</> (descending)
or <literal>ASC</> (ascending) after each column name in the
Optionally one may add the key word <literal>ASC</> (ascending) or
<literal>DESC</> (descending) after each expression in the
<literal>ORDER BY</> clause. If not specified, <literal>ASC</> is
assumed by default. Alternatively, a specific ordering operator
name may be specified. <literal>ASC</> is equivalent to
<literal>USING &lt;</> and <literal>DESC</> is equivalent to
<literal>USING &gt;</>.
name may be specified in the <literal>USING</> clause.
<literal>ASC</> is equivalent to <literal>USING &lt;</> and
<literal>DESC</> is equivalent to <literal>USING &gt;</>.
</para>
<para>
The null value sorts higher than any other value in a domain. In other
words, with ascending sort order nulls sort at the end and with
descending sort order nulls sort at the beginning.
The null value sorts higher than any other value. In other words,
with ascending sort order, null values sort at the end, and with
descending sort order, null values sort at the beginning.
</para>
<para>
......@@ -676,273 +675,147 @@ SELECT name FROM distributors ORDER BY code;
collation order that was established when the database cluster
was initialized.
</para>
</refsect2>
<refsect2 id="SQL-UNION">
<refsect2info>
<date>2000-12-11</date>
</refsect2info>
<title id="sql-union-title">
UNION Clause
</title>
<para>
<synopsis>
<replaceable class="PARAMETER">table_query</replaceable> UNION [ ALL ] <replaceable class="PARAMETER">table_query</replaceable>
[ ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
[ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
[ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
</synopsis>
where
<replaceable class="PARAMETER">table_query</replaceable>
specifies any select expression without an ORDER BY, LIMIT, or FOR UPDATE
clause. (ORDER BY and LIMIT can be attached to a sub-expression
if it is enclosed in parentheses. Without parentheses, these clauses
will be taken to apply to the result of the UNION, not to its right-hand
input expression.)
</para>
<para>
The UNION operator computes the collection (set union) of the rows
returned by the queries involved. The two
<command>SELECT</command> statements that represent the direct
operands of the UNION must produce the same number of columns, and
corresponding columns must be of compatible data types.
</para>
<para>
The result of UNION does not contain any duplicate rows
unless the ALL option is specified. ALL prevents elimination of
duplicates.
</para>
<para>
Multiple UNION operators in the same <command>SELECT</command>
statement are evaluated left to right, unless otherwise indicated
by parentheses.
</para>
<para>
Currently, FOR UPDATE may not be specified either for a UNION result
or for the inputs of a UNION.
</para>
</refsect2>
<refsect2 id="SQL-INTERSECT">
<refsect2info>
<date>2000-12-11</date>
</refsect2info>
<title id="sql-intersect-title">
INTERSECT Clause
</title>
<para>
<synopsis>
<replaceable class="PARAMETER">table_query</replaceable> INTERSECT [ ALL ] <replaceable class="PARAMETER">table_query</replaceable>
[ ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
[ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
[ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
</synopsis>
where
<replaceable class="PARAMETER">table_query</replaceable>
specifies any select expression without an ORDER BY, LIMIT, or
FOR UPDATE clause.
</para>
<refsect2 id="SQL-LIMIT">
<title id="sql-limit-title"><literal>LIMIT</literal> Clause</title>
<para>
INTERSECT is similar to UNION, except that it produces only rows that
appear in both query outputs, rather than rows that appear in either.
The <literal>LIMIT</literal> clause consists of two independent
clauses:
<synopsis>
LIMIT { <replaceable class="parameter">count</replaceable> | ALL }
OFFSET <replaceable class="parameter">start</replaceable>
</synopsis>
<replaceable class="parameter">count</replaceable> specifies the
maximum number of rows to return, and <replaceable
class="parameter">start</replaceable> specifies the number of rows
to skip before starting to return rows.
</para>
<para>
The result of INTERSECT does not contain any duplicate rows
unless the ALL option is specified. With ALL, a row that has
m duplicates in L and n duplicates in R will appear min(m,n) times.
When using <literal>LIMIT</>, it is a good idea to use an
<literal>ORDER BY</> clause that constrains the result rows into a
unique order. Otherwise you will get an unpredictable subset of
the query's rows---you may be asking for the tenth through
twentieth rows, but tenth through twentieth in what ordering? You
don't know what ordering unless you specify <literal>ORDER BY</>.
</para>
<para>
Multiple INTERSECT operators in the same SELECT statement are
evaluated left to right, unless parentheses dictate otherwise.
INTERSECT binds more tightly than UNION --- that is,
A UNION B INTERSECT C will be read as
A UNION (B INTERSECT C) unless otherwise specified by parentheses.
The query planner takes <literal>LIMIT</> into account when
generating a query plan, so you are very likely to get different
plans (yielding different row orders) depending on what you use
for <literal>LIMIT</> and <literal>OFFSET</>. Thus, using
different <literal>LIMIT</>/<literal>OFFSET</> values to select
different subsets of a query result <emphasis>will give
inconsistent results</emphasis> unless you enforce a predictable
result ordering with <literal>ORDER BY</>. This is not a bug; it
is an inherent consequence of the fact that SQL does not promise
to deliver the results of a query in any particular order unless
<literal>ORDER BY</> is used to constrain the order.
</para>
</refsect2>
<refsect2 id="SQL-EXCEPT">
<refsect2info>
<date>2000-12-11</date>
</refsect2info>
<title id="sql-except-title">
EXCEPT Clause
</title>
<para>
<synopsis>
<replaceable class="PARAMETER">table_query</replaceable> EXCEPT [ ALL ] <replaceable class="PARAMETER">table_query</replaceable>
[ ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
[ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
[ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
</synopsis>
where
<replaceable class="PARAMETER">table_query</replaceable>
specifies any select expression without an ORDER BY, LIMIT,
or FOR UPDATE clause.
</para>
<refsect2 id="sql-distinct">
<title id="sql-distinct-title"><literal>DISTINCT</literal> Clause</title>
<para>
EXCEPT is similar to UNION, except that it produces only rows that
appear in the left query's output but not in the right query's output.
If <literal>DISTINCT</> is specified, all duplicate rows are
removed from the result set (one row is kept from each group of
duplicates). <literal>ALL</> specifies the opposite: all rows are
kept; that is the default.
</para>
<para>
The result of EXCEPT does not contain any duplicate rows
unless the ALL option is specified. With ALL, a row that has
m duplicates in L and n duplicates in R will appear max(m-n,0) times.
</para>
<para>
Multiple EXCEPT operators in the same SELECT statement are
evaluated left to right, unless parentheses dictate otherwise.
EXCEPT binds at the same level as UNION.
<literal>DISTINCT ON ( <replaceable
class="parameter">expression</replaceable> [, ...] )</literal>
keeps only the first row of each set of rows where the given
expressions evaluate to equal. The <literal>DISTINCT ON</literal>
expressions are interpreted using the same rules as for
<literal>ORDER BY</> (see above). Note that the <quote>first
row</quote> of each set is unpredictable unless <literal>ORDER
BY</> is used to ensure that the desired row appears first. For
example,
<programlisting>
SELECT DISTINCT ON (location) location, time, report
FROM weather_reports
ORDER BY location, time DESC;
</programlisting>
retrieves the most recent weather report for each location. But
if we had not used <literal>ORDER BY</> to force descending order
of time values for each location, we'd have gotten a report from
an unpredictable time for each location.
</para>
</refsect2>
<refsect2 id="SQL-LIMIT">
<refsect2info>
<date>2000-02-20</date>
</refsect2info>
<title id="sql-limit-title">
LIMIT Clause
</title>
<para>
<synopsis>
LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL }
OFFSET <replaceable class="PARAMETER">start</replaceable>
</synopsis>
where
<replaceable class="PARAMETER">count</replaceable> specifies the
maximum number of rows to return, and
<replaceable class="PARAMETER">start</replaceable> specifies the
number of rows to skip before starting to return rows.
</para>
<para>
LIMIT allows you to retrieve just a portion of the rows that are generated
by the rest of the query. If a limit count is given, no more than that
many rows will be returned. If an offset is given, that many rows will
be skipped before starting to return rows.
</para>
<refsect2 id="SQL-FOR-UPDATE">
<title id="sql-for-update-title"><literal>FOR UPDATE</literal> Clause</title>
<para>
When using LIMIT, it is a good idea to use an ORDER BY clause that
constrains the result rows into a unique order. Otherwise you will get
an unpredictable subset of the query's rows---you may be asking for
the tenth through twentieth rows, but tenth through twentieth in what
ordering? You don't know what ordering unless you specify ORDER BY.
The <literal>FOR UPDATE</literal> clause has this form:
<synopsis>
FOR UPDATE [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ]
</synopsis>
</para>
<para>
As of <productname>PostgreSQL</productname> 7.0, the
query optimizer takes LIMIT into account when generating a query plan,
so you are very likely to get different plans (yielding different row
orders) depending on what you use for LIMIT and OFFSET. Thus, using
different LIMIT/OFFSET values to select different subsets of a query
result <emphasis>will give inconsistent results</emphasis> unless
you enforce a predictable result ordering with ORDER BY. This is not
a bug; it is an inherent consequence of the fact that SQL does not
promise to deliver the results of a query in any particular order
unless ORDER BY is used to constrain the order.
</para>
</refsect2>
<refsect2 id="SQL-FOR-UPDATE">
<refsect2info>
<date>2002-08-28</date>
</refsect2info>
<title id="sql-for-update-title">
FOR UPDATE Clause
</title>
<para>
<synopsis>
FOR UPDATE [ OF <replaceable class="PARAMETER">tablename</replaceable> [, ...] ]
</synopsis>
</para>
<para>
FOR UPDATE causes the rows retrieved by the query to be locked as
though for update. This prevents them from being modified or
deleted by other transactions until the current transaction ends;
that is, other transactions that attempt
<command>UPDATE</command>, <command>DELETE</command>, or
<command>SELECT FOR UPDATE</command> of these rows will be blocked
until the current transaction ends. Also, if an
<command>UPDATE</command>, <command>DELETE</command>, or
<command>SELECT FOR UPDATE</command> from another transaction has
already locked a selected row or rows, <command>SELECT FOR
<literal>FOR UPDATE</literal> causes the rows retrieved by the
<command>SELECT</command> statement to be locked as though for
update. This prevents them from being modified or deleted by
other transactions until the current transaction ends. That is,
other transactions that attempt <command>UPDATE</command>,
<command>DELETE</command>, or <command>SELECT FOR UPDATE</command>
of these rows will be blocked until the current transaction ends.
Also, if an <command>UPDATE</command>, <command>DELETE</command>,
or <command>SELECT FOR UPDATE</command> from another transaction
has already locked a selected row or rows, <command>SELECT FOR
UPDATE</command> will wait for the other transaction to complete,
and will then lock and return the updated row (or no row, if the
row was deleted). For further discussion see <xref linkend="mvcc">.
row was deleted). For further discussion see <xref
linkend="mvcc">.
</para>
<para>
If specific tables are named in FOR UPDATE, then only rows coming
from those tables are locked; any other tables used in the
<command>SELECT</command> are simply read as usual.
If specific tables are named in <literal>FOR UPDATE</literal>,
then only rows coming from those tables are locked; any other
tables used in the <command>SELECT</command> are simply read as
usual.
</para>
<para>
FOR UPDATE cannot be used in contexts where returned rows can't be clearly
identified with individual table rows; for example it can't be used with
aggregation.
<literal>FOR UPDATE</literal> cannot be used in contexts where
returned rows can't be clearly identified with individual table
rows; for example it can't be used with aggregation.
</para>
<para>
FOR UPDATE may appear before LIMIT for compatibility with
pre-7.3 applications. However, it effectively executes after LIMIT,
and so that is the recommended place to write it.
<literal>FOR UPDATE</literal> may appear before
<literal>LIMIT</literal> for compatibility with PostgreSQL
versions before 7.3. It effectively executes after
<literal>LIMIT</literal>, however, and so that is the recommended
place to write it.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-SELECT-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
To join the table <literal>films</literal> with the table
<literal>distributors</literal>:
<programlisting>
<programlisting>
SELECT f.title, f.did, d.name, f.date_prod, f.kind
FROM distributors d, films f
WHERE f.did = d.did
title | did | name | date_prod | kind
---------------------------+-----+------------------+------------+----------
-------------------+-----+--------------+------------+----------
The Third Man | 101 | British Lion | 1949-12-23 | Drama
The African Queen | 101 | British Lion | 1951-08-11 | Romantic
Une Femme est une Femme | 102 | Jean Luc Godard | 1961-03-12 | Romantic
Vertigo | 103 | Paramount | 1958-11-14 | Action
Becket | 103 | Paramount | 1964-02-03 | Drama
48 Hrs | 103 | Paramount | 1982-10-22 | Action
War and Peace | 104 | Mosfilm | 1967-02-12 | Drama
West Side Story | 105 | United Artists | 1961-01-03 | Musical
Bananas | 105 | United Artists | 1971-07-13 | Comedy
Yojimbo | 106 | Toho | 1961-06-16 | Drama
There's a Girl in my Soup | 107 | Columbia | 1970-06-11 | Comedy
Taxi Driver | 107 | Columbia | 1975-05-15 | Action
Absence of Malice | 107 | Columbia | 1981-11-15 | Action
Storia di una donna | 108 | Westward | 1970-08-15 | Romantic
The King and I | 109 | 20th Century Fox | 1956-08-11 | Musical
Das Boot | 110 | Bavaria Atelier | 1981-11-11 | Drama
Bed Knobs and Broomsticks | 111 | Walt Disney | | Musical
(17 rows)
...
</programlisting>
</para>
......@@ -951,7 +824,7 @@ SELECT f.title, f.did, d.name, f.date_prod, f.kind
the results by <literal>kind</literal>:
<programlisting>
SELECT kind, SUM(len) AS total FROM films GROUP BY kind;
SELECT kind, sum(len) AS total FROM films GROUP BY kind;
kind | total
----------+-------
......@@ -960,7 +833,6 @@ SELECT kind, SUM(len) AS total FROM films GROUP BY kind;
Drama | 14:28
Musical | 06:42
Romantic | 04:38
(5 rows)
</programlisting>
</para>
......@@ -970,16 +842,15 @@ SELECT kind, SUM(len) AS total FROM films GROUP BY kind;
that are less than 5 hours:
<programlisting>
SELECT kind, SUM(len) AS total
SELECT kind, sum(len) AS total
FROM films
GROUP BY kind
HAVING SUM(len) < INTERVAL '5 hour';
HAVING sum(len) < interval '5 hours';
kind | total
----------+-------
Comedy | 02:58
Romantic | 04:38
(2 rows)
</programlisting>
</para>
......@@ -988,7 +859,7 @@ SELECT kind, SUM(len) AS total
results according to the contents of the second column
(<literal>name</literal>):
<programlisting>
<programlisting>
SELECT * FROM distributors ORDER BY name;
SELECT * FROM distributors ORDER BY 2;
......@@ -1007,7 +878,6 @@ SELECT * FROM distributors ORDER BY 2;
111 | Walt Disney
112 | Warner Bros.
108 | Westward
(13 rows)
</programlisting>
</para>
......@@ -1016,7 +886,7 @@ SELECT * FROM distributors ORDER BY 2;
<literal>distributors</literal> and
<literal>actors</literal>, restricting the results to those that begin
with letter W in each table. Only distinct rows are wanted, so the
ALL keyword is omitted:
key word <literal>ALL</literal> is omitted.
<programlisting>
distributors: actors:
......@@ -1047,173 +917,135 @@ SELECT actors.name
</para>
<para>
This example shows how to use a table function, both with and without
a column definition list.
This example shows how to use a function in the <literal>FROM</>
clause, both with and without a column definition list.
<programlisting>
distributors:
did | name
-----+--------------
108 | Westward
111 | Walt Disney
112 | Warner Bros.
...
CREATE FUNCTION distributors(int)
RETURNS SETOF distributors AS '
CREATE FUNCTION distributors(int) RETURNS SETOF distributors AS '
SELECT * FROM distributors WHERE did = $1;
' LANGUAGE SQL;
' LANGUAGE SQL;
SELECT * FROM distributors(111);
did | name
-----+-------------
111 | Walt Disney
(1 row)
CREATE FUNCTION distributors_2(int)
RETURNS SETOF RECORD AS '
CREATE FUNCTION distributors_2(int) RETURNS SETOF record AS '
SELECT * FROM distributors WHERE did = $1;
' LANGUAGE SQL;
' LANGUAGE SQL;
SELECT * FROM distributors_2(111) AS (f1 int, f2 text);
f1 | f2
-----+-------------
111 | Walt Disney
(1 row)
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-SELECT-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-SELECT-4">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>Extensions</title>
<refsect1>
<title>Compatibility</title>
<para>
<productname>PostgreSQL</productname> allows one to omit
the <command>FROM</command> clause from a query. This feature
was retained from the original PostQUEL query language. It has
a straightforward use to compute the results of simple expressions:
Of course, the <command>SELECT</command> statement is compatible
with the SQL standard. But there are some extensions and some
missing features.
</para>
<refsect2>
<title>Omitted <literal>FROM</literal> Clauses</title>
<programlisting>
<para>
<productname>PostgreSQL</productname> allows one to omit the
<literal>FROM</literal> clause. It has a straightforward use to
compute the results of simple expressions:
<programlisting>
SELECT 2+2;
?column?
----------
4
</programlisting>
Some other <acronym>SQL</acronym> databases cannot do this except by
introducing a dummy one-row table to do the select from. A less
obvious use is to abbreviate a normal select from one or more tables:
</programlisting>
Some other <acronym>SQL</acronym> databases cannot do this except
by introducing a dummy one-row table from which to do the
<command>SELECT</command>.
</para>
<programlisting>
<para>
A less obvious use is to abbreviate a normal
<command>SELECT</command> from tables:
<programlisting>
SELECT distributors.* WHERE distributors.name = 'Westward';
did | name
-----+----------
108 | Westward
</programlisting>
</programlisting>
This works because an implicit <literal>FROM</literal> item is
added for each table that is referenced in other parts of the
<command>SELECT</command> statement but not mentioned in
<literal>FROM</literal>.
</para>
This works because an implicit FROM item is added for each table that is
referenced in the query but not mentioned in FROM. While this is a convenient
shorthand, it's easy to misuse. For example, the query
<programlisting>
<para>
While this is a convenient shorthand, it's easy to misuse. For
example, the command
<programlisting>
SELECT distributors.* FROM distributors d;
</programlisting>
is probably a mistake; most likely the user meant
<programlisting>
</programlisting>
is probably a mistake; most likely the user meant
<programlisting>
SELECT d.* FROM distributors d;
</programlisting>
rather than the unconstrained join
<programlisting>
</programlisting>
rather than the unconstrained join
<programlisting>
SELECT distributors.* FROM distributors d, distributors distributors;
</programlisting>
that he will actually get. To help detect this sort of mistake,
<Productname>PostgreSQL</Productname> 7.1
and later will warn if the implicit-FROM feature is used in a query that also
contains an explicit FROM clause.
</para>
<para>
The table-function feature is a <productname>PostgreSQL</productname>
extension.
</programlisting>
that he will actually get. To help detect this sort of mistake,
PostgreSQL will warn if the implicit-<literal>FROM</literal>
feature is used in a <command>SELECT</command> statement that also
contains an explicit <literal>FROM</literal> clause.
</para>
</refsect2>
<refsect2 id="R2-SQL-SELECT-5">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
<acronym>SQL92</acronym>
</title>
<para>
</para>
<refsect3 id="R3-SQL-SELECT-1">
<refsect3info>
<date>1998-04-15</date>
</refsect3info>
<title>
SELECT Clause
</title>
<para>
In the <acronym>SQL92</acronym> standard, the optional keyword <literal>AS</>
is just noise and can be
omitted without affecting the meaning.
The <productname>PostgreSQL</productname> parser requires this keyword when
renaming output columns because the type extensibility features lead to
parsing ambiguities
in this context. <literal>AS</literal> is optional in FROM items, however.</para>
<refsect2>
<title>The <literal>AS</literal> Key Word</title>
<para>
The DISTINCT ON phrase is not part of <acronym>SQL92</acronym>.
Nor are LIMIT and OFFSET.
In the SQL standard, the optional key word <literal>AS</> is just
noise and can be omitted without affecting the meaning. The
<productname>PostgreSQL</productname> parser requires this key
word when renaming output columns because the type extensibility
features lead to parsing ambiguities in this context.
<literal>AS</literal> is optional in <literal>FROM</literal>
items, however.
</para>
</refsect2>
<refsect2>
<title>Namespace Available to <literal>GROUP BY</literal> and <literal>ORDER BY</literal></title>
<para>
In <acronym>SQL92</acronym>, an ORDER BY clause may only use result
column names or numbers, while a GROUP BY clause may only use input
column names.
<productname>PostgreSQL</productname> extends each of these clauses to
allow the other choice as well (but it uses the standard's interpretation
if there is ambiguity).
<productname>PostgreSQL</productname> also allows both clauses to specify
arbitrary expressions. Note that names appearing in an expression will
always be taken as input-column names, not as result-column names.
In the SQL standard, an <literal>ORDER BY</literal> clause may
only use result column names or numbers, while a <literal>GROUP
BY</literal> clause may only use expressions based on input column
names. <productname>PostgreSQL</productname> extends each of
these clauses to allow the other choice as well (but it uses the
standard's interpretation if there is ambiguity).
<productname>PostgreSQL</productname> also allows both clauses to
specify arbitrary expressions. Note that names appearing in an
expression will always be taken as input-column names, not as
result-column names.
</para>
</refsect3>
</refsect2>
<refsect3 id="R3-SQL-UNION-1">
<refsect3info>
<date>1998-09-24</date>
</refsect3info>
<title>
UNION/INTERSECT/EXCEPT Clause
</title>
<para>
The <acronym>SQL92</acronym> syntax for UNION/INTERSECT/EXCEPT allows an
additional CORRESPONDING BY option:
<synopsis>
<replaceable class="PARAMETER">table_query</replaceable> UNION [ALL]
[CORRESPONDING [BY (<replaceable class="PARAMETER">column</replaceable> [,...])]]
<replaceable class="PARAMETER">table_query</replaceable>
</synopsis></para>
<refsect2>
<title>Nonstandard Clauses</title>
<para>
The CORRESPONDING BY clause is not supported by
<productname>PostgreSQL</productname>.
The clauses <literal>DISTINCT ON</literal>,
<literal>LIMIT</literal>, and <literal>OFFSET</literal> are not
defined in the SQL standard.
</para>
</refsect3>
</refsect2>
</refsect1>
</refentry>
......
doc/src/sgml/ref/select_into.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.21 2002/11/21 23:34:43 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.22 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,18 +8,14 @@ PostgreSQL documentation
<refentrytitle id="SQL-SELECTINTO-TITLE">SELECT INTO</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
SELECT INTO
</refname>
<refpurpose>
create a new table from the results of a query
</refpurpose></refnamediv>
<refname>SELECT INTO</refname>
<refpurpose>create a new table from the results of a query</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2000-12-11</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) ] ]
* | <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">output_name</replaceable> ] [, ...]
INTO [ TEMPORARY | TEMP ] [ TABLE ] <replaceable class="PARAMETER">new_table</replaceable>
......@@ -32,25 +28,32 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
[ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ]
[ OFFSET <replaceable class="PARAMETER">start</replaceable> ]
[ FOR UPDATE [ OF <replaceable class="PARAMETER">tablename</replaceable> [, ...] ] ]
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect2 id="R2-SQL-SELECTINTO-1">
<refsect2info>
<date>2001-03-20</date>
</refsect2info>
<title>
Inputs
</title>
<refsect1>
<title>Description</title>
<para>
<command>SELECT INTO</command> creates a new table and fills it
with data computed by a query. The data is not returned to the
client, as it is with a normal <command>SELECT</command>. The new
table's columns have the names and data types associated with the
output columns of the <command>SELECT</command>.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>TEMPORARY</term>
<term>TEMP</term>
<term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term>
<listitem>
<para>
If specified, the table is created as a temporary table.
Refer to <xref linkend="sql-createtable" endterm="sql-createtable-title"> for details.
If specified, the table is created as a temporary table. Refer
to <xref linkend="sql-createtable"
endterm="sql-createtable-title"> for details.
</para>
</listitem>
</varlistentry>
......@@ -64,21 +67,15 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
All other inputs are described in detail for
<xref linkend="sql-select" endterm="sql-select-title">.
All other parameters are described in detail under <xref
linkend="sql-select" endterm="sql-select-title">.
</para>
</refsect2>
</refsect1>
<refsect2 id="R2-SQL-SELECTINTO-2">
<refsect2info>
<date>2001-03-20</date>
</refsect2info>
<title>
Outputs
</title>
<refsect1>
<title>Diagnostics</title>
<para>
Refer to
......@@ -87,51 +84,36 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
<xref linkend="sql-select" endterm="sql-select-title">
for a summary of possible output messages.
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-SELECTINTO-1">
<refsect1info>
<date>2001-03-20</date>
</refsect1info>
<title>
Description
</title>
</refsect1>
<para>
<command>SELECT INTO</command> creates a new table and fills it
with data computed by a query. The data is not returned to the
client, as it is with a normal <command>SELECT</command>. The new
table's columns have the names and data types associated with the
output columns of the <command>SELECT</command>.
<refsect1>
<title>Notes</title>
<note>
<para>
<xref linkend="sql-createtableas" endterm="sql-createtableas-title">
is functionally equivalent to <command>SELECT INTO</command>.
<command>CREATE TABLE AS</command> is the recommended syntax, since
<command>SELECT INTO</command> is not standard. In fact, this form of
<command>SELECT INTO</command> is not available in <application>PL/pgSQL</application> or <xref linkend="app-ecpg">,
because they interpret the INTO clause differently.
</para>
</note>
this form of <command>SELECT INTO</command> is not available in
<application>ECPG</application> or
<application>PL/pgSQL</application>, because they interpret the
<literal>INTO</literal> clause differently.
</para>
</refsect1>
<refsect1 id="R1-SQL-SELECTINTO-2">
<title>
Compatibility
</title>
<refsect1>
<title>Compatibility</title>
<para>
SQL92 uses <command>SELECT ... INTO</command> to represent selecting
values into scalar variables of a host program, rather than creating
a new table. This indeed is the usage found in <application>PL/pgSQL</application> and <xref linkend="app-ecpg">.
The SQL standard uses <command>SELECT ... INTO</command> to
represent selecting values into scalar variables of a host program,
rather than creating a new table. This indeed is the usage found
in <application>ECPG</application> (see <xref linkend="ecpg">) and
<application>PL/pgSQL</application> (see <xref linkend="plpgsql">).
The <productname>PostgreSQL</productname> usage of <command>SELECT
INTO</command> to represent table creation is historical. It's best
to use <command>CREATE TABLE AS</command> for this purpose in new code.
(<command>CREATE TABLE AS</command> isn't standard either, but it's
less likely to cause confusion.)
INTO</command> to represent table creation is historical. It's
best to use <command>CREATE TABLE AS</command> for this purpose in
new code. (<command>CREATE TABLE AS</command> isn't standard
either, but it's less likely to cause confusion.)
</para>
</refsect1>
</refentry>
......
doc/src/sgml/ref/set.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.74 2003/04/25 19:45:08 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.75 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,73 +8,20 @@ PostgreSQL documentation
<refentrytitle id="SQL-SET-TITLE">SET</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>SET</refname>
<refpurpose>change a run-time parameter</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<synopsis>
SET [ SESSION | LOCAL ] <replaceable class="PARAMETER">variable</replaceable> { TO | = } { <replaceable class="PARAMETER">value</replaceable> | '<replaceable class="PARAMETER">value</replaceable>' | DEFAULT }
SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</replaceable> | LOCAL | DEFAULT }
</synopsis>
<refsect2 id="R2-SQL-SET-1">
<title>Inputs</title>
<para>
<variablelist>
<varlistentry>
<term><option>SESSION</></term>
<listitem>
<para>
Specifies that the command takes effect for the current session.
(This is the default if neither <option>SESSION</> nor
<option>LOCAL</> appears.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>LOCAL</></term>
<listitem>
<para>
Specifies that the command takes effect for only the current
transaction. After <command>COMMIT</> or <command>ROLLBACK</>,
the session-level setting takes effect again. Note that
<command>SET LOCAL</> will appear to have no effect if it's
executed outside a <command>BEGIN</> block, since the transaction
will end immediately.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">variable</replaceable></term>
<listitem>
<para>
Name of a settable run-time parameter.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">value</replaceable></term>
<listitem>
<para>
New value of parameter. <option>DEFAULT</option> can be
used to specify resetting the parameter to its default
value. Lists of strings are allowed, but more complex
constructs may need to be single or double quoted.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-SET-1">
<refsect1>
<title>Description</title>
<para>
......@@ -83,7 +30,7 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</rep
<xref linkend="runtime-config"> can be changed on-the-fly with
<command>SET</command>.
(But some require superuser privileges to change, and others cannot
be changed after server or session start.) Note that
be changed after server or session start.)
<command>SET</command> only affects the value used by the current
session.
</para>
......@@ -114,236 +61,153 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="PARAMETER">timezone</rep
does not start a new transaction block. See the
<varname>autocommit</> section in <xref linkend="runtime-config"> for details.
</para>
</refsect1>
<para>
Here are additional details about a few of the parameters that can be set:
<variablelist>
<varlistentry>
<term><varname>DATESTYLE</></term>
<listitem>
<para>
Choose the date/time representation style. Two separate
settings are involved: the default date/time output format and the
interpretation of ambiguous input.
</para>
<para>
The following are date/time output styles:
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><literal>ISO</></term>
<term><literal>SESSION</></term>
<listitem>
<para>
Use ISO 8601-style dates and times (<literal>YYYY-MM-DD
HH:MM:SS</literal>). This is the default.
Specifies that the command takes effect for the current session.
(This is the default if neither <literal>SESSION</> nor
<literal>LOCAL</> appears.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SQL</></term>
<term><literal>LOCAL</></term>
<listitem>
<para>
Use Oracle/Ingres-style dates and times. Note that this
style has nothing to do with SQL (which mandates ISO 8601
style); the naming of this option is a historical accident.
Specifies that the command takes effect for only the current
transaction. After <command>COMMIT</> or <command>ROLLBACK</>,
the session-level setting takes effect again. Note that
<command>SET LOCAL</> will appear to have no effect if it is
executed outside a <command>BEGIN</> block, since the
transaction will end immediately.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>PostgreSQL</></term>
<term><replaceable class="PARAMETER">variable</replaceable></term>
<listitem>
<para>
Use traditional <productname>PostgreSQL</productname> format.
Name of a settable run-time parameter. Available parameters are
documented in <xref linkend="runtime-config"> and below.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>German</></term>
<term><replaceable class="PARAMETER">value</replaceable></term>
<listitem>
<para>
Use <literal>dd.mm.yyyy</literal> for numeric date representations.
New value of parameter. Values can be specified as string
constants, identifiers, numbers, or comma-separated lists of
these. <literal>DEFAULT</literal> can be used to specify
resetting the parameter to its default value.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The following two options determine both a substyle of the
<quote>SQL</quote> and <quote>PostgreSQL</quote> output formats
and the preferred interpretation of ambiguous date input.
Besides the configuration parameters documented in <xref
linkend="runtime-config">, there are a few that can only be
adjusted using the <command>SET</command> command or that have a
special syntax:
<variablelist>
<varlistentry>
<term><literal>European</></term>
<term><literal>NAMES</literal></term>
<listitem>
<para>
Use <literal>dd/mm/yyyy</literal> for numeric date representations.
<literal>>SET NAMES <replaceable>value</></> is an alias for
<literal>SET client_encoding TO <replaceable>value</></>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>NonEuropean</></term>
<term><literal>US</></term>
<term><literal>SEED</literal></term>
<listitem>
<para>
Use <literal>mm/dd/yyyy</literal> for numeric date representations.
</para>
</listitem>
</varlistentry>
</variablelist>
Sets the internal seed for the random number generator (the
function <function>random</function>). Allowed values are
floating-point numbers between 0 and 1, which are then
multiplied by 2<superscript>31</>-1.
</para>
<para>
A value for <command>SET DATESTYLE</command> can be one from
the first list (output styles), or one from the second list
(substyles), or one from each separated by a comma.
</para>
<para>
<command>SET DATESTYLE</command> affects interpretation of
input and provides several standard output formats. For
applications needing different variations or tighter control
over input or output, consider using
the <function>to_char</function> family of
functions.
</para>
<para>
There are several now-deprecated means for setting the date style
in addition to the normal methods of setting it via <command>SET</> or
a configuration-file entry:
<simplelist>
<member>
Setting the postmaster's <envar>PGDATESTYLE</envar> environment
variable. (This will be overridden by any of the other methods.)
</member>
<member>
Running postmaster using the option <option>-o -e</option> to
set dates to the <literal>European</literal> convention.
(This overrides environment variables and configuration-file
entries.)
</member>
<member>
Setting the client's <envar>PGDATESTYLE</envar> environment variable.
If <envar>PGDATESTYLE</envar> is set in the frontend environment of a client
based on <application>libpq</>, <application>libpq</> will automatically set <varname>DATESTYLE</> to the
value of <envar>PGDATESTYLE</envar> during connection start-up. This is
equivalent to a manually issued <command>SET DATESTYLE</>.
</member>
</simplelist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>NAMES</term>
<listitem>
<para>
<command>SET NAMES</> is an alias for <command>SET CLIENT_ENCODING</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SEED</term>
<listitem>
<para>
Sets the internal seed for the random number generator.
<variablelist>
<varlistentry>
<term><replaceable class="parameter">value</replaceable></term>
<listitem>
<para>
The value for the seed to be used by the
<function>random</function> function. Allowed
values are floating-point numbers between 0 and 1, which
are then multiplied by 2<superscript>31</>-1.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The seed can also be set by invoking the
<function>setseed</function> SQL function:
<programlisting>
The seed can also be set by invoking the function
<function>setseed</function>:
<programlisting>
SELECT setseed(<replaceable>value</replaceable>);
</programlisting>
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TIME ZONE</term>
<term>TIMEZONE</term>
<term><literal>TIME ZONE</literal></term>
<listitem>
<para>
Sets the default time zone for your session. Arguments can be
an SQL time interval constant, an integer or double precision
constant, or a string representing a time zone name recognized
by the host operating system.
</para>
<para>
Here are some typical values for time zone settings:
<literal>>SET TIME ZONE <replaceable>value</></> is an alias
for <literal>SET timezone TO <replaceable>value</></>. The
syntax <literal>>SET TIME ZONE</literal> allows special syntax
for the time zone specification. Here are examples of valid
values:
<variablelist>
<varlistentry>
<term>'PST8PDT'</term>
<term><literal>'PST8PDT'</literal></term>
<listitem>
<para>
Set the time zone for Berkeley, California.
The time zone for Berkeley, California.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>'Portugal'</term>
<term><literal>'Portugal'</literal></term>
<listitem>
<para>
Set the time zone for Portugal.
The time zone for Portugal.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>'Europe/Rome'</term>
<term><literal>'Europe/Rome'</literal></term>
<listitem>
<para>
Set the time zone for Italy.
The time zone for Italy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>7</term>
<term><literal>7</literal></term>
<listitem>
<para>
Set the time zone to 7 hours offset west from GMT (equivalent
The time zone to 7 hours offset west from UTC (equivalent
to PDT).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>INTERVAL '08:00' HOUR TO MINUTE</term>
<term><literal>INTERVAL '08:00' HOUR TO MINUTE</literal></term>
<listitem>
<para>
Set the time zone to 8 hours offset west from GMT (equivalent
The time zone to 8 hours offset west from UTC (equivalent
to PST).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LOCAL</term>
<term>DEFAULT</term>
<term><literal>LOCAL</literal></term>
<term><literal>DEFAULT</literal></term>
<listitem>
<para>
Set the time zone to your local time zone (the one that
......@@ -352,42 +216,18 @@ SELECT setseed(<replaceable>value</replaceable>);
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The available time zone names depend on your operating
system. For example, on Linux
<filename>/usr/share/zoneinfo</filename> contains the database
of time zones; the names of the files in that directory can be
used as parameters to this command.
</para>
<para>
If an invalid time zone is specified, the time zone
becomes GMT (on most systems anyway).
</para>
<para>
If the <envar>PGTZ</envar> environment variable is set in the frontend
environment of a client based on <application>libpq</>, <application>libpq</> will automatically
<command>SET TIMEZONE</command> to the value of
<envar>PGTZ</envar> during connection start-up.
See <xref linkend="datatype-datetime"> for more information
about time zones.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Use <xref linkend="SQL-SHOW" endterm="SQL-SHOW-title"> to show the
current setting of a parameter.
</para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<para>
<variablelist>
<varlistentry>
......@@ -400,8 +240,7 @@ SELECT setseed(<replaceable>value</replaceable>);
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: '<replaceable>name</replaceable>' is not a
valid option name</computeroutput></term>
<term><computeroutput>ERROR: '<replaceable>name</replaceable>' is not a valid option name</computeroutput></term>
<listitem>
<para>
The parameter you tried to set does not exist.
......@@ -410,8 +249,7 @@ SELECT setseed(<replaceable>value</replaceable>);
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: '<replaceable>name</replaceable>':
permission denied</computeroutput></term>
<term><computeroutput>ERROR: '<replaceable>name</replaceable>': permission denied</computeroutput></term>
<listitem>
<para>
You must be a superuser to alter certain settings.
......@@ -420,17 +258,14 @@ SELECT setseed(<replaceable>value</replaceable>);
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: '<replaceable>name</replaceable>' cannot
be changed after server start</computeroutput></term>
<term><computeroutput>ERROR: '<replaceable>name</replaceable>' cannot be changed after server start</computeroutput></term>
<listitem>
<para>
Some parameters are fixed once the server is started.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
......@@ -438,81 +273,61 @@ SELECT setseed(<replaceable>value</replaceable>);
<para>
The function <function>set_config</function> provides equivalent
capability. See <xref linkend="functions-misc">.
functionality. See <xref linkend="functions-misc">.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
Set the style of date to traditional
<productname>PostgreSQL</productname> with European conventions:
<screen>
SET DATESTYLE TO PostgreSQL,European;
</screen>
Set the schema search path:
<programlisting>
SET search_path TO my_schema, public;
</programlisting>
</para>
<para>
Set the time zone for Berkeley, California, using quotes to
preserve the uppercase spelling of the time zone name (note
that the date style is <literal>PostgreSQL</literal> for this
example):
<screen>
SET TIME ZONE 'PST8PDT';
SELECT CURRENT_TIMESTAMP AS today;
today
------------------------------------
Tue Feb 26 07:32:21.42834 2002 PST
</screen>
Set the style of date to traditional
<productname>POSTGRES</productname> with European conventions:
<screen>
SET datestyle TO postgres,european;
</screen>
</para>
<para>
Set the time zone for Italy (note the required single quotes to handle
the special characters):
<screen>
SET TIME ZONE 'Europe/Rome';
SELECT CURRENT_TIMESTAMP AS today;
Set the time zone for Berkeley, California, using quotes to
preserve the uppercase spelling of the time zone name:
<screen>
SET TIME ZONE 'PST8PDT';
SELECT current_timestamp AS today;
today
-------------------------------
2002-10-08 05:39:35.008271+02
</screen>
2003-04-29 15:02:01.218622-07
</screen>
</para>
</refsect1>
<refsect1 id="R1-SQL-SET-3">
<refsect1>
<title>Compatibility</title>
<refsect2 id="R2-SQL-SET-4">
<title>
SQL92
</title>
<para>
<literal>SET TIME ZONE</literal>
extends syntax defined in
<acronym>SQL9x</acronym>. <acronym>SQL9x</acronym> allows
only numeric time zone offsets while
<productname>PostgreSQL</productname> allows full time zone
specifier strings as well. All other <literal>SET</literal>
features are
<productname>PostgreSQL</productname> extensions.
<literal>SET TIME ZONE</literal> extends syntax defined in the SQL
standard. The standard allows only numeric time zone offsets while
<productname>PostgreSQL</productname> allows more flexible
time-zone specifications. All other <literal>SET</literal>
features are <productname>PostgreSQL</productname> extensions.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<simpara>
<xref linkend="SQL-SHOW" endterm="SQL-SHOW-title">,
<xref linkend="SQL-RESET" endterm="SQL-RESET-title">,
<xref linkend="sql-set-constraints" endterm="sql-set-constraints-title">,
<xref linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title">,
<xref linkend="sql-set-transaction" endterm="sql-set-transaction-title">
</simpara>
<simplelist type="inline">
<member><xref linkend="SQL-RESET" endterm="SQL-RESET-title"></member>
<member><xref linkend="SQL-SHOW" endterm="SQL-SHOW-title"></member>
</simplelist>
</refsect1>
</refentry>
......
doc/src/sgml/ref/set_constraints.sgml
View file @ d1b4327d
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_constraints.sgml,v 1.5 2002/08/17 12:15:48 momjian Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_constraints.sgml,v 1.6 2003/05/04 02:23:16 petere Exp $ -->
<refentry id="SQL-SET-CONSTRAINTS">
<refmeta>
<refentrytitle id="SQL-SET-CONSTRAINTS-title">SET CONSTRAINTS</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>SET CONSTRAINTS</refname>
<refpurpose>set the constraint mode of the current transaction</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2000-06-01</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
SET CONSTRAINTS { ALL | <replaceable class="parameter">constraint</replaceable> [, ...] } { DEFERRED | IMMEDIATE }
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect1>
......@@ -22,39 +21,26 @@ SET CONSTRAINTS { ALL | <replaceable class="parameter">constraint</replaceable>
<para>
<command>SET CONSTRAINTS</command> sets the behavior of constraint
evaluation in the current transaction. In <option>IMMEDIATE
</option> mode, constraints are checked at the end of each
statement. In <option>DEFERRED</option> mode, constraints are not
checked until transaction commit.
</para>
<note>
<para>
This command only alters the behavior of constraints within the
current transaction. Thus, if you execute this command outside
of an explicit transaction block (such as one started with
<command>BEGIN</command>), it will not appear to have any effect.
If you wish to change the behavior of a constraint without needing
to issue a <command>SET CONSTRAINTS</command> command in every
transaction, specify <option>INITIALLY DEFERRED</option> or
<option>INITIALLY IMMEDIATE</option> when you create the constraint.
evaluation in the current transaction. In
<literal>IMMEDIATE</literal> mode, constraints are checked at the
end of each statement. In <literal>DEFERRED</literal> mode,
constraints are not checked until transaction commit.
</para>
</note>
<para>
When you change the mode of a constraint to be <option>IMMEDIATE
</option>, the new constraint mode takes effect retroactively:
any outstanding data modifications that would have been checked
at the end of the transaction (when using
<option>DEFERRED</option>) are instead checked during the
When you change the mode of a constraint to be
<literal>IMMEDIATE</literal>, the new constraint mode takes effect
retroactively: any outstanding data modifications that would have
been checked at the end of the transaction (when using
<literal>DEFERRED</literal>) are instead checked during the
execution of the <command>SET CONSTRAINTS</command> command.
</para>
<para>
Upon creation, a constraint is always give one of three
characteristics: <option>INITIALLY DEFERRED</option>,
<option>INITIALLY IMMEDIATE DEFERRABLE</option>, or
<option>INITIALLY IMMEDIATE NOT DEFERRABLE</option>. The third
characteristics: <literal>INITIALLY DEFERRED</literal>,
<literal>INITIALLY IMMEDIATE DEFERRABLE</literal>, or
<literal>INITIALLY IMMEDIATE NOT DEFERRABLE</literal>. The third
class is not affected by the <command>SET CONSTRAINTS</command>
command.
</para>
......@@ -66,21 +52,30 @@ SET CONSTRAINTS { ALL | <replaceable class="parameter">constraint</replaceable>
</para>
</refsect1>
<refsect1 id="R1-SQL-SET-CONSTRAINT-3">
<title>Compatibility</title>
<refsect1>
<title>Notes</title>
<refsect2 id="R2-SQL-SET-CONSTRAINT-4">
<title>SQL92, SQL99</title>
<para>
This command only alters the behavior of constraints within the
current transaction. Thus, if you execute this command outside of a
transaction block
(<command>BEGIN</command>/<command>COMMIT</command> pair), it will
not appear to have any effect. If you wish to change the behavior
of a constraint without needing to issue a <command>SET
CONSTRAINTS</command> command in every transaction, specify
<literal>INITIALLY DEFERRED</literal> or <literal>INITIALLY
IMMEDIATE</literal> when you create the constraint.
</para>
</refsect1>
<refsect1>
<title>Compatibility</title>
<para>
<command>SET CONSTRAINTS</command> is defined in
<acronym>SQL92</acronym> and <acronym>SQL99</acronym>. The
implementation in <productname>PostgreSQL</productname> complies
with the behavior defined in the standard, except for the
<productname>PostgreSQL</productname> limitation that <command>SET
CONSTRAINTS</command> cannot be applied to check or unique constraints.
This command complies with the behavior defined in the SQL
standard, except for the limitation that, in PostgreSQL, it only
applies to foreign-key constraints.
</para>
</refsect2>
</refsect1>
</refentry>
......
doc/src/sgml/ref/set_session_auth.sgml
View file @ d1b4327d
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_session_auth.sgml,v 1.8 2003/02/19 04:06:28 momjian Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_session_auth.sgml,v 1.9 2003/05/04 02:23:16 petere Exp $ -->
<refentry id="SQL-SET-SESSION-AUTHORIZATION">
<docinfo>
<date>2001-04-21</date>
</docinfo>
<refmeta>
<refentrytitle id="sql-set-session-authorization-title">SET SESSION AUTHORIZATION</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
......@@ -16,7 +12,7 @@
<refsynopsisdiv>
<synopsis>
SET [ SESSION | LOCAL ] SESSION AUTHORIZATION <replaceable class="PARAMETER">username</replaceable>
SET [ SESSION | LOCAL ] SESSION AUTHORIZATION <replaceable class="parameter">username</replaceable>
SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT
RESET SESSION AUTHORIZATION
</synopsis>
......@@ -28,11 +24,10 @@ RESET SESSION AUTHORIZATION
<para>
This command sets the session user identifier and the current user
identifier of the current SQL-session context to be <replaceable
class="PARAMETER">username</replaceable>. The user name may be
written as either an identifier or a string literal. The session
user identifier is valid for the duration of a connection; for
example, it is possible to temporarily become an unprivileged user
and later switch back to become a superuser.
class="parameter">username</replaceable>. The user name may be
written as either an identifier or a string literal. Using this
command, it is possible, for example, to temporarily become an
unprivileged user and later switch back to become a superuser.
</para>
<para>
......@@ -52,7 +47,7 @@ RESET SESSION AUTHORIZATION
</para>
<para>
The <option>SESSION</> and <option>LOCAL</> modifiers act the same
The <literal>SESSION</> and <literal>LOCAL</> modifiers act the same
as for the regular <xref linkend="SQL-SET" endterm="SQL-SET-title">
command.
</para>
......@@ -60,9 +55,8 @@ RESET SESSION AUTHORIZATION
<para>
The <literal>DEFAULT</> and <literal>RESET</> forms reset the session
and current user identifiers to be the originally authenticated user
name. These forms are always accepted.
name. These forms may be executed by any user.
</para>
</refsect1>
<refsect1>
......@@ -88,18 +82,16 @@ SELECT SESSION_USER, CURRENT_USER;
<refsect1>
<title>Compatibility</title>
<simpara>SQL99</simpara>
<para>
SQL99 allows some other expressions to appear in place of the
literal <parameter>username</parameter> which are not important in
practice. <application>PostgreSQL</application> allows identifier
syntax (<literal>"username"</literal>), which SQL does not. SQL
does not allow this command during a transaction;
<application>PostgreSQL</application> does not make
this restriction because there is no reason to. The
privileges necessary to execute this command are left
implementation-defined by the standard.
The SQL standard allows some other expressions to appear in place
of the literal <replaceable>username</replaceable> which are not
important in practice. <application>PostgreSQL</application>
allows identifier syntax (<literal>"username"</literal>), which SQL
does not. SQL does not allow this command during a transaction;
<application>PostgreSQL</application> does not make this
restriction because there is no reason to. The privileges
necessary to execute this command are left implementation-defined
by the standard.
</para>
</refsect1>
</refentry>
......
doc/src/sgml/ref/set_transaction.sgml
View file @ d1b4327d
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_transaction.sgml,v 1.13 2003/03/25 16:15:44 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_transaction.sgml,v 1.14 2003/05/04 02:23:16 petere Exp $ -->
<refentry id="SQL-SET-TRANSACTION">
<docinfo>
<date>2000-11-24</date>
</docinfo>
<refmeta>
<refentrytitle id="SQL-SET-TRANSACTION-TITLE">SET TRANSACTION</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
......@@ -15,12 +11,12 @@
</refnamediv>
<refsynopsisdiv>
<synopsis>
<synopsis>
SET TRANSACTION
[ ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } ] [ READ WRITE | READ ONLY ]
SET SESSION CHARACTERISTICS AS TRANSACTION
[ ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } ] [ READ WRITE | READ ONLY ]
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect1>
......@@ -28,8 +24,8 @@ SET SESSION CHARACTERISTICS AS TRANSACTION
<para>
The <command>SET TRANSACTION</command> command sets the transaction
characteristics of the current SQL-transaction. It has no effect on
any subsequent transactions. <command>SET SESSION
characteristics of the current transaction. It has no effect on any
subsequent transactions. <command>SET SESSION
CHARACTERISTICS</command> sets the default transaction
characteristics for each transaction of a session. <command>SET
TRANSACTION</command> can override it for an individual
......@@ -80,7 +76,9 @@ SET SESSION CHARACTERISTICS AS TRANSACTION
or data-modification statement (<command>SELECT</command>,
<command>INSERT</command>, <command>DELETE</command>,
<command>UPDATE</command>, <command>FETCH</command>,
<command>COPY</command>) of a transaction has been executed.
<command>COPY</command>) of a transaction has been executed. See
<xref linkend="mvcc"> for more information about transaction
isolation and concurrency control.
</para>
<para>
......@@ -117,25 +115,23 @@ SET default_transaction_isolation = '<replaceable>value</replaceable>'
<refsect1 id="R1-SQL-SET-TRANSACTION-3">
<title>Compatibility</title>
<refsect2 id="R2-SQL-SET-TRANSACTION-4">
<title>SQL92, SQL99</title>
<para>
<option>SERIALIZABLE</option> is the default transaction isolation level in
<acronym>SQL</acronym>. <productname>PostgreSQL</productname> does
not provide the isolation levels <option>READ UNCOMMITTED</option>
and <option>REPEATABLE READ</option>. Because of multiversion
concurrency control, the <option>SERIALIZABLE</option> level is not
truly serializable. See <xref linkend="mvcc"> for details.
Both commands are defined in the SQL standard.
<literal>SERIALIZABLE</literal> is the default transaction
isolation level in <acronym>SQL</acronym>; in PostgreSQL it is
<literal>READ COMMITED</literal>, but you can change it as
described above. <productname>PostgreSQL</productname> does not
provide the isolation levels <literal>READ UNCOMMITTED</literal>
and <literal>REPEATABLE READ</literal>. Because of multiversion
concurrency control, the <literal>SERIALIZABLE</literal> level is
not truly serializable. See <xref linkend="mvcc"> for details.
</para>
<para>
In <acronym>SQL</acronym> there is one other transaction
characteristic that can be set with these commands: the size of
the diagnostics area. This concept is not supported in
<productname>PostgreSQL</productname>.
In the SQL standard, there is one other transaction characteristic
that can be set with these commands: the size of the diagnostics
area. This concept is only for use in embedded SQL.
</para>
</refsect2>
</refsect1>
</refentry>
......
doc/src/sgml/ref/show.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/show.sgml,v 1.25 2003/04/25 19:45:08 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/show.sgml,v 1.26 2003/05/04 02:23:16 petere Exp $
PostgreSQL documentation
-->
......@@ -8,58 +8,34 @@ PostgreSQL documentation
<refentrytitle id="SQL-SHOW-TITLE">SHOW</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>SHOW</refname>
<refpurpose>show the value of a run-time parameter</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<synopsis>
SHOW <replaceable class="PARAMETER">name</replaceable>
</synopsis>
<synopsis>
</synopsis>
<synopsis>
SHOW ALL
</synopsis>
<refsect2 id="R2-SQL-SHOW-1">
<title>Inputs</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of a run-time parameter. See
<xref linkend="sql-set" endterm="sql-set-title">
for a list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ALL</term>
<listitem>
<para>
Show all current session parameters.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-SHOW-1">
<refsect1>
<title>Description</title>
<para>
<command>SHOW</command> will display the current setting of
run-time parameters. These variables can be set using the
<command>SET</command> statement, by editing the
<filename>postgresql.conf</filename> configuration file, through the
<envar>PGOPTIONS</envar> environmental variable (when using libpq
or a libpq-based application), or through
command-line flags when starting the
<application>postmaster</application>.
<filename>postgresql.conf</filename> configuration file, through
the <envar>PGOPTIONS</envar> environmental variable (when using
<application>libpq</> or a <application>libpq</>-based
application), or through command-line flags when starting the
<command>postmaster</command>. See <xref
linkend="runtime-config"> for details.
</para>
<para>
......@@ -67,17 +43,25 @@ SHOW ALL
does not start a new transaction block. See the
<varname>autocommit</> section in <xref linkend="runtime-config"> for details.
</para>
</refsect1>
<para>
Available parameters are documented in
<xref linkend="runtime-config"> and on the
<xref linkend="SQL-SET" endterm="SQL-SET-title"> reference page.
In addition, there are a few parameters that can be shown but not set:
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of a run-time parameter. Available parameters are
documented in <xref linkend="runtime-config"> and on the <xref
linkend="SQL-SET" endterm="SQL-SET-title"> reference page. In
addition, there are a few parameters that can be shown but not
set:
<variablelist>
<varlistentry>
<term>SERVER_VERSION</term>
<term><literal>SERVER_VERSION</literal></term>
<listitem>
<para>
Shows the server's version number.
......@@ -86,64 +70,69 @@ SHOW ALL
</varlistentry>
<varlistentry>
<term>SERVER_ENCODING</term>
<term><literal>SERVER_ENCODING</literal></term>
<listitem>
<para>
Shows the server-side multibyte encoding. At present, this
parameter can be shown but not set, because the encoding is
determined at database creation time.
Shows the server-side character set encoding. At present,
this parameter can be shown but not set, because the
encoding is determined at database creation time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LC_COLLATE</term>
<term><literal>LC_COLLATE</literal></term>
<listitem>
<para>
Shows the database's locale setting for collation (text ordering).
At present, this parameter can be shown but not set, because the
setting is determined at <application>initdb</> time.
Shows the database's locale setting for collation (text
ordering). At present, this parameter can be shown but not
set, because the setting is determined at
<command>initdb</> time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LC_CTYPE</term>
<term><literal>LC_CTYPE</literal></term>
<listitem>
<para>
Shows the database's locale setting for character set considerations.
At present, this parameter can be shown but not set, because the
setting is determined at <application>initdb</> time.
Shows the database's locale setting for character
classification. At present, this parameter can be shown but
not set, because the setting is determined at
<command>initdb</> time.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ALL</literal></term>
<listitem>
<para>
Use <xref linkend="SQL-SET" endterm="SQL-SET-title"> to set the value
of settable parameters.
Show the values of all configurations parameters.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>ERROR: Option '<replaceable>name</replaceable>'
is not recognized</computeroutput></term>
<term><computeroutput>ERROR: Option '<replaceable>name</replaceable>' is not recognized</computeroutput></term>
<listitem>
<para>
Message returned if <replaceable>name</replaceable> does
not stand for a known parameter.
Message returned if <replaceable>name</replaceable> does not
stand for a known parameter.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
......@@ -155,10 +144,11 @@ SHOW ALL
</para>
</refsect1>
<refsect1 id="R1-SQL-SHOW-2">
<refsect1>
<title>Examples</title>
<para>
Show the current <varname>DateStyle</varname> setting:
Show the current setting of the parameter <varname>DateStyle</varname>:
<programlisting>
SHOW DateStyle;
......@@ -170,10 +160,9 @@ SHOW DateStyle;
</para>
<para>
Show whether the genetic query optimizer is enabled by displaying
the <varname>geqo</varname> setting:
Show the current setting of the parameter <varname>geqo</varname>:
<programlisting>
SHOW GEQO;
SHOW geqo;
geqo
------
on
......@@ -198,10 +187,9 @@ SHOW ALL;
(94 rows)
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-SHOW-3">
<refsect1>
<title>Compatibility</title>
<para>
......@@ -209,6 +197,15 @@ SHOW ALL;
<productname>PostgreSQL</productname> extension.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="SQL-SET" endterm="SQL-SET-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/runtime.sgml
View file @ d1b4327d
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.177 2003/04/04 03:03:53 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.178 2003/05/04 02:23:16 petere Exp $
-->
<Chapter Id="runtime">
......@@ -1384,9 +1384,10 @@ SET ENABLE_SEQSCAN TO OFF;
<indexterm><primary>date style</></>
<listitem>
<para>
Sets the display format for date and time values, as well as the rules for
interpreting ambiguous date input values.
The default is <literal>ISO, US</>.
Sets the display format for date and time values, as well as
the rules for interpreting ambiguous date input values. See
<xref linkend="datatype-datetime"> for more information. The
default is <literal>ISO, US</>.
</para>
</listitem>
</varlistentry>
......@@ -1556,7 +1557,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<para>
This parameter adjusts the number of digits displayed for
floating-point values, including <type>float4</>, <type>float8</>,
and geometric datatypes. The parameter value is added to the
and geometric data types. The parameter value is added to the
standard number of digits (<literal>FLT_DIG</> or <literal>DBL_DIG</>
as appropriate). The value can be set as high as 2, to include
partially-significant digits; this is especially useful for dumping
......@@ -1813,26 +1814,28 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<indexterm><primary>preload_libraries</></>
<listitem>
<para>
This variable specifies one or more shared libraries that are to be
preloaded at Postmaster start. An initialization function can also be
optionally specified by adding a colon followed by the name of the
initialization function after the library name. For example
<literal>'$libdir/mylib:init_mylib'</literal> would cause <literal>mylib</>
to be preloaded and <literal>init_mylib</> to be executed. If more than
one library is to be loaded, they must be delimited with a comma.
This variable specifies one or more shared libraries that are
to be preloaded at server start. An initialization function
can also be optionally specified by adding a colon followed by
the name of the initialization function after the library
name. For example
<literal>'$libdir/mylib:init_mylib'</literal> would cause
<literal>mylib</> to be preloaded and <literal>init_mylib</>
to be executed. If more than one library is to be loaded, they
must be delimited with a comma.
</para>
<para>
If <literal>mylib</> is not found, the postmaster will fail to start.
However, if <literal>init_mylib</> is not found, <literal>mylib</> will
still be preloaded without executing the initialization function.
If <literal>mylib</> is not found, the server will fail to
start. However, if <literal>init_mylib</> is not found,
<literal>mylib</> will still be preloaded without executing
the initialization function.
</para>
<para>
By preloading a shared library (and initializing it if applicable),
the library startup time is avoided when the library is used later in a
specific backend. However there is a cost in terms of memory duplication
as every backend is forked, whether or not the library is used.
By preloading a shared library (and initializing it if
applicable), the library startup time is avoided when the
library is first used.
</para>
</listitem>
</varlistentry>
......@@ -2057,9 +2060,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<indexterm><primary>time zone</></>
<listitem>
<para>
Sets the time zone for displaying and interpreting time stamps.
The default is to use whatever the system environment
specifies as the time zone.
Sets the time zone for displaying and interpreting time
stamps. The default is to use whatever the system environment
specifies as the time zone. See <xref
linkend="datatype-datetime"> for more information.
</para>
</listitem>
</varlistentry>
......
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