diff options
31 files changed, 3240 insertions, 4452 deletions
diff --git a/doc/src/sgml/ref/declare.sgml b/doc/src/sgml/ref/declare.sgml index 49d380e238b..0aaf0dde43d 100644 --- a/doc/src/sgml/ref/declare.sgml +++ b/doc/src/sgml/ref/declare.sgml @@ -1,5 +1,5 @@ <!-- -$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,222 +8,23 @@ 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> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="parameter">cursorname</replaceable></term> - <listitem> - <para> - The name of the cursor to be used in subsequent - <command>FETCH</command> operations. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>BINARY</term> - <listitem> - <para> - Causes the cursor to return data in binary rather than in text format. - </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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>NO SCROLL</term> - <listitem> - <para> - Specifies that the cursor cannot be used to retrieve rows in a - nonsequential fashion (e.g., backward). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>SCROLL</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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>WITHOUT HOLD</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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>WITH HOLD</term> - <listitem> - <para> - Specifies that the cursor may continue to be used after the - transaction that creates it successfully commits. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable class="parameter">query</replaceable></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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>READ ONLY</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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>UPDATE</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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <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. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - - <para> - The <literal>BINARY</literal>, <literal>INSENSITIVE</literal>, - and <literal>SCROLL</literal> keywords may appear in any order. - </para> - </refsect2> - - <refsect2 id="R2-SQL-DECLARE-2"> - <refsect2info> - <date>1998-04-15</date> - </refsect2info> - <title> - Outputs - </title> - <para> - - <variablelist> - <varlistentry> - <term><computeroutput> -DECLARE CURSOR - </computeroutput></term> - <listitem> - <para> - The message returned if the <command>SELECT</command> is run successfully. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <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 - exists. The previous definition is discarded. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <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 - transaction block, and <literal>WITH HOLD</literal> is not - specified. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> + [ FOR { READ ONLY | UPDATE [ OF <replaceable class="parameter">column</replaceable> [, ...] ] } ] +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DECLARE-1"> - <refsect1info> - <date>1998-09-04</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <title>Description</title> + <para> <command>DECLARE</command> allows a user to create cursors, which can be used to retrieve @@ -236,51 +37,195 @@ ERROR: DECLARE CURSOR may only be used in begin/end transaction blocks 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. + 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> <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>). + a 4-byte value containing the internal representation of the value. </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. + 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> <para> - String representation is architecture-neutral whereas binary + 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. - - <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> + 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><replaceable class="parameter">cursorname</replaceable></term> + <listitem> + <para> + The name of the cursor to be used in subsequent + <command>FETCH</command> operations. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>BINARY</literal></term> + <listitem> + <para> + Causes the cursor to return data in binary rather than in text format. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>INSENSITIVE</literal></term> + <listitem> + <para> + 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><literal>SCROLL</literal></term> + <term><literal>NO SCROLL</literal></term> + <listitem> + <para> + <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><literal>WITH HOLD</literal></term> + <term><literal>WITHOUT HOLD</literal></term> + <listitem> + <para> + <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><replaceable class="parameter">query</replaceable></term> + <listitem> + <para> + 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><literal>FOR READ ONLY</literal></term> + <term><literal>FOR UPDATE</literal></term> + <listitem> + <para> + <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> + + <varlistentry> + <term><replaceable class="parameter">column</replaceable></term> + <listitem> + <para> + 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> + The key words <literal>BINARY</literal>, + <literal>INSENSITIVE</literal>, and <literal>SCROLL</literal> may + appear in any order. </para> + </refsect1> - <refsect2 id="R2-SQL-DECLARE-3"> - <refsect2info> - <date>1998-09-04</date> - </refsect2info> - <title> - Notes - </title> + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DECLARE CURSOR</computeroutput></term> + <listitem> + <para> + 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> + <listitem> + <para> + This message is reported if a cursor with the same name already + exists. The previous definition is discarded. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <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 + transaction block, and <literal>WITH HOLD</literal> is not + specified. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <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> - <para> - <acronym>SQL92</acronym> allows cursors only in embedded - <acronym>SQL</acronym> and in modules. <productname>PostgreSQL</> - permits cursors to be used interactively. - </para> + <refsect1> + <title>Compatibility</title> - <para> - <acronym>SQL92</acronym> allows embedded or modular cursors to - update database information. All <productname>PostgreSQL</> - cursors are read only. - </para> + <para> + The SQL standard allows cursors only in embedded + <acronym>SQL</acronym> and in modules. <productname>PostgreSQL</> + permits cursors to be used interactively. + </para> - <para> - The <literal>BINARY</literal> keyword is a - <productname>PostgreSQL</productname> extension. - </para> - </refsect2> + <para> + The SQL standard allows cursors to update table data. All + <productname>PostgreSQL</> cursors are read only. + </para> + + <para> + Binary cursors are a <productname>PostgreSQL</productname> + extension. + </para> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/drop_aggregate.sgml b/doc/src/sgml/ref/drop_aggregate.sgml index b671fa5c145..539d578653a 100644 --- a/doc/src/sgml/ref/drop_aggregate.sgml +++ b/doc/src/sgml/ref/drop_aggregate.sgml @@ -1,5 +1,5 @@ <!-- -$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,167 +8,126 @@ 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> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="parameter">name</replaceable></term> - <listitem> - <para> - The name (optionally schema-qualified) of an existing aggregate function. - </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. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the aggregate. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the aggregate if there are any dependent objects. - 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> - <variablelist> - <varlistentry> - <term><computeroutput> -DROP AGGREGATE - </computeroutput></term> - <listitem> - <para> - Message returned if the command is 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> - <listitem> - <para> - This message occurs if the aggregate function specified does not - exist in the database. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DROPAGGREGATE-1"> - <refsect1info> - <date>1998-04-15</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <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. + 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> + <listitem> + <para> + The name (optionally schema-qualified) of an existing aggregate function. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">type</replaceable></term> + <listitem> + <para> + The argument data type of the aggregate function, or + <literal>*</literal> if the function accepts any data type. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the aggregate function. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the aggregate function if any objects depend on + it. This is the default. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> - <refsect2 id="R2-SQL-DROPAGGREGATE-3"> - <refsect2info> - <date>1998-04-15</date> - </refsect2info> - <title> - Notes - </title> - - <para> - Use - <xref linkend="sql-createaggregate" endterm="sql-createaggregate-title"> - to create aggregate functions. - </para> - </refsect2> + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP AGGREGATE</computeroutput></term> + <listitem> + <para> + 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> + <listitem> + <para> + This message is returned if the specified aggregate function + does not exist. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + To remove the aggregate function <literal>myavg</literal> for type + <type>integer</type>: +<programlisting> +DROP AGGREGATE myavg(integer); +</programlisting> + </para> </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> - - <para> - There is no <command>DROP AGGREGATE</command> statement - in <acronym>SQL92</acronym>; the statement is a - <productname>PostgreSQL</productname> - language extension. - </para> - </refsect2> + <refsect1> + <title>See Also</title> + + <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 diff --git a/doc/src/sgml/ref/drop_cast.sgml b/doc/src/sgml/ref/drop_cast.sgml index 2f2cec02e14..427796e56bf 100644 --- a/doc/src/sgml/ref/drop_cast.sgml +++ b/doc/src/sgml/ref/drop_cast.sgml @@ -1,4 +1,4 @@ -<!-- $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> - <title>Parameters</title> + <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> diff --git a/doc/src/sgml/ref/drop_conversion.sgml b/doc/src/sgml/ref/drop_conversion.sgml index 535f1aa159e..6e785a84a8f 100644 --- a/doc/src/sgml/ref/drop_conversion.sgml +++ b/doc/src/sgml/ref/drop_conversion.sgml @@ -1,4 +1,4 @@ -<!-- $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> - <title>Parameters</title> + <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> diff --git a/doc/src/sgml/ref/drop_database.sgml b/doc/src/sgml/ref/drop_database.sgml index 4f5095892fc..fb77f53c67c 100644 --- a/doc/src/sgml/ref/drop_database.sgml +++ b/doc/src/sgml/ref/drop_database.sgml @@ -1,5 +1,5 @@ <!-- -$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> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">name</replaceable></term> - <listitem> - <para> - The name of an existing 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> +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> - <variablelist> + <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 the database to remove. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <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> + </refsect1> + + <refsect1> + <title>Notes</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). + This command cannot be executed while connected to the target + 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> - <command>DROP DATABASE</command> cannot be undone. Use it with care! + The is no <command>DROP DATABASE</command> statement in the SQL standard. </para> - - <refsect2 id="R2-SQL-DROPDATABASE-3"> - <refsect2info> - <date>1999-12-11</date> - </refsect2info> - <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. - </para> - - <para> - Refer to - <xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"> - for information on how to create a database. - </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> - - <para> - <command>DROP DATABASE</command> statement is a - <productname>PostgreSQL</productname> language extension; - there is no such command in <acronym>SQL92</acronym>. - </para> - </refsect2> + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member> + </simplelist> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/drop_domain.sgml b/doc/src/sgml/ref/drop_domain.sgml index 5196ae4b899..99c8ec7d44e 100644 --- a/doc/src/sgml/ref/drop_domain.sgml +++ b/doc/src/sgml/ref/drop_domain.sgml @@ -1,126 +1,98 @@ <!-- -$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> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">domainname</replaceable></term> - <listitem> - <para> - The name (optionally schema-qualified) of an existing domain. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>CASCADE</></term> - <listitem> - <para> - Automatically drop objects that depend on the domain - (such as table columns). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>RESTRICT</></term> - <listitem> - <para> - Refuse to drop the domain if there are any dependent objects. - 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> - <variablelist> - <varlistentry> - <term><computeroutput> -DROP DOMAIN - </computeroutput></term> - <listitem> - <para> - The message returned if the command is successful. - </para> - </listitem> - </varlistentry> - <varlistentry> - <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. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +</synopsis> </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> + <refsect1> + <title>Description</title> + <para> - Only the owner of a domain can remove it. + <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> + <listitem> + <para> + The name (optionally schema-qualified) of an existing domain. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</></term> + <listitem> + <para> + Automatically drop objects that depend on the domain (such as + table columns). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</></term> + <listitem> + <para> + Refuse to drop the domain if any objects depend on it. This is + the default. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP DOMAIN</computeroutput></term> + <listitem> + <para> + 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> + <listitem> + <para> + This message occurs if the specified domain does not exist. + </para> + </listitem> + </varlistentry> + </variablelist> + </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"> diff --git a/doc/src/sgml/ref/drop_function.sgml b/doc/src/sgml/ref/drop_function.sgml index 5f872499891..10504630ff9 100644 --- a/doc/src/sgml/ref/drop_function.sgml +++ b/doc/src/sgml/ref/drop_function.sgml @@ -1,5 +1,5 @@ <!-- -$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,129 +8,96 @@ 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> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="parameter">name</replaceable></term> - <listitem> - <para> - The name (optionally schema-qualified) of an existing function. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><replaceable class="parameter">type</replaceable></term> - <listitem> - <para> - The type of a parameter of the function. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the function - (such as operators or triggers). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the function if there are any dependent objects. - 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> - - <variablelist> - <varlistentry> - <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> - <listitem> - <para> - This message is given if the function specified does not - exist in the current database. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DROPFUNCTION-1"> - <refsect1info> - <date>1998-04-15</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <title>Description</title> + <para> - DROP FUNCTION will remove the definition of an existing + <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 input argument types to 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 id="SQL-DROPFUNCTION-notes"> - <title>Notes</title> + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of an existing function. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">type</replaceable></term> + <listitem> + <para> + The data type of an argument of the function. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the function (such as + operators or triggers). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the function if any objects depend on it. This + is the default. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP FUNCTION</computeroutput></term> + <listitem> + <para> + Message returned if the command completes successfully. + </para> + </listitem> + </varlistentry> - <para> - Refer to - <xref linkend="sql-createfunction" endterm="sql-createfunction-title"> - for information on creating functions. - </para> + <varlistentry> + <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 output if the function specified does not exist. + </para> + </listitem> + </varlistentry> + </variablelist> </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 diff --git a/doc/src/sgml/ref/drop_group.sgml b/doc/src/sgml/ref/drop_group.sgml index bb1d7224bb9..c6c6907e751 100644 --- a/doc/src/sgml/ref/drop_group.sgml +++ b/doc/src/sgml/ref/drop_group.sgml @@ -1,5 +1,5 @@ <!-- -$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,89 +8,60 @@ 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> - <para> - - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">name</replaceable></term> - <listitem> - <para> - The name of an existing group. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> - - <refsect2 id="R2-SQL-DROPGROUP-2"> - <refsect2info> - <date>2000-01-14</date> - </refsect2info> - <title> - Outputs - </title> - <para> - <variablelist> - <varlistentry> - <term><computeroutput>DROP GROUP</computeroutput></term> - <listitem> - <para> - The message returned if the group is successfully deleted. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DROPGROUP-1"> - <refsect1info> - <date>2000-01-14</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <title>Description</title> + <para> - <command>DROP GROUP</command> removes the specified group from the database. - The users in the group are not deleted. + <command>DROP GROUP</command> removes the specified group. 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> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="PARAMETER">name</replaceable></term> + <listitem> + <para> + The name of an existing group. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP GROUP</computeroutput></term> + <listitem> + <para> + Message returned if the group was successfully removed. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> - <refsect1 id="R1-SQL-DROPGROUP-2"> - <title> - Usage - </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> - <para> - There is no <command>DROP GROUP</command> in <acronym>SQL92</acronym>. - </para> - </refsect2> + <refsect1> + <title>Compatibility</title> + + <para> + There is no <command>DROP GROUP</command> statement in the SQL standard. + </para> </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 diff --git a/doc/src/sgml/ref/drop_index.sgml b/doc/src/sgml/ref/drop_index.sgml index 149afff0779..b6086ffff39 100644 --- a/doc/src/sgml/ref/drop_index.sgml +++ b/doc/src/sgml/ref/drop_index.sgml @@ -1,5 +1,5 @@ <!-- -$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,161 +8,118 @@ 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> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">index_name</replaceable></term> - <listitem> - <para> - The name (optionally schema-qualified) of an index to remove. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the index. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the index if there are any dependent objects. - 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> - <variablelist> - <varlistentry> - <term><computeroutput> -DROP INDEX - </computeroutput></term> - <listitem> - <para> - The 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> - <listitem> - <para> - This message occurs if <replaceable class="PARAMETER">index_name</replaceable> - is not an index in the database. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DROPINDEX-1"> - <refsect1info> - <date>1998-04-15</date> - </refsect1info> - <title> - Description - </title> + <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> - <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. - </para> - </refsect2> + <variablelist> + <varlistentry> + <term><replaceable class="PARAMETER">index_name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of an index to remove. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the index. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the index if any objects depend on it. This is + the default. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> - <refsect1 id="R1-SQL-DROPINDEX-2"> - <title> - Usage - </title> + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP INDEX</computeroutput></term> + <listitem> + <para> + 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> + <listitem> + <para> + This message is returned if <replaceable + class="PARAMETER">index_name</replaceable> is not an existing + index. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <para> - This command will remove the <literal>title_idx</literal> index: + This command will remove the index <literal>title_idx</literal>: - <programlisting> - DROP INDEX title_idx; - </programlisting> +<programlisting> +DROP INDEX title_idx; +</programlisting> </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>Compatibility</title> + + <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> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-createindex" endterm="sql-createindex-title"></member> + </simplelist> + </refsect1> + </refentry> diff --git a/doc/src/sgml/ref/drop_language.sgml b/doc/src/sgml/ref/drop_language.sgml index e0690a88ac6..5e7a77f8cf0 100644 --- a/doc/src/sgml/ref/drop_language.sgml +++ b/doc/src/sgml/ref/drop_language.sgml @@ -1,5 +1,5 @@ <!-- -$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,163 +8,120 @@ 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> - <para> - - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">name</replaceable></term> - <listitem> - <para> - The name of an existing procedural language. For backward - compatibility, the name may be enclosed by single quotes. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the language - (such as functions in the language). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the language if there are any dependent objects. - This is the default. - </para> - </listitem> - </varlistentry> - </variablelist> - - </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> - <listitem> - <para> - This message is returned if the language is successfully dropped. - </para> - </listitem> - </varlistentry> - <varlistentry> - <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. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - - <refsect1 id="R1-SQL-DROPLANGUAGE-1"> - <refsect1info> - <date>1998-04-15</date> - </refsect1info> - <title> - Description - </title> + + <refsect1> + <title>Description</title> + <para> - <command>DROP PROCEDURAL LANGUAGE</command> will remove the definition + <command>DROP LANGUAGE</command> will remove the definition of the previously registered procedural language called <replaceable class="parameter">name</replaceable>. </para> + </refsect1> - <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> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="PARAMETER">name</replaceable></term> + <listitem> + <para> + The name of an existing procedural language. For backward + compatibility, the name may be enclosed by single quotes. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the language (such as + functions in the language). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the language if any objects depend on it. This + is the default. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> - - <refsect1 id="R1-SQL-DROPLANGUAGE-2"> - <title> - Usage - </title> + + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP LANGUAGE</computeroutput></term> + <listitem> + <para> + 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> + <listitem> + <para> + This message is returned if a language called <replaceable + class="parameter">name</replaceable> is not found in the + database. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <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> - <para> - There is no <command>DROP PROCEDURAL LANGUAGE</command> in - <acronym>SQL92</acronym>. - </para> - </refsect2> + <refsect1> + <title>Compatibility</title> + + <para> + There is no <command>DROP LANGUAGE</command> statement in the SQL + standard. + </para> + </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 diff --git a/doc/src/sgml/ref/drop_opclass.sgml b/doc/src/sgml/ref/drop_opclass.sgml index 3f54baaccdc..3e54959a48d 100644 --- a/doc/src/sgml/ref/drop_opclass.sgml +++ b/doc/src/sgml/ref/drop_opclass.sgml @@ -1,5 +1,5 @@ <!-- -$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,162 +8,118 @@ 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> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="parameter">name</replaceable></term> - <listitem> - <para> - The name (optionally schema-qualified) of an existing operator class. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><replaceable class="parameter">access_method</replaceable></term> - <listitem> - <para> - The name of the index access method the operator class is for. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the operator class. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the operator class if there are any dependent objects. - 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> - - <variablelist> - <varlistentry> - <term><computeroutput> -DROP OPERATOR CLASS - </computeroutput></term> - <listitem> - <para> - The message returned if the command is successful. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +<synopsis> +DROP OPERATOR CLASS <replaceable class="PARAMETER">name</replaceable> USING <replaceable class="PARAMETER">index_method</replaceable> [ CASCADE | RESTRICT ] +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DROPOPCLASS-1"> - <refsect1info> - <date>2002-07-28</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <title>Description</title> + <para> - <command>DROP OPERATOR CLASS</command> drops an existing operator class - from the database. + <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> - <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> + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of an existing operator class. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <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><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the operator class. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the operator class if any objects depend on it. + This is the default. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> - <refsect1 id="R1-SQL-DROPOPCLASS-2"> - <title> - Usage - </title> + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP OPERATOR CLASS</computeroutput></term> + <listitem> + <para> + Message returned if the command was successful. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <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> - <para> - There is no <command>DROP OPERATOR CLASS</command> in - <acronym>SQL92</acronym>. - </para> - </refsect2> + <refsect1> + <title>Compatibility</title> + + <para> + There is no <command>DROP OPERATOR CLASS</command> statement in the + SQL standard. + </para> </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 diff --git a/doc/src/sgml/ref/drop_operator.sgml b/doc/src/sgml/ref/drop_operator.sgml index edd99bd75e3..8f3b1e069c6 100644 --- a/doc/src/sgml/ref/drop_operator.sgml +++ b/doc/src/sgml/ref/drop_operator.sgml @@ -1,5 +1,5 @@ <!-- -$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> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="parameter">id</replaceable></term> - <listitem> - <para> - The identifier (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. - </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. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the operator. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the operator if there are any dependent objects. - 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> - - <variablelist> - <varlistentry> - <term><computeroutput> -DROP OPERATOR - </computeroutput></term> - <listitem> - <para> - The message returned if the command is 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> - <listitem> - <para> - This message occurs 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> - <listitem> - <para> - This message occurs if the left unary operator - specified 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> - <listitem> - <para> - This message occurs if the right unary operator - specified does not exist. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +<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 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> + <refsect1> + <title>Description</title> + <para> - The left or right type of a left or right unary - operator, respectively, must be specified as <literal>NONE</literal>. + <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> - <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. - </para> - <para> - Refer to - <xref linkend="sql-createoperator" endterm="sql-createoperator-title"> - for information on how to create operators. - </para> - </refsect2> + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of an existing operator. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">lefttype</replaceable></term> + <listitem> + <para> + 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 data type of the operator's right operand; write + <literal>NONE</literal> if the operator has no right operand. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the operator. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the operator if any objects depend on it. This + is the default. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> - <refsect1 id="R1-SQL-DROPOPERATOR-2"> - <title> - Usage - </title> - <para> - Remove power operator <literal>a^n</literal> for <literal>int4</literal>: + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP OPERATOR</computeroutput></term> + <listitem> + <para> + Message returned if the command was successful. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <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 is returned if the specified binary operator does not exist. + </para> + </listitem> + </varlistentry> - <programlisting> -DROP OPERATOR ^ (int4, int4); - </programlisting> + <varlistentry> + <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 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">name</replaceable>' taking '<replaceable class="PARAMETER">righttype</replaceable>' does not exist</computeroutput></term> + <listitem> + <para> + This message is returned if the specified right unary operator + does not exist. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + Remove the power operator <literal>a^b</literal> for type <type>integer</type>: +<programlisting> +DROP OPERATOR ^ (integer, integer); +</programlisting> </para> + <para> - Remove left unary negation operator (<literal>! b</literal>) for <type>boolean</type>: - <programlisting> -DROP OPERATOR ! (none, bool); - </programlisting> + Remove the left unary bitwise complement operator + <literal>~b</literal> for type <type>bit</type>: +<programlisting> +DROP OPERATOR ~ (none, bit); +</programlisting> </para> + <para> - Remove right unary factorial operator (<literal>i !</literal>) for - <literal>int4</literal>: - <programlisting> -DROP OPERATOR ! (int4, none); - </programlisting> + Remove the right unary factorial operator <literal>x!</literal> + for type <type>integer</type>: +<programlisting> +DROP OPERATOR ! (integer, none); +</programlisting> </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>Compatibility</title> + + <para> + There is no <command>DROP OPERATOR</command> statement in the SQL standard. + </para> </refsect1> + + <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 diff --git a/doc/src/sgml/ref/drop_rule.sgml b/doc/src/sgml/ref/drop_rule.sgml index afb1b6a874b..0276621c575 100644 --- a/doc/src/sgml/ref/drop_rule.sgml +++ b/doc/src/sgml/ref/drop_rule.sgml @@ -1,5 +1,5 @@ <!-- -$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> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="parameter">name</replaceable></term> - <listitem> - <para> - The name of an existing 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. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the rule. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the rule if there are any dependent objects. - This is the default. - </para> - </listitem> - </varlistentry> - </variablelist> - - </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> - <listitem> - <para> - Message returned if successful. - </para> - </listitem> - </varlistentry> - <varlistentry> - <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. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DROPRULE-1"> - <refsect1info> - <date>1998-09-22</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <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. + <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 the rule to drop. + </para> + </listitem> + </varlistentry> - <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> + <varlistentry> + <term><replaceable class="parameter">relation</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of the table or view that + the rule applies to. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the rule. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the rule if any objects depend on it. This is + the default. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> - - <refsect1 id="R1-SQL-DROPRULE-2"> - <title> - Usage - </title> + + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP RULE</computeroutput></term> + <listitem> + <para> + Message returned if the command was successful. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><computeroutput>ERROR: Rule "<replaceable class="parameter">name</replaceable>" not found</computeroutput></term> + <listitem> + <para> + Message if the specified rule does not exist. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <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> - <para> - There is no <command>DROP RULE</command> in SQL92. - </para> - </refsect2> + <refsect1> + <title>Compatibility</title> + + <para> + There is no <command>DROP RULE</command> statement in the SQL standard. + </para> </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 diff --git a/doc/src/sgml/ref/drop_schema.sgml b/doc/src/sgml/ref/drop_schema.sgml index 8c69893ae2f..5411b257991 100644 --- a/doc/src/sgml/ref/drop_schema.sgml +++ b/doc/src/sgml/ref/drop_schema.sgml @@ -1,5 +1,5 @@ <!-- -$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,107 +8,23 @@ 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> - - <refsect2 id="R2-SQL-DROPSCHEMA-1"> - <refsect2info> - <date>2002-07-18</date> - </refsect2info> - <title> - Inputs - </title> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">name</replaceable></term> - <listitem> - <para> - The name of a schema. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects (tables, functions, etc) that are contained - in the schema. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - 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> - - <variablelist> - <varlistentry> - <term><computeroutput> -DROP SCHEMA - </computeroutput></term> - <listitem> - <para> - The message returned if the schema is successfully dropped. - </para> - </listitem> - </varlistentry> - <varlistentry> - <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. - </para> - </listitem> - </varlistentry> - </variablelist> - - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DROPSCHEMA-1"> - <refsect1info> - <date>2002-07-18</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <title>Description</title> + <para> - <command>DROP SCHEMA</command> removes schemas from the data base. + <command>DROP SCHEMA</command> removes schemas from the database. </para> <para> @@ -116,54 +32,98 @@ ERROR: Schema "<replaceable class="parameter">name</replaceable>" does not exist 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> + <listitem> + <para> + The name of a schema. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects (tables, functions, etc.) that are + contained in the schema. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the schema if it contains any objects. This is + the default. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP SCHEMA</computeroutput></term> + <listitem> + <para> + Message returned if the schema was successfully dropped. + </para> + </listitem> + </varlistentry> - <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> + <varlistentry> + <term><computeroutput>ERROR: Schema "<replaceable class="parameter">name</replaceable>" does not exist</computeroutput></term> + <listitem> + <para> + This message is returned if the specified schema does not exist. + </para> + </listitem> + </varlistentry> + </variablelist> </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> + <refsect1> + <title>Compatibility</title> - <refsect2 id="R2-SQL-DROPSCHEMA-4"> - <refsect2info> - <date>2002-07-18</date> - </refsect2info> - <title> - SQL92 - </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. - </para> - </refsect2> + <para> + <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> </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 diff --git a/doc/src/sgml/ref/drop_sequence.sgml b/doc/src/sgml/ref/drop_sequence.sgml index eafeb6ddac2..fe77e2a3d69 100644 --- a/doc/src/sgml/ref/drop_sequence.sgml +++ b/doc/src/sgml/ref/drop_sequence.sgml @@ -1,5 +1,5 @@ <!-- -$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,160 +8,112 @@ 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> - - <refsect2 id="R2-SQL-DROPSEQUENCE-1"> - <refsect2info> - <date>1998-09-22</date> - </refsect2info> - <title> - Inputs - </title> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">name</replaceable></term> - <listitem> - <para> - The name (optionally schema-qualified) of a sequence. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the sequence. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the sequence if there are any dependent objects. - 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> - - <variablelist> - <varlistentry> - <term><computeroutput> -DROP SEQUENCE - </computeroutput></term> - <listitem> - <para> - The message returned if the sequence is successfully dropped. - </para> - </listitem> - </varlistentry> - <varlistentry> - <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. - </para> - </listitem> - </varlistentry> - </variablelist> - - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DROPSEQUENCE-1"> - <refsect1info> - <date>1998-09-22</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <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. + <command>DROP SEQUENCE</command> removes sequence number generators. </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="PARAMETER">name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of a sequence. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the sequence. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the sequence if any objects depend on it. This + is the default. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> - <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. - </para> - </refsect2> + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP SEQUENCE</computeroutput></term> + <listitem> + <para> + 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> + <listitem> + <para> + Message returned if the specified sequence does not exist. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> - <refsect1 id="R1-SQL-DROPSEQUENCE-2"> - <title> - Usage - </title> + <refsect1> + <title>Examples</title> + <para> - To remove sequence <literal>serial</literal> from database: + To remove the sequence <literal>serial</literal>: - <programlisting> +<programlisting> DROP SEQUENCE serial; - </programlisting> +</programlisting> </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>Compatibility</title> + + <para> + There is no <command>DROP SEQUENCE</command> statement in the SQL standard. + </para> </refsect1> + + <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 diff --git a/doc/src/sgml/ref/drop_table.sgml b/doc/src/sgml/ref/drop_table.sgml index 754dccf3e26..4ebda8787e6 100644 --- a/doc/src/sgml/ref/drop_table.sgml +++ b/doc/src/sgml/ref/drop_table.sgml @@ -1,5 +1,5 @@ <!-- -$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> - - <refsect2 id="R2-SQL-DROPTABLE-1"> - <refsect2info> - <date>1998-09-22</date> - </refsect2info> - <title> - Inputs - </title> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">name</replaceable></term> - <listitem> - <para> - The name (optionally schema-qualified) of an existing table to drop. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the table - (such as views). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the table if there are any dependent objects. - 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> - <variablelist> - <varlistentry> - <term><computeroutput> -DROP TABLE - </computeroutput></term> - <listitem> - <para> - The 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> - <listitem> - <para> - If the specified table does not exist in the database. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DROPTABLE-1"> - <refsect1info> - <date>1998-09-22</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <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>. + Only its owner may destroy a table. To empty a table of rows, + without destroying the table, use <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.) + 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 the table to drop. + </para> + </listitem> + </varlistentry> - <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> + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the table (such as + views). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the table if any objects depend on it. This is + the default. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> - <refsect1 id="R1-SQL-DROPTABLE-2"> - <title> - Usage - </title> + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP TABLE</computeroutput></term> + <listitem> + <para> + 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> + <listitem> + <para> + Message returned if the specified table does not exist. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <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> - - <refsect2 id="R2-SQL-DROPTABLE-4"> - <title> - SQL92 - </title> - <para> - </para> - </refsect2> + <refsect1> + <title>Compatibility</title> + + <para> + This command conforms to the SQL standard. + </para> </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 diff --git a/doc/src/sgml/ref/drop_trigger.sgml b/doc/src/sgml/ref/drop_trigger.sgml index 92602756fd4..5a33d033c24 100644 --- a/doc/src/sgml/ref/drop_trigger.sgml +++ b/doc/src/sgml/ref/drop_trigger.sgml @@ -1,5 +1,5 @@ <!-- -$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,160 +8,121 @@ 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> - <para> - - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">name</replaceable></term> - <listitem> - <para> - The name of an existing trigger. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><replaceable class="PARAMETER">table</replaceable></term> - <listitem> - <para> - The name (optionally schema-qualified) of a table. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the trigger. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the trigger if there are any dependent objects. - 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> - - <variablelist> - <varlistentry> - <term><computeroutput> -DROP TRIGGER - </computeroutput></term> - <listitem> - <para> - The message returned if the trigger is 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> - <listitem> - <para> - This message occurs if the trigger specified does not exist. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DROPTRIGGER-1"> - <refsect1info> - <date>1998-09-22</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <title>Description</title> + <para> <command>DROP TRIGGER</command> will remove an existing - trigger definition. To execute this command the current + 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> + <refsect1> + <title>Parameters</title> - <para> - Destroy the <literal>if_dist_exists</literal> trigger - on table <literal>films</literal>: + <variablelist> + <varlistentry> + <term><replaceable class="PARAMETER">name</replaceable></term> + <listitem> + <para> + The name of the trigger to remove. + </para> + </listitem> + </varlistentry> -<programlisting> -DROP TRIGGER if_dist_exists ON films; -</programlisting> - </para> + <varlistentry> + <term><replaceable class="PARAMETER">table</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of a table for which the + trigger is defined. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the trigger. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the trigger if any objects depend on it. This is + the default. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> - - <refsect1 id="SQL-DROPTRIGGER-compatibility"> - <title>Compatibility</title> - + + <refsect1> + <title>Diagnostics</title> + <variablelist> <varlistentry> - <term>SQL92</term> + <term><computeroutput>DROP TRIGGER</computeroutput></term> <listitem> <para> - There is no <command>DROP TRIGGER</command> statement in - <acronym>SQL92</acronym>. + Message returned if the trigger was successfully dropped. </para> </listitem> </varlistentry> <varlistentry> - <term>SQL99</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> - 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 - <replaceable>name</replaceable></literal>. + Message returned if the specified trigger does not exist. </para> </listitem> </varlistentry> </variablelist> </refsect1> + <refsect1 id="SQL-DROPTRIGGER-examples"> + <title>Examples</title> + + <para> + Destroy the trigger <literal>if_dist_exists</literal> on the table + <literal>films</literal>: + +<programlisting> +DROP TRIGGER if_dist_exists ON films; +</programlisting> + </para> + </refsect1> + + <refsect1 id="SQL-DROPTRIGGER-compatibility"> + <title>Compatibility</title> + + <para> + The <command>DROP TRIGGER</command> statement in + <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> + </refsect1> + <refsect1> <title>See Also</title> @@ -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 diff --git a/doc/src/sgml/ref/drop_type.sgml b/doc/src/sgml/ref/drop_type.sgml index 665ce85e3a0..4267efcb0bd 100644 --- a/doc/src/sgml/ref/drop_type.sgml +++ b/doc/src/sgml/ref/drop_type.sgml @@ -1,5 +1,5 @@ <!-- -$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> - - <refsect2 id="R2-SQL-DROPTYPE-1"> - <refsect2info> - <date>1998-09-22</date> - </refsect2info> - <title> - Inputs - </title> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">typename</replaceable></term> - <listitem> - <para> - The name (optionally schema-qualified) of an existing type. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the type - (such as table columns, functions, operators, etc). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the type if there are any dependent objects. - 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> - <variablelist> - <varlistentry> - <term><computeroutput> -DROP TYPE - </computeroutput></term> - <listitem> - <para> - The message returned if the command is successful. - </para> - </listitem> - </varlistentry> - <varlistentry> - <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. - </para> - </listitem> - </varlistentry> - </variablelist> - - </para> - </refsect2> +</synopsis> </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> + <refsect1> + <title>Description</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 the data type to remove. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the type (such as + table columns, functions, operators). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the type if any objects depend on it. This is + the default. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP TYPE</computeroutput></term> + <listitem> + <para> + 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> + <listitem> + <para> + Message returned if the specified type does not exist. + </para> + </listitem> + </varlistentry> + </variablelist> + </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 diff --git a/doc/src/sgml/ref/drop_user.sgml b/doc/src/sgml/ref/drop_user.sgml index d7f3af80b82..7d094b993d3 100644 --- a/doc/src/sgml/ref/drop_user.sgml +++ b/doc/src/sgml/ref/drop_user.sgml @@ -1,5 +1,5 @@ <!-- -$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> - <title>Parameters</title> - - <para> - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">name</replaceable></term> - <listitem> - <para> - The name of an existing user. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> - + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="PARAMETER">name</replaceable></term> + <listitem> + <para> + The name of the user to remove. + </para> + </listitem> + </varlistentry> + </variablelist> </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> diff --git a/doc/src/sgml/ref/drop_view.sgml b/doc/src/sgml/ref/drop_view.sgml index 9b35d88c040..fd32f92f8ac 100644 --- a/doc/src/sgml/ref/drop_view.sgml +++ b/doc/src/sgml/ref/drop_view.sgml @@ -1,5 +1,5 @@ <!-- -$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> - <para> - - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">name</replaceable></term> - <listitem> - <para> - The name (optionally schema-qualified) of an existing view. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>CASCADE</term> - <listitem> - <para> - Automatically drop objects that depend on the view - (such as other views). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>RESTRICT</term> - <listitem> - <para> - Refuse to drop the view if there are any dependent objects. - This is the default. - </para> - </listitem> - </varlistentry> - </variablelist> - - </para> - </refsect2> - - <refsect2 id="R2-SQL-DROPVIEW-2"> - <refsect2info> - <date>1998-09-22</date> - </refsect2info> - <title> - Outputs - </title> - <para> - - <variablelist> - <varlistentry> - <term><computeroutput> -DROP VIEW - </computeroutput></term> - <listitem> - <para> - The message returned if the command is successful. - </para> - </listitem> - </varlistentry> - <varlistentry> - <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. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-DROPVIEW-1"> - <refsect1info> - <date>1998-09-22</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <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. + <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 the view to remove. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the view (such as + other views). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the view if any objects depend on it. This is + the default. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>DROP VIEW</computeroutput></term> + <listitem> + <para> + Message returned if the command was successful. + </para> + </listitem> + </varlistentry> - <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. - </para> - </refsect2> + <varlistentry> + <term><computeroutput>ERROR: view <replaceable class="parameter">name</replaceable> does not exist</computeroutput></term> + <listitem> + <para> + Message returned if the specified view does not exist. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> - <refsect1 id="R1-SQL-DROPVIEW-2"> - <title> - Usage - </title> + <refsect1> + <title>Examples</title> + <para> This command will remove the view called <literal>kinds</literal>: - </para> - <programlisting> +<programlisting> DROP VIEW kinds; - </programlisting> +</programlisting> + </para> </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>Compatibility</title> + + <para> + This command conforms to the SQL standard. + </para> </refsect1> + + <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 diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml index a1f3b13719f..305e5fc02cc 100644 --- a/doc/src/sgml/ref/fetch.sgml +++ b/doc/src/sgml/ref/fetch.sgml @@ -1,5 +1,5 @@ <!-- -$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,243 +34,20 @@ 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> - <para> - - <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: - - <variablelist> - <varlistentry> - <term>NEXT</term> - <listitem> - <para> - fetch next row. This is the default - if <replaceable class="PARAMETER">direction</replaceable> is omitted. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>PRIOR</term> - <listitem> - <para> - fetch prior row. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FIRST</term> - <listitem> - <para> - fetch first row of query (same as ABSOLUTE 1). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>LAST</term> - <listitem> - <para> - fetch last row of query (same as ABSOLUTE -1). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>ABSOLUTE <replaceable class="PARAMETER">count</replaceable></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> < 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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>RELATIVE <replaceable class="PARAMETER">count</replaceable></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> < 0. - RELATIVE 0 re-fetches current row, if any. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <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>). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>ALL</term> - <listitem> - <para> - fetch all remaining rows (same as FORWARD ALL). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FORWARD</term> - <listitem> - <para> - fetch next row (same as NEXT). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FORWARD <replaceable class="PARAMETER">count</replaceable></term> - <listitem> - <para> - fetch next <replaceable class="PARAMETER">count</replaceable> - rows. FORWARD 0 re-fetches current row. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>FORWARD ALL</term> - <listitem> - <para> - fetch all remaining rows. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>BACKWARD</term> - <listitem> - <para> - fetch prior row (same as PRIOR). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>BACKWARD <replaceable class="PARAMETER">count</replaceable></term> - <listitem> - <para> - fetch prior <replaceable class="PARAMETER">count</replaceable> - rows (scanning backwards). BACKWARD 0 re-fetches current row. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>BACKWARD ALL</term> - <listitem> - <para> - fetch all prior rows (scanning backwards). - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable class="PARAMETER">cursor</replaceable></term> - <listitem> - <para> - An open cursor's name. - </para> - </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: - - <variablelist> - <varlistentry> - <term><computeroutput> -WARNING: PerformPortalFetch: portal "<replaceable class="PARAMETER">cursor</replaceable>" not found - </computeroutput></term> - <listitem> - <para> - There is no cursor with the specified name. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-FETCH-1"> - <refsect1info> - <date>2003-03-11</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <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 + 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, or on any particular row of the result, or after the last row + 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 @@ -286,166 +58,338 @@ WARNING: PerformPortalFetch: portal "<replaceable class="PARAMETER">cursor</rep </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. + 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 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 + 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> - <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> - - <refsect2 id="R2-SQL-FETCH-3"> - <refsect2info> - <date>2003-03-11</date> - </refsect2info> - <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. - </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. - </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. - </para> - - <para> - <xref linkend="sql-declare" endterm="sql-declare-title"> - is used to define a cursor. - Use - <xref linkend="sql-move" endterm="sql-move-title"> - to change cursor position without retrieving data. - </para> - </refsect2> + <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: + + <variablelist> + <varlistentry> + <term><literal>NEXT</literal></term> + <listitem> + <para> + Fetch the next row. This is the default if <replaceable + class="PARAMETER">direction</replaceable> is omitted. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>PRIOR</literal></term> + <listitem> + <para> + Fetch the prior row. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>FIRST</literal></term> + <listitem> + <para> + Fetch the first row of the query (same as <literal>ABSOLUTE 1</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>LAST</literal></term> + <listitem> + <para> + Fetch the last row of the query (same as <literal>ABSOLUTE -1</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ABSOLUTE <replaceable class="PARAMETER">count</replaceable></literal></term> + <listitem> + <para> + 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><literal>RELATIVE <replaceable class="PARAMETER">count</replaceable></literal></term> + <listitem> + <para> + 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> + + <varlistentry> + <term><replaceable class="PARAMETER">count</replaceable></term> + <listitem> + <para> + Fetch the next <replaceable + class="PARAMETER">count</replaceable> rows (same as + <literal>FORWARD <replaceable + class="PARAMETER">count</replaceable></literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ALL</literal></term> + <listitem> + <para> + Fetch all remaining rows (same as <literal>FORWARD ALL</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>FORWARD</literal></term> + <listitem> + <para> + Fetch the next row (same as <literal>NEXT</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>FORWARD <replaceable class="PARAMETER">count</replaceable></literal></term> + <listitem> + <para> + Fetch the next <replaceable + class="PARAMETER">count</replaceable> rows. + <literal>FORWARD 0</literal> re-fetches the current row. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>FORWARD ALL</literal></term> + <listitem> + <para> + Fetch all remaining rows. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>BACKWARD</literal></term> + <listitem> + <para> + Fetch the prior row (same as <literal>PRIOR</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>BACKWARD <replaceable class="PARAMETER">count</replaceable></literal></term> + <listitem> + <para> + 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><literal>BACKWARD ALL</literal></term> + <listitem> + <para> + Fetch all prior rows (scanning backwards). + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <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 <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> + + <varlistentry> + <term><replaceable class="PARAMETER">cursor</replaceable></term> + <listitem> + <para> + An open cursor's name. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Diagnostics</title> + + <variablelist> + <varlistentry> + <term><computeroutput>WARNING: PerformPortalFetch: portal "<replaceable class="PARAMETER">cursor</replaceable>" not found</computeroutput></term> + <listitem> + <para> + There is no cursor with the specified name. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + 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> + <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 currently not supported by + <productname>PostgreSQL</productname>. + </para> + + <para> + <xref linkend="sql-declare" endterm="sql-declare-title"> + is used to define a cursor. Use + <xref linkend="sql-move" endterm="sql-move-title"> + to change cursor position without retrieving data. + </para> </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 + code | title | did | date_prod | kind | len -------+-------------------------+-----+------------+----------+------- BL101 | The Third Man | 101 | 1949-12-23 | Drama | 01:44 BL102 | The African Queen | 101 | 1951-08-11 | Romantic | 01:43 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 + 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> - - <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>. - </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. - </para> - - <para> - <acronym>SQL92</acronym> allows only <literal>FROM</> preceding the - cursor name; the option to use <literal>IN</> is an extension. - </para> - </refsect2> + <refsect1> + <title>Compatibility</title> + + <para> + 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 + <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> + The SQL standard allows only <literal>FROM</> preceding the cursor + name; the option to use <literal>IN</> is an extension. + </para> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/move.sgml b/doc/src/sgml/ref/move.sgml index cd6d6aca0fd..d60ec29c3b5 100644 --- a/doc/src/sgml/ref/move.sgml +++ b/doc/src/sgml/ref/move.sgml @@ -1,5 +1,5 @@ <!-- -$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> - </refnamediv> + <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> - - <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. - </para> + <refsect1> + <title>Diagnostics</title> - <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> + <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. + </para> </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> - code | title | did | date_prod | kind | len --------+--------+-----+-----------+--------+------- - P_303 | 48 Hrs | 103 | 1982-10-22| Action | 01:37 + +-- 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 (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> + <refsect1> + <title>Compatibility</title> - <refsect2 id="R2-SQL-MOVE-4"> - <refsect2info> - <date>1998-09-01</date> - </refsect2info> - <title> - SQL92 - </title> - <para> - There is no <acronym>SQL92</acronym> <command>MOVE</command> statement. - </para> - </refsect2> + <para> + There is no <command>MOVE</command> statement in the SQL standard. + </para> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/reset.sgml b/doc/src/sgml/ref/reset.sgml index bb6860657d2..87d9de30974 100644 --- a/doc/src/sgml/ref/reset.sgml +++ b/doc/src/sgml/ref/reset.sgml @@ -1,5 +1,5 @@ <!-- -$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,95 +8,97 @@ 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> - - <refsect2 id="R2-SQL-RESET-1"> - <title>Inputs</title> - <para> - <variablelist> - <varlistentry> - <term><replaceable class="PARAMETER">variable</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> - Resets all settable run-time parameters to default values. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </refsect2> - +</synopsis> </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> + 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> - The default value is defined as the value that the variable would + <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 postmaster's configuration file or command-line - switches, or per-database or per-user default settings. See - <xref linkend="runtime-config"> for details. + 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</> manual page for details on the transaction - behavior of <command>RESET</>. + 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">parameter</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><literal>ALL</literal></term> + <listitem> + <para> + Resets all settable run-time parameters to default values. + </para> + </listitem> + </varlistentry> + </variablelist> </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; +<screen> +RESET geqo; </screen> </para> </refsect1> diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index 6362840ec03..f983b2a8213 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -1,5 +1,5 @@ <!-- -$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,941 +8,814 @@ 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> - - <refsect2 id="R2-SQL-SELECT-1"> - <refsect2info> - <date>2000-12-11</date> - </refsect2info> - <title> - Inputs - </title> +<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> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>SELECT</command> retrieves rows from one or more tables. + The general processing of <command>SELECT</command> is as follows: + + <orderedlist> + <listitem> + <para> + 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> + + <listitem> + <para> + 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> + + <listitem> + <para> + 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> + + <listitem> + <para> + 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> + + <listitem> + <para> + 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> + + <listitem> + <para> + 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> + + <listitem> + <para> + 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> + + <listitem> + <para> + <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> + + <listitem> + <para> + 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> + </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">expression</replaceable></term> + <term><replaceable class="parameter">table_name</replaceable></term> <listitem> <para> - The name of a table's column or an expression. + 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">output_name</replaceable></term> + <term><replaceable class="parameter">alias</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. + 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">from_item</replaceable></term> + <term><replaceable class="parameter">select</replaceable></term> <listitem> <para> - A table reference, sub-SELECT, table function, or JOIN clause. See below for details. + 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> - + <varlistentry> - <term><replaceable class="PARAMETER">condition</replaceable></term> + <term><replaceable class="parameter">function_name</replaceable></term> <listitem> <para> - A Boolean expression giving a result of true or false. - See the WHERE and HAVING clause descriptions below. + 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><replaceable class="PARAMETER">select</replaceable></term> + <term><replaceable class="parameter">join_type</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). + One of + <itemizedlist> + <listitem> + <para><literal>[ INNER ] JOIN</literal></para> + </listitem> + <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> + + 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> - </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. + A <literal>JOIN</literal> clause, combines two + <literal>FROM</> items. (Use parentheses if necessary to + determine the order of nesting.) </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. + <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> - </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>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> - </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. + 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> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable class="PARAMETER">join_type</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. + <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><replaceable class="PARAMETER">join_condition</replaceable></term> + <term><literal>ON <replaceable class="parameter">join_condition</replaceable></literal></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. + <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><replaceable class="PARAMETER">join_column_list</replaceable></term> + <term><literal>USING (<replaceable class="parameter">join_column</replaceable> [, ...])</literal></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 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> - </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><literal>NATURAL</literal></term> <listitem> <para> - The complete set of rows resulting from the query specification. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <returnvalue><replaceable>count</replaceable></returnvalue> - </term> - <listitem> - <para> - The count of rows returned by the query. + <literal>NATURAL</literal> is shorthand for a + <literal>USING</> list that mentions all columns in the two + tables that have the same names. </para> </listitem> </varlistentry> </variablelist> </para> </refsect2> - </refsynopsisdiv> - - <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">.) - </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. - </para> - - <para> - DISTINCT will eliminate duplicate rows from the result. ALL (the - default) will return all candidate rows, including duplicates. - </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. - </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">.) - </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">.) - </para> - - <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">.) - </para> - - <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. - </para> - - <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">.) - </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">.) - </para> - <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">.) - </para> - - <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">.) - </para> - - <para> - The FOR UPDATE clause causes the <command>SELECT</command> - statement to lock the selected rows against concurrent updates. - </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. - </para> - - <refsect2 id="SQL-FROM"> - <refsect2info> - <date>2000-12-11</date> - </refsect2info> - <title id="sql-from-title"> - FROM Clause - </title> + <refsect2 id="SQL-WHERE"> + <title id="sql-where-title"><literal>WHERE</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>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> - 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>. + The optional <literal>GROUP BY</literal> clause has the general form +<synopsis> +GROUP BY <replaceable class="parameter">expression</replaceable> [, ...] +</synopsis> </para> <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. + <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> - 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. + 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> - <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. - </para> + <refsect2 id="SQL-HAVING"> + <title id="sql-having-title"><literal>HAVING</literal> Clause</title> <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.) + 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> - 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. + <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> - 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>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> - 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>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> - 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>UNION</> does not contain any duplicate + rows unless the <literal>ALL</> option is specified. + <literal>ALL</> prevents elimination of duplicates. </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>UNION</> operators in the same + <command>SELECT</command> statement are evaluated left to right, + unless otherwise indicated by parentheses. </para> - </refsect2> - - <refsect2 id="SQL-WHERE"> - <refsect2info> - <date>2000-03-15</date> - </refsect2info> - <title id="sql-where-title"> - WHERE 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: =, <, <=, >, >= or <>, - 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. - </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> + Currently, <literal>FOR UPDATE</> may not be specified either for + a <literal>UNION</> result or for the inputs of <literal>UNION</>. </para> + </refsect2> - <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> + <refsect2 id="SQL-INTERSECT"> + <title id="sql-intersect-title"><literal>INTERSECT</literal> Clause</title> <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 <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> - </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. + 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> - 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. + 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> - Each column referenced in - <replaceable class="PARAMETER">boolean_expr</replaceable> shall unambiguously - reference a grouping column, unless the reference appears within an - aggregate function. + 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-ORDERBY"> - <refsect2info> - <date>2000-03-15</date> - </refsect2info> - <title id="sql-orderby-title"> - ORDER BY Clause - </title> - <para> - <synopsis> -ORDER BY <replaceable class="PARAMETER">expression</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] - </synopsis></para> - + + <refsect2 id="SQL-EXCEPT"> + <title id="sql-except-title"><literal>EXCEPT</literal> Clause</title> + <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>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> + <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> + 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> - 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> -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. + 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> <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. + 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> + + <refsect2 id="sql-select-list"> + <title id="sql-select-list-title"><command>SELECT</command> List</title> + <para> - Optionally one may add the key word <literal>DESC</> (descending) - or <literal>ASC</> (ascending) after each column name 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 <</> and <literal>DESC</> is equivalent to - <literal>USING ></>. + 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> - 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. + 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"> + <title id="sql-orderby-title"><literal>ORDER BY</literal> Clause</title> <para> - Data of character types is sorted according to the locale-specific - collation order that was established when the database cluster - was initialized. + 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> - </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.) + 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 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. + 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 + <literal>AS</> clause. </para> <para> - The result of UNION does not contain any duplicate rows - unless the ALL option is specified. ALL prevents elimination of - duplicates. + 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 <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> - Multiple UNION operators in the same <command>SELECT</command> - statement are evaluated left to right, unless otherwise indicated - by parentheses. + 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> - Currently, FOR UPDATE may not be specified either for a UNION result - or for the inputs of a UNION. + 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 in the <literal>USING</> clause. + <literal>ASC</> is equivalent to <literal>USING <</> and + <literal>DESC</> is equivalent to <literal>USING ></>. </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. + 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> - INTERSECT is similar to UNION, except that it produces only rows that - appear in both query outputs, rather than rows that appear in either. - </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. - </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. + Data of character types is sorted according to the locale-specific + collation order that was established when the database cluster + was initialized. </para> </refsect2> + + <refsect2 id="SQL-LIMIT"> + <title id="sql-limit-title"><literal>LIMIT</literal> Clause</title> - <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. + 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> - 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. - </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. + 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> - </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. + 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> - <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-distinct"> + <title id="sql-distinct-title"><literal>DISTINCT</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. + 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> - 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. + <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-FOR-UPDATE"> - <refsect2info> - <date>2002-08-28</date> - </refsect2info> - <title id="sql-for-update-title"> - FOR UPDATE Clause - </title> + <title id="sql-for-update-title"><literal>FOR UPDATE</literal> Clause</title> + <para> - <synopsis> - FOR UPDATE [ OF <replaceable class="PARAMETER">tablename</replaceable> [, ...] ] - </synopsis> + The <literal>FOR UPDATE</literal> clause has this form: +<synopsis> +FOR UPDATE [ OF <replaceable class="parameter">table_name</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) + 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 + ... </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 + 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: @@ -1028,12 +898,12 @@ distributors: actors: ... ... SELECT distributors.name - FROM distributors - WHERE distributors.name LIKE 'W%' + FROM distributors + WHERE distributors.name LIKE 'W%' UNION SELECT actors.name - FROM actors - WHERE actors.name LIKE 'W%'; + FROM actors + WHERE actors.name LIKE 'W%'; name ---------------- @@ -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 ' - SELECT * FROM distributors WHERE did = $1; - ' LANGUAGE SQL; +CREATE FUNCTION distributors(int) RETURNS SETOF distributors AS ' + SELECT * FROM distributors WHERE did = $1; +' LANGUAGE SQL; SELECT * FROM distributors(111); did | name -----+------------- 111 | Walt Disney -(1 row) -CREATE FUNCTION distributors_2(int) - RETURNS SETOF RECORD AS ' - SELECT * FROM distributors WHERE did = $1; - ' LANGUAGE SQL; +CREATE FUNCTION distributors_2(int) RETURNS SETOF record AS ' + SELECT * FROM distributors WHERE did = $1; +' 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> + <refsect1> + <title>Compatibility</title> + + <para> + Of course, the <command>SELECT</command> statement is compatible + with the SQL standard. But there are some extensions and some + missing features. + </para> - <refsect2 id="R2-SQL-SELECT-4"> - <refsect2info> - <date>1998-09-24</date> - </refsect2info> - <title>Extensions</title> + <refsect2> + <title>Omitted <literal>FROM</literal> Clauses</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: - - <programlisting> + <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 + 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. +</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> + <title>The <literal>AS</literal> Key Word</title> + <para> + 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> - The table-function feature is a <productname>PostgreSQL</productname> - extension. + 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> </refsect2> - <refsect2 id="R2-SQL-SELECT-5"> - <refsect2info> - <date>1998-09-24</date> - </refsect2info> - <title> - <acronym>SQL92</acronym> - </title> + <refsect2> + <title>Nonstandard Clauses</title> + <para> + The clauses <literal>DISTINCT ON</literal>, + <literal>LIMIT</literal>, and <literal>OFFSET</literal> are not + defined in the SQL standard. </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> - - <para> - The DISTINCT ON phrase is not part of <acronym>SQL92</acronym>. - Nor are LIMIT and OFFSET. - </para> - - <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. - </para> - </refsect3> - - <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> - - <para> - The CORRESPONDING BY clause is not supported by - <productname>PostgreSQL</productname>. - </para> - </refsect3> - </refsect2> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml index c14911638be..131bb6e1a2f 100644 --- a/doc/src/sgml/ref/select_into.sgml +++ b/doc/src/sgml/ref/select_into.sgml @@ -1,5 +1,5 @@ <!-- -$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,71 +28,11 @@ 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> - - <refsect2 id="R2-SQL-SELECTINTO-1"> - <refsect2info> - <date>2001-03-20</date> - </refsect2info> - <title> - Inputs - </title> - - <para> - <variablelist> - <varlistentry> - <term>TEMPORARY</term> - <term>TEMP</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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><replaceable class="PARAMETER">new_table</replaceable></term> - <listitem> - <para> - The name (optionally schema-qualified) of the table to be created. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - - <para> - All other inputs are described in detail for - <xref linkend="sql-select" endterm="sql-select-title">. - </para> - </refsect2> - - <refsect2 id="R2-SQL-SELECTINTO-2"> - <refsect2info> - <date>2001-03-20</date> - </refsect2info> - <title> - Outputs - </title> - - <para> - Refer to - <xref linkend="sql-createtable" endterm="sql-createtable-title"> - and - <xref linkend="sql-select" endterm="sql-select-title"> - for a summary of possible output messages. - </para> - </refsect2> +</synopsis> </refsynopsisdiv> - <refsect1 id="R1-SQL-SELECTINTO-1"> - <refsect1info> - <date>2001-03-20</date> - </refsect1info> - <title> - Description - </title> + <refsect1> + <title>Description</title> <para> <command>SELECT INTO</command> creates a new table and fills it @@ -104,35 +40,81 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac 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> - <note> + <variablelist> + <varlistentry> + <term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term> + <listitem> <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. + If specified, the table is created as a temporary table. Refer + to <xref linkend="sql-createtable" + endterm="sql-createtable-title"> for details. </para> - </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">new_table</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of the table to be created. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + All other parameters are described in detail under <xref + linkend="sql-select" endterm="sql-select-title">. </para> </refsect1> - <refsect1 id="R1-SQL-SELECTINTO-2"> - <title> - Compatibility - </title> + <refsect1> + <title>Diagnostics</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 <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.) - </para> + <para> + Refer to + <xref linkend="sql-createtable" endterm="sql-createtable-title"> + and + <xref linkend="sql-select" endterm="sql-select-title"> + for a summary of possible output messages. + </para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <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 + 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> + <title>Compatibility</title> + + <para> + 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.) + </para> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml index 75dc366c3f9..eba67d05775 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -1,5 +1,5 @@ <!-- -$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> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><literal>SESSION</></term> + <listitem> + <para> + 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>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 is + 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. Available parameters are + documented in <xref linkend="runtime-config"> and below. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">value</replaceable></term> + <listitem> + <para> + 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> - Here are additional details about a few of the parameters that can be set: + 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><varname>DATESTYLE</></term> + <term><literal>NAMES</literal></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: - - <variablelist> - <varlistentry> - <term><literal>ISO</></term> - <listitem> - <para> - Use ISO 8601-style dates and times (<literal>YYYY-MM-DD - HH:MM:SS</literal>). This is the default. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>SQL</></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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>PostgreSQL</></term> - <listitem> - <para> - Use traditional <productname>PostgreSQL</productname> format. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>German</></term> - <listitem> - <para> - Use <literal>dd.mm.yyyy</literal> for numeric date representations. - </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. - - <variablelist> - <varlistentry> - <term><literal>European</></term> - <listitem> - <para> - Use <literal>dd/mm/yyyy</literal> for numeric date representations. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>NonEuropean</></term> - <term><literal>US</></term> - <listitem> - <para> - Use <literal>mm/dd/yyyy</literal> for numeric date representations. - </para> - </listitem> - </varlistentry> - </variablelist> - </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. + <literal>>SET NAMES <replaceable>value</></> is an alias for + <literal>SET client_encoding TO <replaceable>value</></>. </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> + <term><literal>SEED</literal></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> + 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> - 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,43 +216,19 @@ 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> <term><computeroutput>SET</computeroutput></term> @@ -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 + 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. - </para> - </refsect2> + <para> + <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> </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> diff --git a/doc/src/sgml/ref/set_constraints.sgml b/doc/src/sgml/ref/set_constraints.sgml index 32abdee89f3..3d5b58bee2e 100644 --- a/doc/src/sgml/ref/set_constraints.sgml +++ b/doc/src/sgml/ref/set_constraints.sgml @@ -1,20 +1,19 @@ -<!-- $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. + 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> - 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. - </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. - </para> - </refsect2> + <para> + 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> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/set_session_auth.sgml b/doc/src/sgml/ref/set_session_auth.sgml index 88d5578498c..f8c0297adad 100644 --- a/doc/src/sgml/ref/set_session_auth.sgml +++ b/doc/src/sgml/ref/set_session_auth.sgml @@ -1,9 +1,5 @@ -<!-- $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> diff --git a/doc/src/sgml/ref/set_transaction.sgml b/doc/src/sgml/ref/set_transaction.sgml index f43802d2e01..2ff29bc3d5f 100644 --- a/doc/src/sgml/ref/set_transaction.sgml +++ b/doc/src/sgml/ref/set_transaction.sgml @@ -1,9 +1,5 @@ -<!-- $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. - </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>. - </para> - </refsect2> + <para> + 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 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> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml index 0fec5fcce55..dd8e9cf0412 100644 --- a/doc/src/sgml/ref/show.sgml +++ b/doc/src/sgml/ref/show.sgml @@ -1,5 +1,5 @@ <!-- -$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,83 +43,96 @@ 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: - - <variablelist> - - <varlistentry> - <term>SERVER_VERSION</term> - <listitem> - <para> - Shows the server's version number. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>SERVER_ENCODING</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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>LC_COLLATE</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. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>LC_CTYPE</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. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - - <para> - Use <xref linkend="SQL-SET" endterm="SQL-SET-title"> to set the value - of settable parameters. - </para> + <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><literal>SERVER_VERSION</literal></term> + <listitem> + <para> + Shows the server's version number. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>SERVER_ENCODING</literal></term> + <listitem> + <para> + 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><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 + <command>initdb</> time. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>LC_CTYPE</literal></term> + <listitem> + <para> + 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> + 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> - <listitem> - <para> - Message returned if <replaceable>name</replaceable> does - not stand for a known parameter. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> + <variablelist> + <varlistentry> + <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. + </para> + </listitem> + </varlistentry> + </variablelist> </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 diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 9311aabfda3..c525ea4f15d 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,5 +1,5 @@ <!-- -$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> |