mirror of
https://github.com/postgres/postgres.git
synced 2025-12-21 05:21:08 +03:00
This patch makes the following changes to the documentation:
- more work from the SGML police - some grammar improvements: rewriting a paragraph or two, replacing contractions where (IMHO) appropriate - fix missing utility commands in lock mode docs - improve CLUSTER, REINDEX, SET SESSION AUTHORIZATION ref pages Neil Conway
This commit is contained in:
Bruce Momjian
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.55 2003/02/13 05:19:59 momjian Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.56 2003/02/19 04:06:28 momjian Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
@@ -367,7 +367,7 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
|
||||
default and NOT NULL clauses for the new column are not supported.
|
||||
The new column always comes into being with all values NULL.
|
||||
You can use the <literal>SET DEFAULT</literal> form
|
||||
of <command>ALTER TABLE</command> to set the default afterwards.
|
||||
of <command>ALTER TABLE</command> to set the default afterward.
|
||||
(You may also want to update the already existing rows to the
|
||||
new default value, using
|
||||
<xref linkend="sql-update" endterm="sql-update-title">.)
|
||||
@@ -392,19 +392,21 @@ VACUUM FULL table;
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If a table has any descendant tables, it is not permitted to ADD or
|
||||
RENAME a column in the parent table without doing the same to the
|
||||
descendants --- that is, ALTER TABLE ONLY will be rejected. This
|
||||
ensures that the descendants always have columns matching the parent.
|
||||
If a table has any descendant tables, it is not permitted to ADD
|
||||
or RENAME a column in the parent table without doing the same to
|
||||
the descendants --- that is, <command>ALTER TABLE ONLY</command>
|
||||
will be rejected. This ensures that the descendants always have
|
||||
columns matching the parent.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A recursive DROP COLUMN operation will remove a descendant table's column
|
||||
only if the descendant does not inherit that column from any other
|
||||
parents and never had an independent definition of the column.
|
||||
A nonrecursive DROP COLUMN (i.e., ALTER TABLE ONLY ... DROP COLUMN)
|
||||
never removes any descendant columns, but instead marks them as
|
||||
independently defined rather than inherited.
|
||||
A recursive <literal>DROP COLUMN</literal> operation will remove a
|
||||
descendant table's column only if the descendant does not inherit
|
||||
that column from any other parents and never had an independent
|
||||
definition of the column. A nonrecursive <literal>DROP
|
||||
COLUMN</literal> (i.e., <command>ALTER TABLE ONLY ... DROP
|
||||
COLUMN</command>) never removes any descendant columns, but
|
||||
instead marks them as independently defined rather than inherited.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.23 2002/12/30 18:42:12 tgl Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.24 2003/02/19 04:06:28 momjian Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
@@ -117,11 +117,19 @@ CLUSTER
|
||||
<command>CLUSTER</command> without any parameter re-clusters all the tables
|
||||
in the
|
||||
current database that the calling user owns, or all tables if called
|
||||
by a superuser. (Never-clustered tables are not touched.) This
|
||||
by a superuser. (Never-clustered tables are not included.) This
|
||||
form of <command>CLUSTER</command> cannot be called from inside a
|
||||
transaction or function.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When a table is being clustered, an <literal>ACCESS
|
||||
EXCLUSIVE</literal> lock is acquired on it. This prevents any other
|
||||
database operations (both reads and writes) from preceding on the
|
||||
table until the <command>CLUSTER</command> is finished. See the
|
||||
&cite-user; for more information on database locking.
|
||||
</para>
|
||||
|
||||
<refsect2 id="R2-SQL-CLUSTER-3">
|
||||
<refsect2info>
|
||||
<date>1998-09-08</date>
|
||||
@@ -159,8 +167,9 @@ CLUSTER
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<command>CLUSTER</command> preserves GRANT, inheritance, index, foreign
|
||||
key, and other ancillary information about the table.
|
||||
<command>CLUSTER</command> preserves <command>GRANT</command>,
|
||||
inheritance, index, foreign key, and other ancillary information
|
||||
about the table.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@@ -212,13 +221,15 @@ SELECT <replaceable class="parameter">columnlist</replaceable> INTO TABLE <repla
|
||||
Usage
|
||||
</title>
|
||||
<para>
|
||||
Cluster the employees relation on the basis of its ID attribute:
|
||||
Cluster the <literal>employees</literal> relation on the basis of
|
||||
its ID attribute:
|
||||
</para>
|
||||
<programlisting>
|
||||
CLUSTER emp_ind ON emp;
|
||||
</programlisting>
|
||||
<para>
|
||||
Cluster the employees relation using the same index that was used before:
|
||||
Cluster the <literal>employees</literal> relation using the same
|
||||
index that was used before:
|
||||
</para>
|
||||
<programlisting>
|
||||
CLUSTER emp;
|
||||
@@ -248,6 +259,14 @@ CLUSTER;
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>See Also</title>
|
||||
|
||||
<simplelist type="inline">
|
||||
<member><xref linkend="app-clusterdb" endterm="app-clusterdb-title"></member>
|
||||
</simplelist>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.6 2003/02/13 05:37:43 momjian Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.7 2003/02/19 04:06:28 momjian Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
@@ -37,7 +37,7 @@ PostgreSQL documentation
|
||||
in a <productname>PostgreSQL</productname> database. It finds tables
|
||||
that have previously been clustered, and clusters them again on the same
|
||||
index that was last used. Tables that have never been clustered are not
|
||||
touched.
|
||||
affected.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.14 2002/11/17 23:43:32 momjian Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.15 2003/02/19 04:06:28 momjian Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
@@ -38,8 +38,9 @@ REINDEX { DATABASE | TABLE | INDEX } <replaceable class="PARAMETER">name</replac
|
||||
<term>DATABASE</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Recreate all system indexes of a specified database.
|
||||
(User-table indexes are not included.)
|
||||
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>
|
||||
@@ -116,16 +117,35 @@ REINDEX
|
||||
Description
|
||||
</title>
|
||||
<para>
|
||||
<command>REINDEX</command> is used to rebuild corrupted indexes.
|
||||
Although in theory this should never be necessary, in practice
|
||||
indexes may become corrupted due to software bugs or hardware
|
||||
failures. <command>REINDEX</command> provides a recovery method.
|
||||
</para>
|
||||
<command>REINDEX</command> rebuilds an index based on the data
|
||||
stored in the table, replacing the old copy of the index. There are
|
||||
two main reasons to use <command>REINDEX</command>:
|
||||
|
||||
<para>
|
||||
<command>REINDEX</command> also removes certain dead index pages that
|
||||
can't be reclaimed any other way. See the "Routine Reindexing"
|
||||
section in the manual for more information.
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
An index has become corrupted, and no longer contains valid
|
||||
data. Although in theory this should never be necessary, in
|
||||
practice indexes may become corrupted due to software bugs or
|
||||
hardware failures. <command>REINDEX</command> provides a
|
||||
recovery method.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
The index in question contains a lot of dead index pages that
|
||||
are not being reclaimed. This can occur with B+-tree indexes
|
||||
under certain access patterns. <command>REINDEX</command>
|
||||
provides a way to reduce the space consumption of the index by
|
||||
writing a new version of the index without the dead pages. See
|
||||
the <quote>Routine Reindexing</quote> section in the
|
||||
&cite-admin; for more information. The rest of this section
|
||||
mostly discusses how to use <command>REINDEX</command> to
|
||||
recover from index corruption.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_session_auth.sgml,v 1.7 2002/09/21 18:32:54 petere Exp $ -->
|
||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_session_auth.sgml,v 1.8 2003/02/19 04:06:28 momjian Exp $ -->
|
||||
<refentry id="SQL-SET-SESSION-AUTHORIZATION">
|
||||
<docinfo>
|
||||
<date>2001-04-21</date>
|
||||
@@ -16,7 +16,7 @@
|
||||
|
||||
<refsynopsisdiv>
|
||||
<synopsis>
|
||||
SET [ SESSION | LOCAL ] SESSION AUTHORIZATION <parameter>username</parameter>
|
||||
SET [ SESSION | LOCAL ] SESSION AUTHORIZATION <replaceable class="PARAMETER">username</replaceable>
|
||||
SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT
|
||||
RESET SESSION AUTHORIZATION
|
||||
</synopsis>
|
||||
@@ -27,12 +27,12 @@ RESET SESSION AUTHORIZATION
|
||||
|
||||
<para>
|
||||
This command sets the session user identifier and the current user
|
||||
identifier of the current SQL-session context to be
|
||||
<parameter>username</parameter>. The user name may be written as
|
||||
either an identifier or a string literal.
|
||||
The session user identifier is valid for the duration of a
|
||||
connection; for example, it is possible to temporarily become an
|
||||
unprivileged user and later switch back to become a superuser.
|
||||
identifier of the current SQL-session context to be <replaceable
|
||||
class="PARAMETER">username</replaceable>. The user name may be
|
||||
written as either an identifier or a string literal. The session
|
||||
user identifier is valid for the duration of a connection; for
|
||||
example, it is possible to temporarily become an unprivileged user
|
||||
and later switch back to become a superuser.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@@ -68,19 +68,21 @@ RESET SESSION AUTHORIZATION
|
||||
<refsect1>
|
||||
<title>Examples</title>
|
||||
|
||||
<screen>
|
||||
<userinput>SELECT SESSION_USER, CURRENT_USER;</userinput>
|
||||
current_user | session_user
|
||||
<programlisting>
|
||||
SELECT SESSION_USER, CURRENT_USER;
|
||||
|
||||
session_user | current_user
|
||||
--------------+--------------
|
||||
peter | peter
|
||||
|
||||
<userinput>SET SESSION AUTHORIZATION 'paul';</userinput>
|
||||
SET SESSION AUTHORIZATION 'paul';
|
||||
|
||||
<userinput>SELECT SESSION_USER, CURRENT_USER;</userinput>
|
||||
current_user | session_user
|
||||
SELECT SESSION_USER, CURRENT_USER;
|
||||
|
||||
session_user | current_user
|
||||
--------------+--------------
|
||||
paul | paul
|
||||
</screen>
|
||||
</programlisting>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.28 2003/01/19 00:13:31 momjian Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.29 2003/02/19 04:06:28 momjian Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
@@ -286,6 +286,14 @@ VACUUM
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>See Also</title>
|
||||
|
||||
<simplelist type="inline">
|
||||
<member><xref linkend="app-vacuumdb" endterm="app-vacuumdb-title"></member>
|
||||
</simplelist>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
|
||||
Reference in New Issue
Block a user