Skip to content

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

Editing of more reference pages.

parent 3a496c8a
Hide whitespace changes
Inline Side-by-side
Showing with 1663 additions and 2691 deletions
doc/src/sgml/ref/abort.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/abort.sgml,v 1.12 2003/04/15 13:25:08 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/abort.sgml,v 1.13 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -32,6 +32,22 @@ ABORT [ WORK | TRANSACTION ] ...@@ -32,6 +32,22 @@ ABORT [ WORK | TRANSACTION ]
</para> </para>
</refsect1> </refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><literal>WORK</literal></term>
<term><literal>TRANSACTION</literal></term>
<listitem>
<para>
Optional key words. They have no effect.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1> <refsect1>
<title>Diagnostics</title> <title>Diagnostics</title>
...@@ -71,7 +87,7 @@ ABORT [ WORK | TRANSACTION ] ...@@ -71,7 +87,7 @@ ABORT [ WORK | TRANSACTION ]
<para> <para>
To abort all changes: To abort all changes:
<programlisting> <programlisting>
ABORT WORK; ABORT;
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
......
doc/src/sgml/ref/deallocate.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/deallocate.sgml,v 1.1 2002/08/27 04:55:07 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/deallocate.sgml,v 1.2 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,114 +8,79 @@ PostgreSQL documentation ...@@ -8,114 +8,79 @@ PostgreSQL documentation
<refentrytitle id="sql-deallocate-title">DEALLOCATE</refentrytitle> <refentrytitle id="sql-deallocate-title">DEALLOCATE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>DEALLOCATE</refname>
DEALLOCATE <refpurpose>deallocate a prepared statement</refpurpose>
</refname>
<refpurpose>
remove a prepared query
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2002-08-12</date>
</refsynopsisdivinfo>
<synopsis>
DEALLOCATE [ PREPARE ] <replaceable class="PARAMETER">plan_name</replaceable>
</synopsis>
<refsect2 id="R2-SQL-DEALLOCATE-1">
<refsect2info>
<date>2002-08-12</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term>PREPARE</term>
<listitem>
<para>
This keyword is ignored.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">plan_name</replaceable></term>
<listitem>
<para>
The name of the prepared query to remove.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DEALLOCATE-2">
<refsect2info>
<date>2002-08-12</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist> <refsynopsisdiv>
<varlistentry> <synopsis>
<term><computeroutput> DEALLOCATE [ PREPARE ] <replaceable class="parameter">plan_name</replaceable>
<returnvalue>DEALLOCATE</returnvalue> </synopsis>
</computeroutput></term>
<listitem>
<para>
The prepared query was removed successfully.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-DEALLOCATE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2002-08-12</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>DEALLOCATE</command> is used to remove a previously <command>DEALLOCATE</command> is used to deallocate a previously
prepared query. If you do not explicitly prepared SQL statement. If you do not explicitly deallocate a
<command>DEALLOCATE</command> a prepared query, it is removed when prepared statement, it is deallocated when the session ends.
the session ends.
</para> </para>
<para> <para>
For more information on prepared queries, see <xref For more information on prepared statements, see <xref
linkend="sql-prepare" endterm="sql-prepare-title">. linkend="sql-prepare" endterm="sql-prepare-title">.
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-DEALLOCATE-2"> <refsect1>
<title> <title>Parameters</title>
Compatibility
</title> <variablelist>
<varlistentry>
<term><literal>PREPARE</literal></term>
<listitem>
<para>
This key word is ignored.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">plan_name</replaceable></term>
<listitem>
<para>
The name of the prepared statement to deallocate.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>DEALLOCATE</computeroutput></term>
<listitem>
<para>
Message returned if the prepared statement was deallocated successfully.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect2 id="R2-SQL-DEALLOCATE-3"> <refsect1>
<refsect2info> <title>Compatibility</title>
<date>2002-08-12</date>
</refsect2info> <para>
<title> The SQL standard includes a <command>DEALLOCATE</command>
SQL92 statement, but it is only for use in embedded SQL.
</title> </para>
<para>
SQL92 includes a <command>DEALLOCATE</command> statement, but it is
only for use in embedded SQL clients.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/delete.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/delete.sgml,v 1.16 2002/04/23 02:07:16 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/delete.sgml,v 1.17 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,105 +8,28 @@ PostgreSQL documentation ...@@ -8,105 +8,28 @@ PostgreSQL documentation
<refentrytitle id="SQL-DELETE-TITLE">DELETE</refentrytitle> <refentrytitle id="SQL-DELETE-TITLE">DELETE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv>
<refname>
DELETE
</refname>
<refpurpose>
delete rows of a table
</refpurpose>
<refnamediv>
<refname>DELETE</refname>
<refpurpose>delete rows of a table</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE <replaceable class="PARAMETER">condition</replaceable> ] DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE <replaceable class="PARAMETER">condition</replaceable> ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-DELETE-1">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an existing table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">condition</replaceable></term>
<listitem>
<para>
This is an SQL selection query which returns the rows which
are to be deleted.
</para>
<para>
Refer to the SELECT statement for further description
of the WHERE clause.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DELETE-2">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
DELETE <replaceable class="parameter">count</replaceable>
</computeroutput></term>
<listitem>
<para>
Message returned if items are successfully deleted. The
<replaceable class="parameter">count</replaceable> is the number
of rows deleted.
</para>
<para>
If <replaceable class="parameter">count</replaceable> is 0,
no rows were deleted.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-DELETE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-04-15</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>DELETE</command> removes rows which satisfy the WHERE <command>DELETE</command> deletes rows that satisfy the
clause from the specified table. <literal>WHERE</literal> clause from the specified table. If the
<literal>WHERE</literal> clause is absent, the effect is to delete
all rows in the table. The result is a valid, but empty table.
</para> </para>
<para>
If the <firstterm>condition</firstterm> (WHERE clause) is absent,
the effect is to delete all rows in the table.
The result is a valid, but empty table.
<tip> <tip>
<para> <para>
<xref linkend="sql-truncate" endterm="sql-truncate-title"> is a <xref linkend="sql-truncate" endterm="sql-truncate-title"> is a
...@@ -114,39 +37,74 @@ DELETE <replaceable class="parameter">count</replaceable> ...@@ -114,39 +37,74 @@ DELETE <replaceable class="parameter">count</replaceable>
faster mechanism to remove all rows from a table. faster mechanism to remove all rows from a table.
</para> </para>
</tip> </tip>
</para>
<para> <para>
By default DELETE will delete tuples in the table specified By default, <command>DELETE</command> will delete rows in the
and all its sub-tables. If you wish to only update the specified table and all its subtables. If you wish to only delete
specific table mentioned, you should use the ONLY clause. from the specific table mentioned, you must use the
<literal>ONLY</literal> clause.
</para> </para>
<para> <para>
You must have write access to the table in order to modify You must have the <literal>DELETE</literal> privilege on the table
it, as well as read access to any table whose values are to delete from it, as well as the <literal>SELECT</literal>
read in the <replaceable class="parameter">condition</replaceable>. privilege to any table whose values are read in the <replaceable
class="parameter">condition</replaceable>.
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-DELETE-2"> <refsect1>
<title> <title>Parameters</title>
Usage
</title> <variablelist>
<varlistentry>
<term><replaceable class="parameter">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an existing table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">condition</replaceable></term>
<listitem>
<para>
A value expression that returns a value of type
<type>boolean</type> that determines the rows which are to be
deleted.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>DELETE <replaceable class="parameter">count</replaceable></computeroutput></term>
<listitem>
<para>
Message returned if rows are successfully deleted. The
<replaceable class="parameter">count</replaceable> is the number
of rows deleted. If <replaceable
class="parameter">count</replaceable> is 0, no rows were
deleted.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<para> <para>
Remove all films but musicals: Delete all films but musicals:
<programlisting> <programlisting>
DELETE FROM films WHERE kind &lt;&gt; 'Musical'; DELETE FROM films WHERE kind &lt;&gt; 'Musical';
SELECT * FROM films;
<computeroutput>
code | title | did | date_prod | kind | len
-------+---------------------------+-----+------------+---------+-------
UA501 | West Side Story | 105 | 1961-01-03 | Musical | 02:32
TC901 | The King and I | 109 | 1956-08-11 | Musical | 02:13
WD101 | Bed Knobs and Broomsticks | 111 | | Musical | 01:57
(3 rows)
</computeroutput>
</programlisting> </programlisting>
</para> </para>
...@@ -154,42 +112,16 @@ SELECT * FROM films; ...@@ -154,42 +112,16 @@ SELECT * FROM films;
Clear the table <literal>films</literal>: Clear the table <literal>films</literal>:
<programlisting> <programlisting>
DELETE FROM films; DELETE FROM films;
SELECT * FROM films;
<computeroutput>
code | title | did | date_prod | kind | len
------+-------+-----+-----------+------+-----
(0 rows)
</computeroutput>
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-DELETE-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title> <para>
This command conforms to the SQL standard.
<refsect2 id="R2-SQL-DELETE-4"> </para>
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
SQL92
</title>
<para>
<acronym>SQL92</acronym> allows a positioned DELETE statement:
<synopsis>
DELETE FROM <replaceable class="parameter">table</replaceable> WHERE
CURRENT OF <replaceable class="parameter">cursor</replaceable>
</synopsis>
where <replaceable class="parameter">cursor</replaceable>
identifies an open cursor.
Interactive cursors in <productname>PostgreSQL</productname> are read-only.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/end.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/end.sgml,v 1.8 2002/04/21 19:02:39 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/end.sgml,v 1.9 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,145 +8,99 @@ PostgreSQL documentation ...@@ -8,145 +8,99 @@ PostgreSQL documentation
<refentrytitle id="SQL-END-TITLE">END</refentrytitle> <refentrytitle id="SQL-END-TITLE">END</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>END</refname>
END <refpurpose>commit the current transaction</refpurpose>
</refname> </refnamediv>
<refpurpose>
commit the current transaction
</refpurpose>
</refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
END [ WORK | TRANSACTION ] END [ WORK | TRANSACTION ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-END-1">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term>WORK</term>
<term>TRANSACTION</term>
<listitem>
<para>
Optional keywords. They have no effect.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-END-2">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
COMMIT
</computeroutput></term>
<listitem>
<para>
Message returned if the transaction is successfully committed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
WARNING: COMMIT: no transaction in progress
</computeroutput></term>
<listitem>
<para>
If there is no transaction in progress.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-END-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-08</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>END</command> is a <productname>PostgreSQL</productname> <command>END</command> commits the current transaction. All changes
extension, and is a synonym for the SQL92-compatible made by the transaction become visible to others and are guaranteed
<xref linkend="sql-commit" endterm="sql-commit-title">. to be durable if a crash occurs. It is a PostgreSQL extension that
is equivalent to <xref linkend="sql-commit"
endterm="sql-commit-title">.
</para> </para>
</refsect1>
<refsect2 id="R2-SQL-END-3"> <refsect1>
<refsect2info> <title>Parameters</title>
<date>1998-09-08</date>
</refsect2info>
<title>
Notes
</title>
<para>
The keywords WORK and TRANSACTION are noise and can be omitted.
</para>
<para> <variablelist>
Use <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE"> <varlistentry>
to abort a transaction. <term><literal>WORK</literal></term>
</para> <term><literal>TRANSACTION</literal></term>
</refsect2> <listitem>
<para>
Optional key words. They have no effect.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1> </refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>COMMIT</computeroutput></term>
<listitem>
<para>
Message returned if the transaction was successfully committed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>WARNING: COMMIT: no transaction in progress</computeroutput></term>
<listitem>
<para>
Message if there is no transaction in progress.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<refsect1 id="R1-SQL-END-2">
<title>
Usage
</title>
<para> <para>
To make all changes permanent: Use <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE"> to
abort a transaction.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<programlisting> <para>
END WORK; To commit the current transaction and make all changes permanent:
</programlisting> <programlisting>
END;
</programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-END-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-END-4">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
SQL92
</title>
<para> <refsect1>
<command>END</command> is a <productname>PostgreSQL</productname> <title>Compatibility</title>
extension which provides functionality equivalent to
<xref linkend="sql-commit" endterm="sql-commit-title">. <para>
</para> <command>END</command> is a <productname>PostgreSQL</productname>
</refsect2> extension that provides functionality equivalent to <xref
linkend="sql-commit" endterm="sql-commit-title">, which is
specified in the SQL standard.
</para>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/execute.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/execute.sgml,v 1.3 2003/02/02 23:46:37 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/execute.sgml,v 1.4 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,128 +8,100 @@ PostgreSQL documentation ...@@ -8,128 +8,100 @@ PostgreSQL documentation
<refentrytitle id="sql-execute-title">EXECUTE</refentrytitle> <refentrytitle id="sql-execute-title">EXECUTE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>EXECUTE</refname>
EXECUTE <refpurpose>execute a prepared statement</refpurpose>
</refname>
<refpurpose>
execute a prepared query
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2002-08-12</date>
</refsynopsisdivinfo>
<synopsis>
EXECUTE <replaceable class="PARAMETER">plan_name</replaceable> [ (<replaceable class="PARAMETER">parameter</replaceable> [, ...] ) ] [ INTO [ TEMPORARY | TEMP ] <replaceable class="PARAMETER">table</replaceable> ]
</synopsis>
<refsect2 id="R2-SQL-EXECUTE-1">
<refsect2info>
<date>2002-08-12</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">plan_name</replaceable></term>
<listitem>
<para>
The name of the prepared query to execute.
</para>
</listitem>
</varlistentry>
<varlistentry> <refsynopsisdiv>
<term><replaceable class="PARAMETER">parameter</replaceable></term> <synopsis>
<listitem> EXECUTE <replaceable class="PARAMETER">plan_name</replaceable> [ (<replaceable class="PARAMETER">parameter</replaceable> [, ...] ) ] [ INTO [ TEMPORARY | TEMP ] <replaceable class="PARAMETER">table</replaceable> ]
<para> </synopsis>
The actual value of a parameter to the prepared query. This
must be an expression yielding a value of a type compatible
with the data-type specified for this parameter position in
the <command>PREPARE</command> statement that created the
prepared query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name of the table in which to store the results of
executing the query (if it is a <command>SELECT</command>). If
no table is specified, the results are returned to the client
(as normal).
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-EXECUTE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2002-08-12</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>EXECUTE</command> is used to execute a previously prepared <command>EXECUTE</command> is used to execute a previously prepared
query. Since prepared queries only exist for the duration of a statement. Since prepared statements only exist for the duration of a
session, the prepared query must have been created by a session, the prepared statement must have been created by a
<command>PREPARE</command> statement executed earlier in the <command>PREPARE</command> statement executed earlier in the
current session. current session.
</para> </para>
<para> <para>
If the <command>PREPARE</command> statement that created the query If the <command>PREPARE</command> statement that created the statement
specified some parameters, a compatible set of parameters must be specified some parameters, a compatible set of parameters must be
passed to the <command>EXECUTE</command> statement, or else an passed to the <command>EXECUTE</command> statement, or else an
error is raised. Note that (unlike functions) prepared queries are error is raised. Note that (unlike functions) prepared statements are
not overloaded based on the type or number of their parameters: the not overloaded based on the type or number of their parameters; the
name of a prepared query must be unique within a database session. name of a prepared statement must be unique within a database session.
</para> </para>
<para> <para>
Like <command>SELECT INTO</command>, <command>EXECUTE</command> can Like <command>SELECT INTO</command>, <command>EXECUTE</command> can
store the results of executing the query into a newly-created store the results of executing a query into a newly-created
table, by specifying an INTO clause. For more information on this behavior, table, by specifying an <literal>INTO</> clause. For more information on this behavior,
see <xref linkend="sql-selectinto" endterm="sql-selectinto-title">. see <xref linkend="sql-selectinto" endterm="sql-selectinto-title">.
</para> </para>
<para> <para>
For more information on the creation and usage of prepared queries, For more information on the creation and usage of prepared statements,
see <xref linkend="sql-prepare" endterm="sql-prepare-title">. see <xref linkend="sql-prepare" endterm="sql-prepare-title">.
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-EXECUTE-2"> <refsect1>
<title> <title>Parameters</title>
Compatibility
</title> <variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">plan_name</replaceable></term>
<listitem>
<para>
The name of the prepared statement to execute.
</para>
</listitem>
</varlistentry>
<refsect2 id="R2-SQL-EXECUTE-2"> <varlistentry>
<refsect2info> <term><replaceable class="PARAMETER">parameter</replaceable></term>
<date>2002-08-12</date> <listitem>
</refsect2info> <para>
<title> The actual value of a parameter to the prepared statement. This
SQL92 must be an expression yielding a value of a type compatible with
</title> the data type specified for this parameter position in the
<para> <command>PREPARE</command> command that created the prepared
SQL92 includes an <command>EXECUTE</command> statement, but it is statement.
only for use in embedded SQL clients. The </para>
<command>EXECUTE</command> statement implemented by </listitem>
<productname>PostgreSQL</productname> also uses a somewhat </varlistentry>
different syntax.
</para> <varlistentry>
</refsect2> <term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name of the table in which to store the results of executing
the statement (if it is a <command>SELECT</command>). If no
table is specified, the results are returned to the client (as
normal).
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Compatibility</title>
<para>
The SQL standard includes an <command>EXECUTE</command> statement,
but it is only for use in embedded SQL. This version of the
<command>EXECUTE</command> statement also uses a somewhat different
syntax.
</para>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/explain.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.25 2003/03/25 16:15:41 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.26 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,255 +8,212 @@ PostgreSQL documentation ...@@ -8,255 +8,212 @@ PostgreSQL documentation
<refentrytitle id="SQL-EXPLAIN-TITLE">EXPLAIN</refentrytitle> <refentrytitle id="SQL-EXPLAIN-TITLE">EXPLAIN</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>EXPLAIN</refname>
EXPLAIN <refpurpose>show the execution plan of a statement</refpurpose>
</refname>
<refpurpose>
show the execution plan of a statement
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date> EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
</refsynopsisdivinfo> </synopsis>
<synopsis>
EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="PARAMETER">query</replaceable>
</synopsis>
<refsect2 id="R2-SQL-EXPLAIN-1">
<refsect2info>
<date>1998-09-01</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term>ANALYZE</term>
<listitem>
<para>
Flag to carry out the query and show actual run times.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>VERBOSE</term>
<listitem>
<para>
Flag to show detailed query plan dump.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">query</replaceable></term>
<listitem>
<para>
Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>,
<command>DELETE</>, <command>EXECUTE</>,
or <command>DECLARE CURSOR</> query.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-EXPLAIN-2">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term>Query plan</term>
<listitem>
<para>
Explicit query plan from the <productname>PostgreSQL</productname>
planner.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<note>
<para>
Prior to <productname>PostgreSQL</productname> 7.3, the query
plan was emitted in the form of a <literal>NOTICE</literal>
message. Now it appears as a query result (formatted like a
table with a single text column).
</para>
</note>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-EXPLAIN-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-04-15</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
This command displays the execution plan that the This command displays the execution plan that the
<productname>PostgreSQL</productname> planner generates for the <productname>PostgreSQL</productname> planner generates for the
supplied query. The execution plan shows how the table(s) supplied statenebt. The execution plan shows how the table(s)
referenced by the query will be scanned---by plain sequential scan, referenced by the statement will be scanned---by plain sequential scan,
index scan, etc.---and if multiple tables are referenced, what join index scan, etc.---and if multiple tables are referenced, what join
algorithms will be used to bring together the required tuples from algorithms will be used to bring together the required row from
each input table. each input table.
</para> </para>
<para> <para>
The most critical part of the display is the estimated query execution The most critical part of the display is the estimated statement execution
cost, which is the planner's guess at how long it will take to run the cost, which is the planner's guess at how long it will take to run the
query (measured in units of disk page fetches). Actually two numbers statement (measured in units of disk page fetches). Actually two numbers
are shown: the start-up time before the first tuple can be returned, and are shown: the start-up time before the first row can be returned, and
the total time to return all the tuples. For most queries the total time the total time to return all the rows. For most queries the total time
is what matters, but in contexts such as an EXISTS sub-query the planner is what matters, but in contexts such as a subquery in <literal>EXISTS</literal>, the planner
will choose the smallest start-up time instead of the smallest total time will choose the smallest start-up time instead of the smallest total time
(since the executor will stop after getting one tuple, anyway). (since the executor will stop after getting one row, anyway).
Also, if you limit the number of tuples to return with a LIMIT clause, Also, if you limit the number of rows to return with a <literal>LIMIT</literal> clause,
the planner makes an appropriate interpolation between the endpoint the planner makes an appropriate interpolation between the endpoint
costs to estimate which plan is really the cheapest. costs to estimate which plan is really the cheapest.
</para> </para>
<note>
<para>
In order to allow the <productname>PostgreSQL</productname> query
planner to make reasonably informed decisions when optimizing
queries, the <command>ANALYZE</command> statement should be run
to record statistics about the distribution of data within the
table. If you have not done this (or if the statistical distribution
of the data in the table has changed significantly since the last
time <command>ANALYZE</command> was run), the estimated costs
are unlikely to conform to the real properties of the query,
and consequently an inferior query plan may be chosen.
</para>
</note>
<para> <para>
The ANALYZE option causes the query to be actually executed, not only The <literal>ANALYZE</literal> option causes the statement to be actually executed, not only
planned. The total elapsed time expended within each plan node (in planned. The total elapsed time expended within each plan node (in
milliseconds) and total number of rows it actually returned are added to milliseconds) and total number of rows it actually returned are added to
the display. This is useful for seeing whether the planner's estimates the display. This is useful for seeing whether the planner's estimates
are close to reality. are close to reality.
</para> </para>
<caution> <important>
<para> <para>
Keep in mind that the query is actually executed when ANALYZE is used. Keep in mind that the statement is actually executed when
Although <command>EXPLAIN</command> will discard any output that a SELECT <literal>ANALYZE</literal> is used. Although
would return, <command>EXPLAIN</command> will discard any output that a
other side-effects of the query will happen as usual. <command>SELECT</command> would return, other side effects of the
If you wish to use <command>EXPLAIN ANALYZE</command> on an INSERT, statement will happen as usual. If you wish to use
UPDATE, DELETE, or EXECUTE query without letting the query affect your <command>EXPLAIN ANALYZE</command> on an
data, use this approach: <command>INSERT</command>, <command>UPDATE</command>,
<programlisting> <command>DELETE</command>, or <command>EXECUTE</command> statement
without letting the command affect your data, use this approach:
<programlisting>
BEGIN; BEGIN;
EXPLAIN ANALYZE ...; EXPLAIN ANALYZE ...;
ROLLBACK; ROLLBACK;
</programlisting> </programlisting>
</para> </para>
</caution> </important>
</refsect1>
<refsect1>
<title>Parameter</title>
<variablelist>
<varlistentry>
<term><literal>ANALYZE</literal></term>
<listitem>
<para>
Carry out the command and show the actual run times.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>VERBOSE</literal></term>
<listitem>
<para>
Show the full internal representation of the plan tree, rather
than just a summary. Usually this option is only useful for
debugging <productname>PostgreSQL</productname>. The
<literal>VERBOSE</literal> output is either pretty-printed or
not, depending on the setting of the
<varname>explain_pretty_print</varname> configuration parameter.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">statement</replaceable></term>
<listitem>
<para>
Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>,
<command>DELETE</>, <command>EXECUTE</>, or <command>DECLARE</>
statement, whose execution plan you wish to see.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<para> <para>
The VERBOSE option emits the full internal representation of the plan tree, <command>EXPLAIN</command> prints the execution plan of the
rather than just a summary. specified statement from the <productname>PostgreSQL</productname>
Usually this option is only useful for debugging planner.
<productname>PostgreSQL</productname>. The VERBOSE dump is either
pretty-printed or not, depending on the setting of the
<option>EXPLAIN_PRETTY_PRINT</option> configuration parameter.
</para> </para>
</refsect1>
<refsect2 id="R2-SQL-EXPLAIN-3"> <refsect1>
<refsect2info> <title>Notes</title>
<date>1998-04-15</date>
</refsect2info> <para>
<title> There is only sparse documentation on the optimizer's use of cost
Notes information in <productname>PostgreSQL</productname>. Refer to
</title> <xref linkend="using-explain"> for more information.
<para> </para>
There is only sparse documentation on the optimizer's use of cost
information in <productname>PostgreSQL</productname>. <para>
Refer to <xref linkend="using-explain"> for more information. In order to allow the <productname>PostgreSQL</productname> query
</para> planner to make reasonably informed decisions when optimizing
</refsect2> queries, the <command>ANALYZE</command> statement should be run to
record statistics about the distribution of data within the
table. If you have not done this (or if the statistical
distribution of the data in the table has changed significantly
since the last time <command>ANALYZE</command> was run), the
estimated costs are unlikely to conform to the real properties of
the query, and consequently an inferior query plan may be chosen.
</para>
<para>
Prior to <productname>PostgreSQL</productname> 7.3, the plan was
emitted in the form of a <literal>NOTICE</literal> message. Now it
appears as a query result (formatted like a table with a single
text column).
</para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-EXPLAIN-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
To show a query plan for a simple query on a table with a single To show the plan for a simple query on a table with a single
<type>int4</type> column and 10000 rows: <type>integer</type> column and 10000 rows:
<programlisting> <programlisting>
EXPLAIN SELECT * FROM foo; EXPLAIN SELECT * FROM foo;
<computeroutput>
QUERY PLAN QUERY PLAN
--------------------------------------------------------- ---------------------------------------------------------
Seq Scan on foo (cost=0.00..155.00 rows=10000 width=4) Seq Scan on foo (cost=0.00..155.00 rows=10000 width=4)
(1 row) (1 row)
</computeroutput> </programlisting>
</programlisting>
</para> </para>
<para> <para>
If there is an index and we use a query with an indexable WHERE condition, If there is an index and we use a query with an indexable
<command>EXPLAIN</command> will show a different plan: <literal>WHERE</literal> condition, <command>EXPLAIN</command>
might show a different plan:
<programlisting> <programlisting>
EXPLAIN SELECT * FROM foo WHERE i = 4; EXPLAIN SELECT * FROM foo WHERE i = 4;
<computeroutput>
QUERY PLAN QUERY PLAN
-------------------------------------------------------------- --------------------------------------------------------------
Index Scan using fi on foo (cost=0.00..5.98 rows=1 width=4) Index Scan using fi on foo (cost=0.00..5.98 rows=1 width=4)
Index Cond: (i = 4) Index Cond: (i = 4)
(2 rows) (2 rows)
</computeroutput> </programlisting>
</programlisting>
</para> </para>
<para> <para>
And here is an example of a query plan for a query And here is an example of a query plan for a query
using an aggregate function: using an aggregate function:
<programlisting> <programlisting>
EXPLAIN SELECT sum(i) FROM foo WHERE i &lt; 10; EXPLAIN SELECT sum(i) FROM foo WHERE i &lt; 10;
<computeroutput>
QUERY PLAN QUERY PLAN
--------------------------------------------------------------------- ---------------------------------------------------------------------
Aggregate (cost=23.93..23.93 rows=1 width=4) Aggregate (cost=23.93..23.93 rows=1 width=4)
-&gt; Index Scan using fi on foo (cost=0.00..23.92 rows=6 width=4) -&gt; Index Scan using fi on foo (cost=0.00..23.92 rows=6 width=4)
Index Cond: (i &lt; 10) Index Cond: (i &lt; 10)
(3 rows) (3 rows)
</computeroutput> </programlisting>
</programlisting>
</para> </para>
<para> <para>
Here is an example of using EXPLAIN EXECUTE to display the query Here is an example of using <command>EXPLAIN EXECUTE</command> to
plan for a prepared query: display the execution plan for a prepared query:
<programlisting> <programlisting>
PREPARE query(int, int) AS SELECT sum(bar) FROM test PREPARE query(int, int) AS SELECT sum(bar) FROM test
WHERE id &gt; $1 AND id &lt; $2 WHERE id &gt; $1 AND id &lt; $2
GROUP BY foo; GROUP BY foo;
EXPLAIN ANALYZE EXECUTE query(100, 200); EXPLAIN ANALYZE EXECUTE query(100, 200);
<computeroutput>
QUERY PLAN QUERY PLAN
------------------------------------------------------------------------------------------------------------------------- -------------------------------------------------------------------------------------------------------------------------
HashAggregate (cost=39.53..39.53 rows=1 width=8) (actual time=0.66..0.67 rows=7 loops=1) HashAggregate (cost=39.53..39.53 rows=1 width=8) (actual time=0.66..0.67 rows=7 loops=1)
...@@ -264,38 +221,28 @@ EXPLAIN ANALYZE EXECUTE query(100, 200); ...@@ -264,38 +221,28 @@ EXPLAIN ANALYZE EXECUTE query(100, 200);
Index Cond: ((id &gt; $1) AND (id &lt; $2)) Index Cond: ((id &gt; $1) AND (id &lt; $2))
Total runtime: 0.85 msec Total runtime: 0.85 msec
(4 rows) (4 rows)
</computeroutput> </programlisting>
</programlisting>
</para> </para>
<para> <para>
Note that the specific numbers shown, and even the selected query Of course, the specific numbers shown here depend on the actual
strategy, may vary between <productname>PostgreSQL</productname> contents of the tables involved. Also note that the numbers, and
releases due to planner improvements. In addition, the even the selected query strategy, may vary between
<command>ANALYZE</command> command uses random sampling to estimate <productname>PostgreSQL</productname> releases due to planner
data statistics; therefore, it is possible improvements. In addition, the <command>ANALYZE</command> command
for cost estimates to change after a fresh run of uses random sampling to estimate data statistics; therefore, it is
possible for cost estimates to change after a fresh run of
<command>ANALYZE</command>, even if the actual distribution of data <command>ANALYZE</command>, even if the actual distribution of data
in the table has not changed. in the table has not changed.
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-EXPLAIN-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title> <para>
There is no <command>EXPLAIN</command> statement defined in the SQL standard.
<refsect2 id="R2-SQL-EXPLAIN-4"> </para>
<refsect2info>
<date>1998-09-01</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>EXPLAIN</command> statement defined in SQL92.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/grant.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/grant.sgml,v 1.32 2003/01/23 23:38:53 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/grant.sgml,v 1.33 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -43,10 +43,10 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } ...@@ -43,10 +43,10 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
<title>Description</title> <title>Description</title>
<para> <para>
The <command>GRANT</command> command gives specific permissions on The <command>GRANT</command> command gives specific privileges on
an object (table, view, sequence, database, function, procedural language, an object (table, view, sequence, database, function, procedural language,
or schema) to or schema) to
one or more users or groups of users. These permissions are added one or more users or groups of users. These privileges are added
to those already granted, if any. to those already granted, if any.
</para> </para>
...@@ -55,18 +55,18 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } ...@@ -55,18 +55,18 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
privileges are to be granted to all users, including those that may privileges are to be granted to all users, including those that may
be created later. <literal>PUBLIC</literal> may be thought of as an be created later. <literal>PUBLIC</literal> may be thought of as an
implicitly defined group that always includes all users. implicitly defined group that always includes all users.
Note that any particular user will have the sum Any particular user will have the sum
of privileges granted directly to him, privileges granted to any group he of privileges granted directly to him, privileges granted to any group he
is presently a member of, and privileges granted to is presently a member of, and privileges granted to
<literal>PUBLIC</literal>. <literal>PUBLIC</literal>.
</para> </para>
<para> <para>
There is no need to grant privileges to the creator of an object, There is no need to grant privileges to the owner of an object (usually the user that created it),
as the creator has all privileges by default. (The creator could, as the owner has all privileges by default. (The owner could,
however, choose to revoke some of his own privileges for safety.) however, choose to revoke some of his own privileges for safety.)
Note that the right to drop an object, or to alter it in any way is The right to drop an object, or to alter it in any way is
not described by a grantable right; it is inherent in the creator, not described by a grantable right; it is inherent in the owner,
and cannot be granted or revoked. and cannot be granted or revoked.
</para> </para>
...@@ -84,7 +84,7 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } ...@@ -84,7 +84,7 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
<literal>TEMP</> table creation privilege for databases; <literal>TEMP</> table creation privilege for databases;
<literal>EXECUTE</> privilege for functions; and <literal>EXECUTE</> privilege for functions; and
<literal>USAGE</> privilege for languages. <literal>USAGE</> privilege for languages.
The object creator may of course revoke these privileges. (For maximum The object owner may of course revoke these privileges. (For maximum
security, issue the <command>REVOKE</> in the same transaction that security, issue the <command>REVOKE</> in the same transaction that
creates the object; then there is no window in which another user creates the object; then there is no window in which another user
may use the object.) may use the object.)
...@@ -252,7 +252,7 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } ...@@ -252,7 +252,7 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
</para> </para>
<para> <para>
It should be noted that database <firstterm>superusers</> can access It should be noted that database superusers can access
all objects regardless of object privilege settings. This all objects regardless of object privilege settings. This
is comparable to the rights of <literal>root</> in a Unix system. is comparable to the rights of <literal>root</> in a Unix system.
As with <literal>root</>, it's unwise to operate as a superuser As with <literal>root</>, it's unwise to operate as a superuser
...@@ -267,17 +267,18 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } ...@@ -267,17 +267,18 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
</para> </para>
<para> <para>
Use <xref linkend="app-psql">'s <command>\dp</command> command Use <xref linkend="app-psql">'s <command>\z</command> command
to obtain information about existing privileges, for example: to obtain information about existing privileges, for example:
<programlisting> <programlisting>
lusitania=> \dp mytable => \z mytable
Access privileges for database "lusitania" Access privileges for database "lusitania"
Schema | Table | Access privileges Schema | Table | Access privileges
--------+---------+--------------------------------------- --------+---------+---------------------------------------
public | mytable | {=r/postgres,miriam=arwdRxt/postgres,"group todos=arw/postgres"} public | mytable | {=r/postgres,miriam=arwdRxt/postgres,"group todos=arw/postgres"}
(1 row) (1 row)
</programlisting> </programlisting>
The entries shown by <command>\dp</command> are interpreted thus: The entries shown by <command>\z</command> are interpreted thus:
<programlisting> <programlisting>
=xxxx -- privileges granted to PUBLIC =xxxx -- privileges granted to PUBLIC
uname=xxxx -- privileges granted to a user uname=xxxx -- privileges granted to a user
...@@ -305,14 +306,14 @@ lusitania=> \dp mytable ...@@ -305,14 +306,14 @@ lusitania=> \dp mytable
<programlisting> <programlisting>
GRANT SELECT ON mytable TO PUBLIC; GRANT SELECT ON mytable TO PUBLIC;
GRANT SELECT,UPDATE,INSERT ON mytable TO GROUP todos; GRANT SELECT, UPDATE, INSERT ON mytable TO GROUP todos;
</programlisting> </programlisting>
</para> </para>
<para> <para>
If the <quote>Access privileges</> column is empty for a given object, If the <quote>Access privileges</> column is empty for a given object,
it means the object has default privileges (that is, its privileges field it means the object has default privileges (that is, its privileges columm
is NULL). Default privileges always include all privileges for the owner, is null). Default privileges always include all privileges for the owner,
and may include some privileges for <literal>PUBLIC</> depending on the and may include some privileges for <literal>PUBLIC</> depending on the
object type, as explained above. The first <command>GRANT</> or object type, as explained above. The first <command>GRANT</> or
<command>REVOKE</> on an object <command>REVOKE</> on an object
...@@ -325,7 +326,7 @@ will instantiate the default privileges (producing, for example, ...@@ -325,7 +326,7 @@ will instantiate the default privileges (producing, for example,
<title>Examples</title> <title>Examples</title>
<para> <para>
Grant insert privilege to all users on table films: Grant insert privilege to all users on table <literal>films</literal>:
<programlisting> <programlisting>
GRANT INSERT ON films TO PUBLIC; GRANT INSERT ON films TO PUBLIC;
...@@ -344,37 +345,35 @@ GRANT ALL PRIVILEGES ON kinds TO manuel; ...@@ -344,37 +345,35 @@ GRANT ALL PRIVILEGES ON kinds TO manuel;
<refsect1 id="sql-grant-compatibility"> <refsect1 id="sql-grant-compatibility">
<title>Compatibility</title> <title>Compatibility</title>
<refsect2>
<title>SQL92</title>
<para> <para>
The <literal>PRIVILEGES</literal> key word in <literal>ALL According to the SQL standard, the <literal>PRIVILEGES</literal>
PRIVILEGES</literal> is required. <acronym>SQL</acronym> does not key word in <literal>ALL PRIVILEGES</literal> is required. The
support setting the privileges on more than one table per command. SQL standard does not support setting the privileges on more than
one object per command.
</para> </para>
<para> <para>
The <acronym>SQL</acronym> syntax for <literal>GRANT</literal> The SQL standard allows setting privileges for individual columns
allows setting privileges for individual columns within a table: within a table:
<synopsis> <synopsis>
GRANT <replaceable class="PARAMETER">privilege</replaceable> [, ...] GRANT <replaceable class="PARAMETER">privileges</replaceable>
ON <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ] [, ...] ON <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ] [, ...]
TO { PUBLIC | <replaceable class="PARAMETER">username</replaceable> [, ...] } [ WITH GRANT OPTION ] TO { PUBLIC | <replaceable class="PARAMETER">username</replaceable> [, ...] } [ WITH GRANT OPTION ]
</synopsis> </synopsis>
</para> </para>
<para> <para>
<acronym>SQL</acronym> allows to grant the USAGE privilege on The SQL standard provides for a <literal>USAGE</literal> privilege
other kinds of objects: CHARACTER SET, COLLATION, TRANSLATION, DOMAIN. on other kinds of objects: character sets, collations,
translations, domains.
</para> </para>
<para> <para>
The TRIGGER privilege was introduced in SQL99. The RULE privilege The <literal>RULE</literal> privilege, and privileges on
is a PostgreSQL extension. databases, schemas, languages, and sequences are PostgreSQL
extensions.
</para> </para>
</refsect2>
</refsect1> </refsect1>
......
doc/src/sgml/ref/insert.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/insert.sgml,v 1.21 2003/03/25 16:15:42 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/insert.sgml,v 1.22 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,246 +8,207 @@ PostgreSQL documentation ...@@ -8,246 +8,207 @@ PostgreSQL documentation
<refentrytitle id="SQL-INSERT-TITLE">INSERT</refentrytitle> <refentrytitle id="SQL-INSERT-TITLE">INSERT</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>INSERT</refname>
INSERT <refpurpose>create new rows in a table</refpurpose>
</refname>
<refpurpose>
create new rows in a table
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2000-08-08</date>
</refsynopsisdivinfo>
<synopsis>
INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ] INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ]
{ DEFAULT VALUES | VALUES ( { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } [, ...] ) | SELECT <replaceable class="PARAMETER">query</replaceable> } { DEFAULT VALUES | VALUES ( { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } [, ...] ) | <replaceable class="PARAMETER">query</replaceable> }
</synopsis> </synopsis>
<refsect2 id="R2-SQL-INSERT-1">
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an existing table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">column</replaceable></term>
<listitem>
<para>
The name of a column in <replaceable class="PARAMETER">table</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEFAULT VALUES</term>
<listitem>
<para>
All columns will be filled by null values or by values specified
when the table was created using <literal>DEFAULT</> clauses.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">expression</replaceable></term>
<listitem>
<para>
A valid expression or value to assign to <replaceable
class="PARAMETER">column</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">DEFAULT</replaceable></term>
<listitem>
<para>
This column will be filled in by the column DEFAULT clause, or NULL if
a default is not available.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">query</replaceable></term>
<listitem>
<para>
A valid query. Refer to the SELECT statement for a further description
of valid arguments.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-INSERT-2">
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
INSERT <replaceable>oid</replaceable> 1
</computeroutput></term>
<listitem>
<para>
Message returned if only one row was inserted.
<returnvalue><replaceable>oid</replaceable></returnvalue>
is the numeric <acronym>OID</acronym> of the inserted row.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
INSERT 0 <replaceable>#</replaceable>
</computeroutput></term>
<listitem>
<para>
Message returned if more than one rows were inserted.
<returnvalue><replaceable>#</replaceable></returnvalue>
is the number of rows inserted.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-INSERT-1"> <refsect1>
<title> <title>Description</title>
Description
</title>
<para> <para>
<command>INSERT</command> allows one to insert new rows into a <command>INSERT</command> allows one to insert new rows into a
table. One can insert table. One can insert
a single row at a time or several rows as a result of a query. a single row at a time or several rows as a result of a query.
The columns in the target list may be listed in any order.
</para> </para>
<para> <para>
The columns in the target list may be listed in any order.
Each column not present in the target list will be inserted Each column not present in the target list will be inserted
using a default value, either a declared DEFAULT value using a default value, either a declared default value
or NULL. <productname>PostgreSQL</productname> will reject the new or null.
column if a NULL is inserted into a column declared NOT NULL.
</para> </para>
<para> <para>
If the expression for each column If the expression for each column is not of the correct data type,
is not of the correct data type, automatic type coercion will be automatic type conversion will be attempted.
attempted.
</para> </para>
<para> <para>
You must have insert privilege to a table in order to append You must have <literal>INSERT</literal> privilege to a table in
to it, as well as select privilege on any table specified order to insert into it. If you use the <replaceable
in a WHERE clause. class="PARAMETER">query</replaceable> clause to insert rows from a
query, you also need to have <literal>SELECT</literal> privilege on
any table used in the query.
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-INSERT-2"> <refsect1>
<title> <title>Parameters</title>
Usage
</title> <variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an existing table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">column</replaceable></term>
<listitem>
<para>
The name of a column in <replaceable class="PARAMETER">table</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>DEFAULT VALUES</literal></term>
<listitem>
<para>
All columns will be filled their default values.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">expression</replaceable></term>
<listitem>
<para>
An expression or value to assign to <replaceable
class="PARAMETER">column</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>DEFAULT</literal></term>
<listitem>
<para>
This column will be filled with its default value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">query</replaceable></term>
<listitem>
<para>
A query (<command>SELECT</command> statement) that supplies the
rows to be inserted. Refer to the <command>SELECT</command>
statement for a description of the syntax.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>INSERT <replaceable>oid</replaceable> 1</computeroutput></term>
<listitem>
<para>
Message returned if only one row was inserted.
<returnvalue><replaceable>oid</replaceable></returnvalue> is the
<acronym>OID</acronym> of the inserted row.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>INSERT 0 <replaceable>count</replaceable></computeroutput></term>
<listitem>
<para>
Message returned if more than one rows were inserted.
<replaceable>count</replaceable> is the number of rows inserted.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<para> <para>
Insert a single row into table <literal>films</literal>: Insert a single row into table <literal>films</literal>:
<programlisting> <programlisting>
INSERT INTO films VALUES INSERT INTO films VALUES
('UA502','Bananas',105,'1971-07-13','Comedy',INTERVAL '82 minute'); ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes');
</programlisting> </programlisting>
</para> </para>
<para> <para>
In this second example the last column <literal>len</literal> is In this second example, the last column <literal>len</literal> is
omitted and therefore it will have the default value of NULL: omitted and therefore it will have the default value of null:
<programlisting> <programlisting>
INSERT INTO films (code, title, did, date_prod, kind) INSERT INTO films (code, title, did, date_prod, kind)
VALUES ('T_601', 'Yojimbo', 106, DATE '1961-06-16', 'Drama'); VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');
</programlisting> </programlisting>
</para> </para>
<para> <para>
In the third example, we use the DEFAULT values for the date columns The third example uses the <literal>DEFAULT</literal> clause for
rather than specifying an entry. the date columns rather than specifying a value:
<programlisting> <programlisting>
INSERT INTO films VALUES INSERT INTO films VALUES
('UA502','Bananas',105,DEFAULT,'Comedy',INTERVAL '82 minute'); ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes');
INSERT INTO films (code, title, did, date_prod, kind) INSERT INTO films (code, title, did, date_prod, kind)
VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama'); VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama');
</programlisting> </programlisting>
</para>
<para>
Insert a single row into table distributors; note that
only column <literal>name</literal> is specified, so the omitted
column <literal>did</literal> will be assigned its default value:
<programlisting>
INSERT INTO distributors (name) VALUES ('British Lion');
</programlisting>
</para> </para>
<para> <para>
Insert several rows into table films from table <literal>tmp</literal>: This examples inserts several rows into table
<literal>films</literal> from table <literal>tmp</literal>:
<programlisting> <programlisting>
INSERT INTO films SELECT * FROM tmp; INSERT INTO films SELECT * FROM tmp;
</programlisting> </programlisting>
</para> </para>
<para> <para>
Insert into arrays: This example inserts into array columns:
<programlisting> <programlisting>
-- Create an empty 3x3 gameboard for noughts-and-crosses -- Create an empty 3x3 gameboard for noughts-and-crosses
-- (all of these queries create the same board attribute) -- (all of these commands create the same board)
INSERT INTO tictactoe (game, board[1:3][1:3]) INSERT INTO tictactoe (game, board[1:3][1:3])
VALUES (1,'{{"","",""},{},{"",""}}'); VALUES (1,'{{"","",""},{},{"",""}}');
INSERT INTO tictactoe (game, board[3][3]) INSERT INTO tictactoe (game, board[3][3])
VALUES (2,'{}'); VALUES (2,'{}');
INSERT INTO tictactoe (game, board) INSERT INTO tictactoe (game, board)
VALUES (3,'{{,,},{,,},{,,}}'); VALUES (3,'{{,,},{,,},{,,}}');
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-INSERT-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title> <para>
<command>INSERT</command> conforms fully to the SQL standard.
<refsect2 id="R2-SQL-INSERT-4"> Possible limitations of the <replaceable
<title> class="PARAMETER">query</replaceable> clause are documented under
SQL92 <xref linkend="sql-select" endterm="sql-select-title">.
</title> </para>
<para>
<command>INSERT</command> is fully compatible with <acronym>SQL92</acronym>.
Possible limitations in features of the
<replaceable class="PARAMETER">query</replaceable>
clause are documented for
<xref linkend="sql-select" endterm="sql-select-title">.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/listen.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/listen.sgml,v 1.15 2002/09/21 18:32:54 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/listen.sgml,v 1.16 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,121 +8,54 @@ PostgreSQL documentation ...@@ -8,121 +8,54 @@ PostgreSQL documentation
<refentrytitle id="SQL-LISTEN-TITLE">LISTEN</refentrytitle> <refentrytitle id="SQL-LISTEN-TITLE">LISTEN</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>LISTEN</refname>
LISTEN <refpurpose>listen for a notification</refpurpose>
</refname>
<refpurpose>
listen for a notification
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
LISTEN <replaceable class="PARAMETER">name</replaceable> LISTEN <replaceable class="PARAMETER">name</replaceable>
</synopsis> </synopsis>
<refsect2 id="R2-SQL-LISTEN-1">
<refsect2info>
<date>1998-10-07</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
Name of notify condition.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-LISTEN-2">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
LISTEN
</computeroutput></term>
<listitem>
<para>
Message returned upon successful completion of registration.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
WARNING: Async_Listen: We are already listening on <replaceable class="PARAMETER">name</replaceable>
</computeroutput></term>
<listitem>
<para>
If this backend is already registered for that notify condition.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-LISTEN-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-10-07</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>LISTEN</command> registers the current <command>LISTEN</command> registers the current session as a
<productname>PostgreSQL</productname> backend as a listener on the notification condition <replaceable
listener on the notify condition class="PARAMETER">name</replaceable>.
<replaceable class="PARAMETER">name</replaceable>.
</para> </para>
<para> <para>
Whenever the command Whenever the command <command>NOTIFY <replaceable
<command>NOTIFY <replaceable class="PARAMETER">name</replaceable></command> class="PARAMETER">name</replaceable></command> is invoked, either
is invoked, either by this backend or another one connected to by this session or another one connected to the same database, all
the same database, all the backends currently listening on that notify the sessions currently listening on that notification condition are
condition are notified, and each will in turn notify its connected notified, and each will in turn notify its connected client
frontend application. See the discussion of <command>NOTIFY</command> application. See the discussion of <command>NOTIFY</command> for
for more information. more information.
</para> </para>
<para> <para>
A backend can be unregistered for a given notify condition with the A session can be unregistered for a given notify condition with the
<command>UNLISTEN</command> command. Also, a backend's listen registrations <command>UNLISTEN</command> command. A session's listen
are automatically cleared when the backend process exits. registrations are automatically cleared when the session ends.
</para> </para>
<para> <para>
The method a frontend application must use to detect notify events depends on The method a client application must use to detect notification events depends on
which <productname>PostgreSQL</productname> application programming interface it which <productname>PostgreSQL</productname> application programming interface it
uses. With the <application>libpq</> library, the application issues uses. With the <application>libpq</> library, the application issues
<command>LISTEN</command> as an ordinary SQL command, and then must <command>LISTEN</command> as an ordinary SQL command, and then must
periodically call the routine <function>PQnotifies</function> to find out periodically call the function <function>PQnotifies</function> to find out
whether any notify events have been received. Other interfaces such as whether any notification events have been received. Other interfaces such as
<application>libpgtcl</> provide higher-level methods for handling notify events; indeed, <application>libpgtcl</> provide higher-level methods for handling notify events; indeed,
with <application>libpgtcl</> the application programmer should not even issue with <application>libpgtcl</> the application programmer should not even issue
<command>LISTEN</command> or <command>UNLISTEN</command> directly. See the <command>LISTEN</command> or <command>UNLISTEN</command> directly. See the
documentation for the library you are using for more details. documentation for the interface you are using for more details.
</para> </para>
<para> <para>
...@@ -131,64 +64,67 @@ WARNING: Async_Listen: We are already listening on <replaceable class="PARAMETE ...@@ -131,64 +64,67 @@ WARNING: Async_Listen: We are already listening on <replaceable class="PARAMETE
discussion of the use of <command>LISTEN</command> and discussion of the use of <command>LISTEN</command> and
<command>NOTIFY</command>. <command>NOTIFY</command>.
</para> </para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
Name of a notify condition (any identifier).
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect2 id="R2-SQL-LISTEN-3"> <refsect1>
<refsect2info> <title>Diagnostics</title>
<date>1998-10-07</date>
</refsect2info> <variablelist>
<title> <varlistentry>
Notes <term><computeroutput>LISTEN</computeroutput></term>
</title> <listitem>
<para>
<para> Message returned upon successful completion of registration.
<replaceable class="PARAMETER">name</replaceable> </para>
can be any string valid as a name; </listitem>
it need not correspond to the name of any actual table. If </varlistentry>
<replaceable class="PARAMETER">notifyname</replaceable>
is enclosed in double-quotes, it need not even be a syntactically <varlistentry>
valid name, but can be any string up to 63 characters long. <term><computeroutput>WARNING: Async_Listen: We are already listening on <replaceable class="PARAMETER">name</replaceable></computeroutput></term>
</para> <listitem>
<para> <para>
In some previous releases of Message returned if this session is already registered for that notification condition.
<productname>PostgreSQL</productname>, </para>
<replaceable class="PARAMETER">name</replaceable> </listitem>
had to be enclosed in double-quotes when it did not correspond to any existing </varlistentry>
table name, even if syntactically valid as a name. That is no longer required. </variablelist>
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-LISTEN-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
Configure and execute a listen/notify sequence from <application>psql</application>: Configure and execute a listen/notify sequence from <application>psql</application>:
<programlisting> <programlisting>
LISTEN virtual; LISTEN virtual;
NOTIFY virtual; NOTIFY virtual;
Asynchronous NOTIFY 'virtual' from backend with pid '8448' received. Asynchronous NOTIFY 'virtual' from backend with pid '8448' received.
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-LISTEN-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title> <para>
There is no <command>LISTEN</command> statement in the SQL
<refsect2 id="R2-SQL-LISTEN-4"> standard.
<refsect2info> </para>
<date>1998-09-01</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>LISTEN</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/load.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/load.sgml,v 1.16 2003/03/25 16:15:42 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/load.sgml,v 1.17 2003/04/26 23:56:51 petere Exp $
--> -->
<refentry id="SQL-LOAD"> <refentry id="SQL-LOAD">
...@@ -23,11 +23,11 @@ LOAD '<replaceable class="PARAMETER">filename</replaceable>' ...@@ -23,11 +23,11 @@ LOAD '<replaceable class="PARAMETER">filename</replaceable>'
<title>Description</title> <title>Description</title>
<para> <para>
Loads a shared library file into the <productname>PostgreSQL</> This command loads a shared library file into the <productname>PostgreSQL</>
backend's address space. If the file had been loaded previously, server's address space. If the file had been loaded previously,
it is first unloaded. This command is primarily useful to unload it is first unloaded. This command is primarily useful to unload
and reload a shared library file that has been changed since the and reload a shared library file that has been changed since the
backend first loaded it. To make use of the shared library, server first loaded it. To make use of the shared library,
function(s) in it need to be declared using the <xref function(s) in it need to be declared using the <xref
linkend="sql-createfunction" endterm="sql-createfunction-title"> linkend="sql-createfunction" endterm="sql-createfunction-title">
command. command.
......
doc/src/sgml/ref/lock.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/lock.sgml,v 1.34 2002/09/21 18:32:54 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/lock.sgml,v 1.35 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,251 +8,25 @@ PostgreSQL documentation ...@@ -8,251 +8,25 @@ PostgreSQL documentation
<refentrytitle id="sql-lock-title">LOCK</refentrytitle> <refentrytitle id="sql-lock-title">LOCK</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>LOCK</refname>
LOCK <refpurpose>lock a table</refpurpose>
</refname>
<refpurpose>
explicitly lock a table
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2001-07-09</date> LOCK [ TABLE ] <replaceable class="PARAMETER">name</replaceable> [, ...] [ IN <replaceable class="PARAMETER">lockmode</replaceable> MODE ]
</refsynopsisdivinfo>
<synopsis>
LOCK [ TABLE ] <replaceable class="PARAMETER">name</replaceable> [, ...]
LOCK [ TABLE ] <replaceable class="PARAMETER">name</replaceable> [, ...] IN <replaceable class="PARAMETER">lockmode</replaceable> MODE
where <replaceable class="PARAMETER">lockmode</replaceable> is one of: where <replaceable class="PARAMETER">lockmode</replaceable> is one of:
ACCESS SHARE | ROW SHARE | ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE | ACCESS SHARE | ROW SHARE | ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE
SHARE | SHARE ROW EXCLUSIVE | EXCLUSIVE | ACCESS EXCLUSIVE | SHARE | SHARE ROW EXCLUSIVE | EXCLUSIVE | ACCESS EXCLUSIVE
</synopsis> </synopsis>
<refsect2 id="R2-SQL-LOCK-1">
<refsect2info>
<date>1999-06-09</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 lock.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ACCESS SHARE MODE</term>
<listitem>
<para>
This is the least restrictive lock mode. It conflicts only with
ACCESS EXCLUSIVE mode. It is used to protect a table from being
modified by concurrent <command>ALTER TABLE</command>,
<command>DROP TABLE</command> and <command>VACUUM FULL</command>
commands.
</para>
<note>
<para>
The <command>SELECT</command> command acquires a
lock of this mode on referenced tables. In general, any query
that only reads a table and does not modify it will acquire
this lock mode.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>ROW SHARE MODE</term>
<listitem>
<para>
Conflicts with EXCLUSIVE and ACCESS EXCLUSIVE lock modes.
</para>
<note>
<para>
The <command>SELECT FOR UPDATE</command> command acquires a
lock of this mode on the target table(s) (in addition to
<literal>ACCESS SHARE</literal> locks on any other tables
that are referenced but not selected <option>FOR UPDATE</option>).
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>ROW EXCLUSIVE MODE</term>
<listitem>
<para>
Conflicts with SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE and
ACCESS EXCLUSIVE modes.
</para>
<note>
<para>
The commands <command>UPDATE</command>,
<command>DELETE</command>, and <command>INSERT</command>
acquire this lock mode on the target table (in addition to
<literal>ACCESS SHARE</literal> locks on any other referenced
tables). In general, this lock mode will be acquired by any
query that modifies the data in a table.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>SHARE UPDATE EXCLUSIVE MODE</term>
<listitem>
<para>
Conflicts with SHARE UPDATE EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE,
EXCLUSIVE and
ACCESS EXCLUSIVE modes. This mode protects a table against
concurrent schema changes and <command>VACUUM</> runs.
</para>
<note>
<para>
Acquired by <command>VACUUM</command> (without
<option>FULL</option>).
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>SHARE MODE</term>
<listitem>
<para>
Conflicts with ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE,
SHARE ROW EXCLUSIVE, EXCLUSIVE and
ACCESS EXCLUSIVE modes. This mode protects a table against
concurrent data changes.
</para>
<note>
<para>
Acquired by <command>CREATE INDEX</command>.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>SHARE ROW EXCLUSIVE MODE</term>
<listitem>
<para>
Conflicts with ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE, SHARE,
SHARE ROW EXCLUSIVE, EXCLUSIVE and ACCESS EXCLUSIVE modes.
</para>
<note>
<para>
This lock mode is not automatically acquired by any
<productname>PostgreSQL</productname> command.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>EXCLUSIVE MODE</term>
<listitem>
<para>
Conflicts with ROW SHARE, ROW EXCLUSIVE, SHARE UPDATE EXCLUSIVE,
SHARE, SHARE ROW EXCLUSIVE,
EXCLUSIVE and ACCESS EXCLUSIVE modes.
This mode allows only concurrent ACCESS SHARE, i.e., only reads
from the table can proceed in parallel with a transaction holding
this lock mode.
</para>
<note>
<para>
This lock mode is not automatically acquired by any
<productname>PostgreSQL</productname> command.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>ACCESS EXCLUSIVE MODE</term>
<listitem>
<para>
Conflicts with all lock modes. This mode guarantees that the
holder is the only transaction accessing the table in any way.
</para>
<note>
<para>
Acquired by <command>ALTER TABLE</command>,
<command>DROP TABLE</command>, and <command>VACUUM FULL</command>
statements.
This is also the default lock mode for <command>LOCK TABLE</command>
statements that do not specify a mode explicitly.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-LOCK-2">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
LOCK TABLE
</computeroutput></term>
<listitem>
<para>
The lock was successfully acquired.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR <replaceable class="PARAMETER">name</replaceable>: Table does not exist.
</computeroutput></term>
<listitem>
<para>
Message returned if <replaceable class="PARAMETER">name</replaceable>
does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-LOCK-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-24</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>LOCK TABLE</command> obtains a table-level lock, waiting if <command>LOCK TABLE</command> obtains a table-level lock, waiting if
...@@ -263,109 +37,114 @@ ERROR <replaceable class="PARAMETER">name</replaceable>: Table does not exist. ...@@ -263,109 +37,114 @@ ERROR <replaceable class="PARAMETER">name</replaceable>: Table does not exist.
</para> </para>
<para> <para>
When acquiring locks automatically for commands that reference tables, When acquiring locks automatically for commands that reference
<productname>PostgreSQL</productname> always uses the least restrictive tables, <productname>PostgreSQL</productname> always uses the least
lock mode possible. <command>LOCK TABLE</command> restrictive lock mode possible. <command>LOCK TABLE</command>
provides for cases when you might need more restrictive locking. provides for cases when you might need more restrictive locking.
</para> For example, suppose an application runs a transaction at the
isolation level read committed and needs to ensure that data in a
<para> table remains stable for the duration of the transaction. To
For example, suppose an application runs a transaction at READ COMMITTED achieve this you could obtain <literal>SHARE</> lock mode over the
isolation level and needs to ensure that data in a table remains stable
for the duration of the
transaction. To achieve this you could obtain SHARE lock mode over the
table before querying. This will prevent concurrent data changes table before querying. This will prevent concurrent data changes
and ensure subsequent reads of the table see a stable and ensure subsequent reads of the table see a stable view of
view of committed data, because SHARE lock mode conflicts with the ROW committed data, because <literal>SHARE</> lock mode conflicts with
EXCLUSIVE lock acquired by writers, and your the <literal>ROW EXCLUSIVE</> lock acquired by writers, and your
<command>LOCK TABLE <replaceable class="PARAMETER">name</replaceable> IN SHARE MODE</command> <command>LOCK TABLE <replaceable
statement will wait until any concurrent holders of ROW EXCLUSIVE mode class="PARAMETER">name</replaceable> IN SHARE MODE</command>
commit or roll back. Thus, once you obtain the lock, there are no statement will wait until any concurrent holders of <literal>ROW
uncommitted writes outstanding; furthermore none can begin until you EXCLUSIVE</literal> mode locks commit or roll back. Thus, once you
release the lock. obtain the lock, there are no uncommitted writes outstanding;
furthermore none can begin until you release the lock.
<note>
<para>
To achieve a similar effect when running a transaction
at the SERIALIZABLE isolation level, you have to execute the
<command>LOCK TABLE</>
statement before executing any <acronym>DML</> statement. A serializable
transaction's view of data will be frozen when its first <acronym>DML</> statement
begins. A later <command>LOCK</> will still prevent concurrent writes
--- but it
won't ensure that what the transaction reads corresponds to the latest
committed values.
</para>
</note>
</para> </para>
<para> <para>
If a transaction of this sort is going to To achieve a similar effect when running a transaction at the
change the data in the table, then it should use SHARE ROW EXCLUSIVE lock isolation level serializable, you have to execute the <command>LOCK
mode instead of SHARE mode. This ensures that only one transaction of TABLE</> statement before executing any data modification
this type runs at a time. Without this, a deadlock is possible: two statement. A serializable transaction's view of data will be
transactions might both acquire SHARE mode, and then be unable to also frozen when its first data modification statement begins. A later
acquire ROW EXCLUSIVE mode to actually perform their updates. (Note that <command>LOCK TABLE</> will still prevent concurrent writes --- but it
a transaction's own locks never conflict, so a transaction can acquire won't ensure that what the transaction reads corresponds to the
ROW EXCLUSIVE mode when it holds SHARE mode --- but not if anyone else latest committed values.
holds SHARE mode.)
</para> </para>
<para> <para>
Two general rules may be followed to prevent deadlock conditions: If a transaction of this sort is going to change the data in the
table, then it should use <literal>SHARE ROW EXCLUSIVE</> lock mode
instead of <literal>SHARE</> mode. This ensures that only one
transaction of this type runs at a time. Without this, a deadlock
is possible: two transactions might both acquire <literal>SHARE</>
mode, and then be unable to also acquire <literal>ROW EXCLUSIVE</>
mode to actually perform their updates. (Note that a transaction's
own locks never conflict, so a transaction can acquire <literal>ROW
EXCLUSIVE</> mode when it holds <literal>SHARE</> mode --- but not
if anyone else holds <literal>SHARE</> mode.) To avoid deadlocks,
make sure all transactions acquire locks on the same objects in the
same order, and if multiple lock modes are involved for a single
object, then transactions should always acquire the most
restrictive mode first.
</para> </para>
<itemizedlist>
<listitem>
<para>
Transactions have to acquire locks on the same objects in the same order.
</para>
<para>
For example, if one application updates row R1 and than updates
row R2 (in the same transaction) then the second application shouldn't
update row R2 if it's going to update row R1 later (in a single transaction).
Instead, it should update rows R1 and R2 in the same order as the first
application.
</para>
</listitem>
<listitem>
<para>
If multiple lock modes are involved for a single object,
then transactions should always acquire the most restrictive mode first.
</para>
<para>
An example for this rule was given previously when discussing the
use of SHARE ROW EXCLUSIVE mode rather than SHARE mode.
</para>
</listitem>
</itemizedlist>
<para> <para>
<productname>PostgreSQL</productname> does detect deadlocks and will More information about the lock modes and locking strategies can be
rollback at least one waiting transaction to resolve the deadlock. found in <xref linkend="explicit-locking">.
If it is not practical to code an application to follow the above rules
strictly, an alternative solution is to be prepared to retry transactions
when they are aborted by deadlocks.
</para> </para>
</refsect1>
<para> <refsect1>
When locking multiple tables, the command <literal>LOCK a, b;</> is <title>Parameters</title>
equivalent to <literal>LOCK a; LOCK b;</>. The tables are locked one-by-one
in the order specified in the <variablelist>
<command>LOCK</command> command. <varlistentry>
</para> <term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an existing table to
lock.
</para>
<para>
The command <literal>LOCK a, b;</> is equivalent to
<literal>LOCK a; LOCK b;</>. The tables are locked one-by-one in
the order specified in the <command>LOCK</command> command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">lockmode</replaceable></term>
<listitem>
<para>
The lock mode specifies which locks this lock conflicts with.
Lock modes are described in <xref linkend="explicit-locking">.
</para>
<para>
If no lock mode is specified, then <literal>ACCESS
EXCLUSIVE</literal>, the most restrictive mode, is used.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect2 id="R2-SQL-LOCK-3"> <refsect1>
<refsect2info> <title>Diagnostics</title>
<date>1999-06-08</date>
</refsect2info> <variablelist>
<title> <varlistentry>
Notes <term><computeroutput>LOCK TABLE</computeroutput></term>
</title> <listitem>
<para>
Message returned if the lock was successfully acquired.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para> <para>
<literal>LOCK ... IN ACCESS SHARE MODE</> requires <literal>SELECT</> <literal>LOCK ... IN ACCESS SHARE MODE</> requires <literal>SELECT</>
...@@ -375,81 +154,32 @@ ERROR <replaceable class="PARAMETER">name</replaceable>: Table does not exist. ...@@ -375,81 +154,32 @@ ERROR <replaceable class="PARAMETER">name</replaceable>: Table does not exist.
<para> <para>
<command>LOCK</command> is useful only inside a transaction block <command>LOCK</command> is useful only inside a transaction block
(<command>BEGIN</>...<command>COMMIT</>), since the lock is dropped (<command>BEGIN</>/<command>COMMIT</> pair), since the lock is dropped
as soon as the transaction ends. A <command>LOCK</> command appearing as soon as the transaction ends. A <command>LOCK</> command appearing
outside any transaction block forms a self-contained transaction, so the outside any transaction block forms a self-contained transaction, so the
lock will be dropped as soon as it is obtained. lock will be dropped as soon as it is obtained.
</para> </para>
<para> <para>
<acronym>RDBMS</acronym> locking uses the following standard terminology: <command>LOCK TABLE</> only deals with table-level locks, and so
the mode names involving <literal>ROW</> are all misnomers. These
<variablelist> mode names should generally be read as indicating the intention of
<varlistentry> the user to acquire row-level locks within the locked table. Also,
<term>EXCLUSIVE</term> <literal>ROW EXCLUSIVE</> mode is a sharable table lock. Keep in
<listitem> mind that all the lock modes have identical semantics so far as
<para> <command>LOCK TABLE</> is concerned, differing only in the rules
An exclusive lock prevents other locks of the same type from being about which modes conflict with which.
granted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SHARE</term>
<listitem>
<para>
A shared lock allows others to also hold the same type of lock,
but prevents the corresponding EXCLUSIVE lock from being granted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ACCESS</term>
<listitem>
<para>
Locks table schema.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ROW</term>
<listitem>
<para>
Locks individual rows.
</para>
</listitem>
</varlistentry>
</variablelist>
</para> </para>
<para>
<productname>PostgreSQL</productname> does not follow this terminology
exactly. <command>LOCK TABLE</> only deals with table-level locks, and
so the mode names involving ROW are all misnomers. These mode names
should generally be read as indicating the intention of the user to
acquire row-level locks within the locked table. Also,
ROW EXCLUSIVE mode does not follow this naming convention accurately,
since it is a sharable table lock. Keep in mind that all the lock modes
have identical semantics so far as <command>LOCK TABLE</> is concerned,
differing only in the rules about which modes conflict with which.
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-LOCK-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
Obtain a SHARE lock on a primary key table when going to perform Obtain a <literal>SHARE</> lock on a primary key table when going to perform
inserts into a foreign key table: inserts into a foreign key table:
<programlisting> <programlisting>
BEGIN WORK; BEGIN WORK;
LOCK TABLE films IN SHARE MODE; LOCK TABLE films IN SHARE MODE;
SELECT id FROM films SELECT id FROM films
...@@ -458,50 +188,42 @@ SELECT id FROM films ...@@ -458,50 +188,42 @@ SELECT id FROM films
INSERT INTO films_user_comments VALUES INSERT INTO films_user_comments VALUES
(_id_, 'GREAT! I was waiting for it for so long!'); (_id_, 'GREAT! I was waiting for it for so long!');
COMMIT WORK; COMMIT WORK;
</programlisting> </programlisting>
</para> </para>
<para> <para>
Take a SHARE ROW EXCLUSIVE lock on a primary key table when going to perform Take a <literal>SHARE ROW EXCLUSIVE</> lock on a primary key table when going to perform
a delete operation: a delete operation:
<programlisting> <programlisting>
BEGIN WORK; BEGIN WORK;
LOCK TABLE films IN SHARE ROW EXCLUSIVE MODE; LOCK TABLE films IN SHARE ROW EXCLUSIVE MODE;
DELETE FROM films_user_comments WHERE id IN DELETE FROM films_user_comments WHERE id IN
(SELECT id FROM films WHERE rating < 5); (SELECT id FROM films WHERE rating < 5);
DELETE FROM films WHERE rating < 5; DELETE FROM films WHERE rating < 5;
COMMIT WORK; COMMIT WORK;
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-LOCK-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-LOCK-4"> <para>
<refsect2info> There is no <command>LOCK TABLE</command> in the SQL standard,
<date>1998-09-24</date> which instead uses <command>SET TRANSACTION</command> to specify
</refsect2info> concurrency levels on transactions. PostgreSQL supports that too;
<title> see <xref linkend="SQL-SET-TRANSACTION"
SQL92 endterm="SQL-SET-TRANSACTION-TITLE"> for details.
</title> </para>
<para>
There is no <command>LOCK TABLE</command> in <acronym>SQL92</acronym>,
which instead uses <command>SET TRANSACTION</command> to specify
concurrency levels on transactions. We support that too; see
<xref linkend="SQL-SET-TRANSACTION" endterm="SQL-SET-TRANSACTION-TITLE"> for details.
</para>
<para> <para>
Except for ACCESS SHARE, ACCESS EXCLUSIVE, and SHARE UPDATE EXCLUSIVE lock Except for <literal>ACCESS SHARE</>, <literal>ACCESS EXCLUSIVE</>,
modes, the <productname>PostgreSQL</productname> lock modes and the and <literal>SHARE UPDATE EXCLUSIVE</> lock modes, the
<command>LOCK TABLE</command> syntax are compatible with those <productname>PostgreSQL</productname> lock modes and the
present in <productname>Oracle</productname>(TM). <command>LOCK TABLE</command> syntax are compatible with those
</para> present in <productname>Oracle</productname>.
</refsect2> </para>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/notify.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/notify.sgml,v 1.19 2002/09/21 18:32:54 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/notify.sgml,v 1.20 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,113 +8,53 @@ PostgreSQL documentation ...@@ -8,113 +8,53 @@ PostgreSQL documentation
<refentrytitle id="sql-notify-title">NOTIFY</refentrytitle> <refentrytitle id="sql-notify-title">NOTIFY</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>NOTIFY</refname>
NOTIFY <refpurpose>generate a notification</refpurpose>
</refname>
<refpurpose>
generate a notification
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
NOTIFY <replaceable class="PARAMETER">name</replaceable> NOTIFY <replaceable class="PARAMETER">name</replaceable>
</synopsis> </synopsis>
<refsect2 id="R2-SQL-NOTIFY-1">
<refsect2info>
<date>1998-10-07</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">notifyname</replaceable></term>
<listitem>
<para>
Notify condition to be signaled.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-NOTIFY-2">
<refsect2info>
<date>1998-10-07</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
NOTIFY
</computeroutput></term>
<listitem>
<para>
Acknowledgement that notify command has executed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>Notify events</replaceable></term>
<listitem>
<para>
Events are delivered to listening frontends; whether and how each frontend
application reacts depends on its programming.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-NOTIFY-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-10-07</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
The <command>NOTIFY</command> command sends a notify event to each The <command>NOTIFY</command> command sends a notification event to each
frontend application that has previously executed client application that has previously executed
<command>LISTEN <replaceable class="parameter">notifyname</replaceable></command> <command>LISTEN <replaceable class="parameter">name</replaceable></command>
for the specified notify condition in the current database. for the specified notification name in the current database.
</para> </para>
<para> <para>
The information passed to the frontend for a notify event includes the notify The information passed to the client for a notifiation event includes the notification
condition name and the notifying backend process's <acronym>PID</>. It is up to the name and the notifying session's server process <acronym>PID</>. It is up to the
database designer to define the condition names that will be used in a given database designer to define the notification names that will be used in a given
database and what each one means. database and what each one means.
</para> </para>
<para> <para>
Commonly, the notify condition name is the same as the name of some table in Commonly, the notification name is the same as the name of some table in
the database, and the notify event essentially means <quote>I changed this table, the database, and the notify event essentially means, <quote>I changed this table,
take a look at it to see what's new</quote>. But no such association is enforced by take a look at it to see what's new</quote>. But no such association is enforced by
the <command>NOTIFY</command> and <command>LISTEN</command> commands. For the <command>NOTIFY</command> and <command>LISTEN</command> commands. For
example, a database designer could use several different condition names example, a database designer could use several different notification names
to signal different sorts of changes to a single table. to signal different sorts of changes to a single table.
</para> </para>
<para> <para>
<command>NOTIFY</command> provides a simple form of signal or <command>NOTIFY</command> provides a simple form of signal or
<acronym>IPC</> (interprocess communication) mechanism for a collection of processes interprocess communication mechanism for a collection of processes
accessing the same <productname>PostgreSQL</productname> database. accessing the same <productname>PostgreSQL</productname> database.
Higher-level mechanisms can be built by using tables in the database to Higher-level mechanisms can be built by using tables in the database to
pass additional data (beyond a mere condition name) from notifier to pass additional data (beyond a mere notification name) from notifier to
listener(s). listener(s).
</para> </para>
<para> <para>
When <command>NOTIFY</command> is used to signal the occurrence of changes When <command>NOTIFY</command> is used to signal the occurrence of changes
to a particular table, a useful programming technique is to put the to a particular table, a useful programming technique is to put the
...@@ -122,86 +62,91 @@ NOTIFY ...@@ -122,86 +62,91 @@ NOTIFY
In this way, notification happens automatically when the table is changed, In this way, notification happens automatically when the table is changed,
and the application programmer can't accidentally forget to do it. and the application programmer can't accidentally forget to do it.
</para> </para>
<para> <para>
<command>NOTIFY</command> interacts with SQL transactions in some important <command>NOTIFY</command> interacts with SQL transactions in some important
ways. Firstly, if a <command>NOTIFY</command> is executed inside a ways. Firstly, if a <command>NOTIFY</command> is executed inside a
transaction, the notify events are not delivered until and unless the transaction, the notify events are not delivered until and unless the
transaction is committed. This is appropriate, since if the transaction transaction is committed. This is appropriate, since if the transaction
is aborted we would like all the commands within it to have had no is aborted, all the commands within it have had no
effect, including <command>NOTIFY</command>. But it can be disconcerting if one effect, including <command>NOTIFY</command>. But it can be disconcerting if one
is expecting the notify events to be delivered immediately. Secondly, if is expecting the notification events to be delivered immediately. Secondly, if
a listening backend receives a notify signal while it is within a transaction, a listening session receives a notification signal while it is within a transaction,
the notify event will not be delivered to its connected frontend until just the notification event will not be delivered to its connected client until just
after the transaction is completed (either committed or aborted). Again, the after the transaction is completed (either committed or aborted). Again, the
reasoning is that if a notify were delivered within a transaction that was reasoning is that if a notification were delivered within a transaction that was
later aborted, one would want the notification to be undone somehow---but later aborted, one would want the notification to be undone somehow---but
the backend cannot <quote>take back</quote> a notify once it has sent it to the frontend. the server cannot <quote>take back</quote> a notification once it has sent it to the client.
So notify events are only delivered between transactions. The upshot of this So notification events are only delivered between transactions. The upshot of this
is that applications using <command>NOTIFY</command> for real-time signaling is that applications using <command>NOTIFY</command> for real-time signaling
should try to keep their transactions short. should try to keep their transactions short.
</para> </para>
<para> <para>
<command>NOTIFY</command> behaves like Unix signals in one important <command>NOTIFY</command> behaves like Unix signals in one important
respect: if the same condition name is signaled multiple times in quick respect: if the same notification name is signaled multiple times in quick
succession, recipients may get only one notify event for several executions succession, recipients may get only one notification event for several executions
of <command>NOTIFY</command>. So it is a bad idea to depend on the number of <command>NOTIFY</command>. So it is a bad idea to depend on the number
of notifies received. Instead, use <command>NOTIFY</command> to wake up of notifications received. Instead, use <command>NOTIFY</command> to wake up
applications that need to pay attention to something, and use a database applications that need to pay attention to something, and use a database
object (such as a sequence) to keep track of what happened or how many times object (such as a sequence) to keep track of what happened or how many times
it happened. it happened.
</para> </para>
<para> <para>
It is common for a frontend that sends <command>NOTIFY</command> to be It is common for a client that executes <command>NOTIFY</command>
listening on the same notify name itself. In that case it will get back a to be listening on the same notification name itself. In that case
notify event, just like all the other listening frontends. Depending on the it will get back a notification event, just like all the other
application logic, this could result in useless work---for example, listening sessions. Depending on the application logic, this could
re-reading a database table to find the same updates that that frontend just result in useless work, for example, reading a database table to
wrote out. In <productname>PostgreSQL</productname> 6.4 and later, it is find the same updates that that session just wrote out. It is
possible to avoid such extra work by noticing whether the notifying backend possible to avoid such extra work by noticing whether the notifying
process's <acronym>PID</> (supplied in the notify event message) is the same as one's own session's server process <acronym>PID</> (supplied in the
backend's <acronym>PID</> (available from <application>libpq</>). When they are the same, the notify notification event message) is the same as one's own session's
event is one's own work bouncing back, and can be ignored. (Despite what was <acronym>PID</> (available from <application>libpq</>). When they
said in the preceding paragraph, this is a safe technique. are the same, the notification event is one's own work bouncing
<productname>PostgreSQL</productname> keeps self-notifies separate from notifies back, and can be ignored. (Despite what was said in the preceding
arriving from other backends, so you cannot miss an outside notify by ignoring paragraph, this is a safe technique.
your own notifies.) <productname>PostgreSQL</productname> keeps self-notifiications
separate from notifications arriving from other sessions, so you
cannot miss an outside notification by ignoring your own
notifications.)
</para> </para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
Name of the notification to be signaled (any identifier).
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<refsect2 id="R2-SQL-NOTIFY-3"> <variablelist>
<refsect2info> <varlistentry>
<date>1998-10-07</date> <term><computeroutput>NOTIFY</computeroutput></term>
</refsect2info> <listitem>
<title> <para>
Notes Message returned when the commmand has executed.
</title> </para>
<para> </listitem>
<replaceable class="PARAMETER">name</replaceable> </varlistentry>
can be any string valid as a name; </variablelist>
it need not correspond to the name of any actual table. If
<replaceable class="PARAMETER">name</replaceable>
is enclosed in double-quotes, it need not even be a syntactically
valid name, but can be any string up to 63 characters long.
</para>
<para>
In some previous releases of
<productname>PostgreSQL</productname>,
<replaceable class="PARAMETER">name</replaceable>
had to be enclosed in double-quotes when it did not correspond to any existing
table name, even if syntactically valid as a name. That is no longer required.
</para>
<para>
In <productname>PostgreSQL</productname> releases prior to 6.4, the backend
<acronym>PID</> delivered in a notify message was always the <acronym>PID</> of the frontend's own
backend. So it was not possible to distinguish one's own notifies from other
clients' notifies in those earlier releases.
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-NOTIFY-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
Configure and execute a listen/notify sequence from Configure and execute a listen/notify sequence from
<application>psql</application>: <application>psql</application>:
...@@ -214,23 +159,13 @@ Asynchronous NOTIFY 'virtual' from backend with pid '8448' received. ...@@ -214,23 +159,13 @@ Asynchronous NOTIFY 'virtual' from backend with pid '8448' received.
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-NOTIFY-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title> <para>
There is no <command>NOTIFY</command> statement in the SQL
<refsect2 id="R2-SQL-NOTIFY-4"> standard.
<refsect2info> </para>
<date>1998-09-24</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>NOTIFY</command> statement in
<acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/prepare.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/prepare.sgml,v 1.3 2003/03/10 03:53:49 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/prepare.sgml,v 1.4 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,197 +8,158 @@ PostgreSQL documentation ...@@ -8,197 +8,158 @@ PostgreSQL documentation
<refentrytitle id="sql-prepare-title">PREPARE</refentrytitle> <refentrytitle id="sql-prepare-title">PREPARE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>PREPARE</refname>
PREPARE <refpurpose>prepare a statement for execution</refpurpose>
</refname>
<refpurpose>
create a prepared query
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2002-08-12</date> PREPARE <replaceable class="PARAMETER">plan_name</replaceable> [ (<replaceable class="PARAMETER">datatype</replaceable> [, ...] ) ] AS <replaceable class="PARAMETER">statement</replaceable>
</refsynopsisdivinfo> </synopsis>
<synopsis>
PREPARE <replaceable class="PARAMETER">plan_name</replaceable> [ (<replaceable class="PARAMETER">datatype</replaceable> [, ...] ) ] AS <replaceable class="PARAMETER">query</replaceable>
</synopsis>
<refsect2 id="R2-SQL-PREPARE-1">
<refsect2info>
<date>2002-08-12</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">plan_name</replaceable></term>
<listitem>
<para>
An arbitrary name given to this particular prepared query. It
must be unique within a single session, and is used to execute
or remove a previously prepared query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">datatype</replaceable></term>
<listitem>
<para>
The data-type of a parameter to the prepared query.
To refer to the parameters in the prepared query itself,
use <literal>$1</literal>, <literal>$2</literal>, etc.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">query</replaceable></term>
<listitem>
<para>
Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>,
or <command>DELETE</> query.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-PREPARE-2">
<refsect2info>
<date>2002-08-12</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
<returnvalue>PREPARE</returnvalue>
</computeroutput></term>
<listitem>
<para>
The query has been prepared successfully.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-PREPARE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2002-08-12</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>PREPARE</command> creates a prepared query. A prepared <command>PREPARE</command> creates a prepared statement. A prepared
query is a server-side object that can be used to optimize statement is a server-side object that can be used to optimize
performance. When the <command>PREPARE</command> statement is performance. When the <command>PREPARE</command> statement is
executed, the specified query is parsed, rewritten, and executed, the specified statement is parsed, rewritten, and
planned. When a subsequent <command>EXECUTE</command> statement is planned. When an <command>EXECUTE</command> command is subsequently
issued, the prepared query need only be executed. Thus, the issued, the prepared statement need only be executed. Thus, the
parsing, rewriting, and planning stages are only performed once, parsing, rewriting, and planning stages are only performed once,
instead of every time the query is executed. instead of every time the statement is executed.
</para> </para>
<para> <para>
Prepared queries can take parameters: values that are Prepared statements can take parameters: values that are
substituted into the query when it is executed. To specify the substituted into the statement when it is executed. To include
parameters to a prepared query, include a list of data-types with parameters in a prepared statement, supply a list of data types in
the <command>PREPARE</command> statement. In the query itself, you the <command>PREPARE</command> statement, and, in the statement to
can refer to the parameters by position using be prepared itself, refer to the parameters by position using
<literal>$1</literal>, <literal>$2</literal>, etc. When executing <literal>$1</literal>, <literal>$2</literal>, etc. When executing
the query, specify the actual values for these parameters in the the statement, specify the actual values for these parameters in
<command>EXECUTE</command> statement -- refer to <xref the <command>EXECUTE</command> statement. Refer to <xref
linkend="sql-execute" endterm="sql-execute-title"> linkend="sql-execute" endterm="sql-execute-title"> for more
for more information. information about that.
</para> </para>
<para> <para>
Prepared queries are stored locally (in the current backend), and Prepared statements are only stored in and for the duration of
only exist for the duration of the current database session. When the current database session. When
the client exits, the prepared query is forgotten, and so it must be the session ends, the prepared statement is forgotten, and so it must be
re-created before being used again. This also means that a single recreated before being used again. This also means that a single
prepared query cannot be used by multiple simultaneous database prepared statement cannot be used by multiple simultaneous database
clients; however, each client can create their own prepared query clients; however, each client can create their own prepared statement
to use. to use.
</para> </para>
<para> <para>
Prepared queries have the largest performance advantage when a Prepared statements have the largest performance advantage when a
single backend is being used to execute a large number of similar single session is being used to execute a large number of similar
queries. The performance difference will be particularly statements. The performance difference will be particularly
significant if the queries are complex to plan or rewrite. For significant if the statements are complex to plan or rewrite, for
example, if the query involves a join of many tables or requires example, if the query involves a join of many tables or requires
the application of several rules. If the query is relatively simple the application of several rules. If the statement is relatively simple
to plan and rewrite but relatively expensive to execute, the to plan and rewrite but relatively expensive to execute, the
performance advantage of prepared queries will be less noticeable. performance advantage of prepared statements will be less noticeable.
</para> </para>
</refsect1>
<refsect2 id="R2-SQL-PREPARE-3"> <refsect1>
<refsect2info> <title>Parameters</title>
<date>2002-08-12</date>
</refsect2info> <variablelist>
<title> <varlistentry>
Notes <term><replaceable class="PARAMETER">plan_name</replaceable></term>
</title> <listitem>
<para>
<para> An arbitrary name given to this particular prepared
In some situations, the query plan produced by statement. It must be unique within a single session and is
<productname>PostgreSQL</productname> for a prepared query may be subsequently used to execute or deallocate a previously prepared
inferior to the plan produced if the query were submitted and statement.
executed normally. This is because when the query is planned (and </para>
the optimizer attempts to determine the optimal query plan), the </listitem>
actual values of any parameters specified in the query are </varlistentry>
unavailable. <productname>PostgreSQL</productname> collects
statistics on the distribution of data in the table, and can use <varlistentry>
constant values in a query to make guesses about the likely <term><replaceable class="PARAMETER">datatype</replaceable></term>
result of executing the query. Since this data is unavailable when <listitem>
planning prepared queries with parameters, the chosen plan may be <para>
sub-optimal. To examine the query plan The data type of a parameter to the prepared statement. To
<productname>PostgreSQL</productname> has chosen for a prepared refer to the parameters in the prepared statement itself, use
query, use <command>EXPLAIN EXECUTE</command>. <literal>$1</literal>, <literal>$2</literal>, etc.
</para> </para>
</listitem>
<para> </varlistentry>
For more information on query planning and the statistics
collected by <productname>PostgreSQL</productname> for query <varlistentry>
optimization purposes, see the <xref linkend="sql-analyze" <term><replaceable class="PARAMETER">statement</replaceable></term>
endterm="sql-analyze-title"> documentation. <listitem>
</para> <para>
</refsect2> Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>,
or <command>DELETE</> statement.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-PREPARE-3"> <refsect1>
<title> <title>Diagnostics</title>
Compatibility
</title> <variablelist>
<varlistentry>
<refsect2 id="R2-SQL-PREPARE-4"> <term><computeroutput>PREPARE</computeroutput></term>
<refsect2info> <listitem>
<date>2002-08-12</date> <para>
</refsect2info> Message returned if the statement has been prepared successfully.
<title> </para>
SQL92 </listitem>
</title> </varlistentry>
<para> </variablelist>
SQL92 includes a <command>PREPARE</command> statement, but it is </refsect1>
only for use in embedded SQL clients. The
<command>PREPARE</command> statement implemented by <refsect1>
<productname>PostgreSQL</productname> also uses a somewhat <title>Notes</title>
different syntax.
</para> <para>
</refsect2> In some situations, the query plan produced by for a prepared
statement may be inferior to the plan produced if the statement
were submitted and executed normally. This is because when the
statement is planned and the planer attempts to determine the
optimal query plan, the actual values of any parameters specified
in the statement are
unavailable. <productname>PostgreSQL</productname> collects
statistics on the distribution of data in the table, and can use
constant values in a statement to make guesses about the likely
result of executing the statement. Since this data is unavailable
when planning prepared statements with parameters, the chosen plan
may be suboptimal. To examine the query plan
<productname>PostgreSQL</productname> has chosen for a prepared
statement, use <command>EXPLAIN EXECUTE</command>.
</para>
<para>
For more information on query planning and the statistics collected
by <productname>PostgreSQL</productname> for that purpose, see
the <xref linkend="sql-analyze" endterm="sql-analyze-title">
documentation.
</para>
</refsect1>
<refsect1>
<title>Compatibility</title>
<para>
The SQL standard includes a <command>PREPARE</command> statement,
but it is only for use in embedded SQL. This version of the
<command>PREPARE</command> statement also uses a somewhat different
syntax.
</para>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/reindex.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.16 2003/03/25 16:15:43 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.17 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,124 +8,31 @@ PostgreSQL documentation ...@@ -8,124 +8,31 @@ PostgreSQL documentation
<refentrytitle id="SQL-REINDEX-TITLE">REINDEX</refentrytitle> <refentrytitle id="SQL-REINDEX-TITLE">REINDEX</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>REINDEX</refname>
REINDEX <refpurpose>rebuild indexes</refpurpose>
</refname>
<refpurpose>
rebuild corrupted indexes
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2000-03-30</date>
</refsynopsisdivinfo>
<synopsis>
REINDEX { DATABASE | TABLE | INDEX } <replaceable class="PARAMETER">name</replaceable> [ FORCE ] REINDEX { DATABASE | TABLE | INDEX } <replaceable class="PARAMETER">name</replaceable> [ FORCE ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-REINDEX-1">
<refsect2info>
<date>2000-03-30</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term>DATABASE</term>
<listitem>
<para>
Recreate all system indexes of a specified database. Indexes on
user tables are not included. This form of <command>REINDEX</> can
only be used in standalone mode (see below).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TABLE</term>
<listitem>
<para>
Recreate all indexes of a specified table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>INDEX</term>
<listitem>
<para>
Recreate a specified index.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of the specific database/table/index to be reindexed.
Table and index names may be schema-qualified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FORCE</term>
<listitem>
<para>
Force rebuild of system indexes. Without this keyword
<command>REINDEX</> skips system indexes that are not marked invalid.
FORCE is irrelevant for <command>REINDEX INDEX</>, or when reindexing
user indexes.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-REINDEX-2">
<refsect2info>
<date>2000-03-30</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
REINDEX
</computeroutput></term>
<listitem>
<para>
Message returned if the table is successfully reindexed.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-REINDEX-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2000-03-30</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>REINDEX</command> rebuilds an index based on the data <command>REINDEX</command> rebuilds an index based on the data
stored in the table, replacing the old copy of the index. There are stored in the table, replacing the old copy of the index. There are
two main reasons to use <command>REINDEX</command>: two main reasons to use <command>REINDEX</command>:
<orderedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
An index has become corrupted, and no longer contains valid An index has become corrupted, and no longer contains valid
data. Although in theory this should never be necessary, in data. Although in theory this should never happen, in
practice indexes may become corrupted due to software bugs or practice indexes may become corrupted due to software bugs or
hardware failures. <command>REINDEX</command> provides a hardware failures. <command>REINDEX</command> provides a
recovery method. recovery method.
...@@ -135,146 +42,161 @@ REINDEX ...@@ -135,146 +42,161 @@ REINDEX
<listitem> <listitem>
<para> <para>
The index in question contains a lot of dead index pages that The index in question contains a lot of dead index pages that
are not being reclaimed. This can occur with B+-tree indexes are not being reclaimed. This can occur with B-tree indexes in PostgreSQL
under certain access patterns. <command>REINDEX</command> under certain access patterns. <command>REINDEX</command>
provides a way to reduce the space consumption of the index by provides a way to reduce the space consumption of the index by
writing a new version of the index without the dead pages. See writing a new version of the index without the dead pages. See
<xref linkend="routine-reindex"> for more information. The rest of this reference page <xref linkend="routine-reindex"> for more information.
mostly discusses how to use <command>REINDEX</command> to
recover from index corruption.
</para> </para>
</listitem> </listitem>
</orderedlist> </itemizedlist>
</para> </para>
<para> <para>
If you suspect corruption of an index on a user table, you can If you suspect corruption of an index on a user table, you can
simply rebuild that index, or all indexes on the table, using simply rebuild that index, or all indexes on the table, using
<command>REINDEX INDEX</command> or <command>REINDEX TABLE</command>. <command>REINDEX INDEX</command> or <command>REINDEX
TABLE</command>. Another approach to dealing with a corrupted
user-table index is just to drop and recreate it. This may in fact
be preferable if you would like to maintain some semblance of
normal operation on the table meanwhile. <command>REINDEX</>
acquires exclusive lock on the table, while <command>CREATE
INDEX</> only locks out writes not reads of the table.
</para> </para>
<note>
<para>
Another approach to dealing with a corrupted user-table index is
just to drop and recreate it. This may in fact be preferable if
you would like to maintain some semblance of normal operation on
the table meanwhile. <command>REINDEX</> acquires exclusive lock
on the table, while <command>CREATE INDEX</> only locks out writes
not reads of the table.
</para>
</note>
<para> <para>
Things are more difficult if you need to recover from corruption of an Things are more difficult if you need to recover from corruption of
index on a system table. In this case it's important for the backend an index on a system table. In this case it's important for the
doing the recovery to not have used any of the suspect indexes itself. system to not have used any of the suspect indexes itself.
(Indeed, in this sort of scenario you may find that backends are (Indeed, in this sort of scenario you may find that server
crashing immediately at start-up, due to reliance on the corrupted processes are crashing immediately at start-up, due to reliance on
indexes.) To recover safely, the postmaster must be shut down and a the corrupted indexes.) To recover safely, the server must be shut
stand-alone <productname>PostgreSQL</productname> backend must be down and a stand-alone <productname>PostgreSQL</productname> server
started instead, giving it must be started instead with the command-line options
the command-line options -O and -P (these options allow system table <option>-O</option> and <option>-P</option>. (These options allow
modifications and prevent use of system indexes, respectively). Then system table modifications and prevent use of system indexes,
issue <command>REINDEX DATABASE</>, <command>REINDEX TABLE</>, respectively.) Then, <command>REINDEX DATABASE</>,
<command>REINDEX INDEX</>, or depending on how much you want to reconstruct. <command>REINDEX TABLE</>, or <command>REINDEX INDEX</> can be
If in doubt, use <command>REINDEX DATABASE FORCE</> to force reconstruction issued, depending on how much you want to reconstruct. If in
of all system indexes in the database. Then quit the standalone backend doubt, use <command>REINDEX DATABASE FORCE</> to force
and restart the postmaster. reconstruction of all system indexes in the database. Then quit
the standalone server session and restart the real server.
</para> </para>
<para> <para>
Since this is likely the only situation when most people will ever use See the <xref linkend="app-postgres"> reference page for more
a standalone backend, some usage notes might be in order: information about how to interact with the stand-alone server
interface.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<itemizedlist> <variablelist>
<varlistentry>
<term><literal>DATABASE</literal></term>
<listitem> <listitem>
<para> <para>
Start the backend with a command like Recreate all system indexes of a specified database. Indexes on
<screen> user tables are not included. This form of <command>REINDEX</>
<userinput>postgres -D $PGDATA -O -P my_database</userinput> can only be used in stand-alone mode (see above).
</screen>
Provide the correct path to the database area with <option>-D</>, or
make sure that the environment variable <envar>PGDATA</> is set.
Also specify the name of the particular database you want to work in.
</para> </para>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term><literal>TABLE</literal></term>
<listitem> <listitem>
<para> <para>
You can issue any SQL command, not only <command>REINDEX</>. Recreate all indexes of a specified table.
</para> </para>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term><literal>INDEX</literal></term>
<listitem> <listitem>
<para> <para>
Be aware that the standalone backend treats newline as the command Recreate a specified index.
entry terminator; there is no intelligence about semicolons,
as there is in <application>psql</>. To continue a command
across multiple lines, you must type backslash just before each
newline except the last one.
Also, you won't have any of the conveniences of command-line editing
(no command history, for example).
</para> </para>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem> <listitem>
<para> <para>
To quit the backend, type <acronym>EOF</> (<keycombo The name of the specific database, table, or index to be
action="simul"><keycap>Control</><keycap>D</></>, usually). reindexed. Table and index names may be schema-qualified.
</para> </para>
</listitem> </listitem>
</varlistentry>
</itemizedlist> <varlistentry>
<term><literal>FORCE</literal></term>
<listitem>
<para>
Force rebuild of system indexes. Without this key word,
<command>REINDEX</> skips system indexes that are not marked
invalid. <literal>FORCE</> is irrelevant for <command>REINDEX
INDEX</> or when reindexing user indexes.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
See the <xref linkend="app-postgres"> reference page for more information. <variablelist>
</para> <varlistentry>
<term><computeroutput>REINDEX</computeroutput></term>
<listitem>
<para>
Message returned if the indexes were successfully recreated.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-REINDEX-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
Recreate the indexes on the table <literal>mytable</literal>: Recreate the indexes on the table <literal>my_table</literal>:
<programlisting> <programlisting>
REINDEX TABLE mytable; REINDEX TABLE my_table;
</programlisting> </programlisting>
</para> </para>
<para> <para>
Rebuild a single index: Rebuild a single index:
<programlisting> <programlisting>
REINDEX INDEX my_index; REINDEX INDEX my_index;
</programlisting> </programlisting>
</para> </para>
<para> <para>
Rebuild all system indexes (this will only work in a standalone backend): Rebuild all system indexes (this will only work in a stand-alone
server session):
<programlisting> <programlisting>
REINDEX DATABASE my_database FORCE; REINDEX DATABASE my_database FORCE;
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-REINDEX-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title> <para>
There is no <command>REINDEX</command> command in the SQL standard.
<refsect2 id="R2-SQL-REINDEX-4"> </para>
<refsect2info>
<date>2000-03-30</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>REINDEX</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/revoke.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/revoke.sgml,v 1.25 2003/01/23 23:38:53 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/revoke.sgml,v 1.26 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -53,19 +53,19 @@ REVOKE [ GRANT OPTION FOR ] ...@@ -53,19 +53,19 @@ REVOKE [ GRANT OPTION FOR ]
<title>Description</title> <title>Description</title>
<para> <para>
<command>REVOKE</command> allows the creator of an object to revoke The <command>REVOKE</command> command revokes previously granted
previously granted permissions from one or more users or groups of users. privileges from one or more users or groups of users. The key word
The key word <literal>PUBLIC</literal> refers to the implicitly defined <literal>PUBLIC</literal> refers to the implicitly defined group of
group of all users. all users.
</para> </para>
<para> <para>
Note that any particular user will have the sum Note that any particular user will have the sum
of privileges granted directly to him, privileges granted to any group he of privileges granted directly to him, privileges granted to any group he
is presently a member of, and privileges granted to is presently a member of, and privileges granted to
<literal>PUBLIC</literal>. Thus, for example, revoking SELECT privilege <literal>PUBLIC</literal>. Thus, for example, revoking <literal>SELECT</> privilege
from <literal>PUBLIC</literal> does not necessarily mean that all users from <literal>PUBLIC</literal> does not necessarily mean that all users
have lost SELECT privilege on the object: those who have it granted have lost <literal>SELECT</> privilege on the object: those who have it granted
directly or via a group will still have it. directly or via a group will still have it.
</para> </para>
...@@ -138,15 +138,12 @@ REVOKE ALL PRIVILEGES ON kinds FROM manuel; ...@@ -138,15 +138,12 @@ REVOKE ALL PRIVILEGES ON kinds FROM manuel;
<refsect1 id="SQL-REVOKE-compatibility"> <refsect1 id="SQL-REVOKE-compatibility">
<title>Compatibility</title> <title>Compatibility</title>
<refsect2>
<title>SQL92</title>
<para> <para>
The compatibility notes of the <xref linkend="sql-grant" endterm="sql-grant-title"> command The compatibility notes of the <xref linkend="sql-grant" endterm="sql-grant-title"> command
apply analogously to <command>REVOKE</command>. The syntax summary is: apply analogously to <command>REVOKE</command>. The syntax summary is:
<synopsis> <synopsis>
REVOKE [ GRANT OPTION FOR ] { SELECT | INSERT | UPDATE | DELETE | REFERENCES } REVOKE [ GRANT OPTION FOR ] <replaceable class="PARAMETER">privileges</replaceable>
ON <replaceable class="parameter">object</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ] ON <replaceable class="parameter">object</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] } FROM { PUBLIC | <replaceable class="parameter">username</replaceable> [, ...] }
{ RESTRICT | CASCADE } { RESTRICT | CASCADE }
...@@ -154,7 +151,6 @@ REVOKE [ GRANT OPTION FOR ] { SELECT | INSERT | UPDATE | DELETE | REFERENCES } ...@@ -154,7 +151,6 @@ REVOKE [ GRANT OPTION FOR ] { SELECT | INSERT | UPDATE | DELETE | REFERENCES }
One of <literal>RESTRICT</literal> or <literal>CASCADE</literal> One of <literal>RESTRICT</literal> or <literal>CASCADE</literal>
is required. is required.
</para> </para>
</refsect2>
</refsect1> </refsect1>
<refsect1> <refsect1>
......
doc/src/sgml/ref/rollback.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/rollback.sgml,v 1.13 2002/05/18 15:44:47 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/rollback.sgml,v 1.14 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,129 +8,95 @@ PostgreSQL documentation ...@@ -8,129 +8,95 @@ PostgreSQL documentation
<refentrytitle id="SQL-ROLLBACK-TITLE">ROLLBACK</refentrytitle> <refentrytitle id="SQL-ROLLBACK-TITLE">ROLLBACK</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>ROLLBACK</refname>
ROLLBACK <refpurpose>abort the current transaction</refpurpose>
</refname>
<refpurpose>
abort the current transaction
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
ROLLBACK [ WORK | TRANSACTION ] ROLLBACK [ WORK | TRANSACTION ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-ROLLBACK-1">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
Inputs
</title>
<para>
None.
</para>
</refsect2>
<refsect2 id="R2-SQL-ROLLBACK-2">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
ROLLBACK
</computeroutput></term>
<listitem>
<para>
Message returned if successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
WARNING: ROLLBACK: no transaction in progress
</computeroutput></term>
<listitem>
<para>
If there is not any transaction currently in progress.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-ROLLBACK-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-24</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>ROLLBACK</command> rolls back the current transaction and causes <command>ROLLBACK</command> rolls back the current transaction and causes
all the updates made by the transaction to be discarded. all the updates made by the transaction to be discarded.
</para> </para>
</refsect1>
<refsect1>
<title>Parameters</title>
<refsect2 id="R2-SQL-ROLLBACK-3"> <variablelist>
<refsect2info> <varlistentry>
<date>1998-09-24</date> <term><literal>WORK</literal></term>
</refsect2info> <term><literal>TRANSACTION</literal></term>
<title> <listitem>
Notes <para>
</title> Optional key words. They have no effect.
<para> </para>
Use <xref linkend="SQL-COMMIT" endterm="SQL-COMMIT-TITLE"> </listitem>
to successfully terminate a transaction. </varlistentry>
<xref linkend="SQL-ABORT" endterm="SQL-ABORT-TITLE"> is a </variablelist>
synonym for <command>ROLLBACK</command>.
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-ROLLBACK-2"> <refsect1>
<title> <title>Diagnostics</title>
Usage
</title> <variablelist>
<varlistentry>
<term><computeroutput>ROLLBACK</computeroutput></term>
<listitem>
<para>
Message returned if successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>WARNING: ROLLBACK: no transaction in progress</computeroutput></term>
<listitem>
<para>
If there is not any transaction currently in progress.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para> <para>
To abort all changes: Use <xref linkend="SQL-COMMIT" endterm="SQL-COMMIT-TITLE"> to
successfully terminate a transaction.
</para>
</refsect1>
<programlisting> <refsect1>
ROLLBACK WORK; <title>Examples</title>
</programlisting>
<para>
To abort all changes:
<programlisting>
ROLLBACK;
</programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-ROLLBACK-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-ROLLBACK-4"> <para>
<refsect2info> The SQL standard only specifies the two forms
<date>1998-09-24</date> <literal>ROLLBACK</literal> and <literal>ROLLBACK
</refsect2info> WORK</literal>. Otherwise, this command is fully conforming.
<title> </para>
SQL92
</title>
<para>
<acronym>SQL92</acronym> only specifies the two forms <literal>ROLLBACK</literal>
and <literal>ROLLBACK WORK</literal>. Otherwise full compatibility.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/start_transaction.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/start_transaction.sgml,v 1.4 2003/01/10 22:03:27 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/start_transaction.sgml,v 1.5 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
<refentry id="SQL-START-TRANSACTION"> <refentry id="SQL-START-TRANSACTION">
<docinfo>
<date>2002-07-26</date>
</docinfo>
<refmeta> <refmeta>
<refentrytitle id="SQL-START-TRANSACTION-TITLE">START TRANSACTION</refentrytitle> <refentrytitle id="SQL-START-TRANSACTION-TITLE">START TRANSACTION</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
...@@ -19,58 +15,9 @@ PostgreSQL documentation ...@@ -19,58 +15,9 @@ PostgreSQL documentation
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<synopsis> <synopsis>
START TRANSACTION [ ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } ] [ READ WRITE | READ ONLY ] START TRANSACTION [ ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } ] [ READ WRITE | READ ONLY ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-START-TRANSACTION-1">
<refsect2info>
<date>1998-09-27</date>
</refsect2info>
<title>
Inputs
</title>
<para>
None.
</para>
</refsect2>
<refsect2 id="R2-SQL-START-TRANSACTION-2">
<refsect2info>
<date>1998-09-27</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
START TRANSACTION
</computeroutput></term>
<listitem>
<para>
Message returned if successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
WARNING: BEGIN: already a transaction in progress
</computeroutput></term>
<listitem>
<para>
If there is already a transaction in progress when the
command is issued.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1> <refsect1>
...@@ -84,15 +31,50 @@ WARNING: BEGIN: already a transaction in progress ...@@ -84,15 +31,50 @@ WARNING: BEGIN: already a transaction in progress
respects, the behavior of this command is identical to the <xref respects, the behavior of this command is identical to the <xref
linkend="sql-begin" endterm="sql-begin-title"> command. linkend="sql-begin" endterm="sql-begin-title"> command.
</para> </para>
</refsect1>
<refsect1>
<title>Parameters</title>
<para>
See under <xref linkend="sql-set-transaction"
endterm="sql-set-transaction-title"> about the meaning of the
parameters.
</para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>START TRANSACTION</computeroutput></term>
<listitem>
<para>
Message returned if successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>WARNING: BEGIN: already a transaction in progress</computeroutput></term>
<listitem>
<para>
Message returned if there was already a transaction in progress
when the command was issued.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-START-TRANSACTION-3"> <refsect1>
<title>Compatibility</title> <title>Compatibility</title>
<para> <para>
SQL99; but see also the compatibility section of <xref This command conforms to the SQL standard; but see also the
linkend="sql-set-transaction" endterm="sql-set-transaction-title">. compatibility section of <xref linkend="sql-set-transaction"
endterm="sql-set-transaction-title">.
</para> </para>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/truncate.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/truncate.sgml,v 1.9 2002/12/06 03:15:07 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/truncate.sgml,v 1.10 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,76 +8,21 @@ PostgreSQL documentation ...@@ -8,76 +8,21 @@ PostgreSQL documentation
<refentrytitle id="SQL-TRUNCATE-TITLE">TRUNCATE</refentrytitle> <refentrytitle id="SQL-TRUNCATE-TITLE">TRUNCATE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>TRUNCATE</refname>
TRUNCATE <refpurpose>empty a table</refpurpose>
</refname>
<refpurpose>
empty a table
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
TRUNCATE [ TABLE ] <replaceable class="PARAMETER">name</replaceable> TRUNCATE [ TABLE ] <replaceable class="PARAMETER">name</replaceable>
</synopsis> </synopsis>
<refsect2 id="R2-SQL-TRUNCATE-1">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of the table to be truncated.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-TRUNCATE-2">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
TRUNCATE TABLE
</computeroutput></term>
<listitem>
<para>
Message returned if the table is successfully truncated.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-TRUNCATE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-08</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>TRUNCATE</command> quickly removes all rows from a <command>TRUNCATE</command> quickly removes all rows from a
table. It has the same effect as an unqualified table. It has the same effect as an unqualified
...@@ -85,36 +30,55 @@ TRUNCATE TABLE ...@@ -85,36 +30,55 @@ TRUNCATE TABLE
table it is faster. This is most useful on large tables. table it is faster. This is most useful on large tables.
</para> </para>
</refsect1> </refsect1>
<refsect1>
<title>Parameter</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of the table to be truncated.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>TRUNCATE TABLE</computeroutput></term>
<listitem>
<para>
Message returned if the table was successfully truncated.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<refsect1 id="R1-SQL-TRUNCATE-2">
<title>
Usage
</title>
<para> <para>
Truncate the table <literal>bigtable</literal>: Truncate the table <literal>bigtable</literal>:
<programlisting> <programlisting>
TRUNCATE TABLE bigtable; TRUNCATE TABLE bigtable;
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-TRUNCATE-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title> <para>
There is no <command>TRUNCATE</command> command in the SQL standard.
<refsect2 id="R2-SQL-TRUNCATE-4"> </para>
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>TRUNCATE</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/unlisten.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/unlisten.sgml,v 1.20 2002/09/21 18:32:54 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/unlisten.sgml,v 1.21 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,93 +8,30 @@ PostgreSQL documentation ...@@ -8,93 +8,30 @@ PostgreSQL documentation
<refentrytitle>UNLISTEN</refentrytitle> <refentrytitle>UNLISTEN</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>UNLISTEN</refname>
UNLISTEN <refpurpose>stop listening for a notification</refpurpose>
</refname>
<refpurpose>
stop listening for a notification
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1998-10-19</date> UNLISTEN { <replaceable class="PARAMETER">name</replaceable> | * }
</refsynopsisdivinfo> </synopsis>
<synopsis>
UNLISTEN { <replaceable class="PARAMETER">notifyname</replaceable> | * }
</synopsis>
<refsect2 id="R2-SQL-UNLISTEN-1">
<refsect2info>
<date>1998-10-19</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">notifyname</replaceable></term>
<listitem>
<para>
Name of previously registered notify condition.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>*</literal></term>
<listitem>
<para>
All current listen registrations for this backend are cleared.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-UNLISTEN-2">
<refsect2info>
<date>1998-10-19</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
<returnvalue>UNLISTEN</returnvalue>
</computeroutput></term>
<listitem>
<para>
Acknowledgment that statement has executed.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-UNLISTEN-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-10-19</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>UNLISTEN</command> <command>UNLISTEN</command> is used to remove an existing
is used to remove an existing <command>NOTIFY</command> registration. registration for <command>NOTIFY</command> events.
<command>UNLISTEN</command> cancels any existing registration of the current <command>UNLISTEN</command> cancels any existing registration of
<productname>PostgreSQL</productname> session as a listener on the notify the current <productname>PostgreSQL</productname> session as a
condition <replaceable class="PARAMETER">notifyname</replaceable>. listener on the notification <replaceable
The special condition wildcard <literal>*</literal> cancels all listener registrations class="PARAMETER">name</replaceable>. The special wildcard
for the current session. <literal>*</literal> cancels all listener registrations for the
current session.
</para> </para>
<para> <para>
...@@ -103,41 +40,69 @@ UNLISTEN { <replaceable class="PARAMETER">notifyname</replaceable> | * } ...@@ -103,41 +40,69 @@ UNLISTEN { <replaceable class="PARAMETER">notifyname</replaceable> | * }
discussion of the use of <command>LISTEN</command> and discussion of the use of <command>LISTEN</command> and
<command>NOTIFY</command>. <command>NOTIFY</command>.
</para> </para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
Name of a notification (any identifier).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>*</literal></term>
<listitem>
<para>
All current listen registrations for this session are cleared.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>UNLISTEN</computeroutput></term>
<listitem>
<para>
Message returned when the command has executed.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
You unlisten something you were not listening for; no warning or error will appear.
</para>
<refsect2 id="R2-SQL-UNLISTEN-3"> <para>
<refsect2info> At the end of each session, <command>UNLISTEN *</command> ist
<date>1998-10-19</date> automatically executed.
</refsect2info> </para>
<title>
Notes
</title>
<para>
<replaceable class="PARAMETER">notifyname</replaceable>
need not be a valid class name but can be any string valid
as a name up to 64 characters long.
</para>
<para>
The backend does not complain if you unlisten something you were not
listening for.
Each backend will automatically execute <command>UNLISTEN *</command> when
exiting.
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-UNLISTEN-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
To subscribe to an existing registration: To make a registration:
<programlisting> <programlisting>
LISTEN virtual; LISTEN virtual;
LISTEN
NOTIFY virtual; NOTIFY virtual;
NOTIFY
Asynchronous NOTIFY 'virtual' from backend with pid '8448' received Asynchronous NOTIFY 'virtual' from backend with pid '8448' received
</programlisting> </programlisting>
</para> </para>
...@@ -148,30 +113,18 @@ Asynchronous NOTIFY 'virtual' from backend with pid '8448' received ...@@ -148,30 +113,18 @@ Asynchronous NOTIFY 'virtual' from backend with pid '8448' received
<programlisting> <programlisting>
UNLISTEN virtual; UNLISTEN virtual;
UNLISTEN
NOTIFY virtual; NOTIFY virtual;
NOTIFY -- no NOTIFY event is received
-- notice no NOTIFY event is received
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-UNLISTEN-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title> <para>
There is no <command>UNLISTEN</command> command in the SQL standard.
<refsect2 id="R2-SQL-UNLISTEN-4"> </para>
<refsect2info>
<date>1998-10-19</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>UNLISTEN</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/update.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/update.sgml,v 1.20 2002/08/15 02:59:18 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/update.sgml,v 1.21 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,204 +8,136 @@ PostgreSQL documentation ...@@ -8,204 +8,136 @@ PostgreSQL documentation
<refentrytitle id="SQL-UPDATE-TITLE">UPDATE</refentrytitle> <refentrytitle id="SQL-UPDATE-TITLE">UPDATE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>UPDATE</refname>
UPDATE <refpurpose>update rows of a table</refpurpose>
</refname>
<refpurpose>
update rows of a table
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date> UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> SET <replaceable class="PARAMETER">column</replaceable> = <replaceable class="PARAMETER">expression</replaceable> [, ...]
</refsynopsisdivinfo>
<synopsis>
UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> SET <replaceable class="PARAMETER">col</replaceable> = <replaceable class="PARAMETER">expression</replaceable> [, ...]
[ FROM <replaceable class="PARAMETER">fromlist</replaceable> ] [ FROM <replaceable class="PARAMETER">fromlist</replaceable> ]
[ WHERE <replaceable class="PARAMETER">condition</replaceable> ] [ WHERE <replaceable class="PARAMETER">condition</replaceable> ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-UPDATE-1">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an existing table. If
<literal>ONLY</> is specified, only that table is updated. If
<literal>ONLY</> is not specified, the table and all its
descendant tables (if any) are updated. <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 can be altered by changing the
<option>SQL_INHERITANCE</option> configuration option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">column</replaceable></term>
<listitem>
<para>
The name of a column in <replaceable class="PARAMETER">table</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">expression</replaceable></term>
<listitem>
<para>
A valid expression or value to assign to column.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">fromlist</replaceable></term>
<listitem>
<para>
A <productname>PostgreSQL</productname>
non-standard extension to allow columns
from other tables to appear in the WHERE condition.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">condition</replaceable></term>
<listitem>
<para>
Refer to the SELECT statement for a further description
of the WHERE clause.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-UPDATE-2">
<refsect2info>
<date>1998-09-24</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
UPDATE <replaceable class="parameter">#</replaceable>
</computeroutput></term>
<listitem>
<para>
Message returned if successful.
The <replaceable class="parameter">#</replaceable>
means the number of rows updated.
If <replaceable class="parameter">#</replaceable>
is 0 no rows are updated.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-UPDATE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-24</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>UPDATE</command> changes the values of the columns specified for
all rows which satisfy condition. Only the columns
to be modified need appear as columns in the statement.
</para>
<para> <para>
Array references use the same syntax found in <command>UPDATE</command> changes the values of the specified
<xref linkend="sql-select" endterm="sql-select-title">. columns in all rows that satisfy the condition. Only the columns to
That is, either single array elements, a range of array be modified need appear as columns in the statement.
elements or the entire array may be replaced with a single
query.
</para> </para>
<para> <para>
You must have write access to the table in order to modify By default, <command>UPDATE</command> will update rows in the
it, as well as read access to any table whose values are specified table and all its subtables. If you wish to only update
mentioned in the WHERE condition. the specific table mentioned, you must use the <literal>ONLY</>
clause.
</para> </para>
<para> <para>
By default UPDATE will update tuples in the table specified You must have the <literal>UPDATE</literal> privilege on the table
and all its sub-tables. If you wish to only update the to update it, as well as the <literal>SELECT</literal>
specific table mentioned, you should use the ONLY clause. privilege to any table whose values are read in the <replaceable
class="parameter">condition</replaceable>.
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-UPDATE-2"> <refsect1>
<title> <title>Parameters</title>
Usage
</title> <variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of the table to update.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">column</replaceable></term>
<listitem>
<para>
The name of a column in <replaceable class="PARAMETER">table</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">expression</replaceable></term>
<listitem>
<para>
An expression or value to assign to the column.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">fromlist</replaceable></term>
<listitem>
<para>
A list of table expressions, allowing columns from other tables
to appear in the <literal>WHERE</> condition.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">condition</replaceable></term>
<listitem>
<para>
A value expression that returns a value of type
<type>boolean</type> that determines the rows which are to be
updated.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>UPDATE <replaceable class="parameter">count</replaceable></computeroutput></term>
<listitem>
<para>
Message returned if successful. The value <replaceable
class="parameter">count</replaceable> is the number of rows
updated. If <replaceable class="parameter">count</replaceable>
is 0, no rows were updated.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<para> <para>
Change word <literal>Drama</> with <literal>Dramatic</> on column <structfield>kind</>: Change the word <literal>Drama</> to <literal>Dramatic</> in the
column <structfield>kind</> of the table <literal>films</literal>:
<programlisting> <programlisting>
UPDATE films UPDATE filme SET kind = 'Dramatic' WHERE kind = 'Drama';
SET kind = 'Dramatic'
WHERE kind = 'Drama';
SELECT *
FROM films
WHERE kind = 'Dramatic' OR kind = 'Drama';
code | title | did | date_prod | kind | len
-------+---------------+-----+------------+----------+-------
BL101 | The Third Man | 101 | 1949-12-23 | Dramatic | 01:44
P_302 | Becket | 103 | 1964-02-03 | Dramatic | 02:28
M_401 | War and Peace | 104 | 1967-02-12 | Dramatic | 05:57
T_601 | Yojimbo | 106 | 1961-06-16 | Dramatic | 01:50
DA101 | Das Boot | 110 | 1981-11-11 | Dramatic | 02:29
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-UPDATE-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title> <para>
This command conforms to the SQL standard. The
<refsect2 id="R2-SQL-UPDATE-4"> <literal>FROM</literal> clause is a PostgreSQL extension.
<refsect2info> </para>
<date>1998-09-24</date>
</refsect2info>
<title>
SQL92
</title>
<para>
<acronym>SQL92</acronym> defines a different syntax for
the positioned UPDATE statement:
<synopsis>
UPDATE <replaceable>table</replaceable> SET <replaceable>column</replaceable> = <replaceable>expression</replaceable> [, ...]
WHERE CURRENT OF <replaceable class="parameter">cursor</replaceable>
</synopsis>
where <replaceable class="parameter">cursor</replaceable>
identifies an open cursor.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>
......
doc/src/sgml/ref/vacuum.sgml
View file @ 20aae304
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.30 2003/03/25 16:15:44 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.31 2003/04/26 23:56:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
...@@ -8,161 +8,26 @@ PostgreSQL documentation ...@@ -8,161 +8,26 @@ PostgreSQL documentation
<refentrytitle id="sql-vacuum-title">VACUUM</refentrytitle> <refentrytitle id="sql-vacuum-title">VACUUM</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>VACUUM</refname>
VACUUM <refpurpose>garbage-collect and optionally analyze a database</refpurpose>
</refname>
<refpurpose>
garbage-collect and optionally analyze a database
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2001-08-26</date>
</refsynopsisdivinfo>
<synopsis>
VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> ] VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> ]
VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ] VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-VACUUM-1">
<refsect2info>
<date>2001-07-10</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term>FULL</term>
<listitem>
<para>
Selects <quote>full</quote> vacuum, which may reclaim more space,
but takes much longer and exclusively locks the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FREEZE</term>
<listitem>
<para>
Selects aggressive <quote>freezing</quote> of tuples.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>VERBOSE</term>
<listitem>
<para>
Prints a detailed vacuum activity report for each table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ANALYZE</term>
<listitem>
<para>
Updates statistics used by the optimizer to
determine the most efficient way to execute a query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of a specific table to
vacuum. Defaults to all tables in the current database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">column</replaceable></term>
<listitem>
<para>
The name of a specific column to analyze. Defaults to all columns.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-VACUUM-2">
<refsect2info>
<date>1998-10-04</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
<returnvalue>VACUUM</returnvalue>
</computeroutput></term>
<listitem>
<para>
The command is complete.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
INFO: --Relation <replaceable class="PARAMETER">table</replaceable>--
</computeroutput></term>
<listitem>
<para>
The report header for <replaceable class="PARAMETER">table</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
INFO: Pages 98: Changed 25, Reapped 74, Empty 0, New 0;
Tup 1000: Vac 3000, Crash 0, UnUsed 0, MinLen 188, MaxLen 188;
Re-using: Free/Avail. Space 586952/586952; EndEmpty/Avail. Pages 0/74.
Elapsed 0/0 sec.
</computeroutput></term>
<listitem>
<para>
The analysis for <replaceable class="PARAMETER">table</replaceable> itself.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
INFO: Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
</computeroutput></term>
<listitem>
<para>
The analysis for an index on the target table.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-VACUUM-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2001-07-10</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>VACUUM</command> reclaims storage occupied by deleted tuples. <command>VACUUM</command> reclaims storage occupied by deleted tuples.
In normal <productname>PostgreSQL</productname> operation, tuples that In normal <productname>PostgreSQL</productname> operation, tuples that
are deleted or obsoleted by UPDATE are not physically removed from are deleted or obsoleted by an update are not physically removed from
their table; they remain present until a <command>VACUUM</command> is their table; they remain present until a <command>VACUUM</command> is
done. Therefore it's necessary to do <command>VACUUM</command> done. Therefore it's necessary to do <command>VACUUM</command>
periodically, especially on frequently-updated tables. periodically, especially on frequently-updated tables.
...@@ -201,32 +66,137 @@ INFO: Index <replaceable class="PARAMETER">index</replaceable>: Pages 28; ...@@ -201,32 +66,137 @@ INFO: Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
are no other open transactions in the same database, then it is guaranteed are no other open transactions in the same database, then it is guaranteed
that all tuples in the database are <quote>frozen</> and will not be that all tuples in the database are <quote>frozen</> and will not be
subject to transaction ID wraparound problems, no matter how long the subject to transaction ID wraparound problems, no matter how long the
database is left un-vacuumed. database is left unvacuumed.
<command>FREEZE</command> is not recommended for routine use. Its only <command>FREEZE</command> is not recommended for routine use. Its only
intended usage is in connection with preparation of user-defined template intended usage is in connection with preparation of user-defined template
databases, or other databases that are completely read-only and will not databases, or other databases that are completely read-only and will not
receive routine maintenance <command>VACUUM</> operations. receive routine maintenance <command>VACUUM</> operations.
See <xref linkend="maintenance"> for details. See <xref linkend="maintenance"> for details.
</para> </para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><literal>FULL</literal></term>
<listitem>
<para>
Selects <quote>full</quote> vacuum, which may reclaim more
space, but takes much longer and exclusively locks the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>FREEZE</literal></term>
<listitem>
<para>
Selects aggressive <quote>freezing</quote> of tuples.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>VERBOSE</literal></term>
<listitem>
<para>
Prints a detailed vacuum activity report for each table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ANALYZE</literal></term>
<listitem>
<para>
Updates statistics used by the planner to determine the most
efficient way to execute a query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of a specific table to
vacuum. Defaults to all tables in the current database.
</para>
</listitem>
</varlistentry>
<refsect2 id="R2-SQL-VACUUM-3"> <varlistentry>
<refsect2info> <term><replaceable class="PARAMETER">column</replaceable></term>
<date>2001-07-10</date> <listitem>
</refsect2info> <para>
<title> The name of a specific column to analyze. Defaults to all columns.
Notes </para>
</title> </listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>VACUUM</computeroutput></term>
<listitem>
<para>
The command is complete.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>INFO: --Relation <replaceable class="PARAMETER">table</replaceable>--</computeroutput></term>
<listitem>
<para>
The report header for <replaceable class="PARAMETER">table</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>INFO: Pages 98: Changed 25, Reapped 74, Empty 0, New 0;
Tup 1000: Vac 3000, Crash 0, UnUsed 0, MinLen 188, MaxLen 188;
Re-using: Free/Avail. Space 586952/586952; EndEmpty/Avail. Pages 0/74.
Elapsed 0/0 sec.</computeroutput></term>
<listitem>
<para>
The analysis for <replaceable class="PARAMETER">table</replaceable> itself.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>INFO: Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
Tuples 1000: Deleted 3000. Elapsed 0/0 sec.</computeroutput></term>
<listitem>
<para>
The analysis for an index on the target table.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para> <para>
We recommend that active production databases be We recommend that active production databases be
<command>VACUUM</command>-ed frequently (at least nightly), in order to vacuumed frequently (at least nightly), in order to
remove expired rows. After adding or deleting a large number remove expired rows. After adding or deleting a large number
of records, it may be a good idea to issue a <command>VACUUM of rows, it may be a good idea to issue a <command>VACUUM
ANALYZE</command> command for the affected table. This will update the ANALYZE</command> command for the affected table. This will update the
system catalogs with system catalogs with
the results of all recent changes, and allow the the results of all recent changes, and allow the
<productname>PostgreSQL</productname> query optimizer to make better <productname>PostgreSQL</productname> query planner to make better
choices in planning user queries. choices in planning queries.
</para> </para>
<para> <para>
...@@ -236,20 +206,17 @@ INFO: Index <replaceable class="PARAMETER">index</replaceable>: Pages 28; ...@@ -236,20 +206,17 @@ INFO: Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
to occupy less disk space. <command>VACUUM FULL</command> will usually to occupy less disk space. <command>VACUUM FULL</command> will usually
shrink the table more than a plain <command>VACUUM</command> would. shrink the table more than a plain <command>VACUUM</command> would.
</para> </para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-VACUUM-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
The following is an example from running <command>VACUUM</command> on a table The following is an example from running <command>VACUUM</command> on a table
in the regression database: in the regression database:
<programlisting> <programlisting>
regression=> VACUUM VERBOSE ANALYZE onek; => VACUUM VERBOSE ANALYZE onek;
INFO: --Relation onek-- INFO: --Relation onek--
INFO: Index onek_unique1: Pages 14; Tuples 1000: Deleted 3000. INFO: Index onek_unique1: Pages 14; Tuples 1000: Deleted 3000.
CPU 0.00s/0.11u sec elapsed 0.12 sec. CPU 0.00s/0.11u sec elapsed 0.12 sec.
...@@ -265,26 +232,16 @@ INFO: Pages 94: Changed 0, Empty 0; Tup 1000: Vac 3000, Keep 0, UnUsed 0. ...@@ -265,26 +232,16 @@ INFO: Pages 94: Changed 0, Empty 0; Tup 1000: Vac 3000, Keep 0, UnUsed 0.
Total CPU 0.05s/0.45u sec elapsed 0.59 sec. Total CPU 0.05s/0.45u sec elapsed 0.59 sec.
INFO: Analyzing onek INFO: Analyzing onek
VACUUM VACUUM
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-VACUUM-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title> <para>
There is no <command>VACUUM</command> statement in the SQL standard.
<refsect2 id="R2-SQL-VACUUM-4"> </para>
<refsect2info>
<date>1998-10-04</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>VACUUM</command> statement in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1> <refsect1>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment