rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Bring SQL ref pages to consistent format, part 1.

This commit is contained in:
Peter Eisentraut 2003-04-15 13:25:08 +00:00
parent 72aa9488d3
commit 7c084d148f
14 changed files with 1261 additions and 1797 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

160
doc/src/sgml/ref/abort.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/abort.sgml,v 1.11 2002/04/21 19:02:39 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/abort.sgml,v 1.12 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -8,130 +8,82 @@ PostgreSQL documentation
<refentrytitle id="sql-abort-title">ABORT</refentrytitle> <refentrytitle id="sql-abort-title">ABORT</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>ABORT</refname>
ABORT <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>
ABORT [ WORK | TRANSACTION ] ABORT [ WORK | TRANSACTION ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-ABORT-1">
<refsect2info>
<date>1998-09-27</date>
</refsect2info>
<title>
Inputs
</title>
<para>
None.
</para>
</refsect2>
<refsect2 id="R2-SQL-ABORT-2">
<refsect2info>
<date>1998-09-27</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-ABORT-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-27</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>ABORT</command> rolls back the current transaction and causes <command>ABORT</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.
This command is identical This command is identical
in behavior to the <acronym>SQL92</acronym> command <command>ROLLBACK</command>, in behavior to the standard <acronym>SQL</acronym> command <command>ROLLBACK</command>,
and is present only for historical reasons. and is present only for historical reasons.
</para> </para>
<refsect2 id="R2-SQL-ABORT-3">
<refsect2info>
<date>1998-09-27</date>
</refsect2info>
<title>
Notes
</title>
<para>
Use <command>COMMIT</command> to successfully
terminate a transaction.
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-ABORT-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>
Use <command>COMMIT</command> to successfully
terminate a transaction.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para> <para>
To abort all changes: To abort all changes:
<programlisting> <programlisting>
ABORT WORK; ABORT WORK;
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-ABORT-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-ABORT-4"> <para>
<refsect2info> This command is a <productname>PostgreSQL</productname> extension
<date>1998-09-27</date> present for historical reasons. <command>ROLLBACK</command> is the
</refsect2info> equivalent standard SQL command.
<title> </para>
SQL92
</title>
<para>
This command is a <productname>PostgreSQL</productname> extension present
for historical reasons. <command>ROLLBACK</command> is the <acronym>SQL92</acronym>
equivalent command.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>

16
doc/src/sgml/ref/alter_database.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_database.sgml,v 1.5 2003/03/25 16:15:38 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_database.sgml,v 1.6 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -32,18 +32,18 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RESET <replacea
value becomes the session default value. value becomes the session default value.
The database-specific default The database-specific default
overrides whatever setting is present in <filename>postgresql.conf</> overrides whatever setting is present in <filename>postgresql.conf</>
or has been received from the postmaster. or has been received from the <command>postmaster</command> command line.
</para> </para>
<para> <para>
Only a superuser or the database owner can change the session defaults for a Only the database owner or a superuser can change the session defaults for a
database. database.
</para> </para>
</refsect1>
<refsect2> <refsect1>
<title>Parameters</title> <title>Parameters</title>
<para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term> <term><replaceable class="PARAMETER">name</replaceable></term>
@ -77,14 +77,11 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RESET <replacea
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Diagnostics</title> <title>Diagnostics</title>
<para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><computeroutput>ALTER DATABASE</computeroutput></term> <term><computeroutput>ALTER DATABASE</computeroutput></term>
@ -105,7 +102,6 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RESET <replacea
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>

158
doc/src/sgml/ref/alter_group.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.8 2002/04/21 19:02:39 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.9 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -8,92 +8,29 @@ PostgreSQL documentation
<refentrytitle id="SQL-ALTERGROUP-title">ALTER GROUP</refentrytitle> <refentrytitle id="SQL-ALTERGROUP-title">ALTER GROUP</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>ALTER GROUP</refname>
ALTER GROUP <refpurpose>add users to a group or remove users from a group</refpurpose>
</refname>
<refpurpose>
add users to a group or remove users from a group
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2000-01-14</date> ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> ADD USER <replaceable class="PARAMETER">username</replaceable> [, ... ]
</refsynopsisdivinfo> ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> DROP USER <replaceable class="PARAMETER">username</replaceable> [, ... ]
<synopsis> </synopsis>
ALTER GROUP <replaceable class="PARAMETER">name</replaceable> ADD USER <replaceable class="PARAMETER">username</replaceable> [, ... ]
ALTER GROUP <replaceable class="PARAMETER">name</replaceable> DROP USER <replaceable class="PARAMETER">username</replaceable> [, ... ]
</synopsis>
<refsect2 id="R2-SQL-ALTERGROUP-1">
<refsect2info>
<date>2000-01-14</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of the group to modify.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">username</replaceable></term>
<listitem>
<para>
Users which are to be added or removed from the group. The user
names must exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-ALTERGROUP-2">
<refsect2info>
<date>2000-01-14</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>ALTER GROUP</computeroutput></term>
<listitem>
<para>
Message returned if the alteration was successful.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-ALTERGROUP-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2000-01-14</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>ALTER GROUP</command> is used to add or remove users from a <command>ALTER GROUP</command> is used to add or remove users from a
group. Only database superusers can use this command. group. Only database superusers can use this command.
Adding a user to a group does not create the user. Similarly, removing Adding a user to a group does not create the user. Similarly, removing
a user from a group does not drop the user itself. a user from a group does not drop the user itself.
</para> </para>
<para> <para>
Use <xref linkend="SQL-CREATEGROUP" endterm="SQL-CREATEGROUP-title"> Use <xref linkend="SQL-CREATEGROUP" endterm="SQL-CREATEGROUP-title">
to create a new group and <xref linkend="SQL-DROPGROUP" to create a new group and <xref linkend="SQL-DROPGROUP"
@ -101,10 +38,48 @@ ALTER GROUP <replaceable class="PARAMETER">name</replaceable> DROP USER <replace
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-ALTERGROUP-2"> <refsect1>
<title> <title>Parameter</title>
Usage
</title> <variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">groupname</replaceable></term>
<listitem>
<para>
The name of the group to modify.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">username</replaceable></term>
<listitem>
<para>
Users which are to be added or removed from the group. The users
must exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>ALTER GROUP</computeroutput></term>
<listitem>
<para>
Message returned if the alteration was successful.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<para> <para>
Add users to a group: Add users to a group:
@ -121,24 +96,13 @@ ALTER GROUP workers DROP USER beth;
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-ALTERGROUP-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-ALTERGROUP-4"> <para>
<refsect2info> There is no <command>ALTER GROUP</command> statement in the SQL
<date>2000-01-14</date> standard. The concept of roles is similar.
</refsect2info> </para>
<title>
SQL92
</title>
<para>
There is no <command>ALTER GROUP</command> statement in
<acronym>SQL92</acronym>. The concept of roles is
similar.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>

530
doc/src/sgml/ref/alter_table.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.58 2003/03/25 16:15:38 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.59 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -8,19 +8,14 @@ PostgreSQL documentation
<refentrytitle id="sql-altertable-title">ALTER TABLE</refentrytitle> <refentrytitle id="sql-altertable-title">ALTER TABLE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>ALTER TABLE</refname>
ALTER TABLE <refpurpose>change the definition of a table</refpurpose>
</refname>
<refpurpose>
change the definition of a table
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ] ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ]
ADD [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> <replaceable class="PARAMETER">type</replaceable> [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ] ADD [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> <replaceable class="PARAMETER">type</replaceable> [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ]
ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ] ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ]
@ -48,179 +43,19 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
OWNER TO <replaceable class="PARAMETER">new_owner</replaceable> OWNER TO <replaceable class="PARAMETER">new_owner</replaceable>
ALTER TABLE <replaceable class="PARAMETER">table</replaceable> ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
CLUSTER ON <replaceable class="PARAMETER">index_name</replaceable> CLUSTER ON <replaceable class="PARAMETER">index_name</replaceable>
</synopsis> </synopsis>
<refsect2 id="R2-SQL-ALTERTABLE-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 (possibly schema-qualified) of an existing table to
alter. If <literal>ONLY</> is specified, only that table is
altered. 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>
Name of a new or existing column.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER"> type </replaceable></term>
<listitem>
<para>
Type of the new column.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER"> new_column </replaceable></term>
<listitem>
<para>
New name for an existing column.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER"> new_table </replaceable></term>
<listitem>
<para>
New name for the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER"> table_constraint </replaceable></term>
<listitem>
<para>
New table constraint for the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER"> constraint_name </replaceable></term>
<listitem>
<para>
Name of an existing constraint to drop.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">new_owner </replaceable></term>
<listitem>
<para>
The user name of the new owner of the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER"> index_name </replaceable></term>
<listitem>
<para>
The index name on which the table should be marked for clustering.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<listitem>
<para>
Automatically drop objects that depend on the dropped column
or constraint (for example, views referencing the column).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTRICT</term>
<listitem>
<para>
Refuse to drop the column or constraint if there are any dependent
objects. This is the default behavior.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-ALTERTABLE-2">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>ALTER TABLE</computeroutput></term>
<listitem>
<para>
Message returned from column or table renaming.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR</computeroutput></term>
<listitem>
<para>
Message returned if table or column is not available.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-ALTERTABLE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-04-15</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>ALTER TABLE</command> changes the definition of an existing table. <command>ALTER TABLE</command> changes the definition of an existing table.
There are several sub-forms: There are several subforms:
</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>ADD COLUMN</term> <term><literal>ADD COLUMN</literal></term>
<listitem> <listitem>
<para> <para>
This form adds a new column to the table using the same syntax as This form adds a new column to the table using the same syntax as
@ -230,45 +65,45 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>DROP COLUMN</term> <term><literal>DROP COLUMN</literal></term>
<listitem> <listitem>
<para> <para>
This form drops a column from a table. Note that indexes and This form drops a column from a table. Indexes and
table constraints involving the column will be automatically table constraints involving the column will be automatically
dropped as well. You will need to say <literal>CASCADE</> if dropped as well. You will need to say <literal>CASCADE</> if
anything outside the table depends on the column --- for example, anything outside the table depends on the column, for example,
foreign key references, views, etc. foreign key references or views.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>SET/DROP DEFAULT</term> <term><literal>SET</literal>/<literal>DROP DEFAULT</literal></term>
<listitem> <listitem>
<para> <para>
These forms set or remove the default value for a column. Note These forms set or remove the default value for a column.
that defaults only apply to subsequent <command>INSERT</command> The default values only apply to subsequent <command>INSERT</command>
commands; they do not cause rows already in the table to change. commands; they do not cause rows already in the table to change.
Defaults may also be created for views, in which case they are Defaults may also be created for views, in which case they are
inserted into <command>INSERT</> statements on the view before inserted into <command>INSERT</> statements on the view before
the view's ON INSERT rule is applied. the view's <literal>ON INSERT</literal> rule is applied.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>SET/DROP NOT NULL</term> <term><literal>SET</literal>/<literal>DROP NOT NULL</literal></term>
<listitem> <listitem>
<para> <para>
These forms change whether a column is marked to allow NULL These forms change whether a column is marked to allow null
values or to reject NULL values. You may only <literal>SET NOT NULL</> values or to reject null values. You can only use <literal>SET
when the table contains no null values in the column. NOT NULL</> when the column contains no null values.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>SET STATISTICS</term> <term><literal>SET STATISTICS</literal></term>
<listitem> <listitem>
<para> <para>
This form This form
@ -281,39 +116,40 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>SET STORAGE</term> <term><literal>SET STORAGE</literal></term>
<listitem> <listitem>
<para> <para>
This form sets the storage mode for a column. This controls whether this This form sets the storage mode for a column. This controls whether this
column is held inline or in a supplementary table, and whether the data column is held inline or in a supplementary table, and whether the data
should be compressed or not. <literal>PLAIN</literal> must be used should be compressed or not. <literal>PLAIN</literal> must be used
for fixed-length values such as <literal>INTEGER</literal> and is for fixed-length values such as <type>integer</type> and is
inline, uncompressed. <literal>MAIN</literal> is for inline, inline, uncompressed. <literal>MAIN</literal> is for inline,
compressible data. <literal>EXTERNAL</literal> is for external, compressible data. <literal>EXTERNAL</literal> is for external,
uncompressed data and <literal>EXTENDED</literal> is for external, uncompressed data, and <literal>EXTENDED</literal> is for external,
compressed data. <literal>EXTENDED</literal> is the default for all compressed data. <literal>EXTENDED</literal> is the default for all
data types that support it. The use of <literal>EXTERNAL</literal> will data types that support it. The use of <literal>EXTERNAL</literal> will, for example,
make substring operations on a TEXT column faster, at the penalty of make substring operations on a <type>text</type> column faster, at the penalty of
increased storage space. increased storage space.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>SET WITHOUT OIDS</term> <term><literal>SET WITHOUT OIDS</literal></term>
<listitem> <listitem>
<para> <para>
Removes the <literal>OID</literal> column from the the table. Removing (setting without) This form removes the <literal>oid</literal> column from the
oids from a table also do not occur immediately. The space an <literal>OID</literal> table. Removing OIDs from a table does not occur immediately.
uses will be reclaimed when the tuple is updated. Without updating the tuple, both the The space that the OID uses will be reclaimed when the row is
space and the value of the <literal>OID</literal> are maintained indefinitely. This is updated. Without updating the row, both the space and the value
semantically similar to the <literal>DROP COLUMN</literal> process. of the OID are kept indefinitely. This is semantically similar
to the <literal>DROP COLUMN</literal> process.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>RENAME</term> <term><literal>RENAME</literal></term>
<listitem> <listitem>
<para> <para>
The <literal>RENAME</literal> forms change the name of a table The <literal>RENAME</literal> forms change the name of a table
@ -324,7 +160,7 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>ADD <replaceable class="PARAMETER">table_constraint</replaceable></term> <term><literal>ADD <replaceable class="PARAMETER">table_constraint</replaceable></literal></term>
<listitem> <listitem>
<para> <para>
This form adds a new constraint to a table using the same syntax as This form adds a new constraint to a table using the same syntax as
@ -334,7 +170,7 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>DROP CONSTRAINT</term> <term><literal>DROP CONSTRAINT</literal></term>
<listitem> <listitem>
<para> <para>
This form drops constraints on a table. This form drops constraints on a table.
@ -346,17 +182,17 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>OWNER</term> <term><literal>OWNER</literal></term>
<listitem> <listitem>
<para> <para>
This form changes the owner of the table, index, sequence or view to the This form changes the owner of the table, index, sequence, or view to the
specified user. specified user.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>CLUSTER</term> <term><literal>CLUSTER</literal></term>
<listitem> <listitem>
<para> <para>
This form marks a table for future <xref linkend="SQL-CLUSTER" endterm="sql-cluster-title"> This form marks a table for future <xref linkend="SQL-CLUSTER" endterm="sql-cluster-title">
@ -366,27 +202,166 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
<para> <para>
You must own the table to use <command>ALTER TABLE</>; except for You must own the table to use <command>ALTER TABLE</>; except for
<command>ALTER TABLE OWNER</>, which may only be executed by a superuser. <command>ALTER TABLE OWNER</>, which may only be executed by a superuser.
</para> </para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (possibly schema-qualified) of an existing table to
alter. If <literal>ONLY</> is specified, only that table is
altered. 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 altered, 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
configuration parameter <varname>sql_inheritance</varname>.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">column</replaceable></term>
<listitem>
<para>
Name of a new or existing column.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">type</replaceable></term>
<listitem>
<para>
Data type of the new column.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">new_column</replaceable></term>
<listitem>
<para>
New name for an existing column.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">new_table</replaceable></term>
<listitem>
<para>
New name for the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">table_constraint</replaceable></term>
<listitem>
<para>
New table constraint for the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">constraint_name</replaceable></term>
<listitem>
<para>
Name of an existing constraint to drop.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">new_owner</replaceable></term>
<listitem>
<para>
The user name of the new owner of the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">index_name</replaceable></term>
<listitem>
<para>
The index name on which the table should be marked for clustering.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Automatically drop objects that depend on the dropped column
or constraint (for example, views referencing the column).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>RESTRICT</literal></term>
<listitem>
<para>
Refuse to drop the column or constraint if there are any dependent
objects. This is the default behavior.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>ALTER TABLE</computeroutput></term>
<listitem>
<para>
Message returned if successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR</computeroutput></term>
<listitem>
<para>
Message returned if table or column does not exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<refsect2 id="R2-SQL-ALTERTABLE-3">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
Notes
</title>
<para> <para>
The keyword <literal>COLUMN</literal> is noise and can be omitted. The key word <literal>COLUMN</literal> is noise and can be omitted.
</para> </para>
<para> <para>
In the current implementation of <literal>ADD COLUMN</literal>, In the current implementation of <literal>ADD COLUMN</literal>,
default and NOT NULL clauses for the new column are not supported. default and <literal>NOT NULL</> clauses for the new column are not supported.
The new column always comes into being with all values NULL. The new column always comes into being with all values null.
You can use the <literal>SET DEFAULT</literal> form You can use the <literal>SET DEFAULT</literal> form
of <command>ALTER TABLE</command> to set the default afterward. of <command>ALTER TABLE</command> to set the default afterward.
(You may also want to update the already existing rows to the (You may also want to update the already existing rows to the
@ -397,25 +372,25 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
</para> </para>
<para> <para>
The <literal>DROP COLUMN</literal> command does not physically remove The <literal>DROP COLUMN</literal> form does not physically remove
the column, but simply makes it invisible to SQL operations. Subsequent the column, but simply makes it invisible to SQL operations. Subsequent
inserts and updates of the table will store a NULL for the column. insert and update operations in the table will store a null value for the column.
Thus, dropping a column is quick but it will not immediately reduce the Thus, dropping a column is quick but it will not immediately reduce the
on-disk size of your table, as the space occupied on-disk size of your table, as the space occupied
by the dropped column is not reclaimed. The space will be by the dropped column is not reclaimed. The space will be
reclaimed over time as existing rows are updated. reclaimed over time as existing rows are updated.
To reclaim the space at once, do a dummy <command>UPDATE</> of all rows To reclaim the space at once, do a dummy <command>UPDATE</> of all rows
and then vacuum, as in: and then vacuum, as in:
<programlisting> <programlisting>
UPDATE table SET col = col; UPDATE table SET col = col;
VACUUM FULL table; VACUUM FULL table;
</programlisting> </programlisting>
</para> </para>
<para> <para>
If a table has any descendant tables, it is not permitted to ADD 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 or rename a column in the parent table without doing the same to
the descendants --- that is, <command>ALTER TABLE ONLY</command> the descendants. That is, <command>ALTER TABLE ONLY</command>
will be rejected. This ensures that the descendants always have will be rejected. This ensures that the descendants always have
columns matching the parent. columns matching the parent.
</para> </para>
@ -431,126 +406,115 @@ VACUUM FULL table;
</para> </para>
<para> <para>
Changing any part of the schema of a system Changing any part of a system catalog table is not permitted.
catalog is not permitted.
</para> </para>
<para> <para>
Refer to <command>CREATE TABLE</command> for a further description Refer to <command>CREATE TABLE</command> for a further description
of valid arguments. <xref linkend="ddl"> has further information on of valid parameters. <xref linkend="ddl"> has further information on
inheritance. inheritance.
</para> </para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-ALTERTABLE-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
To add a column of type <type>varchar</type> to a table: To add a column of type <type>varchar</type> to a table:
<programlisting> <programlisting>
ALTER TABLE distributors ADD COLUMN address VARCHAR(30); ALTER TABLE distributors ADD COLUMN address varchar(30);
</programlisting> </programlisting>
</para> </para>
<para> <para>
To drop a column from a table: To drop a column from a table:
<programlisting> <programlisting>
ALTER TABLE distributors DROP COLUMN address RESTRICT; ALTER TABLE distributors DROP COLUMN address RESTRICT;
</programlisting> </programlisting>
</para> </para>
<para> <para>
To rename an existing column: To rename an existing column:
<programlisting> <programlisting>
ALTER TABLE distributors RENAME COLUMN address TO city; ALTER TABLE distributors RENAME COLUMN address TO city;
</programlisting> </programlisting>
</para> </para>
<para> <para>
To rename an existing table: To rename an existing table:
<programlisting> <programlisting>
ALTER TABLE distributors RENAME TO suppliers; ALTER TABLE distributors RENAME TO suppliers;
</programlisting> </programlisting>
</para> </para>
<para> <para>
To add a NOT NULL constraint to a column: To add a not-null constraint to a column:
<programlisting> <programlisting>
ALTER TABLE distributors ALTER COLUMN street SET NOT NULL; ALTER TABLE distributors ALTER COLUMN street SET NOT NULL;
</programlisting> </programlisting>
To remove a NOT NULL constraint from a column: To remove a not-null constraint from a column:
<programlisting> <programlisting>
ALTER TABLE distributors ALTER COLUMN street DROP NOT NULL; ALTER TABLE distributors ALTER COLUMN street DROP NOT NULL;
</programlisting> </programlisting>
</para> </para>
<para> <para>
To add a check constraint to a table: To add a check constraint to a table:
<programlisting> <programlisting>
ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5); ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5);
</programlisting> </programlisting>
</para> </para>
<para> <para>
To remove a check constraint from a table and all its children: To remove a check constraint from a table and all its children:
<programlisting> <programlisting>
ALTER TABLE distributors DROP CONSTRAINT zipchk; ALTER TABLE distributors DROP CONSTRAINT zipchk;
</programlisting> </programlisting>
</para> </para>
<para> <para>
To add a foreign key constraint to a table: To add a foreign key constraint to a table:
<programlisting> <programlisting>
ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses(address) MATCH FULL; ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses (address) MATCH FULL;
</programlisting> </programlisting>
</para> </para>
<para> <para>
To add a (multicolumn) unique constraint to a table: To add a (multicolumn) unique constraint to a table:
<programlisting> <programlisting>
ALTER TABLE distributors ADD CONSTRAINT dist_id_zipcode_key UNIQUE (dist_id, zipcode); ALTER TABLE distributors ADD CONSTRAINT dist_id_zipcode_key UNIQUE (dist_id, zipcode);
</programlisting> </programlisting>
</para> </para>
<para> <para>
To add an automatically named primary key constraint to a table, noting To add an automatically named primary key constraint to a table, noting
that a table can only ever have one primary key: that a table can only ever have one primary key:
<programlisting> <programlisting>
ALTER TABLE distributors ADD PRIMARY KEY (dist_id); ALTER TABLE distributors ADD PRIMARY KEY (dist_id);
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-ALTERTABLE-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-ALTERTABLE-4"> <para>
<refsect2info> The <literal>ADD COLUMN</literal> form conforms with the SQL
<date>1998-04-15</date> standard, with the exception that it does not support defaults and
</refsect2info> not-null constraints, as explained above. The <literal>ALTER
<title>SQL92</title> COLUMN</literal> form is in full conformance.
<para> </para>
The <literal>ADD COLUMN</literal> form is compliant with the exception that
it does not support defaults and NOT NULL constraints, as explained above.
The <literal>ALTER COLUMN</literal> form is in full compliance.
</para>
<para> <para>
The clauses to rename tables, columns, indexes, and sequences are The clauses to rename tables, columns, indexes, views, and sequences are
<productname>PostgreSQL</productname> extensions from SQL92. <productname>PostgreSQL</productname> extensions of the SQL standard.
</para> </para>
<para> <para>
<command>ALTER TABLE DROP COLUMN</> can be used to drop the only column <command>ALTER TABLE DROP COLUMN</> can be used to drop the only
of a table, leaving a zero-column table. This is an extension from SQL92, column of a table, leaving a zero-column table. This is an
which disallows zero-column tables. extension of SQL, which disallows zero-column tables.
</para> </para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>

215
doc/src/sgml/ref/alter_trigger.sgml
View File

@ -1,162 +1,117 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_trigger.sgml,v 1.4 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
<refentry id="SQL-ALTERTRIGGER"> <refentry id="SQL-ALTERTRIGGER">
<refmeta> <refmeta>
<refentrytitle id="sql-altertrigger-title"> <refentrytitle id="sql-altertrigger-title">ALTER TRIGGER</refentrytitle>
ALTER TRIGGER
</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>ALTER TRIGGER</refname>
ALTER TRIGGER <refpurpose>change the definition of a trigger</refpurpose>
</refname>
<refpurpose>
change the definition of a trigger
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2002-04-19</date>
</refsynopsisdivinfo>
<synopsis>
ALTER TRIGGER <replaceable class="PARAMETER">trigger</replaceable> ON <replaceable class="PARAMETER">table</replaceable> ALTER TRIGGER <replaceable class="PARAMETER">trigger</replaceable> ON <replaceable class="PARAMETER">table</replaceable>
RENAME TO <replaceable class="PARAMETER">newname</replaceable> RENAME TO <replaceable class="PARAMETER">newname</replaceable>
</synopsis> </synopsis>
<refsect2 id="R2-SQL-ALTERTRIGGER-1">
<refsect2info>
<date>2002-04-19</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER"> trigger </replaceable></term>
<listitem>
<para>
The name of an existing trigger to alter.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER"> table </replaceable></term>
<listitem>
<para>
The name of the table on which this trigger acts.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER"> newname </replaceable></term>
<listitem>
<para>
New name for the existing trigger.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-ALTERTRIGGER-2">
<refsect2info>
<date>2002-04-19</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>ALTER TRIGGER</computeroutput></term>
<listitem>
<para>
Message returned from trigger renaming.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR</computeroutput></term>
<listitem>
<para>
Message returned if trigger is not available, or new name is a duplicate of another existing trigger on the table.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-ALTERTRIGGER-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2002-04-19</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>ALTER TRIGGER</command> changes the definition of an existing trigger. <command>ALTER TRIGGER</command> changes properties of an existing
The <literal>RENAME</literal> clause causes the name of a trigger on the given table trigger. The <literal>RENAME</literal> clause changes the name of
to change without otherwise changing the trigger definition. the given trigger without otherwise changing the trigger
definition.
</para> </para>
<para> <para>
You must own the table on which the trigger acts in order to change its properties. You must own the table on which the trigger acts to be allowed to change its properties.
</para> </para>
<refsect2 id="R2-SQL-ALTERTRIGGER-3">
<refsect2info>
<date>2002-04-19</date>
</refsect2info>
<title>
Notes
</title>
<para>
Refer to <command>CREATE TRIGGER</command> for a further description
of valid arguments.
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-ALTERTRIGGER-2"> <refsect1>
<title> <title>Parameter</title>
Usage
</title> <variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">trigger</replaceable></term>
<listitem>
<para>
The name of an existing trigger to alter.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name of the table on which this trigger acts.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">newname</replaceable></term>
<listitem>
<para>
The new name for the trigger.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>ALTER TRIGGER</computeroutput></term>
<listitem>
<para>
Message returned if successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR</computeroutput></term>
<listitem>
<para>
If the trigger does not exist, or the new name is a duplicate of
another existing trigger on the table.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<para> <para>
To rename an existing trigger: To rename an existing trigger:
<programlisting> <programlisting>
ALTER TRIGGER emp_stamp ON emp RENAME TO emp_track_chgs; ALTER TRIGGER emp_stamp ON emp RENAME TO emp_track_chgs;
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-ALTERTRIGGER-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-ALTERTRIGGER-4"> <para>
<refsect2info> <command>ALTER TRIGGER</command> is a <productname>PostgreSQL</>
<date>2002-04-19</date> extension of the SQL standard.
</refsect2info> </para>
<title>SQL92</title>
<para>
<command>ALTER TRIGGER</command> is a <productname>PostgreSQL</>
extension of SQL92.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>

32
doc/src/sgml/ref/alter_user.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.26 2003/03/25 16:15:39 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.27 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -20,7 +20,7 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> [ [ WITH ] <rep
where <replaceable class="PARAMETER">option</replaceable> can be: where <replaceable class="PARAMETER">option</replaceable> can be:
[ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
| CREATEDB | NOCREATEDB | CREATEDB | NOCREATEDB
| CREATEUSER | NOCREATEUSER | CREATEUSER | NOCREATEUSER
| VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>' | VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
@ -42,8 +42,8 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
<para> <para>
The first variant of this command in the synopsis changes certain The first variant of this command in the synopsis changes certain
global user privileges and authentication settings. (See below for global user privileges and authentication settings. (See below for
details.) Only a database superuser can change privileges and details.) Only a database superuser can change these privileges and
password expiration with this command. Ordinary users can only the password expiration with this command. Ordinary users can only
change their own password. change their own password.
</para> </para>
@ -52,15 +52,15 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
a specified configuration variable. Whenever the user subsequently a specified configuration variable. Whenever the user subsequently
starts a new session, the specified value becomes the session default, starts a new session, the specified value becomes the session default,
overriding whatever setting is present in <filename>postgresql.conf</> overriding whatever setting is present in <filename>postgresql.conf</>
or has been received from the postmaster. or has been received from the <command>postmaster</command> command line.
Ordinary users can change their own session defaults. Ordinary users can change their own session defaults.
Superusers can change anyone's session defaults. Superusers can change anyone's session defaults.
</para> </para>
</refsect1>
<refsect2> <refsect1>
<title>Parameters</title> <title>Parameters</title>
<para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><replaceable class="PARAMETER">username</replaceable></term> <term><replaceable class="PARAMETER">username</replaceable></term>
@ -99,8 +99,8 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
<listitem> <listitem>
<para> <para>
These clauses define a user's ability to create databases. If These clauses define a user's ability to create databases. If
<literal>CREATEDB</literal> is specified, the user being <literal>CREATEDB</literal> is specified, the user
defined will be allowed to create his own databases. Using will be allowed to create his own databases. Using
<literal>NOCREATEDB</literal> will deny a user the ability to <literal>NOCREATEDB</literal> will deny a user the ability to
create databases. create databases.
</para> </para>
@ -125,7 +125,7 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
<para> <para>
The date (and, optionally, the time) The date (and, optionally, the time)
at which this user's password is to expire. To set the password at which this user's password is to expire. To set the password
never to expire, use 'infinity'. never to expire, use <literal>'infinity'</>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -152,14 +152,11 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Diagnostics</title> <title>Diagnostics</title>
<para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><computeroutput>ALTER USER</computeroutput></term> <term><computeroutput>ALTER USER</computeroutput></term>
@ -175,12 +172,11 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
<listitem> <listitem>
<para> <para>
Error message returned if the specified user is not known to Error message returned if the specified user is not known to
the database. the database system.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -226,10 +222,10 @@ ALTER USER manuel VALID UNTIL 'Jan 31 2030';
<para> <para>
Change a user's valid until date, specifying that his Change a user's valid until date, specifying that his
authorization should expire at midday on 4th May 1998 using authorization should expire at midday on 4th May 2005 using
the time zone which is one hour ahead of <acronym>UTC</>: the time zone which is one hour ahead of <acronym>UTC</>:
<programlisting> <programlisting>
ALTER USER chris VALID UNTIL 'May 4 12:00:00 1998 +1'; ALTER USER chris VALID UNTIL 'May 4 12:00:00 2005 +1';
</programlisting> </programlisting>
</para> </para>

184
doc/src/sgml/ref/analyze.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/analyze.sgml,v 1.11 2003/03/25 16:15:39 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/analyze.sgml,v 1.12 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -8,97 +8,24 @@ PostgreSQL documentation
<refentrytitle id="sql-analyze-title">ANALYZE</refentrytitle> <refentrytitle id="sql-analyze-title">ANALYZE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>ANALYZE</refname>
ANALYZE <refpurpose>collect statistics about a database</refpurpose>
</refname>
<refpurpose>
collect statistics about a database
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>2001-05-04</date>
</refsynopsisdivinfo>
<synopsis>
ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ] ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-ANALYZE-1">
<refsect2info>
<date>2001-05-04</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term>VERBOSE</term>
<listitem>
<para>
Enables display of progress messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (possibly schema-qualified) of a specific table to
analyze. 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-ANALYZE-2">
<refsect2info>
<date>2001-05-04</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
<returnvalue>ANALYZE</returnvalue>
</computeroutput></term>
<listitem>
<para>
The command is complete.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-ANALYZE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2001-05-04</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>ANALYZE</command> collects statistics about the contents of <command>ANALYZE</command> collects statistics about the contents of
<productname>PostgreSQL</productname> tables, and stores the results in tables in the database, and stores the results in
the system table <literal>pg_statistic</literal>. Subsequently, the system table <literal>pg_statistic</literal>. Subsequently,
the query planner uses the statistics to help determine the most efficient the query planner uses the statistics to help determine the most efficient
execution plans for queries. execution plans for queries.
@ -108,16 +35,61 @@ ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<rep
With no parameter, <command>ANALYZE</command> examines every table in the With no parameter, <command>ANALYZE</command> examines every table in the
current database. With a parameter, <command>ANALYZE</command> examines current database. With a parameter, <command>ANALYZE</command> examines
only that table. It is further possible to give a list of column names, only that table. It is further possible to give a list of column names,
in which case only the statistics for those columns are updated. in which case only the statistics for those columns are collected.
</para> </para>
</refsect1>
<refsect2 id="R2-SQL-ANALYZE-3"> <refsect1>
<refsect2info> <title>Parameters</title>
<date>2001-05-04</date>
</refsect2info> <variablelist>
<title> <varlistentry>
Notes <term><literal>VERBOSE</literal></term>
</title> <listitem>
<para>
Enables display of progress messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (possibly schema-qualified) of a specific table to
analyze. 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>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>ANALYZE</computeroutput></term>
<listitem>
<para>
The command is complete.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para> <para>
It is a good idea to run <command>ANALYZE</command> periodically, or It is a good idea to run <command>ANALYZE</command> periodically, or
@ -138,7 +110,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<rep
<para> <para>
For large tables, <command>ANALYZE</command> takes a random sample of the For large tables, <command>ANALYZE</command> takes a random sample of the
table contents, rather than examining every row. This allows even very table contents, rather than examining every row. This allows even very
large tables to be analyzed in a small amount of time. Note however large tables to be analyzed in a small amount of time. Note, however,
that the statistics are only approximate, and will change slightly each that the statistics are only approximate, and will change slightly each
time <command>ANALYZE</command> is run, even if the actual table contents time <command>ANALYZE</command> is run, even if the actual table contents
did not change. This may result in small changes in the planner's did not change. This may result in small changes in the planner's
@ -159,7 +131,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<rep
The extent of analysis can be controlled by adjusting the The extent of analysis can be controlled by adjusting the
<literal>default_statistics_target</> parameter variable, or on a <literal>default_statistics_target</> parameter variable, or on a
column-by-column basis by setting the per-column column-by-column basis by setting the per-column
statistics target with <command>ALTER TABLE ALTER COLUMN SET statistics target with <command>ALTER TABLE ... ALTER COLUMN ... SET
STATISTICS</command> (see STATISTICS</command> (see
<xref linkend="sql-altertable" endterm="sql-altertable-title">). The <xref linkend="sql-altertable" endterm="sql-altertable-title">). The
target value sets the maximum number of entries in the most-common-value target value sets the maximum number of entries in the most-common-value
@ -170,7 +142,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<rep
in <literal>pg_statistic</literal>. in <literal>pg_statistic</literal>.
In particular, setting the statistics target to zero disables collection of In particular, setting the statistics target to zero disables collection of
statistics for that column. It may be useful to do that for columns that statistics for that column. It may be useful to do that for columns that
are never used as part of the WHERE, GROUP BY, or ORDER BY clauses of are never used as part of the <literal>WHERE</>, <literal>GROUP BY</>, or <literal>ORDER BY</> clauses of
queries, since the planner will have no use for statistics on such columns. queries, since the planner will have no use for statistics on such columns.
</para> </para>
@ -180,26 +152,14 @@ ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<rep
the target causes a proportional increase in the time and space needed the target causes a proportional increase in the time and space needed
to do <command>ANALYZE</command>. to do <command>ANALYZE</command>.
</para> </para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-ANALYZE-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-ANALYZE-4"> <para>
<refsect2info> There is no <command>ANALYZE</command> statement in the SQL standard.
<date>2001-05-04</date> </para>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>ANALYZE</command> statement in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>

301
doc/src/sgml/ref/begin.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/begin.sgml,v 1.22 2003/03/25 16:15:39 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/begin.sgml,v 1.23 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -8,218 +8,137 @@ PostgreSQL documentation
<refentrytitle id="SQL-BEGIN-TITLE">BEGIN</refentrytitle> <refentrytitle id="SQL-BEGIN-TITLE">BEGIN</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>BEGIN</refname>
BEGIN <refpurpose>start a transaction block</refpurpose>
</refname> </refnamediv>
<refpurpose>
start a transaction block
</refpurpose>
</refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
BEGIN [ WORK | TRANSACTION ] BEGIN [ WORK | TRANSACTION ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-BEGIN-1">
<refsect2info>
<date>1999-06-11</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-BEGIN-2">
<refsect2info>
<date>1999-06-11</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
BEGIN
</computeroutput></term>
<listitem>
<para>
This signifies that a new transaction has been started.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
WARNING: BEGIN: already a transaction in progress
</computeroutput></term>
<listitem>
<para>
This indicates that a transaction was already in progress.
The current transaction is not affected.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-BEGIN-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1999-06-11</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
By default, <productname>PostgreSQL</productname> executes transactions By default, <productname>PostgreSQL</productname> executes
in <firstterm>unchained mode</firstterm> transactions in <quote>autocommit</quote> mode, that is, each
(also known as <quote>autocommit</quote> in other database statement is executed in its own transaction and a commit is
systems). implicitly performed at the end of the statement (if execution was
In other words, each user statement is executed in its own transaction successful, otherwise a rollback is done).
and a commit is implicitly performed at the end of the statement <command>BEGIN</command> initiates a transaction block, that is,
(if execution was successful, otherwise a rollback is done). all statements after <command>BEGIN</command> command will be
<command>BEGIN</command> initiates a user transaction in chained mode, executed in a single transaction until an explicit <xref
i.e., all user statements after <command>BEGIN</command> command will linkend="sql-commit" endterm="sql-commit-title"> or <xref
be executed in a single transaction until an explicit linkend="sql-rollback" endterm="sql-rollback-title">. Statements
<xref linkend="sql-commit" endterm="sql-commit-title"> or are executed more quickly in a transaction block, because
<xref linkend="sql-rollback" endterm="sql-rollback-title">. transaction start/commit requires significant CPU and disk
Statements are executed more quickly in chained mode, activity. Execution of multiple statements inside a transaction is
because transaction start/commit requires significant CPU and disk also useful to ensure consistency when changing several related
activity. Execution of multiple statements inside a transaction tables: other sessions will be unable to see the intermediate states
is also useful to ensure consistency when changing several wherein not all the related updates have been done.
related tables: other clients will be unable to see the intermediate
states wherein not all the related updates have been done.
</para>
<para>
The default transaction isolation level in
<productname>PostgreSQL</productname>
is READ COMMITTED, wherein each query inside the transaction sees changes
committed before that query begins execution. So, you have to use
<command>SET TRANSACTION ISOLATION LEVEL SERIALIZABLE</command>
just after <command>BEGIN</command> if you need more rigorous transaction
isolation. (Alternatively, you can change the default transaction
isolation level; see <xref linkend="runtime-config"> for details.)
In SERIALIZABLE mode queries will see only changes committed before
the entire
transaction began (actually, before execution of the first <acronym>DML</> statement
in the transaction).
</para>
<para>
Transactions have the standard <acronym>ACID</acronym>
(atomic, consistent, isolatable, and durable) properties.
</para> </para>
</refsect1>
<refsect2 id="R2-SQL-BEGIN-3"> <refsect1>
<refsect2info> <title>Parameters</title>
<date>1999-06-11</date>
</refsect2info>
<title>
Notes
</title>
<para>
<xref linkend="sql-start-transaction"
endterm="sql-start-transaction-title"> has the same functionality
as <command>BEGIN</>.
</para>
<para>
Use <xref linkend="SQL-COMMIT" endterm="SQL-COMMIT-TITLE">
or
<xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE">
to terminate a transaction.
</para>
<para> <variablelist>
Refer to <xref linkend="sql-lock" endterm="sql-lock-title"> <varlistentry>
for further information <term><literal>WORK</literal></term>
about locking tables inside a transaction. <term><literal>TRANSACTION</literal></term>
</para> <listitem>
<para>
Optional key words. They have no effect.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>BEGIN</computeroutput></term>
<listitem>
<para>
This signifies that a new transaction has been started.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>WARNING: BEGIN: already a transaction in progress</computeroutput></term>
<listitem>
<para>
This indicates that a transaction was already in progress. The
current transaction is not affected.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<xref linkend="sql-start-transaction"
endterm="sql-start-transaction-title"> has the same functionality
as <command>BEGIN</>.
</para>
<para> <para>
If you turn <varname>autocommit</> mode off, then <command>BEGIN</> Use <xref linkend="SQL-COMMIT" endterm="SQL-COMMIT-TITLE"> or
is not required: any SQL command automatically starts a transaction. <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE">
</para> to terminate a transaction.
</refsect2> </para>
<para>
If you turn the configuration parameter <varname>autocommit</> off,
then <command>BEGIN</> is not required: any SQL command
automatically starts a transaction.
</para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-BEGIN-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
To begin a user transaction: To begin a transaction block:
<programlisting> <programlisting>
BEGIN WORK; BEGIN;
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-BEGIN-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-BEGIN-4"> <para>
<refsect2info> <command>BEGIN</command> is a <productname>PostgreSQL</productname>
<date>1999-06-11</date> language extension. There is no explicit <command>BEGIN</command>
</refsect2info> command in the SQL standard; transaction initiation is
<title> always implicit and it terminates either with a
SQL92 <command>COMMIT</command> or <command>ROLLBACK</command> statement.
</title> </para>
<para> <para>
<command>BEGIN</command> Other relational database systems may offer an autocommit feature
is a <productname>PostgreSQL</productname> language extension. as a convenience.
There is no explicit <command>BEGIN</command> </para>
command in <acronym>SQL92</acronym>;
transaction initiation is always implicit and it terminates either
with a <command>COMMIT</command> or <command>ROLLBACK</command> statement.
<note> <para>
<para> Incidentally, the <literal>BEGIN</literal> key word is used for a
Many relational database systems offer an autocommit feature as a different purpose in embedded SQL. You are advised to be careful
convenience. about the transaction semantics when porting database applications.
</para> </para>
</note>
</para>
<para>
Incidentally, the <literal>BEGIN</literal> keyword is used for a different
purpose in embedded SQL. You are advised to be careful about the transaction
semantics when porting database applications.
</para>
<para>
<acronym>SQL92</acronym> also requires SERIALIZABLE to be the default
transaction isolation level.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>

6
doc/src/sgml/ref/checkpoint.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/checkpoint.sgml,v 1.8 2003/03/25 16:15:39 petere Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/checkpoint.sgml,v 1.9 2003/04/15 13:25:08 petere Exp $ -->
<refentry id="sql-checkpoint"> <refentry id="sql-checkpoint">
<refmeta> <refmeta>
@ -24,8 +24,8 @@ CHECKPOINT
Write-Ahead Logging (WAL) puts a checkpoint in the transaction log Write-Ahead Logging (WAL) puts a checkpoint in the transaction log
every so often. (To adjust the automatic checkpoint interval, see every so often. (To adjust the automatic checkpoint interval, see
the run-time the run-time
configuration options <parameter>CHECKPOINT_SEGMENTS</parameter> configuration options <varname>checkpoint_segments</varname>
and <parameter>CHECKPOINT_TIMEOUT</parameter>.) and <varname>checkpoint_timeout</varname>.)
The <command>CHECKPOINT</command> command forces an immediate checkpoint The <command>CHECKPOINT</command> command forces an immediate checkpoint
when the command is issued, without waiting for a scheduled checkpoint. when the command is issued, without waiting for a scheduled checkpoint.
</para> </para>

192
doc/src/sgml/ref/close.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/close.sgml,v 1.13 2002/05/18 15:44:47 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/close.sgml,v 1.14 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -8,144 +8,104 @@ PostgreSQL documentation
<refentrytitle id="SQL-CLOSE-TITLE">CLOSE</refentrytitle> <refentrytitle id="SQL-CLOSE-TITLE">CLOSE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CLOSE</refname>
CLOSE <refpurpose>close a cursor</refpurpose>
</refname>
<refpurpose>
close a cursor
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
CLOSE <replaceable class="PARAMETER">cursor</replaceable> CLOSE <replaceable class="PARAMETER">cursor</replaceable>
</synopsis> </synopsis>
<refsect2 id="R2-SQL-CLOSE-1">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">cursor</replaceable></term>
<listitem>
<para>
The name of an open cursor to close.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CLOSE-2">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CLOSE CURSOR
</computeroutput></term>
<listitem>
<para>
Message returned if the cursor is successfully closed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
WARNING: PerformPortalClose: portal "<replaceable class="PARAMETER">cursor</replaceable>" not found
</computeroutput></term>
<listitem>
<para>
This warning is given if
<replaceable class="PARAMETER">cursor</replaceable> is not
declared or has already been closed.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-CLOSE-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-08</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>CLOSE</command> frees the resources associated with an open cursor. <command>CLOSE</command> frees the resources associated with an open cursor.
After the cursor is closed, no subsequent operations After the cursor is closed, no subsequent operations
are allowed on it. A cursor should be closed when it is are allowed on it. A cursor should be closed when it is
no longer needed. no longer needed.
</para> </para>
<para> <para>
An implicit close is executed for every open cursor when a Every open cursor is implicitly closed when a transaction is
transaction is terminated by <command>COMMIT</command> terminated by <command>COMMIT</command> or
or <command>ROLLBACK</command>. <command>ROLLBACK</command>.
</para> </para>
</refsect1>
<refsect2 id="R2-SQL-CLOSE-3"> <refsect1>
<refsect2info> <title>Parameters</title>
<date>1998-09-08</date>
</refsect2info> <variablelist>
<title> <varlistentry>
Notes <term><replaceable class="PARAMETER">cursor</replaceable></term>
</title> <listitem>
<para> <para>
<productname>PostgreSQL</productname> does not have The name of an open cursor to close.
an explicit <command>OPEN</command> cursor statement; </para>
a cursor is considered open when it is declared. </listitem>
Use the <command>DECLARE</command> statement to declare a cursor. </varlistentry>
</para> </variablelist>
</refsect2> </refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CLOSE CURSOR</computeroutput></term>
<listitem>
<para>
Message returned if the cursor is successfully closed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>WARNING: PerformPortalClose: portal "<replaceable class="PARAMETER">cursor</replaceable>" not found</computeroutput></term>
<listitem>
<para>
This warning is given if <replaceable
class="PARAMETER">cursor</replaceable> is not declared or has
already been closed.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CLOSE-2"> <refsect1>
<title> <title>Notes</title>
Usage
</title> <para>
<productname>PostgreSQL</productname> does not have an explicit
<command>OPEN</command> cursor statement; a cursor is considered
open when it is declared. Use the <command>DECLARE</command>
statement to declare a cursor.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para> <para>
Close the cursor <literal>liahona</literal>: Close the cursor <literal>liahona</literal>:
</para> <programlisting>
<programlisting>
CLOSE liahona; CLOSE liahona;
</programlisting> </programlisting>
</para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CLOSE-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-CLOSE-4"> <para>
<refsect2info> <command>CLOSE</command> is fully conforming with the SQL standard.
<date>1998-09-08</date> </para>
</refsect2info>
<title>
SQL92
</title>
<para>
<command>CLOSE</command> is fully compatible with SQL92.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>

230
doc/src/sgml/ref/cluster.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.25 2003/03/25 16:15:39 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.26 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -8,89 +8,27 @@ PostgreSQL documentation
<refentrytitle id="sql-cluster-title">CLUSTER</refentrytitle> <refentrytitle id="sql-cluster-title">CLUSTER</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>CLUSTER</refname>
CLUSTER <refpurpose>cluster a table according to an index</refpurpose>
</refname>
<refpurpose>
cluster a table according to an index
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
CLUSTER <replaceable class="PARAMETER">indexname</replaceable> ON <replaceable class="PARAMETER">tablename</replaceable> CLUSTER <replaceable class="PARAMETER">indexname</replaceable> ON <replaceable class="PARAMETER">tablename</replaceable>
CLUSTER <replaceable class="PARAMETER">tablename</replaceable> CLUSTER <replaceable class="PARAMETER">tablename</replaceable>
CLUSTER CLUSTER
</synopsis> </synopsis>
<refsect2 id="R2-SQL-CLUSTER-1">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Inputs
</title>
<para>
</para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">indexname</replaceable></term>
<listitem>
<para>
The name of an index.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (possibly schema-qualified) of a table.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2 id="R2-SQL-CLUSTER-2">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CLUSTER
</computeroutput></term>
<listitem>
<para>
The clustering was done successfully.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-CLUSTER-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-08</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>CLUSTER</command> instructs <productname>PostgreSQL</productname> <command>CLUSTER</command> instructs <productname>PostgreSQL</productname>
to cluster the table specified to cluster the table specified
by <replaceable class="parameter">table</replaceable> by <replaceable class="parameter">tablename</replaceable>
based on the index specified by based on the index specified by
<replaceable class="parameter">indexname</replaceable>. The index must <replaceable class="parameter">indexname</replaceable>. The index must
already have been defined on already have been defined on
@ -102,19 +40,19 @@ CLUSTER
based on the index information. Clustering is a one-time operation: based on the index information. Clustering is a one-time operation:
when the table is subsequently updated, the changes are when the table is subsequently updated, the changes are
not clustered. That is, no attempt is made to store new or not clustered. That is, no attempt is made to store new or
updated tuples according to their index order. If one wishes, one can updated rows according to their index order. If one wishes, one can
periodically re-cluster by issuing the command again. periodically recluster by issuing the command again.
</para> </para>
<para> <para>
When a table is clustered, <productname>PostgreSQL</productname> When a table is clustered, <productname>PostgreSQL</productname>
remembers on which index it was clustered. The form remembers on which index it was clustered. The form
<command>CLUSTER <replaceable class="parameter">tablename</replaceable></command>, <command>CLUSTER <replaceable class="parameter">tablename</replaceable></command>,
re-clusters the table on the same index that it was clustered before. reclusters the table on the same index that it was clustered before.
</para> </para>
<para> <para>
<command>CLUSTER</command> without any parameter re-clusters all the tables <command>CLUSTER</command> without any parameter reclusters all the tables
in the in the
current database that the calling user owns, or all tables if called current database that the calling user owns, or all tables if called
by a superuser. (Never-clustered tables are not included.) This by a superuser. (Never-clustered tables are not included.) This
@ -129,33 +67,62 @@ CLUSTER
table until the <command>CLUSTER</command> is finished. See table until the <command>CLUSTER</command> is finished. See
<xref linkend="explicit-locking"> for more information on database locking. <xref linkend="explicit-locking"> for more information on database locking.
</para> </para>
</refsect1>
<refsect2 id="R2-SQL-CLUSTER-3"> <refsect1>
<refsect2info> <title>Parameter</title>
<date>1998-09-08</date>
</refsect2info> <variablelist>
<title> <varlistentry>
Notes <term><replaceable class="PARAMETER">indexname</replaceable></term>
</title> <listitem>
<para>
The name of an index.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">tablename</replaceable></term>
<listitem>
<para>
The name (possibly schema-qualified) of a table.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CLUSTER</computeroutput></term>
<listitem>
<para>
The clustering was done successfully.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para> <para>
In cases where you are accessing single rows randomly In cases where you are accessing single rows randomly
within a table, the actual order of the data in the heap within a table, the actual order of the data in the
table is unimportant. However, if you tend to access some table is unimportant. However, if you tend to access some
data more than others, and there is an index that groups data more than others, and there is an index that groups
them together, you will benefit from using <command>CLUSTER</command>. them together, you will benefit from using <command>CLUSTER</command>.
</para> If you are requesting a range of indexed values from a table, or a
<para>
Another place where <command>CLUSTER</command> is helpful is in
cases where you use an
index to pull out several rows from a table. If you are
requesting a range of indexed values from a table, or a
single indexed value that has multiple rows that match, single indexed value that has multiple rows that match,
<command>CLUSTER</command> will help because once the index identifies the <command>CLUSTER</command> will help because once the index identifies the
heap page for the first row that matches, all other rows heap page for the first row that matches, all other rows
that match are probably already on the same heap page, that match are probably already on the same heap page,
saving disk accesses and speeding up the query. and so you save disk accesses and speed up the query.
</para> </para>
<para> <para>
@ -166,23 +133,17 @@ CLUSTER
sizes. sizes.
</para> </para>
<para>
<command>CLUSTER</command> preserves <command>GRANT</command>,
inheritance, index, foreign key, and other ancillary information
about the table.
</para>
<para> <para>
Because <command>CLUSTER</command> remembers the clustering information, Because <command>CLUSTER</command> remembers the clustering information,
one can cluster the tables one wants clustered manually the first time, and one can cluster the tables one wants clustered manually the first time, and
setup a timed event similar to <command>VACUUM</command> so that the tables setup a timed event similar to <command>VACUUM</command> so that the tables
are periodically re-clustered. are periodically reclustered.
</para> </para>
<para> <para>
Because the optimizer records statistics about the ordering of tables, it Because the planner records statistics about the ordering of tables, it
is advisable to run <command>ANALYZE</command> on the newly clustered is advisable to run <command>ANALYZE</command> on the newly clustered
table. Otherwise, the optimizer may make poor choices of query plans. table. Otherwise, the planner may make poor choices of query plans.
</para> </para>
<para> <para>
@ -196,68 +157,57 @@ CLUSTER
but the majority of a big table will not fit in the cache.) but the majority of a big table will not fit in the cache.)
The other way to cluster a table is to use The other way to cluster a table is to use
<programlisting> <programlisting>
SELECT <replaceable class="parameter">columnlist</replaceable> INTO TABLE <replaceable class="parameter">newtable</replaceable> CREATE TABLE <replaceable class="parameter">newtable</replaceable> AS
FROM <replaceable class="parameter">table</replaceable> ORDER BY <replaceable class="parameter">columnlist</replaceable> SELECT <replaceable class="parameter">columnlist</replaceable> FROM <replaceable class="parameter">table</replaceable> ORDER BY <replaceable class="parameter">columnlist</replaceable>;
</programlisting> </programlisting>
which uses the <productname>PostgreSQL</productname> sorting code in which uses the <productname>PostgreSQL</productname> sorting code in
the ORDER BY clause to create the desired order; this is usually much the <literal>ORDER BY</literal> clause to create the desired order; this is usually much
faster than an index scan for faster than an index scan for
unordered data. You then drop the old table, use unordered data. You then drop the old table, use
<command>ALTER TABLE...RENAME</command> <command>ALTER TABLE ... RENAME</command>
to rename <replaceable class="parameter">newtable</replaceable> to the old name, and to rename <replaceable class="parameter">newtable</replaceable> to the old name, and
recreate the table's indexes. However, this approach does not preserve recreate the table's indexes. However, this approach does not preserve
OIDs, constraints, foreign key relationships, granted privileges, and OIDs, constraints, foreign key relationships, granted privileges, and
other ancillary properties of the table --- all such items must be other ancillary properties of the table --- all such items must be
manually recreated. manually recreated.
</para> </para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CLUSTER-2"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
Cluster the <literal>employees</literal> relation on the basis of Cluster the table <literal>employees</literal> on the basis of
its ID attribute: its index <literal>emp_ind</literal>:
</para> <programlisting>
<programlisting>
CLUSTER emp_ind ON emp; CLUSTER emp_ind ON emp;
</programlisting> </programlisting>
</para>
<para> <para>
Cluster the <literal>employees</literal> relation using the same Cluster the <literal>employees</literal> relation using the same
index that was used before: index that was used before:
</para> <programlisting>
<programlisting>
CLUSTER emp; CLUSTER emp;
</programlisting> </programlisting>
</para>
<para> <para>
Cluster all the tables on the database that have previously been clustered: Cluster all the tables on the database that have previously been clustered:
</para> <programlisting>
<programlisting>
CLUSTER; CLUSTER;
</programlisting> </programlisting>
</para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-CLUSTER-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-CLUSTER-4"> <para>
<refsect2info> There is no <command>CLUSTER</command> statement in the SQL standard.
<date>1998-09-08</date> </para>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>CLUSTER</command> statement in SQL92.
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1> <refsect1>

220
doc/src/sgml/ref/comment.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/comment.sgml,v 1.20 2002/07/12 18:43:12 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/comment.sgml,v 1.21 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -8,21 +8,16 @@ PostgreSQL documentation
<refentrytitle id="SQL-COMMENT-TITLE">COMMENT</refentrytitle> <refentrytitle id="SQL-COMMENT-TITLE">COMMENT</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>COMMENT</refname>
COMMENT <refpurpose>define or change the comment of an object</refpurpose>
</refname>
<refpurpose>
define or change the comment of an object
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
COMMENT ON COMMENT ON
[ {
TABLE <replaceable class="PARAMETER">object_name</replaceable> | TABLE <replaceable class="PARAMETER">object_name</replaceable> |
COLUMN <replaceable class="PARAMETER">table_name</replaceable>.<replaceable class="PARAMETER">column_name</replaceable> | COLUMN <replaceable class="PARAMETER">table_name</replaceable>.<replaceable class="PARAMETER">column_name</replaceable> |
AGGREGATE <replaceable class="PARAMETER">agg_name</replaceable> (<replaceable class="PARAMETER">agg_type</replaceable>) | AGGREGATE <replaceable class="PARAMETER">agg_name</replaceable> (<replaceable class="PARAMETER">agg_type</replaceable>) |
@ -38,83 +33,21 @@ COMMENT ON
TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> | TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
TYPE <replaceable class="PARAMETER">object_name</replaceable> | TYPE <replaceable class="PARAMETER">object_name</replaceable> |
VIEW <replaceable class="PARAMETER">object_name</replaceable> VIEW <replaceable class="PARAMETER">object_name</replaceable>
] IS <replaceable class="PARAMETER">'text'</replaceable> } IS <replaceable class="PARAMETER">'text'</replaceable>
</synopsis> </synopsis>
<refsect2 id="R2-SQL-COMMENT-1">
<refsect2info>
<date>1999-10-25</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">object_name,
table_name.column_name, agg_name, constraint_name, func_name, op, rule_name, trigger_name</replaceable></term>
<listitem>
<para>
The name of the object to be be commented. Names of tables,
aggregates, domains, functions, indexes, operators, sequences, types,
and views
may be schema-qualified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">text</replaceable></term>
<listitem>
<para>
The comment to add.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-COMMENT-2">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
COMMENT
</computeroutput></term>
<listitem>
<para>
Message returned if the table is successfully commented.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-COMMENT-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-10-25</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>COMMENT</command> stores a comment about a database object. <command>COMMENT</command> stores a comment about a database object.
Comments can be Comments can be
easily retrieved with <command>psql</command>'s easily retrieved with the <application>psql</application> commands
<command>\dd</command>, <command>\d+</command>, or <command>\l+</command> <command>\dd</command>, <command>\d+</command>, and <command>\l+</command>.
commands. Other user interfaces to retrieve comments can be built atop Other user interfaces to retrieve comments can be built atop
the same built-in functions that <command>psql</command> uses, namely the same built-in functions that <application>psql</application> uses, namely
<function>obj_description()</> and <function>col_description()</>. <function>obj_description</> and <function>col_description</>.
</para> </para>
<para> <para>
@ -124,75 +57,114 @@ COMMENT
string. string.
Comments are automatically dropped when the object is dropped. Comments are automatically dropped when the object is dropped.
</para> </para>
<note>
<para>
There is presently no security mechanism
for comments: any user connected to a database can see all the comments
for objects in that database (although only superusers can change
comments for objects that they don't own). Therefore, don't put
security-critical information in comments.
</para>
</note>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-COMMENT-2"> <refsect1>
<title> <title>Parameters</title>
Usage
</title> <variablelist>
<varlistentry>
<term><replaceable class="parameter">object_name</replaceable></term>
<term><replaceable class="parameter">table_name.column_name</replaceable></term>
<term><replaceable class="parameter">aggname</replaceable></term>
<term><replaceable class="parameter">constraint_name</replaceable></term>
<term><replaceable class="parameter">func_name</replaceable></term>
<term><replaceable class="parameter">op</replaceable></term>
<term><replaceable class="parameter">rule_name</replaceable></term>
<term><replaceable class="parameter">trigger_name</replaceable></term>
<listitem>
<para>
The name of the object to be be commented. Names of tables,
aggregates, domains, functions, indexes, operators, sequences,
types, and views may be schema-qualified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">text</replaceable></term>
<listitem>
<para>
The new comment.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>COMMENT</computeroutput></term>
<listitem>
<para>
Message returned if the comment was successfully changed.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
There is presently no security mechanism for comments: any user
connected to a database can see all the comments for objects in
that database (although only superusers can change comments for
objects that they don't own). Therefore, don't put
security-critical information in comments.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para> <para>
Attach a comment to the table <literal>mytable</literal>: Attach a comment to the table <literal>mytable</literal>:
<programlisting> <programlisting>
COMMENT ON TABLE mytable IS 'This is my table.'; COMMENT ON TABLE mytable IS 'This is my table.';
</programlisting> </programlisting>
Remove it again: Remove it again:
<programlisting> <programlisting>
COMMENT ON TABLE mytable IS NULL; COMMENT ON TABLE mytable IS NULL;
</programlisting> </programlisting>
</para> </para>
<para> <para>
Some more examples: Some more examples:
<programlisting> <programlisting>
COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance'; COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
COMMENT ON COLUMN my_table.my_field IS 'Employee ID number'; COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
COMMENT ON DATABASE my_database IS 'Development Database'; COMMENT ON DATABASE my_database IS 'Development Database';
COMMENT ON DOMAIN my_domain IS 'Email Address Domain'; COMMENT ON DOMAIN my_domain IS 'Email Address Domain';
COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral'; COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee id'; COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';
COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts'; COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
COMMENT ON OPERATOR ^ (NONE, text) IS 'This is a prefix operator on text'; COMMENT ON OPERATOR ^ (NONE, text) IS 'This is a prefix operator on text';
COMMENT ON RULE my_rule ON my_table IS 'Logs UPDATES of employee records'; COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
COMMENT ON SCHEMA my_schema IS 'Departmental data'; COMMENT ON SCHEMA my_schema IS 'Departmental data';
COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys'; COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
COMMENT ON TABLE my_schema.my_table IS 'Employee Information'; COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for R.I.'; COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
COMMENT ON TYPE complex IS 'Complex Number datatype'; COMMENT ON TYPE complex IS 'Complex number data type';
COMMENT ON VIEW my_view IS 'View of departmental costs'; COMMENT ON VIEW my_view IS 'View of departmental costs';
</programlisting> </programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-COMMENT-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-COMMENT-4"> <para>
<refsect2info> There is no <command>COMMENT</command> command in the SQL standard.
<date>1998-09-08</date> </para>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>COMMENT</command> in <acronym>SQL92</acronym>.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>

185
doc/src/sgml/ref/commit.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/commit.sgml,v 1.14 2002/04/21 19:02:39 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/commit.sgml,v 1.15 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -8,141 +8,96 @@ PostgreSQL documentation
<refentrytitle id="SQL-COMMIT-TITLE">COMMIT</refentrytitle> <refentrytitle id="SQL-COMMIT-TITLE">COMMIT</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>COMMIT</refname>
COMMIT <refpurpose>commit the current transaction</refpurpose>
</refname>
<refpurpose>
commit the current transaction
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
COMMIT [ WORK | TRANSACTION ] COMMIT [ WORK | TRANSACTION ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-COMMIT-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-COMMIT-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-COMMIT-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>1998-09-08</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>COMMIT</command> commits the current transaction. All <command>COMMIT</command> commits the current transaction. All
changes made by the transaction become visible to others changes made by the transaction become visible to others
and are guaranteed to be durable if a crash occurs. and are guaranteed to be durable if a crash occurs.
</para> </para>
</refsect1>
<refsect2 id="R2-SQL-COMMIT-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>
<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>
<refsect1 id="R1-SQL-COMMIT-2"> <refsect1>
<title> <title>Notes</title>
Usage
</title>
<para> <para>
To make all changes permanent: Use <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE"> to
<programlisting> abort a transaction.
COMMIT WORK; </para>
</programlisting> </refsect1>
<refsect1>
<title>Examples</title>
<para>
To commit the current transaction and make all changes permanent:
<programlisting>
COMMIT;
</programlisting>
</para> </para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-COMMIT-3"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-COMMIT-4"> <para>
<refsect2info> The SQL standard only specifies the two forms
<date>1998-09-08</date> <literal>COMMIT</literal> and <literal>COMMIT
</refsect2info> WORK</literal>. Otherwise, this command is fully conforming.
<title> </para>
SQL92
</title>
<para>
<acronym>SQL92</acronym> only specifies the two forms <literal>COMMIT</literal>
and <literal>COMMIT WORK</literal>. Otherwise full compatibility.
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>

629
doc/src/sgml/ref/copy.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/copy.sgml,v 1.41 2003/03/27 16:51:27 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/copy.sgml,v 1.42 2003/04/15 13:25:08 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -8,186 +8,35 @@ PostgreSQL documentation
<refentrytitle id="sql-copy-title">COPY</refentrytitle> <refentrytitle id="sql-copy-title">COPY</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo> <refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta> </refmeta>
<refnamediv> <refnamediv>
<refname> <refname>COPY</refname>
COPY <refpurpose>copy data between files and tables</refpurpose>
</refname>
<refpurpose>
copy data between files and tables
</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <synopsis>
<date>1999-12-11</date>
</refsynopsisdivinfo>
<synopsis>
COPY <replaceable class="parameter">table</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ] COPY <replaceable class="parameter">table</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
FROM { '<replaceable class="parameter">filename</replaceable>' | <filename>stdin</filename> } FROM { '<replaceable class="parameter">filename</replaceable>' | STDIN }
[ [ WITH ] [ [ WITH ]
[ BINARY ] [ BINARY ]
[ OIDS ] [ OIDS ]
[ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ] [ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ]
[ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ] ] [ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ] ]
COPY <replaceable class="parameter">table</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ] COPY <replaceable class="parameter">table</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
TO { '<replaceable class="parameter">filename</replaceable>' | <filename>stdout</filename> } TO { '<replaceable class="parameter">filename</replaceable>' | STDOUT }
[ [ WITH ] [ [ WITH ]
[ BINARY ] [ BINARY ]
[ OIDS ] [ OIDS ]
[ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ] [ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ]
[ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ] ] [ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ] ]
</synopsis> </synopsis>
<refsect2 id="R2-SQL-COPY-1">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">table</replaceable></term>
<listitem>
<para>
The name (possibly schema-qualified) of an existing table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">column</replaceable></term>
<listitem>
<para>
An optional list of columns to be copied. If no column list is
specified, all columns will be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
The absolute Unix path name of the input or output file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>stdin</filename></term>
<listitem>
<para>
Specifies that input comes from the client application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>stdout</filename></term>
<listitem>
<para>
Specifies that output goes to the client application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BINARY</term>
<listitem>
<para>
Changes the behavior of field formatting, forcing all data to be
stored or read in binary format rather than as text. You can not
specify <option>DELIMITER</option> or <option>NULL</option>
in binary mode.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>OIDS</term>
<listitem>
<para>
Specifies copying the internal object id (OID) for each row.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">delimiter</replaceable></term>
<listitem>
<para>
The single character that separates fields within each row (line) of the file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">null string</replaceable></term>
<listitem>
<para>
The string that represents a NULL value. The default is
<quote><literal>\N</literal></quote> (backslash-N). You might
prefer an empty string, for example.
</para>
<note>
<para>
On a <command>COPY FROM</command>, any data item that matches
this string will be stored as a NULL value, so you should
make sure that you use the same string as you used with
<command>COPY TO</command>.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-COPY-2">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
COPY
</computeroutput></term>
<listitem>
<para>
The copy completed successfully.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: <replaceable>reason</replaceable>
</computeroutput></term>
<listitem>
<para>
The copy failed for the reason stated in the error message.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-SQL-COPY-1"> <refsect1>
<refsect1info> <title>Description</title>
<date>2001-01-02</date>
</refsect1info>
<title>
Description
</title>
<para> <para>
<command>COPY</command> moves data between <command>COPY</command> moves data between
<productname>PostgreSQL</productname> tables and standard file-system <productname>PostgreSQL</productname> tables and standard file-system
@ -207,61 +56,186 @@ ERROR: <replaceable>reason</replaceable>
<para> <para>
<command>COPY</command> with a file name instructs the <command>COPY</command> with a file name instructs the
<productname>PostgreSQL</productname> backend to directly read from <productname>PostgreSQL</productname> server to directly read from
or write to a file. The file must be accessible to the backend and or write to a file. The file must be accessible to the server and
the name must be specified from the viewpoint of the backend. When the name must be specified from the viewpoint of the server. When
<filename>stdin</filename> or <filename>stdout</filename> is <literal>STDIN</literal> or <literal>STDOUT</literal> is
specified, data is transmitted via the connection between the specified, data is transmitted via the connection between the
client frontend and the backend. client and the server.
</para>
<tip> </refsect1>
<para>
Do not confuse <command>COPY</command> with the <refsect1>
<application>psql</application> instruction <title>Parameters</title>
<command>\copy</command>. <command>\copy</command> invokes
<command>COPY FROM stdin</command> or <command>COPY TO <variablelist>
stdout</command>, and then fetches/stores the data in a file <varlistentry>
accessible to the <application>psql</application> client. Thus, <term><replaceable class="parameter">table</replaceable></term>
file accessibility and access rights depend on the client rather <listitem>
than the backend when <command>\copy</command> is used. <para>
</para> The name (possibly schema-qualified) of an existing table.
</tip> </para>
</para> </listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">column</replaceable></term>
<listitem>
<para>
An optional list of columns to be copied. If no column list is
specified, all columns will be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
The absolute path name of the input or output file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>STDIN</literal></term>
<listitem>
<para>
Specifies that input comes from the client application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>STDOUT</literal></term>
<listitem>
<para>
Specifies that output goes to the client application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>BINARY</literal></term>
<listitem>
<para>
Forces all data to be stored or read in binary format rather
than as text. You cannot specify the <option>DELIMITER</option>
or <option>NULL</option> options in binary mode.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>OIDS</literal></term>
<listitem>
<para>
Specifies copying the OID for each row. (An error is raised if
<literal>OIDS</literal> is specified for a table that does not
have OIDs.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">delimiter</replaceable></term>
<listitem>
<para>
The single character that separates columns within each row
(line) of the file. The default is a tab character.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">null string</replaceable></term>
<listitem>
<para>
The string that represents a null value. The default is
<literal>\N</literal> (backslash-N). You might prefer an empty
string, for example.
</para>
<note>
<para>
On a <command>COPY FROM</command>, any data item that matches
this string will be stored as a null value, so you should make
sure that you use the same string as you used with
<command>COPY TO</command>.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>COPY</computeroutput></term>
<listitem>
<para>
The copy operation completed successfully.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<refsect2 id="R2-SQL-COPY-3">
<refsect2info>
<date>2001-01-02</date>
</refsect2info>
<title>
Notes
</title>
<para> <para>
<command>COPY</command> can only be used with plain tables, not <command>COPY</command> can only be used with plain tables, not
with views. with views.
</para> </para>
<para> <para>
The BINARY keyword will force all data to be The <literal>BINARY</literal> key word will force all data to be
stored/read as binary format rather than as text. It is stored/read as binary format rather than as text. It is
somewhat faster than the normal copy command, but a binary copy somewhat faster than the normal text mode, but a binary format
file is not portable across machine architectures. file is not portable across machine architectures.
</para>
<para>
By default, a text copy uses a tab ("\t") character as a delimiter
between fields. The field delimiter may be changed to any other
single character with the keyword <option>DELIMITER</option>. Characters
in data fields that happen to match the delimiter character will be
backslash quoted.
</para> </para>
<para> <para>
You must have <firstterm>select privilege</firstterm> on any table You must have select privilege on any table
whose values are read by <command>COPY TO</command>, and whose values are read by <command>COPY TO</command>, and
<firstterm>insert privilege</firstterm> on a table into which values insert privilege on a table into which values
are being inserted by <command>COPY FROM</command>. The backend also are being inserted by <command>COPY FROM</command>.
needs appropriate Unix permissions for any file read or written by </para>
<command>COPY</command>.
<para>
Files named in a <command>COPY</command> command are read or written
directly by the server, not by the client application. Therefore,
they must reside on or be accessible to the database server machine,
not the client. They must be accessible to and readable or writable
by the <application>PostgreSQL</application> user (the user ID the
server runs as), not the client. <command>COPY</command> naming a
file is only allowed to database superusers, since it allows reading
or writing any file that the server has privileges to access.
</para>
<para>
Do not confuse <command>COPY</command> with the
<application>psql</application> instruction
<command>\copy</command>. <command>\copy</command> invokes
<command>COPY FROM STDIN</command> or <command>COPY TO
STDOUT</command>, and then fetches/stores the data in a file
accessible to the <application>psql</application> client. Thus,
file accessibility and access rights depend on the client rather
than the server when <command>\copy</command> is used.
</para>
<para>
It is recommended that the file name used in <command>COPY</command>
always be specified as an absolute path. This is enforced by the
server in the case of <command>COPY TO</command>, but for
<command>COPY FROM</command> you do have the option of reading from
a file specified by a relative path. The path will be interpreted
relative to the working directory of the server process (somewhere below
the data directory), not the client's working directory.
</para> </para>
<para> <para>
@ -272,87 +246,52 @@ ERROR: <replaceable>reason</replaceable>
<para> <para>
<command>COPY</command> stops operation at the first error. This <command>COPY</command> stops operation at the first error. This
should not lead to problems in the event of a <command>COPY should not lead to problems in the event of a <command>COPY
TO</command>, but the target relation will already have received TO</command>, but the target table will already have received
earlier rows in a <command>COPY FROM</command>. These rows will not earlier rows in a <command>COPY FROM</command>. These rows will not
be visible or accessible, but they still occupy disk space. This may be visible or accessible, but they still occupy disk space. This may
amount to a considerable amount of wasted disk space if the failure amount to a considerable amount of wasted disk space if the failure
happened well into a large copy operation. You may wish to invoke happened well into a large copy operation. You may wish to invoke
<command>VACUUM</command> to recover the wasted space. <command>VACUUM</command> to recover the wasted space.
</para> </para>
<para>
Files named in a <command>COPY</command> command are read or written
directly by the backend, not by the client application. Therefore,
they must reside on or be accessible to the database server machine,
not the client. They must be accessible to and readable or writable
by the <application>PostgreSQL</application> user (the user ID the
server runs as), not the client. <command>COPY</command> naming a
file is only allowed to database superusers, since it allows reading
or writing any file that the backend has privileges to access.
<tip>
<para>
The
<application>psql</application> instruction <command>\copy</command>
reads or writes files on the client machine with the client's
permissions, so it is not restricted to superusers.
</para>
</tip>
</para>
<para>
It is recommended that the file name used in <command>COPY</command>
always be specified as an absolute path. This is enforced by the
backend in the case of <command>COPY TO</command>, but for
<command>COPY FROM</command> you do have the option of reading from
a file specified by a relative path. The path will be interpreted
relative to the backend's working directory (somewhere below
<filename>$PGDATA</filename>), not the client's working directory.
</para>
</refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-COPY-2"> <refsect1>
<refsect1info>
<date>2001-01-02</date>
</refsect1info>
<title>File Formats</title> <title>File Formats</title>
<refsect2> <refsect2>
<refsect2info>
<date>2002-02-12</date>
</refsect2info>
<title>Text Format</title> <title>Text Format</title>
<para> <para>
When <command>COPY</command> is used without the BINARY option, When <command>COPY</command> is used without the <literal>BINARY</literal> option,
the file read or written is a text file with one line per table row. the data read or written is a text file with one line per table row.
Columns (attributes) in a row are separated by the delimiter character. Columns in a row are separated by the delimiter character.
The attribute values themselves are strings generated by the The column values themselves are strings generated by the
output function, or acceptable to the input function, of each output function, or acceptable to the input function, of each
attribute's data type. The specified null-value string is used in attribute's data type. The specified null-value string is used in
place of attributes that are NULL. place of columns that are null.
<command>COPY FROM</command> will raise an error if any line of the <command>COPY FROM</command> will raise an error if any line of the
input file contains more or fewer columns than are expected. input file contains more or fewer columns than are expected.
If <literal>OIDS</literal> is specified, the OID is read or written as the first column,
preceding the user data columns.
</para> </para>
<para>
If OIDS is specified, the OID is read or written as the first column,
preceding the user data columns. (An error is raised if OIDS is
specified for a table that does not have OIDs.)
</para>
<para> <para>
End of data can be represented by a single line containing just End of data can be represented by a single line containing just
backslash-period (<literal>\.</>). An end-of-data marker is backslash-period (<literal>\.</>). An end-of-data marker is
not necessary when reading from a Unix file, since the end of file not necessary when reading from a file, since the end of file
serves perfectly well; but an end marker must be provided when copying serves perfectly well; but an end marker must be provided when copying
data to or from a client application. data to or from a client application.
</para> </para>
<para> <para>
Backslash characters (<literal>\</>) may be used in the Backslash characters (<literal>\</>) may be used in the
<command>COPY</command> data to quote data characters that might <command>COPY</command> data to quote data characters that might
otherwise be taken as row or column delimiters. In particular, the otherwise be taken as row or column delimiters. In particular, the
following characters <emphasis>must</> be preceded by a backslash if following characters <emphasis>must</> be preceded by a backslash if
they appear as part of an attribute value: backslash itself, they appear as part of a column value: backslash itself,
newline, and the current delimiter character. newline, and the current delimiter character.
</para> </para>
<para> <para>
The following special backslash sequences are recognized by The following special backslash sequences are recognized by
<command>COPY FROM</command>: <command>COPY FROM</command>:
@ -404,47 +343,44 @@ ERROR: <replaceable>reason</replaceable>
backslash sequence, but it does use the other sequences listed above backslash sequence, but it does use the other sequences listed above
for those control characters. for those control characters.
</para> </para>
<para> <para>
Never put a backslash before a data character <literal>N</> or period Never put a backslash before a data character <literal>N</> or period
(<literal>.</>). Such pairs will be mistaken for the default null string (<literal>.</>). Such pairs will be mistaken for the default null string
or the end-of-data marker, respectively. Any other backslashed character or the end-of-data marker, respectively. Any other backslashed character
that is not mentioned in the above table will be taken to represent itself. that is not mentioned in the above table will be taken to represent itself.
</para> </para>
<para> <para>
It is strongly recommended that applications generating COPY data convert It is strongly recommended that applications generating COPY data convert
data newlines and carriage returns to the <literal>\n</> and data newlines and carriage returns to the <literal>\n</> and
<literal>\r</> sequences respectively. At present <literal>\r</> sequences respectively. At present it is
(<productname>PostgreSQL</productname> 7.2 and older versions) it is
possible to represent a data carriage return without any special quoting, possible to represent a data carriage return without any special quoting,
and to represent a data newline by a backslash and newline. However, and to represent a data newline by a backslash and newline. However,
these representations will not be accepted by default in future releases. these representations will not be accepted by default in future releases.
</para> </para>
<para> <para>
Note that the end of each row is marked by a Unix-style newline Note that the end of each row is marked by a Unix-style newline
("\n"). Presently, <command>COPY FROM</command> will not behave as (<quote><literal>\n</></>). Presently, <command>COPY FROM</command> will not behave as
desired if given a file containing DOS- or Mac-style newlines. desired if given a file containing DOS- or Mac-style newlines.
This is expected to change in future releases. This is expected to change in future releases.
</para> </para>
</refsect2> </refsect2>
<refsect2> <refsect2>
<refsect2info>
<date>2001-01-02</date>
</refsect2info>
<title>Binary Format</title> <title>Binary Format</title>
<para> <para>
The file format used for <command>COPY BINARY</command> changed in The file format used for <command>COPY BINARY</command> changed in
<application>PostgreSQL</application> v7.1. The new format consists <application>PostgreSQL</application> 7.1. The new format consists
of a file header, zero or more tuples, and a file trailer. of a file header, zero or more tuples containing the row data, and
a file trailer.
</para> </para>
<refsect3> <refsect3>
<refsect3info> <title>File Header</title>
<date>2001-01-02</date>
</refsect3info>
<title>
File Header
</title>
<para> <para>
The file header consists of 24 bytes of fixed fields, followed The file header consists of 24 bytes of fixed fields, followed
by a variable-length header extension area. The fixed fields are: by a variable-length header extension area. The fixed fields are:
@ -454,11 +390,11 @@ ERROR: <replaceable>reason</replaceable>
<term>Signature</term> <term>Signature</term>
<listitem> <listitem>
<para> <para>
12-byte sequence <literal>PGBCOPY\n\377\r\n\0</> --- note that the null 12-byte sequence <literal>PGBCOPY\n\377\r\n\0</> --- note that the zero byte
is a required part of the signature. (The signature is designed to allow is a required part of the signature. (The signature is designed to allow
easy identification of files that have been munged by a non-8-bit-clean easy identification of files that have been munged by a non-8-bit-clean
transfer. This signature will be changed by newline-translation transfer. This signature will be changed by newline-translation
filters, dropped nulls, dropped high bits, or parity changes.) filters, dropped zero bytes, dropped high bits, or parity changes.)
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -467,7 +403,7 @@ filters, dropped nulls, dropped high bits, or parity changes.)
<term>Integer layout field</term> <term>Integer layout field</term>
<listitem> <listitem>
<para> <para>
int32 constant 0x01020304 in source's byte order. Potentially, a reader 32-bit integer constant 0x01020304 in source's byte order. Potentially, a reader
could engage in byte-flipping of subsequent fields if the wrong byte could engage in byte-flipping of subsequent fields if the wrong byte
order is detected here. order is detected here.
</para> </para>
@ -478,7 +414,7 @@ order is detected here.
<term>Flags field</term> <term>Flags field</term>
<listitem> <listitem>
<para> <para>
int32 bit mask to denote important aspects of the file format. Bits are 32-bit integer bit mask to denote important aspects of the file format. Bits are
numbered from 0 (<acronym>LSB</>) to 31 (<acronym>MSB</>) --- note that this field is stored numbered from 0 (<acronym>LSB</>) to 31 (<acronym>MSB</>) --- note that this field is stored
with source's endianness, as are all subsequent integer fields. Bits with source's endianness, as are all subsequent integer fields. Bits
16-31 are reserved to denote critical file format issues; a reader 16-31 are reserved to denote critical file format issues; a reader
@ -491,7 +427,7 @@ only one flag bit is defined, and the rest must be zero:
<term>Bit 16</term> <term>Bit 16</term>
<listitem> <listitem>
<para> <para>
if 1, OIDs are included in the dump; if 0, not if 1, OIDs are included in the data; if 0, not
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -504,8 +440,8 @@ only one flag bit is defined, and the rest must be zero:
<term>Header extension area length</term> <term>Header extension area length</term>
<listitem> <listitem>
<para> <para>
int32 length in bytes of remainder of header, not including self. In 32-bit integer, length in bytes of remainder of header, not including self.
the initial version this will be zero, and the first tuple follows Currently, this is zero, and the first tuple follows
immediately. Future changes to the format might allow additional data immediately. Future changes to the format might allow additional data
to be present in the header. A reader should silently skip over any header to be present in the header. A reader should silently skip over any header
extension data it does not know what to do with. extension data it does not know what to do with.
@ -531,17 +467,12 @@ is left for a later release.
</refsect3> </refsect3>
<refsect3> <refsect3>
<refsect3info> <title>Tuples</title>
<date>2001-01-02</date>
</refsect3info>
<title>
Tuples
</title>
<para> <para>
Each tuple begins with an int16 count of the number of fields in the Each tuple begins with a 16-bit integer count of the number of fields in the
tuple. (Presently, all tuples in a table will have the same count, but tuple. (Presently, all tuples in a table will have the same count, but
that might not always be true.) Then, repeated for each field in the that might not always be true.) Then, repeated for each field in the
tuple, there is an int16 <structfield>typlen</> word possibly followed by field data. tuple, there is a 16-bit integer <structfield>typlen</> word possibly followed by field data.
The <structfield>typlen</> field is interpreted thus: The <structfield>typlen</> field is interpreted thus:
<variablelist> <variablelist>
@ -549,7 +480,7 @@ The <structfield>typlen</> field is interpreted thus:
<term>Zero</term> <term>Zero</term>
<listitem> <listitem>
<para> <para>
Field is NULL. No data follows. Field is null. No data follows.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -558,7 +489,7 @@ The <structfield>typlen</> field is interpreted thus:
<term>&gt; 0</term> <term>&gt; 0</term>
<listitem> <listitem>
<para> <para>
Field is a fixed-length data type. Exactly N Field is a fixed-length data type. Exactly that many
bytes of data follow the <structfield>typlen</> word. bytes of data follow the <structfield>typlen</> word.
</para> </para>
</listitem> </listitem>
@ -570,7 +501,7 @@ The <structfield>typlen</> field is interpreted thus:
<para> <para>
Field is a <literal>varlena</> data type. The next four Field is a <literal>varlena</> data type. The next four
bytes are the <literal>varlena</> header, which contains bytes are the <literal>varlena</> header, which contains
the total value length including itself. the total value length including the header itself.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -587,7 +518,7 @@ The <structfield>typlen</> field is interpreted thus:
</para> </para>
<para> <para>
For non-NULL fields, the reader can check that the <structfield>typlen</> matches the For nonnull fields, the reader can check that the <structfield>typlen</> matches the
expected <structfield>typlen</> for the destination column. This provides a simple expected <structfield>typlen</> for the destination column. This provides a simple
but very useful check that the data is as expected. but very useful check that the data is as expected.
</para> </para>
@ -602,23 +533,19 @@ you from moving a binary file across machines).
</para> </para>
<para> <para>
If OIDs are included in the dump, the OID field immediately follows the If OIDs are included in the file, the OID field immediately follows the
field-count word. It is a normal field except that it's not included field-count word. It is a normal field except that it's not included
in the field-count. In particular it has a <structfield>typlen</> --- this will allow in the field-count. In particular it has a <structfield>typlen</> --- this will allow
handling of 4-byte vs 8-byte OIDs without too much pain, and will allow handling of 4-byte vs. 8-byte OIDs without too much pain, and will allow
OIDs to be shown as NULL if that ever proves desirable. OIDs to be shown as null if that ever proves desirable.
</para> </para>
</refsect3> </refsect3>
<refsect3> <refsect3>
<refsect3info> <title>File Trailer</title>
<date>2001-01-02</date>
</refsect3info>
<title>
File Trailer
</title>
<para> <para>
The file trailer consists of an int16 word containing -1. This is The file trailer consists of an 16-bit integer word containing -1. This is
easily distinguished from a tuple's field-count word. easily distinguished from a tuple's field-count word.
</para> </para>
@ -631,48 +558,47 @@ OIDs to be shown as NULL if that ever proves desirable.
</refsect2> </refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-COPY-3"> <refsect1>
<title> <title>Examples</title>
Usage
</title>
<para> <para>
The following example copies a table to standard output, The following example copies a table to the client
using a vertical bar (|) as the field delimiter: using the vertical bar (<literal>|</literal>) as the field delimiter:
<programlisting>
COPY country TO STDOUT WITH DELIMITER '|';
</programlisting>
</para> </para>
<programlisting>
COPY country TO <filename>stdout</filename> WITH DELIMITER '|';
</programlisting>
<para> <para>
To copy data from a Unix file into the <literal>country</> table: To copy data from a file into the <literal>country</> table:
</para> <programlisting>
<programlisting>
COPY country FROM '/usr1/proj/bray/sql/country_data'; COPY country FROM '/usr1/proj/bray/sql/country_data';
</programlisting> </programlisting>
</para>
<para> <para>
Here is a sample of data suitable for copying into a table from Here is a sample of data suitable for copying into a table from
<filename>stdin</filename> (so it has the termination sequence on the <literal>STDIN</literal> (so it must have the termination sequence on the
last line): last line):
</para> <programlisting>
<programlisting>
AF AFGHANISTAN AF AFGHANISTAN
AL ALBANIA AL ALBANIA
DZ ALGERIA DZ ALGERIA
ZM ZAMBIA ZM ZAMBIA
ZW ZIMBABWE ZW ZIMBABWE
\. \.
</programlisting> </programlisting>
<para> Note that the white space on each line is actually a tab character.
Note that the white space on each line is actually a TAB.
</para> </para>
<para> <para>
The following is the same data, output in binary format on a The following is the same data, output in binary format on a
Linux/i586 machine. The data is shown after filtering through the Linux/i586 machine. The data is shown after filtering through the
Unix utility <command>od -c</command>. The table has three fields; Unix utility <command>od -c</command>. The table has three columns;
the first is <type>char(2)</type>, the second is <type>text</type>, the first has type <type>char(2)</type>, the second has type <type>text</type>,
and the third is <type>integer</type>. All the rows have a null value and the third has type <type>integer</type>. All the rows have a null value
in the third field. in the third column.
</para> <programlisting>
<programlisting>
0000000 P G B C O P Y \n 377 \r \n \0 004 003 002 001 0000000 P G B C O P Y \n 377 \r \n \0 004 003 002 001
0000020 \0 \0 \0 \0 \0 \0 \0 \0 003 \0 377 377 006 \0 \0 \0 0000020 \0 \0 \0 \0 \0 \0 \0 \0 003 \0 377 377 006 \0 \0 \0
0000040 A F 377 377 017 \0 \0 \0 A F G H A N I S 0000040 A F 377 377 017 \0 \0 \0 A F G H A N I S
@ -683,38 +609,33 @@ ZW ZIMBABWE
0000160 M 377 377 \n \0 \0 \0 Z A M B I A \0 \0 003 0000160 M 377 377 \n \0 \0 \0 Z A M B I A \0 \0 003
0000200 \0 377 377 006 \0 \0 \0 Z W 377 377 \f \0 \0 \0 Z 0000200 \0 377 377 006 \0 \0 \0 Z W 377 377 \f \0 \0 \0 Z
0000220 I M B A B W E \0 \0 377 377 0000220 I M B A B W E \0 \0 377 377
</programlisting> </programlisting>
</para>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-COPY-6"> <refsect1>
<title> <title>Compatibility</title>
Compatibility
</title>
<refsect2 id="R2-SQL-COPY-4"> <para>
<refsect2info> There is no <command>COPY</command> statement in the SQL standard.
<date>1998-09-08</date> </para>
</refsect2info>
<title> <para>
SQL92 The following syntax was used before PostgreSQL version 7.3 and is
</title> still supported:
<para>
There is no <command>COPY</command> statement in SQL92. <synopsis>
</para> COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ]
<para> FROM { '<replaceable class="parameter">filename</replaceable>' | STDIN }
The following syntax was used by pre-7.3 applications and is still supported: [ [USING] DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ]
<synopsis> [ WITH NULL AS '<replaceable class="parameter">null string</replaceable>' ]
COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ]
FROM { '<replaceable class="parameter">filename</replaceable>' | <filename>stdin</filename> } COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ]
[ [USING] DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ] TO { '<replaceable class="parameter">filename</replaceable>' | STDOUT }
[ WITH NULL AS '<replaceable class="parameter">null string</replaceable>' ] [ [USING] DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ]
COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ] [ WITH NULL AS '<replaceable class="parameter">null string</replaceable>' ]
TO { '<replaceable class="parameter">filename</replaceable>' | <filename>stdout</filename> } </synopsis>
[ [USING] DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ] </para>
[ WITH NULL AS '<replaceable class="parameter">null string</replaceable>' ]
</synopsis>
</para>
</refsect2>
</refsect1> </refsect1>
</refentry> </refentry>