mirror of https://github.com/postgres/postgres
Bring SQL ref pages to consistent format, part 1.
This commit is contained in:
parent
72aa9488d3
commit
7c084d148f
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -8,130 +8,82 @@ PostgreSQL documentation
|
|||
<refentrytitle id="sql-abort-title">ABORT</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>
|
||||
ABORT
|
||||
</refname>
|
||||
<refpurpose>
|
||||
abort the current transaction
|
||||
</refpurpose>
|
||||
<refname>ABORT</refname>
|
||||
<refpurpose>abort the current transaction</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>1999-07-20</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
<synopsis>
|
||||
ABORT [ WORK | TRANSACTION ]
|
||||
</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>
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-ABORT-1">
|
||||
<refsect1info>
|
||||
<date>1998-09-27</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<command>ABORT</command> rolls back the current transaction and causes
|
||||
all the updates made by the transaction to be discarded.
|
||||
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.
|
||||
</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 id="R1-SQL-ABORT-2">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Diagnostics</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>
|
||||
To abort all changes:
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
ABORT WORK;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-ABORT-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-ABORT-4">
|
||||
<refsect2info>
|
||||
<date>1998-09-27</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
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>
|
||||
<para>
|
||||
This command is a <productname>PostgreSQL</productname> extension
|
||||
present for historical reasons. <command>ROLLBACK</command> is the
|
||||
equivalent standard SQL command.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -32,18 +32,18 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RESET <replacea
|
|||
value becomes the session default value.
|
||||
The database-specific default
|
||||
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>
|
||||
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.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect2>
|
||||
<title>Parameters</title>
|
||||
<refsect1>
|
||||
<title>Parameters</title>
|
||||
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><replaceable class="PARAMETER">name</replaceable></term>
|
||||
|
@ -77,14 +77,11 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RESET <replacea
|
|||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Diagnostics</title>
|
||||
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><computeroutput>ALTER DATABASE</computeroutput></term>
|
||||
|
@ -105,7 +102,6 @@ ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RESET <replacea
|
|||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -8,92 +8,29 @@ PostgreSQL documentation
|
|||
<refentrytitle id="SQL-ALTERGROUP-title">ALTER GROUP</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>
|
||||
ALTER GROUP
|
||||
</refname>
|
||||
<refpurpose>
|
||||
add users to a group or remove users from a group
|
||||
</refpurpose>
|
||||
<refname>ALTER GROUP</refname>
|
||||
<refpurpose>add users to a group or remove users from a group</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>2000-01-14</date>
|
||||
</refsynopsisdivinfo>
|
||||
<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>
|
||||
<synopsis>
|
||||
ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> ADD USER <replaceable class="PARAMETER">username</replaceable> [, ... ]
|
||||
ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> DROP USER <replaceable class="PARAMETER">username</replaceable> [, ... ]
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-ALTERGROUP-1">
|
||||
<refsect1info>
|
||||
<date>2000-01-14</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<command>ALTER GROUP</command> is used to add or remove users from a
|
||||
group. Only database superusers can use this command.
|
||||
Adding a user to a group does not create the user. Similarly, removing
|
||||
a user from a group does not drop the user itself.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Use <xref linkend="SQL-CREATEGROUP" endterm="SQL-CREATEGROUP-title">
|
||||
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>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-ALTERGROUP-2">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Parameter</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>
|
||||
Add users to a group:
|
||||
|
||||
|
@ -121,24 +96,13 @@ ALTER GROUP workers DROP USER beth;
|
|||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-ALTERGROUP-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-ALTERGROUP-4">
|
||||
<refsect2info>
|
||||
<date>2000-01-14</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
SQL92
|
||||
</title>
|
||||
<para>
|
||||
There is no <command>ALTER GROUP</command> statement in
|
||||
<acronym>SQL92</acronym>. The concept of roles is
|
||||
similar.
|
||||
</para>
|
||||
</refsect2>
|
||||
<para>
|
||||
There is no <command>ALTER GROUP</command> statement in the SQL
|
||||
standard. The concept of roles is similar.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -8,19 +8,14 @@ PostgreSQL documentation
|
|||
<refentrytitle id="sql-altertable-title">ALTER TABLE</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>
|
||||
ALTER TABLE
|
||||
</refname>
|
||||
<refpurpose>
|
||||
change the definition of a table
|
||||
</refpurpose>
|
||||
<refname>ALTER TABLE</refname>
|
||||
<refpurpose>change the definition of a table</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>1999-07-20</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
<synopsis>
|
||||
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> [ ... ] ]
|
||||
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>
|
||||
ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
|
||||
CLUSTER ON <replaceable class="PARAMETER">index_name</replaceable>
|
||||
</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>
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-ALTERTABLE-1">
|
||||
<refsect1info>
|
||||
<date>1998-04-15</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<command>ALTER TABLE</command> changes the definition of an existing table.
|
||||
There are several sub-forms:
|
||||
</para>
|
||||
There are several subforms:
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>ADD COLUMN</term>
|
||||
<term><literal>ADD COLUMN</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
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>
|
||||
<term>DROP COLUMN</term>
|
||||
<term><literal>DROP COLUMN</literal></term>
|
||||
<listitem>
|
||||
<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
|
||||
dropped as well. You will need to say <literal>CASCADE</> if
|
||||
anything outside the table depends on the column --- for example,
|
||||
foreign key references, views, etc.
|
||||
anything outside the table depends on the column, for example,
|
||||
foreign key references or views.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>SET/DROP DEFAULT</term>
|
||||
<term><literal>SET</literal>/<literal>DROP DEFAULT</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
These forms set or remove the default value for a column. Note
|
||||
that defaults only apply to subsequent <command>INSERT</command>
|
||||
These forms set or remove the default value for a column.
|
||||
The default values only apply to subsequent <command>INSERT</command>
|
||||
commands; they do not cause rows already in the table to change.
|
||||
Defaults may also be created for views, in which case they are
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>SET/DROP NOT NULL</term>
|
||||
<term><literal>SET</literal>/<literal>DROP NOT NULL</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
These forms change whether a column is marked to allow NULL
|
||||
values or to reject NULL values. You may only <literal>SET NOT NULL</>
|
||||
when the table contains no null values in the column.
|
||||
These forms change whether a column is marked to allow null
|
||||
values or to reject null values. You can only use <literal>SET
|
||||
NOT NULL</> when the column contains no null values.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>SET STATISTICS</term>
|
||||
<term><literal>SET STATISTICS</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This form
|
||||
|
@ -281,39 +116,40 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>SET STORAGE</term>
|
||||
<term><literal>SET STORAGE</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
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
|
||||
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,
|
||||
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
|
||||
data types that support it. The use of <literal>EXTERNAL</literal> will
|
||||
make substring operations on a TEXT column faster, at the penalty of
|
||||
data types that support it. The use of <literal>EXTERNAL</literal> will, for example,
|
||||
make substring operations on a <type>text</type> column faster, at the penalty of
|
||||
increased storage space.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>SET WITHOUT OIDS</term>
|
||||
<term><literal>SET WITHOUT OIDS</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Removes the <literal>OID</literal> column from the the table. Removing (setting without)
|
||||
oids from a table also do not occur immediately. The space an <literal>OID</literal>
|
||||
uses will be reclaimed when the tuple is updated. Without updating the tuple, both the
|
||||
space and the value of the <literal>OID</literal> are maintained indefinitely. This is
|
||||
semantically similar to the <literal>DROP COLUMN</literal> process.
|
||||
This form removes the <literal>oid</literal> column from the
|
||||
table. Removing OIDs from a table does not occur immediately.
|
||||
The space that the OID uses will be reclaimed when the row is
|
||||
updated. Without updating the row, both the space and the value
|
||||
of the OID are kept indefinitely. This is semantically similar
|
||||
to the <literal>DROP COLUMN</literal> process.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>RENAME</term>
|
||||
<term><literal>RENAME</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The <literal>RENAME</literal> forms change the name of a table
|
||||
|
@ -324,7 +160,7 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>ADD <replaceable class="PARAMETER">table_constraint</replaceable></term>
|
||||
<term><literal>ADD <replaceable class="PARAMETER">table_constraint</replaceable></literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
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>
|
||||
<term>DROP CONSTRAINT</term>
|
||||
<term><literal>DROP CONSTRAINT</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This form drops constraints on a table.
|
||||
|
@ -346,17 +182,17 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>OWNER</term>
|
||||
<term><literal>OWNER</literal></term>
|
||||
<listitem>
|
||||
<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.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>CLUSTER</term>
|
||||
<term><literal>CLUSTER</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
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>
|
||||
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You must own the table to use <command>ALTER TABLE</>; except for
|
||||
<command>ALTER TABLE OWNER</>, which may only be executed by a superuser.
|
||||
</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>
|
||||
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>
|
||||
In the current implementation of <literal>ADD COLUMN</literal>,
|
||||
default and NOT NULL clauses for the new column are not supported.
|
||||
The new column always comes into being with all values NULL.
|
||||
default and <literal>NOT NULL</> clauses for the new column are not supported.
|
||||
The new column always comes into being with all values null.
|
||||
You can use the <literal>SET DEFAULT</literal> form
|
||||
of <command>ALTER TABLE</command> to set the default afterward.
|
||||
(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>
|
||||
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
|
||||
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
|
||||
on-disk size of your table, as the space occupied
|
||||
by the dropped column is not reclaimed. The space will be
|
||||
reclaimed over time as existing rows are updated.
|
||||
To reclaim the space at once, do a dummy <command>UPDATE</> of all rows
|
||||
and then vacuum, as in:
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
UPDATE table SET col = col;
|
||||
VACUUM FULL table;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If a table has any descendant tables, it is not permitted to ADD
|
||||
or RENAME a column in the parent table without doing the same to
|
||||
the descendants --- that is, <command>ALTER TABLE ONLY</command>
|
||||
If a table has any descendant tables, it is not permitted to add
|
||||
or rename a column in the parent table without doing the same to
|
||||
the descendants. That is, <command>ALTER TABLE ONLY</command>
|
||||
will be rejected. This ensures that the descendants always have
|
||||
columns matching the parent.
|
||||
</para>
|
||||
|
@ -431,126 +406,115 @@ VACUUM FULL table;
|
|||
</para>
|
||||
|
||||
<para>
|
||||
Changing any part of the schema of a system
|
||||
catalog is not permitted.
|
||||
Changing any part of a system catalog table is not permitted.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-ALTERTABLE-2">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Examples</title>
|
||||
|
||||
<para>
|
||||
To add a column of type <type>varchar</type> to a table:
|
||||
<programlisting>
|
||||
ALTER TABLE distributors ADD COLUMN address VARCHAR(30);
|
||||
</programlisting>
|
||||
<programlisting>
|
||||
ALTER TABLE distributors ADD COLUMN address varchar(30);
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To drop a column from a table:
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
ALTER TABLE distributors DROP COLUMN address RESTRICT;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To rename an existing column:
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
ALTER TABLE distributors RENAME COLUMN address TO city;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To rename an existing table:
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
ALTER TABLE distributors RENAME TO suppliers;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To add a NOT NULL constraint to a column:
|
||||
<programlisting>
|
||||
To add a not-null constraint to a column:
|
||||
<programlisting>
|
||||
ALTER TABLE distributors ALTER COLUMN street SET NOT NULL;
|
||||
</programlisting>
|
||||
To remove a NOT NULL constraint from a column:
|
||||
<programlisting>
|
||||
</programlisting>
|
||||
To remove a not-null constraint from a column:
|
||||
<programlisting>
|
||||
ALTER TABLE distributors ALTER COLUMN street DROP NOT NULL;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To add a check constraint to a table:
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5);
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To remove a check constraint from a table and all its children:
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
ALTER TABLE distributors DROP CONSTRAINT zipchk;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To add a foreign key constraint to a table:
|
||||
<programlisting>
|
||||
ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses(address) MATCH FULL;
|
||||
</programlisting>
|
||||
<programlisting>
|
||||
ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses (address) MATCH FULL;
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To add a (multicolumn) unique constraint to a table:
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
ALTER TABLE distributors ADD CONSTRAINT dist_id_zipcode_key UNIQUE (dist_id, zipcode);
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To add an automatically named primary key constraint to a table, noting
|
||||
that a table can only ever have one primary key:
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
ALTER TABLE distributors ADD PRIMARY KEY (dist_id);
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-ALTERTABLE-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-ALTERTABLE-4">
|
||||
<refsect2info>
|
||||
<date>1998-04-15</date>
|
||||
</refsect2info>
|
||||
<title>SQL92</title>
|
||||
<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>
|
||||
The <literal>ADD COLUMN</literal> form conforms with the SQL
|
||||
standard, 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 conformance.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The clauses to rename tables, columns, indexes, and sequences are
|
||||
<productname>PostgreSQL</productname> extensions from SQL92.
|
||||
</para>
|
||||
<para>
|
||||
The clauses to rename tables, columns, indexes, views, and sequences are
|
||||
<productname>PostgreSQL</productname> extensions of the SQL standard.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<command>ALTER TABLE DROP COLUMN</> can be used to drop the only column
|
||||
of a table, leaving a zero-column table. This is an extension from SQL92,
|
||||
which disallows zero-column tables.
|
||||
</para>
|
||||
|
||||
</refsect2>
|
||||
<para>
|
||||
<command>ALTER TABLE DROP COLUMN</> can be used to drop the only
|
||||
column of a table, leaving a zero-column table. This is an
|
||||
extension of SQL, which disallows zero-column tables.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
<refentry id="SQL-ALTERTRIGGER">
|
||||
<refmeta>
|
||||
<refentrytitle id="sql-altertrigger-title">
|
||||
ALTER TRIGGER
|
||||
</refentrytitle>
|
||||
<refentrytitle id="sql-altertrigger-title">ALTER TRIGGER</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>
|
||||
ALTER TRIGGER
|
||||
</refname>
|
||||
<refpurpose>
|
||||
change the definition of a trigger
|
||||
</refpurpose>
|
||||
<refname>ALTER TRIGGER</refname>
|
||||
<refpurpose>change the definition of a trigger</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>2002-04-19</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
<synopsis>
|
||||
ALTER TRIGGER <replaceable class="PARAMETER">trigger</replaceable> ON <replaceable class="PARAMETER">table</replaceable>
|
||||
RENAME TO <replaceable class="PARAMETER">newname</replaceable>
|
||||
</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>
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-ALTERTRIGGER-1">
|
||||
<refsect1info>
|
||||
<date>2002-04-19</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<command>ALTER TRIGGER</command> changes the definition of an existing trigger.
|
||||
The <literal>RENAME</literal> clause causes the name of a trigger on the given table
|
||||
to change without otherwise changing the trigger definition.
|
||||
<command>ALTER TRIGGER</command> changes properties of an existing
|
||||
trigger. The <literal>RENAME</literal> clause changes the name of
|
||||
the given trigger without otherwise changing the trigger
|
||||
definition.
|
||||
</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>
|
||||
|
||||
<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 id="R1-SQL-ALTERTRIGGER-2">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Parameter</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>
|
||||
To rename an existing trigger:
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
ALTER TRIGGER emp_stamp ON emp RENAME TO emp_track_chgs;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-ALTERTRIGGER-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-ALTERTRIGGER-4">
|
||||
<refsect2info>
|
||||
<date>2002-04-19</date>
|
||||
</refsect2info>
|
||||
<title>SQL92</title>
|
||||
<para>
|
||||
<command>ALTER TRIGGER</command> is a <productname>PostgreSQL</>
|
||||
extension of SQL92.
|
||||
</para>
|
||||
</refsect2>
|
||||
<para>
|
||||
<command>ALTER TRIGGER</command> is a <productname>PostgreSQL</>
|
||||
extension of the SQL standard.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -20,7 +20,7 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> [ [ WITH ] <rep
|
|||
|
||||
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
|
||||
| CREATEUSER | NOCREATEUSER
|
||||
| VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
|
||||
|
@ -42,8 +42,8 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
|
|||
<para>
|
||||
The first variant of this command in the synopsis changes certain
|
||||
global user privileges and authentication settings. (See below for
|
||||
details.) Only a database superuser can change privileges and
|
||||
password expiration with this command. Ordinary users can only
|
||||
details.) Only a database superuser can change these privileges and
|
||||
the password expiration with this command. Ordinary users can only
|
||||
change their own password.
|
||||
</para>
|
||||
|
||||
|
@ -52,15 +52,15 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
|
|||
a specified configuration variable. Whenever the user subsequently
|
||||
starts a new session, the specified value becomes the session default,
|
||||
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.
|
||||
Superusers can change anyone's session defaults.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect2>
|
||||
<title>Parameters</title>
|
||||
<refsect1>
|
||||
<title>Parameters</title>
|
||||
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><replaceable class="PARAMETER">username</replaceable></term>
|
||||
|
@ -99,8 +99,8 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
|
|||
<listitem>
|
||||
<para>
|
||||
These clauses define a user's ability to create databases. If
|
||||
<literal>CREATEDB</literal> is specified, the user being
|
||||
defined will be allowed to create his own databases. Using
|
||||
<literal>CREATEDB</literal> is specified, the user
|
||||
will be allowed to create his own databases. Using
|
||||
<literal>NOCREATEDB</literal> will deny a user the ability to
|
||||
create databases.
|
||||
</para>
|
||||
|
@ -125,7 +125,7 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
|
|||
<para>
|
||||
The date (and, optionally, the time)
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -152,14 +152,11 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
|
|||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Diagnostics</title>
|
||||
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><computeroutput>ALTER USER</computeroutput></term>
|
||||
|
@ -175,12 +172,11 @@ ALTER USER <replaceable class="PARAMETER">username</replaceable> RESET <replacea
|
|||
<listitem>
|
||||
<para>
|
||||
Error message returned if the specified user is not known to
|
||||
the database.
|
||||
the database system.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
@ -226,10 +222,10 @@ ALTER USER manuel VALID UNTIL 'Jan 31 2030';
|
|||
|
||||
<para>
|
||||
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</>:
|
||||
<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>
|
||||
</para>
|
||||
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -8,97 +8,24 @@ PostgreSQL documentation
|
|||
<refentrytitle id="sql-analyze-title">ANALYZE</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>
|
||||
ANALYZE
|
||||
</refname>
|
||||
<refpurpose>
|
||||
collect statistics about a database
|
||||
</refpurpose>
|
||||
<refname>ANALYZE</refname>
|
||||
<refpurpose>collect statistics about a database</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>2001-05-04</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
<synopsis>
|
||||
ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
|
||||
</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>
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-ANALYZE-1">
|
||||
<refsect1info>
|
||||
<date>2001-05-04</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<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 query planner uses the statistics to help determine the most efficient
|
||||
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
|
||||
current database. With a parameter, <command>ANALYZE</command> examines
|
||||
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>
|
||||
</refsect1>
|
||||
|
||||
<refsect2 id="R2-SQL-ANALYZE-3">
|
||||
<refsect2info>
|
||||
<date>2001-05-04</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Notes
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Parameters</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><literal>VERBOSE</literal></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>
|
||||
</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>
|
||||
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>
|
||||
For large tables, <command>ANALYZE</command> takes a random sample of the
|
||||
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
|
||||
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
|
||||
|
@ -159,7 +131,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> [ (<rep
|
|||
The extent of analysis can be controlled by adjusting the
|
||||
<literal>default_statistics_target</> parameter variable, or on a
|
||||
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
|
||||
<xref linkend="sql-altertable" endterm="sql-altertable-title">). The
|
||||
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 particular, setting the statistics target to zero disables collection of
|
||||
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.
|
||||
</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
|
||||
to do <command>ANALYZE</command>.
|
||||
</para>
|
||||
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-ANALYZE-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-ANALYZE-4">
|
||||
<refsect2info>
|
||||
<date>2001-05-04</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
SQL92
|
||||
</title>
|
||||
<para>
|
||||
There is no <command>ANALYZE</command> statement in <acronym>SQL92</acronym>.
|
||||
</para>
|
||||
</refsect2>
|
||||
<para>
|
||||
There is no <command>ANALYZE</command> statement in the SQL standard.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -8,218 +8,137 @@ PostgreSQL documentation
|
|||
<refentrytitle id="SQL-BEGIN-TITLE">BEGIN</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>
|
||||
BEGIN
|
||||
</refname>
|
||||
<refpurpose>
|
||||
start a transaction block
|
||||
</refpurpose>
|
||||
|
||||
</refnamediv>
|
||||
<refname>BEGIN</refname>
|
||||
<refpurpose>start a transaction block</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>1999-07-20</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
<synopsis>
|
||||
BEGIN [ WORK | TRANSACTION ]
|
||||
</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>
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-BEGIN-1">
|
||||
<refsect1info>
|
||||
<date>1999-06-11</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
By default, <productname>PostgreSQL</productname> executes transactions
|
||||
in <firstterm>unchained mode</firstterm>
|
||||
(also known as <quote>autocommit</quote> in other database
|
||||
systems).
|
||||
In other words, each user statement is executed in its own transaction
|
||||
and a commit is implicitly performed at the end of the statement
|
||||
(if execution was successful, otherwise a rollback is done).
|
||||
<command>BEGIN</command> initiates a user transaction in chained mode,
|
||||
i.e., all user statements after <command>BEGIN</command> command will
|
||||
be executed in a single transaction until an explicit
|
||||
<xref linkend="sql-commit" endterm="sql-commit-title"> or
|
||||
<xref linkend="sql-rollback" endterm="sql-rollback-title">.
|
||||
Statements are executed more quickly in chained mode,
|
||||
because transaction start/commit requires significant CPU and disk
|
||||
activity. Execution of multiple statements inside a transaction
|
||||
is also useful to ensure consistency when changing several
|
||||
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.
|
||||
By default, <productname>PostgreSQL</productname> executes
|
||||
transactions in <quote>autocommit</quote> mode, that is, each
|
||||
statement is executed in its own transaction and a commit is
|
||||
implicitly performed at the end of the statement (if execution was
|
||||
successful, otherwise a rollback is done).
|
||||
<command>BEGIN</command> initiates a transaction block, that is,
|
||||
all statements after <command>BEGIN</command> command will be
|
||||
executed in a single transaction until an explicit <xref
|
||||
linkend="sql-commit" endterm="sql-commit-title"> or <xref
|
||||
linkend="sql-rollback" endterm="sql-rollback-title">. Statements
|
||||
are executed more quickly in a transaction block, because
|
||||
transaction start/commit requires significant CPU and disk
|
||||
activity. Execution of multiple statements inside a transaction is
|
||||
also useful to ensure consistency when changing several related
|
||||
tables: other sessions will be unable to see the intermediate states
|
||||
wherein not all the related updates have been done.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect2 id="R2-SQL-BEGIN-3">
|
||||
<refsect2info>
|
||||
<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>
|
||||
<refsect1>
|
||||
<title>Parameters</title>
|
||||
|
||||
<para>
|
||||
Refer to <xref linkend="sql-lock" endterm="sql-lock-title">
|
||||
for further information
|
||||
about locking tables inside a transaction.
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><literal>WORK</literal></term>
|
||||
<term><literal>TRANSACTION</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Optional key words. They have no effect.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<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>
|
||||
If you turn <varname>autocommit</> mode off, then <command>BEGIN</>
|
||||
is not required: any SQL command automatically starts a transaction.
|
||||
</para>
|
||||
</refsect2>
|
||||
<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>
|
||||
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 id="R1-SQL-BEGIN-2">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Examples</title>
|
||||
|
||||
<para>
|
||||
To begin a user transaction:
|
||||
To begin a transaction block:
|
||||
|
||||
<programlisting>
|
||||
BEGIN WORK;
|
||||
</programlisting>
|
||||
<programlisting>
|
||||
BEGIN;
|
||||
</programlisting>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-BEGIN-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-BEGIN-4">
|
||||
<refsect2info>
|
||||
<date>1999-06-11</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
SQL92
|
||||
</title>
|
||||
<para>
|
||||
<command>BEGIN</command> is a <productname>PostgreSQL</productname>
|
||||
language extension. There is no explicit <command>BEGIN</command>
|
||||
command in the SQL standard; transaction initiation is
|
||||
always implicit and it terminates either with a
|
||||
<command>COMMIT</command> or <command>ROLLBACK</command> statement.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<command>BEGIN</command>
|
||||
is a <productname>PostgreSQL</productname> language extension.
|
||||
There is no explicit <command>BEGIN</command>
|
||||
command in <acronym>SQL92</acronym>;
|
||||
transaction initiation is always implicit and it terminates either
|
||||
with a <command>COMMIT</command> or <command>ROLLBACK</command> statement.
|
||||
<para>
|
||||
Other relational database systems may offer an autocommit feature
|
||||
as a convenience.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Many relational database systems offer an autocommit feature as a
|
||||
convenience.
|
||||
</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>
|
||||
<para>
|
||||
Incidentally, the <literal>BEGIN</literal> key word is used for a
|
||||
different purpose in embedded SQL. You are advised to be careful
|
||||
about the transaction semantics when porting database applications.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
|
|
@ -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">
|
||||
<refmeta>
|
||||
|
@ -24,8 +24,8 @@ CHECKPOINT
|
|||
Write-Ahead Logging (WAL) puts a checkpoint in the transaction log
|
||||
every so often. (To adjust the automatic checkpoint interval, see
|
||||
the run-time
|
||||
configuration options <parameter>CHECKPOINT_SEGMENTS</parameter>
|
||||
and <parameter>CHECKPOINT_TIMEOUT</parameter>.)
|
||||
configuration options <varname>checkpoint_segments</varname>
|
||||
and <varname>checkpoint_timeout</varname>.)
|
||||
The <command>CHECKPOINT</command> command forces an immediate checkpoint
|
||||
when the command is issued, without waiting for a scheduled checkpoint.
|
||||
</para>
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -8,144 +8,104 @@ PostgreSQL documentation
|
|||
<refentrytitle id="SQL-CLOSE-TITLE">CLOSE</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>
|
||||
CLOSE
|
||||
</refname>
|
||||
<refpurpose>
|
||||
close a cursor
|
||||
</refpurpose>
|
||||
<refname>CLOSE</refname>
|
||||
<refpurpose>close a cursor</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>1999-07-20</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
<synopsis>
|
||||
CLOSE <replaceable class="PARAMETER">cursor</replaceable>
|
||||
</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>
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-CLOSE-1">
|
||||
<refsect1info>
|
||||
<date>1998-09-08</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<command>CLOSE</command> frees the resources associated with an open cursor.
|
||||
After the cursor is closed, no subsequent operations
|
||||
are allowed on it. A cursor should be closed when it is
|
||||
no longer needed.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
An implicit close is executed for every open cursor when a
|
||||
transaction is terminated by <command>COMMIT</command>
|
||||
or <command>ROLLBACK</command>.
|
||||
Every open cursor is implicitly closed when a transaction is
|
||||
terminated by <command>COMMIT</command> or
|
||||
<command>ROLLBACK</command>.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect2 id="R2-SQL-CLOSE-3">
|
||||
<refsect2info>
|
||||
<date>1998-09-08</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Notes
|
||||
</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>
|
||||
</refsect2>
|
||||
<refsect1>
|
||||
<title>Parameters</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><replaceable class="PARAMETER">cursor</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The name of an open cursor to close.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</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 id="R1-SQL-CLOSE-2">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Notes</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>
|
||||
Close the cursor <literal>liahona</literal>:
|
||||
</para>
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
CLOSE liahona;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-CLOSE-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-CLOSE-4">
|
||||
<refsect2info>
|
||||
<date>1998-09-08</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
SQL92
|
||||
</title>
|
||||
<para>
|
||||
<command>CLOSE</command> is fully compatible with SQL92.
|
||||
</para>
|
||||
</refsect2>
|
||||
<para>
|
||||
<command>CLOSE</command> is fully conforming with the SQL standard.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -8,89 +8,27 @@ PostgreSQL documentation
|
|||
<refentrytitle id="sql-cluster-title">CLUSTER</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>
|
||||
CLUSTER
|
||||
</refname>
|
||||
<refpurpose>
|
||||
cluster a table according to an index
|
||||
</refpurpose>
|
||||
<refname>CLUSTER</refname>
|
||||
<refpurpose>cluster a table according to an index</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>1999-07-20</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
<synopsis>
|
||||
CLUSTER <replaceable class="PARAMETER">indexname</replaceable> ON <replaceable class="PARAMETER">tablename</replaceable>
|
||||
CLUSTER <replaceable class="PARAMETER">tablename</replaceable>
|
||||
CLUSTER
|
||||
</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>
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-CLUSTER-1">
|
||||
<refsect1info>
|
||||
<date>1998-09-08</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<command>CLUSTER</command> instructs <productname>PostgreSQL</productname>
|
||||
to cluster the table specified
|
||||
by <replaceable class="parameter">table</replaceable>
|
||||
by <replaceable class="parameter">tablename</replaceable>
|
||||
based on the index specified by
|
||||
<replaceable class="parameter">indexname</replaceable>. The index must
|
||||
already have been defined on
|
||||
|
@ -102,19 +40,19 @@ CLUSTER
|
|||
based on the index information. Clustering is a one-time operation:
|
||||
when the table is subsequently updated, the changes are
|
||||
not clustered. That is, no attempt is made to store new or
|
||||
updated tuples according to their index order. If one wishes, one can
|
||||
periodically re-cluster by issuing the command again.
|
||||
updated rows according to their index order. If one wishes, one can
|
||||
periodically recluster by issuing the command again.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When a table is clustered, <productname>PostgreSQL</productname>
|
||||
remembers on which index it was clustered. The form
|
||||
<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>
|
||||
<command>CLUSTER</command> without any parameter re-clusters all the tables
|
||||
<command>CLUSTER</command> without any parameter reclusters all the tables
|
||||
in the
|
||||
current database that the calling user owns, or all tables if called
|
||||
by a superuser. (Never-clustered tables are not included.) This
|
||||
|
@ -129,33 +67,62 @@ CLUSTER
|
|||
table until the <command>CLUSTER</command> is finished. See
|
||||
<xref linkend="explicit-locking"> for more information on database locking.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect2 id="R2-SQL-CLUSTER-3">
|
||||
<refsect2info>
|
||||
<date>1998-09-08</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Notes
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Parameter</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><replaceable class="PARAMETER">indexname</replaceable></term>
|
||||
<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>
|
||||
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
|
||||
data more than others, and there is an index that groups
|
||||
them together, you will benefit from using <command>CLUSTER</command>.
|
||||
</para>
|
||||
|
||||
<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
|
||||
If you are requesting a range of indexed values from a table, or a
|
||||
single indexed value that has multiple rows that match,
|
||||
<command>CLUSTER</command> will help because once the index identifies the
|
||||
heap page for the first row that matches, all other rows
|
||||
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>
|
||||
|
@ -166,23 +133,17 @@ CLUSTER
|
|||
sizes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<command>CLUSTER</command> preserves <command>GRANT</command>,
|
||||
inheritance, index, foreign key, and other ancillary information
|
||||
about the table.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Because <command>CLUSTER</command> remembers the clustering information,
|
||||
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
|
||||
are periodically re-clustered.
|
||||
are periodically reclustered.
|
||||
</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
|
||||
table. Otherwise, the optimizer may make poor choices of query plans.
|
||||
table. Otherwise, the planner may make poor choices of query plans.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
@ -196,68 +157,57 @@ CLUSTER
|
|||
but the majority of a big table will not fit in the cache.)
|
||||
The other way to cluster a table is to use
|
||||
|
||||
<programlisting>
|
||||
SELECT <replaceable class="parameter">columnlist</replaceable> INTO TABLE <replaceable class="parameter">newtable</replaceable>
|
||||
FROM <replaceable class="parameter">table</replaceable> ORDER BY <replaceable class="parameter">columnlist</replaceable>
|
||||
</programlisting>
|
||||
<programlisting>
|
||||
CREATE TABLE <replaceable class="parameter">newtable</replaceable> AS
|
||||
SELECT <replaceable class="parameter">columnlist</replaceable> FROM <replaceable class="parameter">table</replaceable> ORDER BY <replaceable class="parameter">columnlist</replaceable>;
|
||||
</programlisting>
|
||||
|
||||
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
|
||||
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
|
||||
recreate the table's indexes. However, this approach does not preserve
|
||||
OIDs, constraints, foreign key relationships, granted privileges, and
|
||||
other ancillary properties of the table --- all such items must be
|
||||
manually recreated.
|
||||
</para>
|
||||
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-CLUSTER-2">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Examples</title>
|
||||
|
||||
<para>
|
||||
Cluster the <literal>employees</literal> relation on the basis of
|
||||
its ID attribute:
|
||||
</para>
|
||||
<programlisting>
|
||||
Cluster the table <literal>employees</literal> on the basis of
|
||||
its index <literal>emp_ind</literal>:
|
||||
<programlisting>
|
||||
CLUSTER emp_ind ON emp;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Cluster the <literal>employees</literal> relation using the same
|
||||
index that was used before:
|
||||
</para>
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
CLUSTER emp;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Cluster all the tables on the database that have previously been clustered:
|
||||
</para>
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
CLUSTER;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-CLUSTER-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-CLUSTER-4">
|
||||
<refsect2info>
|
||||
<date>1998-09-08</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
SQL92
|
||||
</title>
|
||||
<para>
|
||||
There is no <command>CLUSTER</command> statement in SQL92.
|
||||
</para>
|
||||
</refsect2>
|
||||
<para>
|
||||
There is no <command>CLUSTER</command> statement in the SQL standard.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -8,21 +8,16 @@ PostgreSQL documentation
|
|||
<refentrytitle id="SQL-COMMENT-TITLE">COMMENT</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>
|
||||
COMMENT
|
||||
</refname>
|
||||
<refpurpose>
|
||||
define or change the comment of an object
|
||||
</refpurpose>
|
||||
<refname>COMMENT</refname>
|
||||
<refpurpose>define or change the comment of an object</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>1999-07-20</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
<synopsis>
|
||||
COMMENT ON
|
||||
[
|
||||
{
|
||||
TABLE <replaceable class="PARAMETER">object_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>) |
|
||||
|
@ -38,83 +33,21 @@ COMMENT ON
|
|||
TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> |
|
||||
TYPE <replaceable class="PARAMETER">object_name</replaceable> |
|
||||
VIEW <replaceable class="PARAMETER">object_name</replaceable>
|
||||
] IS <replaceable class="PARAMETER">'text'</replaceable>
|
||||
</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>
|
||||
} IS <replaceable class="PARAMETER">'text'</replaceable>
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-COMMENT-1">
|
||||
<refsect1info>
|
||||
<date>1998-10-25</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<command>COMMENT</command> stores a comment about a database object.
|
||||
Comments can be
|
||||
easily retrieved with <command>psql</command>'s
|
||||
<command>\dd</command>, <command>\d+</command>, or <command>\l+</command>
|
||||
commands. Other user interfaces to retrieve comments can be built atop
|
||||
the same built-in functions that <command>psql</command> uses, namely
|
||||
<function>obj_description()</> and <function>col_description()</>.
|
||||
easily retrieved with the <application>psql</application> commands
|
||||
<command>\dd</command>, <command>\d+</command>, and <command>\l+</command>.
|
||||
Other user interfaces to retrieve comments can be built atop
|
||||
the same built-in functions that <application>psql</application> uses, namely
|
||||
<function>obj_description</> and <function>col_description</>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
@ -124,75 +57,114 @@ COMMENT
|
|||
string.
|
||||
Comments are automatically dropped when the object is dropped.
|
||||
</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 id="R1-SQL-COMMENT-2">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Parameters</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>
|
||||
Attach a comment to the table <literal>mytable</literal>:
|
||||
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
COMMENT ON TABLE mytable IS 'This is my table.';
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
|
||||
Remove it again:
|
||||
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
COMMENT ON TABLE mytable IS NULL;
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Some more examples:
|
||||
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
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 DOMAIN my_domain IS 'Email Address Domain';
|
||||
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 ^ (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 SEQUENCE my_sequence IS 'Used to generate primary keys';
|
||||
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 TYPE complex IS 'Complex Number datatype';
|
||||
COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
|
||||
COMMENT ON TYPE complex IS 'Complex number data type';
|
||||
COMMENT ON VIEW my_view IS 'View of departmental costs';
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-COMMENT-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-COMMENT-4">
|
||||
<refsect2info>
|
||||
<date>1998-09-08</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
SQL92
|
||||
</title>
|
||||
<para>
|
||||
There is no <command>COMMENT</command> in <acronym>SQL92</acronym>.
|
||||
</para>
|
||||
</refsect2>
|
||||
<para>
|
||||
There is no <command>COMMENT</command> command in the SQL standard.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -8,141 +8,96 @@ PostgreSQL documentation
|
|||
<refentrytitle id="SQL-COMMIT-TITLE">COMMIT</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>
|
||||
COMMIT
|
||||
</refname>
|
||||
<refpurpose>
|
||||
commit the current transaction
|
||||
</refpurpose>
|
||||
<refname>COMMIT</refname>
|
||||
<refpurpose>commit the current transaction</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>1999-07-20</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
<synopsis>
|
||||
COMMIT [ WORK | TRANSACTION ]
|
||||
</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>
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-COMMIT-1">
|
||||
<refsect1info>
|
||||
<date>1998-09-08</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<command>COMMIT</command> commits the current transaction. All
|
||||
changes made by the transaction become visible to others
|
||||
and are guaranteed to be durable if a crash occurs.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect2 id="R2-SQL-COMMIT-3">
|
||||
<refsect2info>
|
||||
<date>1998-09-08</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Notes
|
||||
</title>
|
||||
<para>
|
||||
The keywords WORK and TRANSACTION are noise and can be omitted.
|
||||
</para>
|
||||
<refsect1>
|
||||
<title>Parameters</title>
|
||||
|
||||
<para>
|
||||
Use <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE">
|
||||
to abort a transaction.
|
||||
</para>
|
||||
</refsect2>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><literal>WORK</literal></term>
|
||||
<term><literal>TRANSACTION</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Optional key words. They have no effect.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<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 id="R1-SQL-COMMIT-2">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Notes</title>
|
||||
|
||||
<para>
|
||||
To make all changes permanent:
|
||||
<programlisting>
|
||||
COMMIT WORK;
|
||||
</programlisting>
|
||||
Use <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE"> to
|
||||
abort a transaction.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Examples</title>
|
||||
|
||||
<para>
|
||||
To commit the current transaction and make all changes permanent:
|
||||
<programlisting>
|
||||
COMMIT;
|
||||
</programlisting>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-COMMIT-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-COMMIT-4">
|
||||
<refsect2info>
|
||||
<date>1998-09-08</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
SQL92
|
||||
</title>
|
||||
<para>
|
||||
<acronym>SQL92</acronym> only specifies the two forms <literal>COMMIT</literal>
|
||||
and <literal>COMMIT WORK</literal>. Otherwise full compatibility.
|
||||
</para>
|
||||
</refsect2>
|
||||
<para>
|
||||
The SQL standard only specifies the two forms
|
||||
<literal>COMMIT</literal> and <literal>COMMIT
|
||||
WORK</literal>. Otherwise, this command is fully conforming.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
|
|
@ -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
|
||||
-->
|
||||
|
||||
|
@ -8,186 +8,35 @@ PostgreSQL documentation
|
|||
<refentrytitle id="sql-copy-title">COPY</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>
|
||||
COPY
|
||||
</refname>
|
||||
<refpurpose>
|
||||
copy data between files and tables
|
||||
</refpurpose>
|
||||
<refname>COPY</refname>
|
||||
<refpurpose>copy data between files and tables</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>1999-12-11</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
<synopsis>
|
||||
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 ]
|
||||
[ BINARY ]
|
||||
[ OIDS ]
|
||||
[ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ]
|
||||
[ NULL [ AS ] '<replaceable class="parameter">null string</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 ]
|
||||
[ BINARY ]
|
||||
[ OIDS ]
|
||||
[ DELIMITER [ AS ] '<replaceable class="parameter">delimiter</replaceable>' ]
|
||||
[ NULL [ AS ] '<replaceable class="parameter">null string</replaceable>' ] ]
|
||||
</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>
|
||||
</synopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-COPY-1">
|
||||
<refsect1info>
|
||||
<date>2001-01-02</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
<command>COPY</command> moves data between
|
||||
<productname>PostgreSQL</productname> tables and standard file-system
|
||||
|
@ -207,61 +56,186 @@ ERROR: <replaceable>reason</replaceable>
|
|||
|
||||
<para>
|
||||
<command>COPY</command> with a file name instructs the
|
||||
<productname>PostgreSQL</productname> backend to directly read from
|
||||
or write to a file. The file must be accessible to the backend and
|
||||
the name must be specified from the viewpoint of the backend. When
|
||||
<filename>stdin</filename> or <filename>stdout</filename> is
|
||||
<productname>PostgreSQL</productname> server to directly read from
|
||||
or write to a file. The file must be accessible to the server and
|
||||
the name must be specified from the viewpoint of the server. When
|
||||
<literal>STDIN</literal> or <literal>STDOUT</literal> is
|
||||
specified, data is transmitted via the connection between the
|
||||
client frontend and the backend.
|
||||
|
||||
<tip>
|
||||
<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 backend when <command>\copy</command> is used.
|
||||
</para>
|
||||
</tip>
|
||||
</para>
|
||||
client and the server.
|
||||
</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.
|
||||
</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>
|
||||
<command>COPY</command> can only be used with plain tables, not
|
||||
with views.
|
||||
</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
|
||||
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.
|
||||
</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>
|
||||
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
|
||||
<firstterm>insert privilege</firstterm> on a table into which values
|
||||
are being inserted by <command>COPY FROM</command>. The backend also
|
||||
needs appropriate Unix permissions for any file read or written by
|
||||
<command>COPY</command>.
|
||||
insert privilege on a table into which values
|
||||
are being inserted by <command>COPY FROM</command>.
|
||||
</para>
|
||||
|
||||
<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>
|
||||
|
@ -272,87 +246,52 @@ ERROR: <replaceable>reason</replaceable>
|
|||
<para>
|
||||
<command>COPY</command> stops operation at the first error. This
|
||||
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
|
||||
be visible or accessible, but they still occupy disk space. This may
|
||||
amount to a considerable amount of wasted disk space if the failure
|
||||
happened well into a large copy operation. You may wish to invoke
|
||||
<command>VACUUM</command> to recover the wasted space.
|
||||
</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 id="R1-SQL-COPY-2">
|
||||
<refsect1info>
|
||||
<date>2001-01-02</date>
|
||||
</refsect1info>
|
||||
<refsect1>
|
||||
<title>File Formats</title>
|
||||
|
||||
<refsect2>
|
||||
<refsect2info>
|
||||
<date>2002-02-12</date>
|
||||
</refsect2info>
|
||||
<title>Text Format</title>
|
||||
|
||||
<para>
|
||||
When <command>COPY</command> is used without the BINARY option,
|
||||
the file read or written is a text file with one line per table row.
|
||||
Columns (attributes) in a row are separated by the delimiter character.
|
||||
The attribute values themselves are strings generated by the
|
||||
When <command>COPY</command> is used without the <literal>BINARY</literal> option,
|
||||
the data read or written is a text file with one line per table row.
|
||||
Columns in a row are separated by the delimiter character.
|
||||
The column values themselves are strings generated by the
|
||||
output function, or acceptable to the input function, of each
|
||||
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
|
||||
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>
|
||||
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>
|
||||
End of data can be represented by a single line containing just
|
||||
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
|
||||
data to or from a client application.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Backslash characters (<literal>\</>) may be used in the
|
||||
<command>COPY</command> data to quote data characters that might
|
||||
otherwise be taken as row or column delimiters. In particular, the
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following special backslash sequences are recognized by
|
||||
<command>COPY FROM</command>:
|
||||
|
@ -404,47 +343,44 @@ ERROR: <replaceable>reason</replaceable>
|
|||
backslash sequence, but it does use the other sequences listed above
|
||||
for those control characters.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Never put a backslash before a data character <literal>N</> or period
|
||||
(<literal>.</>). Such pairs will be mistaken for the default null string
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is strongly recommended that applications generating COPY data convert
|
||||
data newlines and carriage returns to the <literal>\n</> and
|
||||
<literal>\r</> sequences respectively. At present
|
||||
(<productname>PostgreSQL</productname> 7.2 and older versions) it is
|
||||
<literal>\r</> sequences respectively. At present it is
|
||||
possible to represent a data carriage return without any special quoting,
|
||||
and to represent a data newline by a backslash and newline. However,
|
||||
these representations will not be accepted by default in future releases.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
This is expected to change in future releases.
|
||||
</para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<refsect2info>
|
||||
<date>2001-01-02</date>
|
||||
</refsect2info>
|
||||
<title>Binary Format</title>
|
||||
|
||||
<para>
|
||||
The file format used for <command>COPY BINARY</command> changed in
|
||||
<application>PostgreSQL</application> v7.1. The new format consists
|
||||
of a file header, zero or more tuples, and a file trailer.
|
||||
<application>PostgreSQL</application> 7.1. The new format consists
|
||||
of a file header, zero or more tuples containing the row data, and
|
||||
a file trailer.
|
||||
</para>
|
||||
|
||||
<refsect3>
|
||||
<refsect3info>
|
||||
<date>2001-01-02</date>
|
||||
</refsect3info>
|
||||
<title>
|
||||
File Header
|
||||
</title>
|
||||
<title>File Header</title>
|
||||
|
||||
<para>
|
||||
The file header consists of 24 bytes of fixed fields, followed
|
||||
by a variable-length header extension area. The fixed fields are:
|
||||
|
@ -454,11 +390,11 @@ ERROR: <replaceable>reason</replaceable>
|
|||
<term>Signature</term>
|
||||
<listitem>
|
||||
<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
|
||||
easy identification of files that have been munged by a non-8-bit-clean
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -467,7 +403,7 @@ filters, dropped nulls, dropped high bits, or parity changes.)
|
|||
<term>Integer layout field</term>
|
||||
<listitem>
|
||||
<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
|
||||
order is detected here.
|
||||
</para>
|
||||
|
@ -478,7 +414,7 @@ order is detected here.
|
|||
<term>Flags field</term>
|
||||
<listitem>
|
||||
<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
|
||||
with source's endianness, as are all subsequent integer fields. Bits
|
||||
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>
|
||||
<listitem>
|
||||
<para>
|
||||
if 1, OIDs are included in the dump; if 0, not
|
||||
if 1, OIDs are included in the data; if 0, not
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -504,8 +440,8 @@ only one flag bit is defined, and the rest must be zero:
|
|||
<term>Header extension area length</term>
|
||||
<listitem>
|
||||
<para>
|
||||
int32 length in bytes of remainder of header, not including self. In
|
||||
the initial version this will be zero, and the first tuple follows
|
||||
32-bit integer, length in bytes of remainder of header, not including self.
|
||||
Currently, this is zero, and the first tuple follows
|
||||
immediately. Future changes to the format might allow additional data
|
||||
to be present in the header. A reader should silently skip over any header
|
||||
extension data it does not know what to do with.
|
||||
|
@ -531,17 +467,12 @@ is left for a later release.
|
|||
</refsect3>
|
||||
|
||||
<refsect3>
|
||||
<refsect3info>
|
||||
<date>2001-01-02</date>
|
||||
</refsect3info>
|
||||
<title>
|
||||
Tuples
|
||||
</title>
|
||||
<title>Tuples</title>
|
||||
<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
|
||||
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:
|
||||
|
||||
<variablelist>
|
||||
|
@ -549,7 +480,7 @@ The <structfield>typlen</> field is interpreted thus:
|
|||
<term>Zero</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Field is NULL. No data follows.
|
||||
Field is null. No data follows.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -558,7 +489,7 @@ The <structfield>typlen</> field is interpreted thus:
|
|||
<term>> 0</term>
|
||||
<listitem>
|
||||
<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.
|
||||
</para>
|
||||
</listitem>
|
||||
|
@ -570,7 +501,7 @@ The <structfield>typlen</> field is interpreted thus:
|
|||
<para>
|
||||
Field is a <literal>varlena</> data type. The next four
|
||||
bytes are the <literal>varlena</> header, which contains
|
||||
the total value length including itself.
|
||||
the total value length including the header itself.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -587,7 +518,7 @@ The <structfield>typlen</> field is interpreted thus:
|
|||
</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
|
||||
but very useful check that the data is as expected.
|
||||
</para>
|
||||
|
@ -602,23 +533,19 @@ you from moving a binary file across machines).
|
|||
</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
|
||||
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
|
||||
OIDs to be shown as NULL if that ever proves desirable.
|
||||
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.
|
||||
</para>
|
||||
</refsect3>
|
||||
|
||||
<refsect3>
|
||||
<refsect3info>
|
||||
<date>2001-01-02</date>
|
||||
</refsect3info>
|
||||
<title>
|
||||
File Trailer
|
||||
</title>
|
||||
<title>File Trailer</title>
|
||||
|
||||
<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.
|
||||
</para>
|
||||
|
||||
|
@ -631,48 +558,47 @@ OIDs to be shown as NULL if that ever proves desirable.
|
|||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-COPY-3">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Examples</title>
|
||||
|
||||
<para>
|
||||
The following example copies a table to standard output,
|
||||
using a vertical bar (|) as the field delimiter:
|
||||
The following example copies a table to the client
|
||||
using the vertical bar (<literal>|</literal>) as the field delimiter:
|
||||
<programlisting>
|
||||
COPY country TO STDOUT WITH DELIMITER '|';
|
||||
</programlisting>
|
||||
</para>
|
||||
<programlisting>
|
||||
COPY country TO <filename>stdout</filename> WITH DELIMITER '|';
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
To copy data from a Unix file into the <literal>country</> table:
|
||||
</para>
|
||||
<programlisting>
|
||||
To copy data from a file into the <literal>country</> table:
|
||||
<programlisting>
|
||||
COPY country FROM '/usr1/proj/bray/sql/country_data';
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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):
|
||||
</para>
|
||||
<programlisting>
|
||||
<programlisting>
|
||||
AF AFGHANISTAN
|
||||
AL ALBANIA
|
||||
DZ ALGERIA
|
||||
ZM ZAMBIA
|
||||
ZW ZIMBABWE
|
||||
\.
|
||||
</programlisting>
|
||||
<para>
|
||||
Note that the white space on each line is actually a TAB.
|
||||
</programlisting>
|
||||
Note that the white space on each line is actually a tab character.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following is the same data, output in binary format on a
|
||||
Linux/i586 machine. The data is shown after filtering through the
|
||||
Unix utility <command>od -c</command>. The table has three fields;
|
||||
the first is <type>char(2)</type>, the second is <type>text</type>,
|
||||
and the third is <type>integer</type>. All the rows have a null value
|
||||
in the third field.
|
||||
</para>
|
||||
<programlisting>
|
||||
Unix utility <command>od -c</command>. The table has three columns;
|
||||
the first has type <type>char(2)</type>, the second has type <type>text</type>,
|
||||
and the third has type <type>integer</type>. All the rows have a null value
|
||||
in the third column.
|
||||
<programlisting>
|
||||
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
|
||||
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
|
||||
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
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-COPY-6">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-COPY-4">
|
||||
<refsect2info>
|
||||
<date>1998-09-08</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
SQL92
|
||||
</title>
|
||||
<para>
|
||||
There is no <command>COPY</command> statement in SQL92.
|
||||
</para>
|
||||
<para>
|
||||
The following syntax was used by pre-7.3 applications and is still supported:
|
||||
<synopsis>
|
||||
COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ]
|
||||
FROM { '<replaceable class="parameter">filename</replaceable>' | <filename>stdin</filename> }
|
||||
[ [USING] DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ]
|
||||
[ WITH NULL AS '<replaceable class="parameter">null string</replaceable>' ]
|
||||
COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ]
|
||||
TO { '<replaceable class="parameter">filename</replaceable>' | <filename>stdout</filename> }
|
||||
[ [USING] DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ]
|
||||
[ WITH NULL AS '<replaceable class="parameter">null string</replaceable>' ]
|
||||
</synopsis>
|
||||
</para>
|
||||
</refsect2>
|
||||
<para>
|
||||
There is no <command>COPY</command> statement in the SQL standard.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following syntax was used before PostgreSQL version 7.3 and is
|
||||
still supported:
|
||||
|
||||
<synopsis>
|
||||
COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ]
|
||||
FROM { '<replaceable class="parameter">filename</replaceable>' | STDIN }
|
||||
[ [USING] DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ]
|
||||
[ WITH NULL AS '<replaceable class="parameter">null string</replaceable>' ]
|
||||
|
||||
COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ]
|
||||
TO { '<replaceable class="parameter">filename</replaceable>' | STDOUT }
|
||||
[ [USING] DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ]
|
||||
[ WITH NULL AS '<replaceable class="parameter">null string</replaceable>' ]
|
||||
</synopsis>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
|
Loading…
Reference in New Issue