database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-13 07:41:39 +03:00
Code Activity

Markup and editing adjustments...

Browse Source
This commit is contained in:
Thomas G. Lockhart
1998-09-16 14:43:12 +00:00
parent 5a68fd56cd
commit d2a907c6ad
18 changed files with 986 additions and 884 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -18,9 +18,9 @@ Modifies table properties
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
[*] ADD [COLUMN] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE> [ * ] ADD [ COLUMN ] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE>
ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
[*] RENAME [COLUMN] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> TO <REPLACEABLE CLASS="PARAMETER">newcolumn</REPLACEABLE> [ * ] RENAME [ COLUMN ] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> TO <REPLACEABLE CLASS="PARAMETER">newcolumn</REPLACEABLE>
ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
RENAME TO <REPLACEABLE CLASS="PARAMETER">newtable</REPLACEABLE> RENAME TO <REPLACEABLE CLASS="PARAMETER">newtable</REPLACEABLE>
</SYNOPSIS> </SYNOPSIS>
@ -103,14 +103,14 @@ Outputs
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>status</ReturnValue> <replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>ALTER</ReturnValue> <returnvalue>ALTER</returnvalue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -121,7 +121,7 @@ Outputs
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>NEW</ReturnValue> <returnvalue>NEW</returnvalue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -156,9 +156,9 @@ Outputs
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
ALTER TABLE changes the definition of an existing table. <command>ALTER TABLE</command> changes the definition of an existing table.
The new columns and their types are specified in the same style The new columns and their types are specified in the same style
and with the the same restrictions as in CREATE TABLE. and with the the same restrictions as in <command>CREATE TABLE</command>.
The RENAME clause causes the name of a table or column The RENAME clause causes the name of a table or column
to change without changing any of the data contained in to change without changing any of the data contained in
the affected table. Thus, the table or column will the affected table. Thus, the table or column will
@ -178,18 +178,15 @@ Notes
<PARA> <PARA>
The keyword COLUMN is noise and can be omitted. The keyword COLUMN is noise and can be omitted.
<PARA>
ALTER TABLE/RENAME is a PostgreSQL language extension.
<PARA> <PARA>
<Quote>[*]</Quote> following a name of a table indicates that statement <Quote>[*]</Quote> following a name of a table indicates that statement
should be run over that table and all tables below it in the should be run over that table and all tables below it in the
inheritance hierarchy. inheritance hierarchy.
Refer to PostgreSQL User's Guide for further The PostgreSQL User's Guide has further
information on inheritance. information on inheritance.
<PARA> <PARA>
Refer to the CREATE TABLE reference for further description Refer to CREATE TABLE for a further description
of valid arguments. of valid arguments.
</REFSECT2> </REFSECT2>
@ -232,23 +229,30 @@ Compatibility
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
SQL92 specifies some additional capabilities for ALTER TABLE <command>ALTER TABLE/RENAME</command>
statement which are not yet directly supported by <ProductName>Postgres</ProductName>: is a <productname>Postgres</productname> language extension.
<PARA>
SQL92 specifies some additional capabilities for <command>ALTER TABLE</command>
statement which are not yet directly supported by
<ProductName>Postgres</ProductName>:
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<Synopsis> <Synopsis>
ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER [COLUMN] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER [ COLUMN ] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
SET DEFAULT <REPLACEABLE CLASS="PARAMETER">default</REPLACEABLE> SET DEFAULT <REPLACEABLE CLASS="PARAMETER">default</REPLACEABLE>
ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER [COLUMN] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
ADD [CONSTRAINT <REPLACEABLE CLASS="PARAMETER">constraint</REPLACEABLE>] <REPLACEABLE CLASS="PARAMETER">table-constraint</REPLACEABLE> ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER [ COLUMN ] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
ADD [ CONSTRAINT <REPLACEABLE CLASS="PARAMETER">constraint</REPLACEABLE> ] <REPLACEABLE CLASS="PARAMETER">table-constraint</REPLACEABLE>
</Synopsis> </Synopsis>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Puts the default value or constraint specified into the Puts the default value or constraint specified into the
definition of column in the table. See CREATE TABLE for the definition of column in the table.
See <command>CREATE TABLE</command> for the
syntax of the default and table-constraint clauses. syntax of the default and table-constraint clauses.
If a default clause already exists, it will be replaced by If a default clause already exists, it will be replaced by
the new definition. If any constraints on this column already the new definition. If any constraints on this column already
@ -307,7 +311,7 @@ DROP TABLE temp;
<TERM> <TERM>
<Synopsis> <Synopsis>
ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
DROP [COLUMN] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> { RESTRICT | CASCADE } DROP [ COLUMN ] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> { RESTRICT | CASCADE }
</Synopsis> </Synopsis>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
@ -335,23 +339,3 @@ DROP TABLE temp;
</PARA> </PARA>
</VARIABLELIST> </VARIABLELIST>
</REFENTRY> </REFENTRY>
<!--
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
<ReturnValue></ReturnValue>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>&bull;
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA>
</PARA>
-->

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

@ -14,26 +14,26 @@
</REFPURPOSE> </REFPURPOSE>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<synopsis> <synopsis>
ALTER USER <replaceable class="PARAMETER">username</replaceable> ALTER USER <replaceable class="PARAMETER">username</replaceable>
[WITH PASSWORD <replaceable class="PARAMETER">password</replaceable>] [ WITH PASSWORD <replaceable class="PARAMETER">password</replaceable> ]
[CREATEDB | NOCREATEDB] [ CREATEDB | NOCREATEDB ]
[CREATEUSER | NOCREATEUSER] [ CREATEUSER | NOCREATEUSER ]
[IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...] ] [ IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...] ]
[VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'] [ VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>' ]
</synopsis> </synopsis>
<REFSECT2 ID="R2-SQL-ALTERUSER-1"> <REFSECT2 ID="R2-SQL-ALTERUSER-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
Refer to CREATE USER statement for a detailed description of each Refer to <command>CREATE USER</command> for a detailed description of each
clause. clause.
</para> </para>
<VARIABLELIST> <VARIABLELIST>
@ -47,6 +47,7 @@
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER"> password </REPLACEABLE> <REPLACEABLE CLASS="PARAMETER"> password </REPLACEABLE>
@ -57,6 +58,7 @@
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER"> groupname </REPLACEABLE> <REPLACEABLE CLASS="PARAMETER"> groupname </REPLACEABLE>
@ -67,13 +69,15 @@
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<REPLACEABLE CLASS="PARAMETER"> abstime </REPLACEABLE> <REPLACEABLE CLASS="PARAMETER"> abstime </REPLACEABLE>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The date (and, optionally, the time) at which this user's access is to be terminated. The date (and, optionally, the time)
at which this user's access is to be terminated.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -82,7 +86,7 @@
<REFSECT2 ID="R2-SQL-ALTERUSER-2"> <REFSECT2 ID="R2-SQL-ALTERUSER-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -92,14 +96,14 @@
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>status</ReturnValue> <replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>ALTER USER</ReturnValue> <returnvalue>ALTER USER</returnvalue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -110,7 +114,7 @@
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>ERROR: alterUser: user "username" does not exist</ReturnValue> <returnvalue>ERROR: alterUser: user "username" does not exist</returnvalue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -129,16 +133,18 @@
<REFSECT1 ID="R1-SQL-ALTERUSER-1"> <REFSECT1 ID="R1-SQL-ALTERUSER-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
ALTER USER is used to change the attributes of a user's <command>ALTER USER</command> is used to change the attributes of a user's
PostgreSQL account. Please note that it is not possible <productname>Postgres</productname> account.
Please note that it is not possible
to alter a user's "usesysid" via the alter user to alter a user's "usesysid" via the alter user
statement. Also, it is only possible for the PostgreSQL statement. Also, it is only possible for the
<productname>Postgres</productname>
user or any user with read and modify permissions on user or any user with read and modify permissions on
"pg_shadow" to alter user passwords. "pg_shadow" to alter user passwords.
</PARA> </PARA>
@ -150,21 +156,24 @@
<REFSECT2 ID="R2-SQL-ALTERUSER-3"> <REFSECT2 ID="R2-SQL-ALTERUSER-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
ALTER USER statement is a PostgreSQL language extension. <command>ALTER USER</command> statement
is a <productname>Postgres</productname>
language extension.
</para> </para>
<para> <para>
Refer to CREATE/DROP USER statements to create/remove an user Refer to <command>CREATE/DROP USER</command>
to create or remove a user
account. account.
</para> </para>
<para> <para>
At the current release (6.3.2), the IN GROUP clause is parsed In the current release (v6.4), the IN GROUP clause is parsed
but has no effect. When it is fully implemented, it is but has no affect. When it is fully implemented, it is
intended to modify the pg_group relation. intended to modify the pg_group relation.
</para> </para>
</REFSECT2> </REFSECT2>
@ -178,13 +187,13 @@
Change a user password Change a user password
</PARA> </PARA>
<ProgramListing> <ProgramListing>
ALTER USER davide WITH PASSWORD hu8jmn3; ALTER USER davide WITH PASSWORD hu8jmn3;
</ProgramListing> </ProgramListing>
<para> <para>
Change a user's valid until date Change a user's valid until date
</para> </para>
<ProgramListing> <ProgramListing>
ALTER USER manuel VALID UNTIL 'Jan 31 2030'; ALTER USER manuel VALID UNTIL 'Jan 31 2030';
</ProgramListing> </ProgramListing>
<para> <para>
Change a user's valid until date, specifying that his Change a user's valid until date, specifying that his
@ -192,19 +201,19 @@ authorisation should expire at midday on 4th May 1998 using
the time zone which is one hour ahead of UTC the time zone which is one hour ahead of UTC
</para> </para>
<ProgramListing> <ProgramListing>
ALTER USER chris VALID UNTIL 'May 4 12:00:00 1998 +1'; ALTER USER chris VALID UNTIL 'May 4 12:00:00 1998 +1';
</ProgramListing> </ProgramListing>
<para> <para>
Give a user the ability to create other users and new databases. Give a user the ability to create other users and new databases.
</para> </para>
<programlisting> <programlisting>
ALTER USER miriam CREATEUSER CREATEDB; ALTER USER miriam CREATEUSER CREATEDB;
</programlisting> </programlisting>
<para> <para>
Place a user in two groups Place a user in two groups
</para> </para>
<programlisting> <programlisting>
ALTER USER miriam IN GROUP sales, payroll; ALTER USER miriam IN GROUP sales, payroll;
</programlisting> </programlisting>
</REFSECT1> </REFSECT1>
@ -217,13 +226,15 @@ the time zone which is one hour ahead of UTC
<REFSECT2 ID="R2-SQL-ALTERUSER-4"> <REFSECT2 ID="R2-SQL-ALTERUSER-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no ALTER USER statement in SQL92. The standard leaves There is no <command>ALTER USER</command> statement in
<acronym>SQL92</acronym>.
The standard leaves
the definition of users to the implementation. the definition of users to the implementation.
</PARA> </PARA>
</refsect1> </refsect1>

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

@ -16,38 +16,26 @@
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
BEGIN { WORK | TRANSACTION } BEGIN [ WORK | TRANSACTION ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-BEGINWORK-1"> <REFSECT2 ID="R2-SQL-BEGINWORK-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>
None None
</ReturnValue>
</TERM>
<LISTITEM>
<para></para>
</LISTITEM>
</varlistentry>
</VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-BEGINWORK-2"> <REFSECT2 ID="R2-SQL-BEGINWORK-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -57,14 +45,14 @@
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
status <replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>BEGIN</ReturnValue> <returnvalue>BEGIN</returnvalue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -74,18 +62,12 @@
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue> <returnvalue>NOTICE: BeginTransactionBlock and not in default state</returnvalue>
NOTICE: BeginTransactionBlock and not in default state
</ReturnValue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
This indicates that a transaction was already in progress. This indicates that a transaction was already in progress.
<comment> The current transaction is not affected.
What happens to command queries already run
in the transaction? Does this have no effect, or does
it restart the transaction?
</comment>
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -99,17 +81,20 @@
<REFSECT1 ID="R1-SQL-BEGINWORK-1"> <REFSECT1 ID="R1-SQL-BEGINWORK-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<para> <para>
BEGIN begins a user transaction which PostgreSQL will <command>BEGIN</command> initiates a user transaction
guarantee is serialisable with respect to all concurrently which <productname>Postgres</productname> will
executing transactions. PostgreSQL uses two-phase locking guarantee is serializable with respect to all concurrently
executing transactions. <productname>Postgres</productname> uses two-phase
locking
to perform this task. If the transaction is committed, to perform this task. If the transaction is committed,
PostgreSQL will ensure either that all updates are done orelse <productname>Postgres</productname> will ensure either that all updates are
done or else
that none of that none of
them are done. Transactions have the standard ACID them are done. Transactions have the standard ACID
(atomic, consistent, isolatable, and durable) property. (atomic, consistent, isolatable, and durable) property.
@ -117,7 +102,7 @@
<REFSECT2 ID="R2-SQL-BEGINWORK-3"> <REFSECT2 ID="R2-SQL-BEGINWORK-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
@ -126,18 +111,15 @@
The keyword TRANSACTION is just a cosmetic alternative to WORK. The keyword TRANSACTION is just a cosmetic alternative to WORK.
Neither keyword need be specified. Neither keyword need be specified.
</PARA> </PARA>
<PARA> <PARA>
BEGIN statement is a PostgreSQL language extension. Refer to the <command>LOCK</command> statement for further information
about locking tables inside a transaction.
</PARA> </PARA>
<PARA> <PARA>
Refer to the LOCK statement for further information about locking Use <command>COMMIT</command> or <command>ROLLBACK</command>
tables inside a transaction. to terminate a transaction.
</PARA>
<PARA>
Use COMMIT or ROLLBACK to terminate a transaction.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
@ -146,9 +128,9 @@
Usage Usage
</TITLE> </TITLE>
<PARA>To begin a user transaction: <PARA>To begin a user transaction:
</PARA>
<ProgramListing> <ProgramListing>
BEGIN WORK; BEGIN WORK;
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>
@ -157,17 +139,19 @@
Compatibility Compatibility
</TITLE> </TITLE>
<PARA> <PARA>
</PARA> <command>BEGIN</command>
is a <productname>Postgres</productname> language extension.
<REFSECT2 ID="R2-SQL-BEGINWORK-4"> <REFSECT2 ID="R2-SQL-BEGINWORK-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no explicit "BEGIN WORK" in SQL92; transaction initiation There is no explicit BEGIN WORK command in <acronym>SQL92</acronym>;
transaction initiation
is always implicit and it terminates either with a COMMIT or with is always implicit and it terminates either with a COMMIT or with
a ROLLBACK statement. a ROLLBACK statement.
</PARA> </PARA>

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

@ -15,7 +15,7 @@
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
@ -23,25 +23,16 @@ CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
<REFSECT2 ID="R2-SQL-CLOSE-1"> <REFSECT2 ID="R2-SQL-CLOSE-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>
<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</ReturnValue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -50,14 +41,11 @@ CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CLOSE-2"> <REFSECT2 ID="R2-SQL-CLOSE-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -67,15 +55,16 @@ CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>
status
</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue> <ReturnValue>CLOSE</ReturnValue>
CLOSE
</ReturnValue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -85,9 +74,7 @@ CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue> <ReturnValue>NOTICE PerformPortalClose: portal "<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>" not found</ReturnValue>
NOTICE PerformPortalClose: portal "<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>" not found
</ReturnValue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -107,33 +94,35 @@ CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
<REFSECT1 ID="R1-SQL-CLOSE-1"> <REFSECT1 ID="R1-SQL-CLOSE-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
CLOSE frees the resources associated with an open cursor. <command>CLOSE</command> frees the resources associated with an open cursor.
After the cursor is closed, no subsequent operations After the cursor is closed, no subsequent operations
are allowed on it. A cursor should be closed when it is are allowed on it. A cursor should be closed when it is
no longer needed. no longer needed.
</PARA> </PARA>
<PARA> <PARA>
An implicit close is executed for every open cursor when a An implicit close is executed for every open cursor when a
transaction is terminated by COMMIT or ROLLBACK. transaction is terminated by <command>COMMIT</command>
or <command>ROLLBACK</command>.
</PARA> </PARA>
<REFSECT2 ID="R2-SQL-CLOSE-3"> <REFSECT2 ID="R2-SQL-CLOSE-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
PostgreSQL does not have an explicit OPEN cursor statement; <productname>Postgres</productname> does not have
a cursor is considered open when it is DECLAREd. an explicit <command>OPEN</command> cursor statement;
Use DECLARE to declare a cursor. a cursor is considered open when it is declared.
Use the <command>DECLARE</command> statement to declare a cursor.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1> </refsect1>
@ -146,7 +135,7 @@ CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
Close the cursor liahona: Close the cursor liahona:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CLOSE liahona; CLOSE liahona;
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>
@ -159,13 +148,13 @@ CLOSE <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
<REFSECT2 ID="R2-SQL-CLOSE-4"> <REFSECT2 ID="R2-SQL-CLOSE-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
CLOSE is fully compatibile with SQL92. <command>CLOSE</command> is fully compatible with SQL92.
</PARA> </PARA>
</refsect2> </refsect2>
</refsect1> </refsect1>

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

@ -15,15 +15,15 @@
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> CLUSTER <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> ON <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CLUSTER-1"> <REFSECT2 ID="R2-SQL-CLUSTER-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
@ -33,9 +33,7 @@
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>
<REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE>
</ReturnValue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -45,9 +43,7 @@
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</ReturnValue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -60,7 +56,7 @@
<REFSECT2 ID="R2-SQL-CLUSTER-2"> <REFSECT2 ID="R2-SQL-CLUSTER-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -70,13 +66,14 @@
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>CLUSTER</ReturnValue> <returnvalue>CLUSTER</returnvalue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -86,11 +83,11 @@
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>ERROR: relation &lt;<REPLACEABLE CLASS="PARAMETER">tablerelation_number</REPLACEABLE>&gt; inherits "invoice"</ReturnValue> <returnvalue>ERROR: relation &lt;<REPLACEABLE CLASS="PARAMETER">tablerelation_number</REPLACEABLE>&gt; inherits "invoice"</returnvalue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
???
<comment> <comment>
This is not documented anywhere. It seems not to be possible to This is not documented anywhere. It seems not to be possible to
cluster a table that is inherited. cluster a table that is inherited.
@ -100,11 +97,11 @@
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>ERROR: Relation x does not exist!</ReturnValue> <returnvalue>ERROR: Relation x does not exist!</returnvalue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
???
<comment> <comment>
The relation complained of was not shown in the error message, The relation complained of was not shown in the error message,
which contained a random string instead of the relation name. which contained a random string instead of the relation name.
@ -122,27 +119,37 @@
<REFSECT1 ID="R1-SQL-CLUSTER-1"> <REFSECT1 ID="R1-SQL-CLUSTER-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
This command instructs PostgreSQL to cluster the class specified <command>CLUSTER</command> instructs <productname>Postgres</productname>
to cluster the class specified
by <replaceable class="parameter">classname</replaceable> approximately by <replaceable class="parameter">classname</replaceable> approximately
based on the index specified by based on the index specified by
<replaceable class="parameter">indexname</replaceable>. The index must <replaceable class="parameter">indexname</replaceable>. The index must
already have been defined on <replaceable class="parameter">classname</replaceable>. already have been defined on
<replaceable class="parameter">classname</replaceable>.
</PARA> </PARA>
<para> <para>
When a class is clustered, it is physically reordered When a class is clustered, it is physically reordered
based on the index information. The clustering is static. based on the index information. The clustering is static.
In other words, as the class is updated, the changes are In other words, as the class is updated, the changes are
not clustered. No attempt is made to keep new instances or not clustered. No attempt is made to keep new instances or
updated tuples clustered. If he wishes, the user can updated tuples clustered. If one wishes, one can
recluster manually by issuing the command again. recluster manually by issuing the command again.
</para> </para>
<REFSECT2 ID="R2-SQL-CLUSTER-3">
<REFSECT2INFO>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
<para> <para>
The table is actually copied to a temporary table in index The table is actually copied to a temporary table in index
order, then renamed back to the original name. For this order, then renamed back to the original name. For this
@ -155,16 +162,15 @@
within a table, the actual order of the data in the heap within a table, the actual order of the data in the heap
table is unimportant. However, if you tend to access some table is unimportant. However, if you tend to access some
data more than others, and there is an index that groups data more than others, and there is an index that groups
them together, you will benefit from using the CLUSTER them together, you will benefit from using <command>CLUSTER</command>.
command.
</para> </para>
<para> <para>
Another place CLUSTER is good is in cases where you use an Another place <command>CLUSTER</command> is helpful is in cases where you use an
index to pull out several rows from a table. If you are index to pull out several rows from a table. If you are
requesting a range of indexed values from a table, or a requesting a range of indexed values from a table, or a
single indexed value that has multiple rows that match, single indexed value that has multiple rows that match,
CLUSTER will help because once the index identifies the <command>CLUSTER</command> will help because once the index identifies the
heap page for the first row that matches, all other rows heap page for the first row that matches, all other rows
that match are probably already on the same heap page, that match are probably already on the same heap page,
saving disk accesses and speeding up the query. saving disk accesses and speeding up the query.
@ -172,25 +178,27 @@
<para> <para>
There are two ways to cluster data. The first is with the There are two ways to cluster data. The first is with the
CLUSTER command, which reorders the original table with <command>CLUSTER</command> command, which reorders the original table with
the ordering of the index you specify. This can be slow the ordering of the index you specify. This can be slow
on large tables because the rows are fetched from the heap on large tables because the rows are fetched from the heap
in index order, and if the heap table is unordered, the in index order, and if the heap table is unordered, the
entries are on random pages, so there is one disk page entries are on random pages, so there is one disk page
retrieved for every row moved. PostgreSQL has a cache, retrieved for every row moved. <productname>Postgres</productname> has a cache,
but the majority of a big table will not fit in the cache. but the majority of a big table will not fit in the cache.
</para> </para>
<para> <para>
Another way is to use Another way to cluster data is to use
<programlisting>SELECT ... INTO TABLE temp FROM ... ORDER BY ...</programlisting> <programlisting>
This uses the PostgreSQL sorting code in SELECT ... INTO TABLE <replaceable class="parameter">temp</replaceable> FROM ... ORDER BY ...
</programlisting>
This uses the <productname>Postgres</productname> sorting code in
ORDER BY to match the index, and is much faster for ORDER BY to match the index, and is much faster for
unordered data. You then drop the old table, use unordered data. You then drop the old table, use
<programlisting>ALTER TABLE RENAME</programlisting> <command>ALTER TABLE/RENAME</command>
to rename 'temp' to the old name, and to rename <replaceable class="parameter">temp</replaceable> to the old name, and
recreate the b bindexes. The only problem is that oids recreate any indexes. The only problem is that <acronym>OID</acronym>s
will not be preserved. From then on, CLUSTER should be will not be preserved. From then on, <command>CLUSTER</command> should be
fast because most of the heap data has already been fast because most of the heap data has already been
ordered, and the existing index is used. ordered, and the existing index is used.
</para> </para>
@ -204,7 +212,7 @@
Cluster the employees relation on the basis of its salary attribute Cluster the employees relation on the basis of its salary attribute
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CLUSTER emp_ind ON emp CLUSTER emp_ind ON emp
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>
@ -217,13 +225,13 @@
<REFSECT2 ID="R2-SQL-CLUSTER-4"> <REFSECT2 ID="R2-SQL-CLUSTER-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no CLUSTER statement in SQL92. There is no <command>CLUSTER</command> statement in SQL92.
</PARA> </PARA>
</refsect2> </refsect2>
</refsect1> </refsect1>

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

@ -16,63 +16,43 @@
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
COMMIT [ WORK ] COMMIT [ WORK | TRANSACTION ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-COMMIT-1"> <REFSECT2 ID="R2-SQL-COMMIT-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA> None
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>None</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-COMMIT-2"> <REFSECT2 ID="R2-SQL-COMMIT-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>END</ReturnValue> <returnvalue>END</returnvalue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -82,8 +62,7 @@ Message returned if the transaction is successfully committed.
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>NOTICE EndTransactionBlock and not inprogress/abort state <returnvalue>NOTICE EndTransactionBlock and not inprogress/abort state</returnvalue>
</ReturnValue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -100,29 +79,29 @@ If there is no transaction in progress.
<REFSECT1 ID="R1-SQL-COMMIT-1"> <REFSECT1 ID="R1-SQL-COMMIT-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
COMMIT commits the current transaction. All <command>COMMIT</command> commits the current transaction. All
changes made by the transaction become visible to others changes made by the transaction become visible to others
and are guaranteed to be durable if a crash occurs. and are guaranteed to be durable if a crash occurs.
</PARA> </PARA>
<REFSECT2 ID="R2-SQL-COMMIT-3"> <REFSECT2 ID="R2-SQL-COMMIT-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
The keyword WORK is noise and can be omitted. The keywords WORK and TRANSACTION are noise and can be omitted.
</PARA> </PARA>
<para> <para>
Refer to ROLLBACK statements to abort a transaction. Use the <command>ROLLBACK</command> statement to abort a transaction.
</para> </para>
</REFSECT2> </REFSECT2>
</refsect1> </refsect1>
@ -135,7 +114,7 @@ If there is no transaction in progress.
To make all changes permanent: To make all changes permanent:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
COMMIT WORK; COMMIT WORK;
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>
@ -148,7 +127,7 @@ To make all changes permanent:
<REFSECT2 ID="R2-SQL-COMMIT-4"> <REFSECT2 ID="R2-SQL-COMMIT-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92

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

@ -14,69 +14,112 @@
</REFPURPOSE> </REFPURPOSE>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
COPY [BINARY] <replaceable class="parameter">table</replaceable> [WITH OIDS] COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ]
TO|FROM '<replaceable class="parameter">filename</replaceable>'|stdin|stdout FROM { '<replaceable class="parameter">filename</replaceable>' | <filename>stdin</filename> }
[USING DELIMITERS '<replaceable class="parameter">delimiter</replaceable>'] [ USING DELIMITERS '<replaceable class="parameter">delimiter</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>' ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-COPY-1"> <REFSECT2 ID="R2-SQL-COPY-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">table</replaceable></ReturnValue> BINARY
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The name of a table. Changes the behavior of field formatting, forcing all data to be
stored or read as binary objects rather than as text.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">delimiter</replaceable></ReturnValue> <replaceable class="parameter">table</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
A character that delimits fields. The name of an existing table.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
WITH OIDS
</TERM>
<LISTITEM>
<PARA>
Copies the internal unique object id (OID) for each row.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">filename</replaceable>
</TERM>
<LISTITEM>
<PARA>
The absolute Unix pathname of the input or output file.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<filename>stdin</filename>
</TERM>
<LISTITEM>
<PARA>
Specifies that input comes from a pipe or terminal.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<filename>stdout</filename>
</TERM>
<LISTITEM>
<PARA>
Specifies that output goes to a pipe or terminal.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">delimiter</replaceable>
</TERM>
<LISTITEM>
<PARA>
A character that delimits the input or output fields.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-COPY-2"> <REFSECT2 ID="R2-SQL-COPY-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
Status <Replaceable>status</Replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -110,84 +153,82 @@
<REFSECT1 ID="R1-SQL-COPY-1"> <REFSECT1 ID="R1-SQL-COPY-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
<command>COPY</command> moves data between PostgreSQL tables and <command>COPY</command> moves data between
standard Unix files. The keyword <function>BINARY</function> <productname>Postgres</productname> tables and
changes the behavior of field formatting, as described standard Unix files.
below. <replaceable class="parameter">Table</replaceable> is the
name of an existing table. The keyword <function>WITH <para>
OIDS</function> copies the internal unique object id (OID) for each <command>COPY</command> instructs
row. <replaceable class="parameter">Filename</replaceable> is the the <productname>Postgres</productname> backend
absolute Unix pathname of the file. In place of a filename, the to directly read from or write to a file. The file must be directly visible to
keywords <function>stdin</function> and <function>stdout</function> the backend and the name must be specified from the viewpoint of the backend.
can be used, so that input to <command>COPY</command> can be written If <filename>stdin</filename> or <filename>stdout</filename> are specified, data flows through the client frontend to
by a libpq application and output from <command>COPY</command> can the backend.
be read by a libpq application.
</para>
<para>
The <function>BINARY</function> keyword will force all data to be
stored/read as binary objects rather than as ASCII text. It is
somewhat faster than the normal copy command, but is not
generally portable, and the files generated are somewhat larger,
although this factor is highly dependent on the data itself. By
default, an ASCII copy uses a tab (\t) character as a delimiter.
The delimiter may also be changed to any other single character
with the keyword <function>USING DELIMITERS</function>. Characters
in data fields which happen to match the delimiter character will
be quoted.
</para>
<REFSECT2 ID="R2-SQL-COPY-3"> <REFSECT2 ID="R2-SQL-COPY-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<para>
The BINARY keyword will force all data to be
stored/read as binary objects rather than as text. It is
somewhat faster than the normal copy command, but is not
generally portable, and the files generated are somewhat larger,
although this factor is highly dependent on the data itself. By
default, a text copy uses a tab ("\t") character as a delimiter.
The delimiter may also be changed to any other single character
with the keyword phrase USING DELIMITERS. Characters
in data fields which happen to match the delimiter character will
be quoted.
</para>
<para> <para>
You must have select access on any table whose values are read by You must have select access on any table whose values are read by
<command>COPY</command>, and either insert or update access to a <command>COPY</command>, and either insert or update access to a
table into which values are being inserted by <command>COPY</command>. table into which values are being inserted by <command>COPY</command>.
The backend also needs appropriate Unix permissions for any file read The backend also needs appropriate Unix permissions for any file read
or written by <command>COPY</command>. or written by <command>COPY</command>.
<comment>
Is this right? The man page talked of read, write and append access, which
is neither SQL nor Unix terminology.
</comment>
</para> </para>
<para> <para>
The keyword <function>USING DELIMITERS</function> is inaptly The keyword phrase USING DELIMITERS specifies a single character
named, since only a single character may be specified. (If a to be used for all delimiters between columns. If multiple characters
group of characters is specified, only the first character is are specified in the delimiter string, only the first character is
used.) used.
</para>
<para> <tip>
WARNING: do not confuse <command>COPY</command> with the <para>
<command>psql</command> instruction <command>\copy</command>. Do not confuse <command>COPY</command> with the
</para> <application>psql</application> instruction <command>\copy</command>.
</tip>
</REFSECT2> </REFSECT2>
</refsect1> </refsect1>
<refsect1 ID="R1-SQL-COPY-2"> <refsect1 ID="R1-SQL-COPY-2">
<refsect1info> <refsect1info>
<date>1998-05-04</date> <date>1998-05-04</date>
</refsect1info> </refsect1info>
<title>Format of output files</title> <title>File Formats</title>
<refsect2> <refsect2>
<refsect2info> <refsect2info>
<date>1998-05-04</date> <date>1998-05-04</date>
</refsect2info> </refsect2info>
<title>ASCII copy format</title> <title>Text Format</title>
<para> <para>
When <command>COPY</command> is used without <function>BINARY</function>, When <command>COPY TO</command> is used without the BINARY option,
the file generated will have each instance on a single line, with each the file generated will have each row (instance) on a single line, with each
attribute separated by the delimiter character. Embedded column (attribute) separated by the delimiter character. Embedded
delimiter characters will be preceded by a backslash character delimiter characters will be preceded by a backslash character
(\). The attribute values themselves are strings generated by the ("\"). The attribute values themselves are strings generated by the
output function associated with each attribute type. The output output function associated with each attribute type. The output
function for a type should not try to generate the backslash function for a type should not try to generate the backslash
character; this will be handled by <command>COPY</command> itself. character; this will be handled by <command>COPY</command> itself.
@ -195,29 +236,31 @@ is neither SQL nor Unix terminology.
<para> <para>
The actual format for each instance is The actual format for each instance is
<programlisting> <programlisting>
&lt;attr1&gt;&lt;<replaceable class=parameter>separator</replaceable>&gt;&lt;attr2&gt;&lt;<replaceable class=parameter>separator</replaceable>&gt;...&lt;<replaceable class=parameter>separator</replaceable>&gt;&lt;attr<replaceable class="parameter">n</replaceable>&gt;&lt;newline&gt;</programlisting> &lt;attr1&gt;&lt;<replaceable class=parameter>separator</replaceable>&gt;&lt;attr2&gt;&lt;<replaceable class=parameter>separator</replaceable>&gt;...&lt;<replaceable class=parameter>separator</replaceable>&gt;&lt;attr<replaceable class="parameter">n</replaceable>&gt;&lt;newline&gt;
</programlisting>
The oid is placed on the beginning of the line The oid is placed on the beginning of the line
if <function>WITH OIDS</function> is specified. if WITH OIDS is specified.
</para> </para>
<para> <para>
If <command>COPY</command> is sending its output to standard If <command>COPY</command> is sending its output to standard
output instead of a file, it will send a backslash(\) and a period output instead of a file, it will send a backslash("\") and a period
(.) followed immediately by a newline, on a separate line, (".") followed immediately by a newline, on a separate line,
when it is done. Similarly, if <command>COPY</command> is reading when it is done. Similarly, if <command>COPY</command> is reading
from standard input, it will expect a backslash (\) and a period from standard input, it will expect a backslash ("\") and a period
(.) followed by a newline, as the first three characters on a (".") followed by a newline, as the first three characters on a
line, to denote end-of-file. However, <command>COPY</command> line to denote end-of-file. However, <command>COPY</command>
will terminate (followed by the backend itself) if a true EOF is will terminate (followed by the backend itself) if a true EOF is
encountered. encountered before this special end-of-file pattern is found.
</para> </para>
<para> <para>
The backslash character has special meaning. NULL attributes are The backslash character has other special meanings. NULL attributes are
output as \N. A literal backslash character is output as two output as "\N". A literal backslash character is output as two
consecutive backslashes. A literal tab character is represented consecutive backslashes ("\\"). A literal tab character is represented
as a backslash and a tab. A literal newline character is as a backslash and a tab. A literal newline character is
represented as a backslash and a newline. When loading ASCII data represented as a backslash and a newline. When loading text data
not generated by PostgreSQL, you will need to convert backslash not generated by <acronym>Postgres</acronym>,
characters (\) to double-backslashes (\\) to ensure that they are loaded you will need to convert backslash
characters ("\") to double-backslashes ("\\") to ensure that they are loaded
properly. properly.
</para> </para>
</refsect2> </refsect2>
@ -225,7 +268,7 @@ is neither SQL nor Unix terminology.
<refsect2info> <refsect2info>
<date>1998-05-04</date> <date>1998-05-04</date>
</refsect2info> </refsect2info>
<title>Binary copy format</title> <title>Binary Format</title>
<para> <para>
In the case of <command>COPY BINARY</command>, the first four In the case of <command>COPY BINARY</command>, the first four
bytes in the file will be the number of instances in the file. If bytes in the file will be the number of instances in the file. If
@ -270,16 +313,8 @@ is neither SQL nor Unix terminology.
<entry>number of null attributes</entry> <entry>number of null attributes</entry>
</row> </row>
<row> <row>
<entry>[uint32</entry> <entry>[uint32,...,uint32]</entry>
<entry>attribute number of first null attribute, counting from 0</entry> <entry>attribute numbers of attributes, counting from 0</entry>
</row>
<row>
<entry>...</entry>
<entry>...</entry>
</row>
<row>
<entry>uint32</entry>
<entry>attribute number of last null attribute]</entry>
</row> </row>
<row> <row>
<entry>-</entry> <entry>-</entry>
@ -294,12 +329,12 @@ is neither SQL nor Unix terminology.
<refsect2info> <refsect2info>
<date>1998-05-04</date> <date>1998-05-04</date>
</refsect2info> </refsect2info>
<title>Alignment of binary data</title> <title>Alignment of Binary Data</title>
<para> <para>
On Sun-3s, 2-byte attributes are aligned on two-byte boundaries, On Sun-3s, 2-byte attributes are aligned on two-byte boundaries,
and all larger attributes are aligned on four-byte boundaries. and all larger attributes are aligned on four-byte boundaries.
Character attributes are aligned on single-byte boundaries. On Character attributes are aligned on single-byte boundaries. On
other machines, all attributes larger than 1 byte are aligned on most other machines, all attributes larger than 1 byte are aligned on
four-byte boundaries. Note that variable length attributes are four-byte boundaries. Note that variable length attributes are
preceded by the attribute's length; arrays are simply contiguous preceded by the attribute's length; arrays are simply contiguous
streams of the array element type. streams of the array element type.
@ -313,19 +348,22 @@ is neither SQL nor Unix terminology.
Usage Usage
</TITLE> </TITLE>
<PARA> <PARA>
To copy a table to standard output, using | as a delimiter The following example copies a table to standard output,
using a vertical bar ("|") as the field
delimiter:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
COPY country TO stdout USING DELIMITERS '|'; COPY country TO <filename>stdout</filename> USING DELIMITERS '|';
</ProgramListing> </ProgramListing>
<PARA> <PARA>
To copy data from a Unix file into a table: To copy data from a Unix file into a table "country":
</PARA> </PARA>
<ProgramListing> <ProgramListing>
COPY country FROM '/usr1/proj/bray/sql/country_data'; COPY country FROM '/usr1/proj/bray/sql/country_data';
</ProgramListing> </ProgramListing>
<PARA> <PARA>
A sample of data suitable for copying into a table from <filename>stdin</filename> (so it Here is a sample of data suitable for copying into a table
from <filename>stdin</filename> (so it
has the termination sequence on the last line): has the termination sequence on the last line):
</PARA> </PARA>
<ProgramListing> <ProgramListing>
@ -338,10 +376,13 @@ has the termination sequence on the last line):
\. \.
</ProgramListing> </ProgramListing>
<PARA> <PARA>
The same data, output in binary format on a Linux Intel machine. 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 The data is shown after filtering through
three fields; the first is <classname>char(2)</classname> and the second is <classname>text</classname>. All the the Unix utility <command>od -c</command>. The table has
rows have a null value in the third field). Notice how the <classname>char(2)</classname> three fields; the first is <classname>char(2)</classname>
and the second is <classname>text</classname>. All the
rows have a null value in the third field.
Notice how the <classname>char(2)</classname>
field is padded with nulls to four bytes and the text field is field is padded with nulls to four bytes and the text field is
preceded by its length: preceded by its length:
</PARA> </PARA>
@ -359,32 +400,32 @@ has the termination sequence on the last line):
</ProgramListing> </ProgramListing>
</refsect1> </refsect1>
<refsect1 ID="R1-SQL-COPY-4">
<title>See also</title>
<para>
insert(l), create table(l), vacuum(l), libpq.
</para>
</refsect1>
<refsect1 ID="R1-SQL-COPY-5"> <refsect1 ID="R1-SQL-COPY-5">
<title>Bugs</title> <title>Bugs</title>
<para> <para>
<command>COPY</command> stops operation at the first error. This <command>COPY</command> stops operation at the first error. This
should not lead to problems in the event of a copy from, but the should not lead to problems in the event of
target relation will, of course, be partially modified in a copy a <command>COPY FROM</command>, but the
to. The <command>VACUUM</command> query should be used to clean up target relation will, of course, be partially modified in a
<command>COPY TO</command>.
The <command>VACUUM</command> query should be used to clean up
after a failed copy. after a failed copy.
</para> </para>
<para> <para>
Because Postgres' current directory is not the same as the user's Because the Postgres backend's current working directory
working directory, the result of copying to a file "foo" (without is not usually the same as the user's
working directory, the result of copying to a file
"<filename>foo</filename>" (without
additional path information) may yield unexpected results for the additional path information) may yield unexpected results for the
naive user. In this case, "foo" will wind up in $PGDATA/foo. In naive user. In this case, <filename>foo</filename>
general, the full pathname should be used when specifying files to will wind up in <filename>$PGDATA/foo</filename>. In
general, the full pathname as it would appear to the backend server machine
should be used when specifying files to
be copied. be copied.
</para> </para>
<para> <para>
Files used as arguments to the copy command must reside on or be Files used as arguments to <command>COPY</command>
must reside on or be
accessible to the database server machine by being either on accessible to the database server machine by being either on
local disks or on a networked file system. local disks or on a networked file system.
</para> </para>
@ -405,13 +446,13 @@ has the termination sequence on the last line):
<REFSECT2 ID="R2-SQL-COPY-4"> <REFSECT2 ID="R2-SQL-COPY-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-08</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no COPY statement in SQL92. There is no <command>COPY</command> statement in SQL92.
</PARA> </PARA>
</refsect2> </refsect2>
</refsect1> </refsect1>

231
doc/src/sgml/ref/create_aggregate.sgml
View File

@ -6,10 +6,6 @@
<REFMISCINFO>SQL - Language Statements</REFMISCINFO> <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA> </REFMETA>
<comment>This entry needs a lot of work, especially some
usefully complex examples. Since I don't yet understand it, I
haven't done this.</comment>
<REFNAMEDIV> <REFNAMEDIV>
<REFNAME> <REFNAME>
CREATE AGGREGATE CREATE AGGREGATE
@ -19,32 +15,28 @@ haven't done this.</comment>
</REFPURPOSE> </REFPURPOSE>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CREATE AGGREGATE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [AS] CREATE AGGREGATE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [ AS ]
([ SFUNC1 = <REPLACEABLE CLASS="PARAMETER">state_transition_function1</REPLACEABLE> ( BASETYPE = <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
, BASETYPE = <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE> [ , SFUNC1 = <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
, STYPE1 = <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE> ] , STYPE1 = <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE> ]
[, SFUNC2 = <REPLACEABLE CLASS="PARAMETER">state_transition_function2</REPLACEABLE> [ , SFUNC2 = <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>
, STYPE2 = <REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE> ] , STYPE2 = <REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE> ]
[, FINALFUNC = <REPLACEABLE CLASS="PARAMETER">final_function</REPLACEABLE> ] [ , FINALFUNC = <REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE> ]
[, INITCOND1 = <REPLACEABLE CLASS="PARAMETER">initial_condition1</REPLACEABLE> ] [ , INITCOND1 = <REPLACEABLE CLASS="PARAMETER">initial_condition1</REPLACEABLE> ]
[, INITCOND2 = <REPLACEABLE CLASS="PARAMETER">initial_condition2</REPLACEABLE> ] [ , INITCOND2 = <REPLACEABLE CLASS="PARAMETER">initial_condition2</REPLACEABLE> ]
) )
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-1"> <REFSECT2 ID="R2-SQL-CREATEAGGREGATE-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<variablelist>
<varlistentry>
<term></term>
<listitem>
<PARA> <PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
@ -57,88 +49,115 @@ haven't done this.</comment>
</para> </para>
</LISTITEM> </LISTITEM>
</varlistentry> </varlistentry>
<varlistentry>
<term>
<REPLACEABLE CLASS="PARAMETER">state_transition_function1</REPLACEABLE>
</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
</term> </term>
<listitem> <listitem>
<para> <para>
The fundamental data type on which this aggregate function operates.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
</term>
<listitem>
<para>
The state transition function
to be called for every non-NULL field from the source column.
It takes a variable of
type <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE> as
the first argument and that field as the
second argument.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
</term> </term>
<listitem> <listitem>
<para> <para>
The return type of the first transition function.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<REPLACEABLE CLASS="PARAMETER">state-transition_function2</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>
</term> </term>
<listitem> <listitem>
<para> <para>
The state transition function
to be called for every non-NULL field from the source column.
It takes a variable
of type <REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>
as the only argument and returns a variable of the same type.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>
</term> </term>
<listitem> <listitem>
<para> <para>
The return type of the second transition function.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<REPLACEABLE CLASS="PARAMETER">final_function</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>
</term> </term>
<listitem> <listitem>
<para> <para>
The final function
called after traversing all input fields. This function must
take two arguments of types
<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
and
<REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<REPLACEABLE CLASS="PARAMETER">initial_condition1</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">initial_condition1</REPLACEABLE>
</term> </term>
<listitem> <listitem>
<para> <para>
The initial value for the first transition function argument.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<REPLACEABLE CLASS="PARAMETER">initial_condition2</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">initial_condition2</REPLACEABLE>
</term> </term>
<listitem> <listitem>
<para> <para>
The initial value for the second transition function argument.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</PARA>
</listitem>
</varlistentry>
</variablelist>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-2"> <REFSECT2 ID="R2-SQL-CREATEAGGREGATE-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -148,6 +167,7 @@ haven't done this.</comment>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -172,82 +192,130 @@ haven't done this.</comment>
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-1"> <REFSECT1 ID="R1-SQL-CREATEAGGREGATE-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<para>
<command>CREATE AGGREGATE</command>
allows a user or programmer to extend <productname>Postgres</productname>
functionality by defining new aggregate functions. Some aggregate functions
for base types such as <function>min(int4)</function>
and <function>avg(float8)</function> are already provided in the base
distribution. If one defines new types or needs an aggregate function not
already provided then <command>CREATE AGGREGATE</command>
can be used to provide the desired features.
<PARA> <PARA>
An aggregate function can use up to three functions, two An aggregate function can require up to three functions, two
state transition functions, X1 and X2: state transition functions,
X1( internal-state1, next-data_item ) ---> next-internal-state1 <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
X2( internal-state2 ) ---> next-internal-state2 and <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>:
and a final calculation function, F: <programlisting>
F(internal-state1, internal-state2) ---> aggregate-value <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>( internal-state1, next-data_item ) ---> next-internal-state1
These functions are required to have the following properties: <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>( internal-state2 ) ---> next-internal-state2
</programlisting>
and a final calculation function,
<REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>:
<programlisting>
<REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>(internal-state1, internal-state2) ---> aggregate-value
</programlisting>
<para>
<productname>Postgres</productname> creates up to two temporary variables
(referred to here as <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
and <REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>)
to hold intermediate results used as arguments to the transition functions.
<para>
These transition functions are required to have the following properties:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
The arguments to state-transition-function-1 must The arguments to
be (stype1,basetype), and its return value must be <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
stype1. must be
<REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
of type
<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
and
<REPLACEABLE CLASS="PARAMETER">column_value</REPLACEABLE>
of type <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>.
The return value must be of type
<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
and will be used as the first argument in the next call to
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The argument and return value of state-transition- The argument and return value of
function-2 must be stype2. <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>
must be
<REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
of type
<REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The arguments to the final-calculation-function The arguments to the final-calculation-function
must be (stype1,stype2), and its return value must must be
be a POSTGRES base type (not necessarily the same <REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
as basetype. and
<REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
and its return value must
be a <productname>Postgres</productname>
base type (not necessarily
<REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
which had been specified for BASETYPE).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The final-calculation-function should be specified FINALFUNC should be specified
if and only if both state-transition functions are if and only if both state-transition functions are
specified. specified.
</para </para
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</PARA> </PARA>
<para>
Note that it is possible to specify aggregate functions
that have varying combinations of state and final functions.
For example, the "count" aggregate requires sfunc2
(an incrementing function) but not sfunc1 or finalfunc,
whereas the "sum" aggregate requires sfunc1 (an addition
function) but not sfunc2 or finalfunc and the "average"
aggregate requires both of the above state functions as
well as a finalfunc (a division function) to produce its
answer. In any case, at least one state function must be
defined, and any sfunc2 must have a corresponding initcond2.
</para>
<para> <para>
Aggregates also require two initial conditions, one for An aggregate function may also require one or two initial conditions,
one for
each transition function. These are specified and stored each transition function. These are specified and stored
in the database as fields of type text. in the database as fields of type <type>text</type>.
</para> </para>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-3"> <REFSECT2 ID="R2-SQL-CREATEAGGREGATE-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA>
CREATE AGGREGATE function is a PostgreSQL language extension.
</PARA>
<para> <para>
Refer to DROP AGGREGATE function to drop aggregate functions. Use <command>DROP AGGREGATE</command>
to drop aggregate functions.
</para> </para>
<para>
It is possible to specify aggregate functions
that have varying combinations of state and final functions.
For example, the <function>count</function> aggregate requires SFUNC2
(an incrementing function) but not SFUNC1 or FINALFUNC,
whereas the <function>sum</function> aggregate requires SFUNC1 (an addition
function) but not SFUNC2 or FINALFUNC and the <function>avg</function>
aggregate requires
both of the above state functions as
well as a FINALFUNC (a division function) to produce its
answer. In any case, at least one state function must be
defined, and any SFUNC2 must have a corresponding INITCOND2.
</para>
</REFSECT2> </REFSECT2>
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-2"> <REFSECT1 ID="R1-SQL-CREATEAGGREGATE-2">
@ -255,10 +323,10 @@ haven't done this.</comment>
Usage Usage
</TITLE> </TITLE>
<PARA> <PARA>
</PARA> Refer to the chapter on aggregate functions
<ProgramListing> in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
</ProgramListing> on aggregate functions for
complete examples of usage.
</REFSECT1> </REFSECT1>
@ -267,17 +335,18 @@ haven't done this.</comment>
Compatibility Compatibility
</TITLE> </TITLE>
<PARA> <PARA>
</PARA>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-4"> <REFSECT2 ID="R2-SQL-CREATEAGGREGATE-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no CREATE AGGREGATE function on SQL92. <command>CREATE AGGREGATE</command>
is a <productname>Postgres</productname> language extension.
There is no <command>CREATE AGGREGATE</command> in SQL92.
</PARA> </PARA>
</REFENTRY> </REFENTRY>

53
doc/src/sgml/ref/create_database.sgml
View File

@ -17,7 +17,7 @@
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CREATE DATABASE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [WITH LOCATION = '<replaceable class="parameter">dbpath</replaceable>'] CREATE DATABASE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [ WITH LOCATION = '<replaceable class="parameter">dbpath</replaceable>' ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-1"> <REFSECT2 ID="R2-SQL-CREATEDATABASE-1">
@ -28,13 +28,6 @@
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -62,9 +55,6 @@
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-2"> <REFSECT2 ID="R2-SQL-CREATEDATABASE-2">
@ -79,6 +69,7 @@
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -142,10 +133,11 @@ There was a problem with creating the required directory; this operation will
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
<command>CREATE DATABASE</command> statement is a Postgres language extension. <command>CREATE DATABASE</command> is a <productname>Postgres</productname>
language extension.
</PARA> </PARA>
<para> <para>
Refer to <command>DROP DATABASE</command> statement to remove a database. Use <command>DROP DATABASE</command> to remove a database.
</para> </para>
</REFSECT2> </REFSECT2>
@ -157,26 +149,26 @@ There was a problem with creating the required directory; this operation will
To create a new database: To create a new database:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput> <prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
</ProgramListing> </ProgramListing>
<PARA> <PARA>
To create a new database in an alternate area <filename>~/private_db</filename>: To create a new database in an alternate area <filename>~/private_db</filename>:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
<prompt>$</prompt> <userinput>mkdir private_db</userinput> <prompt>$</prompt> <userinput>mkdir private_db</userinput>
<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput> <prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
<computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput> <computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
<prompt>$</prompt> <userinput>psql olly</userinput> <prompt>$</prompt> <userinput>psql olly</userinput>
<computeroutput>Welcome to the POSTGRESQL interactive sql monitor: <computeroutput>Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL Please read the file COPYRIGHT for copyright terms of POSTGRESQL
type \? for help on slash commands type \? for help on slash commands
type \q to quit type \q to quit
type \g or terminate with semicolon to execute query type \g or terminate with semicolon to execute query
You are currently connected to the database: template1 You are currently connected to the database: template1
<prompt>olly=></prompt></computeroutput> <userinput>create database elsewhere with location = '/home/olly/private_db';</userinput> <prompt>olly=></prompt></computeroutput> <userinput>create database elsewhere with location = '/home/olly/private_db';</userinput>
<computeroutput>CREATEDB</computeroutput> <computeroutput>CREATEDB</computeroutput>
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>
@ -186,8 +178,12 @@ There was a problem with creating the required directory; this operation will
Bugs Bugs
</TITLE> </TITLE>
<PARA> <PARA>
There are security and data integrity issues involved with using alternate database locations There are security and data integrity issues
specified with absolute path names. See the Administrator's Guide for more information. involved with using alternate database locations
specified with absolute path names, and by default
only an environment variable known to the backend may be
specified for an alternate location.
See the Administrator's Guide for more information.
</PARA> </PARA>
</refsect1> </refsect1>
@ -207,7 +203,6 @@ Not sure if the dump/reload would guarantee that the alternate data area gets re
Compatibility Compatibility
</TITLE> </TITLE>
<PARA> <PARA>
</PARA>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-4"> <REFSECT2 ID="R2-SQL-CREATEDATABASE-4">
<REFSECT2INFO> <REFSECT2INFO>
@ -217,7 +212,7 @@ Not sure if the dump/reload would guarantee that the alternate data area gets re
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no <command>CREATE DATABASE</command> statement on SQL92. There is no <command>CREATE DATABASE</command> statement in SQL92.
</PARA> </PARA>
<para> <para>
The equivalent command in standard SQL is <command>CREATE SCHEMA</command>. The equivalent command in standard SQL is <command>CREATE SCHEMA</command>.

136
doc/src/sgml/ref/create_function.sgml
View File

@ -15,30 +15,23 @@
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ([<replaceable class="parameter">ftype</replaceable> [, ...]]) CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
RETURNS <replaceable class="parameter">rtype</replaceable> RETURNS <replaceable class="parameter">rtype</replaceable>
AS <replaceable class="parameter">path</replaceable> AS <replaceable class="parameter">path</replaceable>
LANGUAGE '<replaceable class="parameter">langname</replaceable>' LANGUAGE '<replaceable class="parameter">langname</replaceable>'
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATEFUNCTION-1"> <REFSECT2 ID="R2-SQL-CREATEFUNCTION-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -87,21 +80,21 @@
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
may be '<literal>c</literal>', '<literal>sql</literal>', '<literal>internal</literal>' or '<replaceable class="parameter">plname</replaceable>'. may be '<literal>C</literal>', '<literal>sql</literal>',
(where '<replaceable class="parameter">plname</replaceable>' is the language name of a created procedural '<literal>internal</literal>'
language. See <command>CREATE LANGUAGE</command> for details). or '<replaceable class="parameter">plname</replaceable>',
where '<replaceable class="parameter">plname</replaceable>'
is the name of a created procedural
language. See <command>CREATE LANGUAGE</command> for details.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEFUNCTION-2"> <REFSECT2 ID="R2-SQL-CREATEFUNCTION-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -111,6 +104,7 @@
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -134,32 +128,34 @@
<REFSECT1 ID="R1-SQL-CREATEFUNCTION-1"> <REFSECT1 ID="R1-SQL-CREATEFUNCTION-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
With this command, a PostgreSQL user can register a function <command>CREATE FUNCTION</command> allows a
with PostgreSQL. Subsequently, this user is treated as the <productname>Postgres</productname> user
to register a function
with a database. Subsequently, this user is treated as the
owner of the function. owner of the function.
</PARA> </PARA>
<REFSECT2 ID="R2-SQL-CREATEFUNCTION-3"> <REFSECT2 ID="R2-SQL-CREATEFUNCTION-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
Refer to <citetitle>PostgreSQL User's Guide</citetitle> chapter 6 for further information. Refer to the chapter on functions
<comment>This reference needs to be corrected.</comment> in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
for further information.
</PARA> </PARA>
<PARA> <PARA>
Refer to the <citerefentry> Use <command>DROP FUNCTION</command>
<refentrytitle>DROP FUNCTION</refentrytitle> to drop user-defined functions.
</citerefentry> statement to drop functions.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
@ -171,15 +167,17 @@
To create a simple SQL function: To create a simple SQL function:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CREATE FUNCTION one() RETURNS int4 CREATE FUNCTION one() RETURNS int4
AS 'SELECT 1 AS RESULT' AS 'SELECT 1 AS RESULT'
LANGUAGE 'sql'; LANGUAGE 'sql';
SELECT one() AS answer; SELECT one() AS answer;
<computeroutput>answer <computeroutput>
------ answer
1 </computeroutput> ------
1
</computeroutput>
</ProgramListing> </ProgramListing>
<para> <para>
To create a C function, calling a routine from a user-created To create a C function, calling a routine from a user-created
@ -188,17 +186,18 @@
is correct. It is intended for use in a CHECK contraint. is correct. It is intended for use in a CHECK contraint.
</para> </para>
<programlisting> <programlisting>
<userinput>CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool <userinput>
AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c'; CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
CREATE TABLE product CREATE TABLE product
( (
id char(8) PRIMARY KEY, id char(8) PRIMARY KEY,
eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}') eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
REFERENCES brandname(ean_prefix), REFERENCES brandname(ean_prefix),
eancode char(6) CHECK (eancode ~ '[0-9]{6}'), eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode)) CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
);</userinput> );</userinput>
</programlisting> </programlisting>
</REFSECT1> </REFSECT1>
@ -216,39 +215,44 @@
Compatibility Compatibility
</TITLE> </TITLE>
<PARA> <PARA>
The CREATE FUNCTION statement is a PostgreSQL language extension. <command>CREATE FUNCTION</command> is
a <productname>Postgres</productname> language extension.
</PARA> </PARA>
<REFSECT2 ID="R2-SQL-CREATEFUNCTION-4"> <REFSECT2 ID="R2-SQL-CREATEFUNCTION-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL/PSM<footnote> SQL/PSM
<para>
PSM stands for Persistent Stored Modules, it is a procedural
language and it was originally hoped that PSM would be ratified
as an official standard by late 1996. However PSM will
eventually become a standard.
</para>
</footnote>
</TITLE> </TITLE>
<para> <para>
The SQL/PSM CREATE FUNCTION statement has the following syntax:
<programlisting> <note>
CREATE FUNCTION <replaceable class="parameter">name</replaceable> <para>
( [ [IN|OUT|INOUT] <replaceable class="parameter">parm</replaceable> <replaceable class="parameter">type</replaceable> [, ...] ]) PSM stands for Persistent Stored Modules. It is a procedural
RETURNS <replaceable class="parameter">rtype</replaceable> language and it was originally hoped that PSM would be ratified
LANGUAGE '<replaceable class="parameter">langname</replaceable>' as an official standard by late 1996. As of mid-1998, this
ESPECIFIC <replaceable class="parameter">routine</replaceable> has not yet happened, but it is hoped that PSM will
<replaceable class="parameter">SQL-statement</replaceable> eventually become a standard.
</programlisting> </para>
</note>
SQL/PSM <command>CREATE FUNCTION</command> has the following syntax:
<synopsis>
CREATE FUNCTION <replaceable class="parameter">name</replaceable>
( [ [ IN | OUT | INOUT ] <replaceable class="parameter">parm</replaceable> <replaceable class="parameter">type</replaceable> [, ...] ] )
RETURNS <replaceable class="parameter">rtype</replaceable>
LANGUAGE '<replaceable class="parameter">langname</replaceable>'
ESPECIFIC <replaceable class="parameter">routine</replaceable>
<replaceable class="parameter">SQL-statement</replaceable>
</synopsis>
</para> </para>
</refsect2> </refsect2>
</refsect1> </refsect1>
</REFENTRY> </REFENTRY>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file
Local variables: Local variables:
mode: sgml mode: sgml

110
doc/src/sgml/ref/create_index.sgml
View File

@ -14,41 +14,33 @@
</REFPURPOSE> </REFPURPOSE>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CREATE [UNIQUE] INDEX <replaceable class="parameter">index_name</replaceable> CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
ON <replaceable class="parameter">table</replaceable> [USING <replaceable class="parameter">acc_name</replaceable> ] ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">acc_name</replaceable> ]
( <replaceable class="parameter">column</replaceable> [<replaceable class="parameter">ops_name</replaceable>] [, ...] ) ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable>] [, ...] )
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
CREATE [UNIQUE] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">acc_name</replaceable> ]
ON <replaceable class="parameter">table</replaceable> [USING <replaceable class="parameter">acc_name</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) <replaceable class="parameter">ops_name</replaceable> )
( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) <replaceable class="parameter">ops_name</replaceable> )
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATEINDEX-1"> <REFSECT2 ID="R2-SQL-CREATEINDEX-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<function>UNIQUE</function> UNIQUE
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
<function>UNIQUE</function> causes the system to check for Causes the system to check for
duplicate values when the index is created (if data duplicate values when the index is created (if data
already exist) and each time data is added. Attempts to already exist) and each time data is added. Attempts to
insert or update non-duplicate data will generate an insert or update non-duplicate data will generate an
@ -134,17 +126,18 @@
An associated operator class. An associated operator class.
The following select list returns all ops_names: The following select list returns all ops_names:
<programlisting> <programlisting>
SELECT am.amname AS acc_name, SELECT am.amname AS acc_name,
opc.opcname AS ops_name, opc.opcname AS ops_name,
opr.oprname AS ops_comp opr.oprname AS ops_comp
FROM pg_am am, pg_amop amop, FROM pg_am am, pg_amop amop,
pg_opclass opc, pg_operator opr pg_opclass opc, pg_operator opr
WHERE amop.amopid = am.oid AND WHERE amop.amopid = am.oid AND
amop.amopclaid = opc.oid AND amop.amopclaid = opc.oid AND
amop.amopopr = opr.oid amop.amopopr = opr.oid
ORDER BY acc_name, ops_name, ops_comp ORDER BY acc_name, ops_name, ops_comp
</programlisting> </programlisting>
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -160,14 +153,12 @@
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEINDEX-2"> <REFSECT2 ID="R2-SQL-CREATEINDEX-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -177,6 +168,7 @@
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -210,14 +202,23 @@
<REFSECT1 ID="R1-SQL-CREATEINDEX-1"> <REFSECT1 ID="R1-SQL-CREATEINDEX-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
This command constructs an index called <replaceable class="parameter">index_name</replaceable>. This command constructs an index
</PARA> <replaceable class="parameter">index_name</replaceable>.
on the specified
<replaceable class="parameter">table</replaceable>.
<tip>
<para>
Indices are primarily used to enhance database performance.
But inappropriate use will result in slower performance.
</tip>
<para> <para>
In the first syntax shown above, the key fields for the In the first syntax shown above, the key fields for the
index are specified as column names; a column may also have index are specified as column names; a column may also have
@ -242,7 +243,7 @@
<REFSECT2 ID="R2-SQL-CREATEINDEX-3"> <REFSECT2 ID="R2-SQL-CREATEINDEX-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
@ -252,10 +253,8 @@
indices. Up to 7 keys may be specified. indices. Up to 7 keys may be specified.
</PARA> </PARA>
<para> <para>
Use the <citerefentry> Use <command>DROP INDEX</command>
<refentrytitle>DROP INDEX</refentrytitle> to remove an index.
</citerefentry>
statement to remove indexes.
</para> </para>
</REFSECT2> </REFSECT2>
@ -267,24 +266,27 @@
in the table <literal>films</literal>: in the table <literal>films</literal>:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CREATE UNIQUE INDEX title_idx CREATE UNIQUE INDEX title_idx
ON films (title); ON films (title);
</ProgramListing> </ProgramListing>
<!--
<comment>
Is this example correct?
</comment>
<para> <para>
To create a rtree index on a point attribute so that we To create a rtree index on a point attribute so that we
can efficiently use box operators on the result of the can efficiently use box operators on the result of the
conversion function: conversion function:
</para> </para>
<programlisting> <programlisting>
CREATE INDEX pointloc CREATE INDEX pointloc
ON points USING RTREE (point2box(location) box_ops); ON points USING RTREE (point2box(location) box_ops);
SELECT * FROM points
SELECT * FROM points WHERE point2box(points.pointloc) = boxes.box;
WHERE point2box(points.pointloc) = boxes.box;
<comment>
Is this example correct?
</comment>
</programlisting> </programlisting>
-->
</REFSECT1> </REFSECT1>
<REFSECT1 ID="R1-SQL-CREATEINDEX-3"> <REFSECT1 ID="R1-SQL-CREATEINDEX-3">
@ -296,16 +298,16 @@ Is this example correct?
<REFSECT2 ID="R2-SQL-CREATEINDEX-4"> <REFSECT2 ID="R2-SQL-CREATEINDEX-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
CREATE INDEX is a PostgreSQL language extension. CREATE INDEX is a <productname>Postgres</productname> language extension.
</PARA> </PARA>
<para> <para>
There is no CREATE INDEX command in SQL92. There is no <command>CREATE INDEX</command> command in SQL92.
</para> </para>
</refsect2> </refsect2>
</refsect1> </refsect1>

125
doc/src/sgml/ref/create_language.sgml
View File

@ -15,29 +15,22 @@
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CREATE [TRUSTED] PROCEDURAL LANGUAGE '<replaceable class="parameter">langname</replaceable>' CREATE [ TRUSTED ] PROCEDURAL LANGUAGE '<replaceable class="parameter">langname</replaceable>'
HANDLER <replaceable class="parameter">call_handler</replaceable> HANDLER <replaceable class="parameter">call_handler</replaceable>
LANCOMPILER '<replaceable class="parameter">comment</replaceable>' LANCOMPILER '<replaceable class="parameter">comment</replaceable>'
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-1"> <REFSECT2 ID="R2-SQL-CREATELANGUAGE-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -99,14 +92,12 @@
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-2"> <REFSECT2 ID="R2-SQL-CREATELANGUAGE-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -116,6 +107,7 @@
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -152,22 +144,25 @@
<REFSECT1 ID="R1-SQL-CREATELANGUAGE-1"> <REFSECT1 ID="R1-SQL-CREATELANGUAGE-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
Using <command>CREATE LANGUAGE</command>, a PostgreSQL user can register Using <command>CREATE LANGUAGE</command>, a
a new language with PostgreSQL. Subsequently, functions and <productname>Postgres</productname> user can register
a new language with <productname>Postgres</productname>.
Subsequently, functions and
trigger procedures can be defined in this new language. trigger procedures can be defined in this new language.
The user must have the PostgreSQL superuser privilege to The user must have the <productname>Postgres</productname>
superuser privilege to
register a new language. register a new language.
</PARA> </PARA>
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-3"> <REFSECT2 ID="R2-SQL-CREATELANGUAGE-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Writing PL handlers Writing PL handlers
@ -175,9 +170,9 @@
<PARA> <PARA>
The call handler for a procedural language must be written The call handler for a procedural language must be written
in a compiler language such as 'C' and registered with in a compiler language such as 'C' and registered with
PostgreSQL as a function taking no arguments and returning <productname>Postgres</productname> as a function taking
opaque type. no arguments and returning the
<comment>What does `opaque type' mean?</comment> <type>opaque</type> type, a placeholder for unspecified or undefined types..
This prevents the call handler from being This prevents the call handler from being
called directly as a function from queries. called directly as a function from queries.
</para> </para>
@ -214,11 +209,11 @@
It's up to the call handler to fetch the It's up to the call handler to fetch the
<filename>pg_proc</filename> entry and <filename>pg_proc</filename> entry and
to analyze the argument and return types of the called to analyze the argument and return types of the called
procedure. The <function>AS</function> clause from the procedure. The AS clause from the
<command>CREATE FUNCTION</command> of <command>CREATE FUNCTION</command> of
the procedure will be found in the <literal>prosrc</literal> the procedure will be found in the <literal>prosrc</literal>
attribute of the attribute of the
<filename>pg_proc</filename> entry. This may be the <filename>pg_proc</filename> table entry. This may be the
source text in the procedural source text in the procedural
language itself (like for PL/Tcl), a pathname to a language itself (like for PL/Tcl), a pathname to a
file or anything else that tells the call handler what to file or anything else that tells the call handler what to
@ -227,43 +222,40 @@
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-4"> <REFSECT2 ID="R2-SQL-CREATELANGUAGE-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
Use <citerefentry> Use <command>CREATE FUNCTION</command>
<refentrytitle>CREATE FUNCTION</refentrytitle>
</citerefentry>
to create a function. to create a function.
</para> </para>
<para> <para>
Use <citerefentry> Use <command>DROP LANGUAGE</command> to drop procedural languages.
<refentrytitle>DROP LANGUAGE</refentrytitle>
</citerefentry> to drop procedural languages.
</para> </para>
<para> <para>
Refer to the table <filename>pg_language</filename> Refer to the table <filename>pg_language</filename>
for further information: for further information:
<programlisting> <programlisting>
<computeroutput> <computeroutput>
Table = pg_language Table = pg_language
+--------------------------+--------------------------+-------+ +--------------------------+--------------------------+-------+
| Field | Type | Length| | Field | Type | Length|
+--------------------------+--------------------------+-------+ +--------------------------+--------------------------+-------+
| lanname | name | 32 | | lanname | name | 32 |
| lancompiler | text | var | | lancompiler | text | var |
+--------------------------+--------------------------+-------+ +--------------------------+--------------------------+-------+
lanname |lancompiler
--------+--------------
internal|n/a
lisp |/usr/ucb/liszt
C |/bin/cc
sql |postgres
</computeroutput>
</programlisting>
lanname |lancompiler
--------+--------------
internal|n/a
lisp |/usr/ucb/liszt
C |/bin/cc
sql |postgres
</computeroutput>
</programlisting>
</para> </para>
</refsect2> </refsect2>
</refsect1> </refsect1>
@ -274,11 +266,9 @@
</TITLE> </TITLE>
<PARA> <PARA>
Since the call handler for a procedural language must be Since the call handler for a procedural language must be
registered with PostgreSQL in the 'C' language, it inherits registered with <productname>Postgres</productname> in the 'C' language,
all the restrictions of 'C' functions. it inherits
<comment> all the capabilities and restrictions of 'C' functions.
What are these restrictions?
</comment>
</para> </para>
</refsect1> </refsect1>
<REFSECT1 ID="R1-SQL-CREATELANGUAGE-5"> <REFSECT1 ID="R1-SQL-CREATELANGUAGE-5">
@ -340,22 +330,21 @@
</ProgramListing> </ProgramListing>
<para> <para>
Only a few thousand lines of code have to be added instead Only a few thousand lines of code have to be added instead
of the dots to complete the PL call handler. See <citerefentry> of the dots to complete the PL call handler.
<refentrytitle>CREATE FUNCTION</refentrytitle> See <command>CREATE FUNCTION</command> for information on how to compile
</citerefentry> for information on how to compile
it into a loadable module it into a loadable module
.</para> .</para>
<para> <para>
The following commands then register the sample procedural The following commands then register the sample procedural
language.</para> language:
<programlisting> <programlisting>
CREATE FUNCTION plsample_call_handler () RETURNS opaque CREATE FUNCTION plsample_call_handler () RETURNS opaque
AS '/usr/local/pgsql/lib/plsample.so' AS '/usr/local/pgsql/lib/plsample.so'
LANGUAGE 'C'; LANGUAGE 'C';
CREATE PROCEDURAL LANGUAGE 'plsample' CREATE PROCEDURAL LANGUAGE 'plsample'
HANDLER plsample_call_handler HANDLER plsample_call_handler
LANCOMPILER 'PL/Sample'; LANCOMPILER 'PL/Sample';
</programlisting> </programlisting>
</REFSECT1> </REFSECT1>
@ -364,18 +353,18 @@
Compatibility Compatibility
</TITLE> </TITLE>
<PARA> <PARA>
CREATE LANGUAGE is a PostgreSQL extension. CREATE LANGUAGE is a <productname>Postgres</productname> extension.
</PARA> </PARA>
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-5"> <REFSECT2 ID="R2-SQL-CREATELANGUAGE-5">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no CREATE LANGUAGE statement in SQL92. There is no <command>CREATE LANGUAGE</command> statement in SQL92.
</PARA> </PARA>
</refsect2> </refsect2>
</refsect1> </refsect1>

248
doc/src/sgml/ref/create_operator.sgml
View File

@ -15,37 +15,31 @@
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CREATE OPERATOR <replaceable>name</replaceable> CREATE OPERATOR <replaceable>name</replaceable>
([ LEFTARG = <replaceable class="parameter">type1</replaceable> ] ( PROCEDURE = <replaceable class="parameter">func_name</replaceable>
[, RIGHTARG = <replaceable class="parameter">type2</replaceable> ] [, LEFTARG = <replaceable class="parameter">type1</replaceable> ]
, PROCEDURE = <replaceable class="parameter">func_name</replaceable> [, RIGHTARG = <replaceable class="parameter">type2</replaceable> ]
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ]
[, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ]
[, HASHES ] [, HASHES ]
[, JOIN = <replaceable class="parameter">join_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
[, SORT = <replaceable class="parameter">sort_op</replaceable> [, ...] ] [, SORT = <replaceable class="parameter">sort_op</replaceable> [, ...] ]
) )
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-1"> <REFSECT2 ID="R2-SQL-CREATEOPERATOR-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA> </PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
@ -53,25 +47,7 @@
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The name of an existing aggregate function. The operator to be defined. See below for allowable characters.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">type1</replaceable>
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">type2</replaceable>
</TERM>
<LISTITEM>
<PARA>
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -81,6 +57,29 @@
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The function used to implement this operator.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">type1</replaceable>
</TERM>
<LISTITEM>
<PARA>
The type for the left-hand side of the operator, if any. This option would be
omitted for a right-unary operator.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">type2</replaceable>
</TERM>
<LISTITEM>
<PARA>
The type for the right-hand side of the operator, if any. This option would be
omitted for a left-unary operator.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -90,6 +89,7 @@
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The corresponding commutative operator.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -99,6 +99,7 @@
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The corresponding negation operator.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -108,6 +109,17 @@
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The corresponding restriction operator.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
HASHES
</TERM>
<LISTITEM>
<PARA>
This operator can support a hash-join algorithm.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -117,6 +129,7 @@
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Procedure supporting table joins.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -126,18 +139,17 @@
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Operator to use for sorting.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-2"> <REFSECT2 ID="R2-SQL-CREATEOPERATOR-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -147,6 +159,7 @@
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -170,59 +183,62 @@
<REFSECT1 ID="R1-SQL-CREATEOPERATOR-1"> <REFSECT1 ID="R1-SQL-CREATEOPERATOR-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
</TITLE> </TITLE>
<PARA> <PARA>
This command defines a new user operator, operator_name. <command>CREATE OPERATOR</command> defines a new operator,
<replaceable class="parameter">name</replaceable>.
The user who defines an operator becomes its owner. The user who defines an operator becomes its owner.
</para> </para>
<para> <para>
The operator_name is a sequence of up to sixteen punctua The operator <replaceable class="parameter">name</replaceable>
tion characters. The following characters are valid for is a sequence of up to thirty two (32) characters in any combination
single-character operator names:<literallayout> from the following:
<literallayout>
+ - * / &lt; &gt; = ~ ! @ # % ^ & | ` ? $ :
</literallayout>
<note>
<para>
No alphabetic characters are allowed in an operator name.
This enables <productname>Postgres</productname> to parse SQL input
into tokens without requiring spaces between each token.
</note>
~ ! @ # % ^ & ` ? </literallayout>
</para>
<para>
If the operator name is more than one character long, it
may consist of any combination of the above characters or
the following additional characters:<literallayout>
| $ : + - * / &lt; &gt; =</literallayout>
</para> </para>
<para> <para>
The operator "!=" is mapped to "&lt;&gt;" on input, and they are The operator "!=" is mapped to "&lt;&gt;" on input, so they are
therefore equivalent. therefore equivalent.
</para> </para>
<para> <para>
At least one of leftarg and rightarg must be defined. For At least one of LEFTARG and RIGHTARG must be defined. For
binary operators, both should be defined. For right unary binary operators, both should be defined. For right unary
operators, only arg1 should be defined, while for left operators, only LEFTARG should be defined, while for left
unary operators only arg2 should be defined. unary operators only RIGHTARG should be defined.
</para> </para>
<para> <para>
The name of the operator, operator_name, can be composed Also, the
of symbols only. Also, the func_name procedure must have <replaceable class="parameter">func_name</replaceable> procedure must have
been previously defined using create function(l) and must been previously defined using <command>CREATE FUNCTION</command> and must
have one or two arguments. be defined to accept the correct number of arguments
(either one or two).
</para> </para>
<para> <para>
The commutator operator is present so that Postgres can The commutator operator is present so that
reverse the order of the operands if it wishes. For exam <productname>Postgres</productname> can
ple, the operator area-less-than, >>>, would have a commu reverse the order of the operands if it wishes.
tator operator, area-greater-than, <<<. Suppose that an For example, the operator area-less-than, &lt;&lt;&lt;,
operator, area-equal, ===, exists, as well as an area not would have a commutator
equal, !==. Hence, the query optimizer could freely con operator, area-greater-than, &gt;&gt;&gt;.
vert: Hence, the query optimizer could freely convert:
<programlisting> <programlisting>
"0,0,1,1"::box >>> MYBOXES.description "0,0,1,1"::box &gt;&gt;&gt; MYBOXES.description
</programlisting> </programlisting>
to to
<programlisting> <programlisting>
MYBOXES.description <<< "0,0,1,1"::box</programlisting> MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box</programlisting>
</para> </para>
<para> <para>
This allows the execution code to always use the latter This allows the execution code to always use the latter
@ -230,17 +246,21 @@
what. what.
</para> </para>
<para> <para>
Suppose that an
operator, area-equal, ===, exists, as well as an area not
equal, !==.
The negator operator allows the query optimizer to convert The negator operator allows the query optimizer to convert
<programlisting> <programlisting>
NOT MYBOXES.description === "0,0,1,1"::box NOT MYBOXES.description === "0,0,1,1"::box
</programlisting> </programlisting>
to to
<programlisting> <programlisting>
MYBOXES.description !== "0,0,1,1"::box MYBOXES.description !== "0,0,1,1"::box
</programlisting> </programlisting>
</para> </para>
<para> <para>
If a commutator operator name is supplied, Postgres If a commutator operator name is supplied,
<productname>Postgres</productname>
searches for it in the catalog. If it is found and it searches for it in the catalog. If it is found and it
does not yet have a commutator itself, then the commutator's does not yet have a commutator itself, then the commutator's
entry is updated to have the current (new) operator entry is updated to have the current (new) operator
@ -256,22 +276,25 @@
</para> </para>
<para> <para>
The next two specifications are present to support the The next two specifications are present to support the
query optimizer in performing joins. Postgres can always query optimizer in performing joins.
<productname>Postgres</productname> can always
evaluate a join (i.e., processing a clause with two tuple evaluate a join (i.e., processing a clause with two tuple
variables separated by an operator that returns a boolean) variables separated by an operator that returns a boolean)
by iterative substitution [WONG76]. In addition, Postgres by iterative substitution [WONG76].
In addition, <productname>Postgres</productname>
is planning on implementing a hash-join algorithm along is planning on implementing a hash-join algorithm along
the lines of [SHAP86]; however, it must know whether this the lines of [SHAP86]; however, it must know whether this
strategy is applicable. For example, a hash-join strategy is applicable.
For example, a hash-join
algorithm is usable for a clause of the form: algorithm is usable for a clause of the form:
<programlisting> <programlisting>
MYBOXES.description === MYBOXES2.description MYBOXES.description === MYBOXES2.description
</programlisting> </programlisting>
but not for a clause of the form: but not for a clause of the form:
<programlisting> <programlisting>
MYBOXES.description <<< MYBOXES2.description. MYBOXES.description &lt;&lt;&lt; MYBOXES2.description.
</programlisting> </programlisting>
The hashes flag gives the needed information to the query The HASHES flag gives the needed information to the query
optimizer concerning whether a hash join strategy is optimizer concerning whether a hash join strategy is
usable for the operator in question.</para> usable for the operator in question.</para>
<para> <para>
@ -279,15 +302,16 @@
optimizer whether merge-sort is a usable join strategy and optimizer whether merge-sort is a usable join strategy and
what operators should be used to sort the two operand what operators should be used to sort the two operand
classes. For the === clause above, the optimizer must classes. For the === clause above, the optimizer must
sort both relations using the operator, <<<. On the other sort both relations using the operator, &lt;&lt;&lt;. On the other
hand, merge-sort is not usable with the clause: hand, merge-sort is not usable with the clause:
<programlisting> <programlisting>
MYBOXES.description <<< MYBOXES2.description MYBOXES.description &lt;&lt;&lt; MYBOXES2.description
</programlisting> </programlisting>
</para> </para>
<para> <para>
If other join strategies are found to be practical, Post If other join strategies are found to be practical,
gres will change the optimizer and run-time system to use <productname>Postgres</productname>
will change the optimizer and run-time system to use
them and will require additional specification when an them and will require additional specification when an
operator is defined. Fortunately, the research community operator is defined. Fortunately, the research community
invents new join strategies infrequently, and the added invents new join strategies infrequently, and the added
@ -299,12 +323,14 @@
the query optimizer can estimate result sizes. If a the query optimizer can estimate result sizes. If a
clause of the form: clause of the form:
<programlisting> <programlisting>
MYBOXES.description <<< "0,0,1,1"::box MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box
</programlisting> </programlisting>
is present in the qualification, then Postgres may have to is present in the qualification,
then <productname>Postgres</productname> may have to
estimate the fraction of the instances in MYBOXES that estimate the fraction of the instances in MYBOXES that
satisfy the clause. The function res_proc must be a reg satisfy the clause. The function
istered function (meaning it is already defined using <replaceable class="parameter">res_proc</replaceable>
must be a registered function (meaning it is already defined using
define function(l)) which accepts one argument of the correct define function(l)) which accepts one argument of the correct
data type and returns a floating point number. The data type and returns a floating point number. The
query optimizer simply calls this function, passing the query optimizer simply calls this function, passing the
@ -322,13 +348,14 @@
<para> <para>
The difference between the function The difference between the function
<programlisting> <programlisting>
my_procedure_1 (MYBOXES.description, "0,0,1,1"::box) my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
</programlisting> </programlisting>
and the operator and the operator
<programlisting> <programlisting>
MYBOXES.description === "0,0,1,1"::box MYBOXES.description === "0,0,1,1"::box
</programlisting> </programlisting>
is that Postgres attempts to optimize operators and can is that <productname>Postgres</productname>
attempts to optimize operators and can
decide to use an index to restrict the search space when decide to use an index to restrict the search space when
operators are involved. However, there is no attempt to operators are involved. However, there is no attempt to
optimize functions, and they are performed by brute force. optimize functions, and they are performed by brute force.
@ -338,18 +365,17 @@
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-3"> <REFSECT2 ID="R2-SQL-CREATEOPERATOR-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<PARA> <PARA>
Refer to <citetitle>PostgreSQL User's Guide</citetitle> chapter 5 Refer to the chapter on operators in the
<comment> <citetitle>PostgreSQL User's Guide</citetitle>
This reference must be corrected.
</comment>
for further information. for further information.
Refer to DROP OPERATOR statement to drop operators. Refer to <command>DROP OPERATOR</command> to delete
user-defined operators from a database.
</REFSECT2> </REFSECT2>
@ -361,16 +387,16 @@
area-equality, for the BOX data type. area-equality, for the BOX data type.
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CREATE OPERATOR === ( CREATE OPERATOR === (
LEFTARG = box, LEFTARG = box,
RIGHTARG = box, RIGHTARG = box,
PROCEDURE = area_equal_procedure, PROCEDURE = area_equal_procedure,
COMMUTATOR = ===, COMMUTATOR = ===,
NEGATOR = !==, NEGATOR = !==,
RESTRICT = area_restriction_procedure, RESTRICT = area_restriction_procedure,
HASHES, HASHES,
JOIN = area-join-procedure, JOIN = area-join-procedure,
SORT = <<<, <<<) SORT = <<<, <<<)
</ProgramListing> </ProgramListing>
@ -381,18 +407,18 @@
Compatibility Compatibility
</TITLE> </TITLE>
<PARA> <PARA>
CREATE OPERATOR is a PostgreSQL extension of SQL. CREATE OPERATOR is a <productname>Postgres</productname> extension.
</PARA> </PARA>
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-4"> <REFSECT2 ID="R2-SQL-CREATEOPERATOR-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-09</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no CREATE OPERATOR statement on SQL92. There is no CREATE OPERATOR statement in <acronym>SQL92</acronym>.
</PARA> </PARA>
</refsect2> </refsect2>
</refsect1> </refsect1>

164
doc/src/sgml/ref/create_rule.sgml
View File

@ -14,35 +14,28 @@
</REFPURPOSE> </REFPURPOSE>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-11</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CREATE RULE <replaceable class="parameter">name</replaceable> CREATE RULE <replaceable class="parameter">name</replaceable>
AS ON <replaceable class="parameter">event</replaceable> AS ON <replaceable class="parameter">event</replaceable>
TO <replaceable class="parameter">object</replaceable> [WHERE <replaceable class="parameter">condition</replaceable>] TO <replaceable class="parameter">object</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
DO [INSTEAD] DO [ INSTEAD ] [ <replaceable class="parameter">action</replaceable> | NOTHING ]
[<replaceable class="parameter">action</replaceable> | NOTHING ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATERULE-1"> <REFSECT2 ID="R2-SQL-CREATERULE-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-11</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA> </PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">name</replaceable></ReturnValue> <replaceable class="parameter">name</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -52,31 +45,34 @@
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">event</replaceable></ReturnValue> <replaceable class="parameter">event</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Event is one of <literal>select</literal>, <literal>update</literal>, <literal>delete</literal> or <literal>insert</literal>. Event is one of <literal>select</literal>,
<literal>update</literal>, <literal>delete</literal>
or <literal>insert</literal>.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">object</replaceable></ReturnValue> <replaceable class="parameter">object</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Object is either <replaceable class="parameter">table</replaceable> or <replaceable class="parameter">table</replaceable>.<replaceable class="parameter">column</replaceable>. Object is either <replaceable class="parameter">table</replaceable>
or <replaceable class="parameter">table</replaceable>.<replaceable class="parameter">column</replaceable>.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">condition</replaceable></ReturnValue> <replaceable class="parameter">condition</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Any SQL <literal>where</literal> clause. <literal>new</literal> or Any SQL WHERE clause. <literal>new</literal> or
<literal>current</literal> can appear instead of an instance <literal>current</literal> can appear instead of an instance
variable whenever an instance variable is permissible in SQL. variable whenever an instance variable is permissible in SQL.
</PARA> </PARA>
@ -84,25 +80,23 @@
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">action</replaceable></ReturnValue> <replaceable class="parameter">action</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Any SQL-statement. <literal>new</literal> or Any SQL statement. <literal>new</literal> or
<literal>current</literal> can appear instead of an instance <literal>current</literal> can appear instead of an instance
variable whenever an instance variable is permissible in SQL. variable whenever an instance variable is permissible in SQL.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</VARIABLELIST> </VARIABLELIST>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATERULE-2"> <REFSECT2 ID="R2-SQL-CREATERULE-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-11</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -112,6 +106,7 @@
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -136,7 +131,7 @@
<REFSECT1 ID="R1-SQL-CREATERULE-1"> <REFSECT1 ID="R1-SQL-CREATERULE-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-11</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
@ -146,13 +141,13 @@
accessed, updated, inserted or deleted, there is a current instance (for accessed, updated, inserted or deleted, there is a current instance (for
retrieves, updates and deletes) and a new instance (for updates and retrieves, updates and deletes) and a new instance (for updates and
appends). If the <replaceable class="parameter">event</replaceable> appends). If the <replaceable class="parameter">event</replaceable>
specified in the <literal>on</literal> clause and the specified in the ON clause and the
<replaceable class="parameter">condition</replaceable> specified in the <replaceable class="parameter">condition</replaceable> specified in the
<literal>where</literal> clause are true for the current instance, the WHERE clause are true for the current instance, the
<replaceable class="parameter">action</replaceable> part of the rule is <replaceable class="parameter">action</replaceable> part of the rule is
executed. First, however, values from fields in the current instance executed. First, however, values from fields in the current instance
and/or the new instance are substituted for and/or the new instance are substituted for
<literal> current.</literal><replaceable class="parameter">attribute-name</replaceable> <literal>current.</literal><replaceable class="parameter">attribute-name</replaceable>
and <literal>new.</literal><replaceable class="parameter">attribute-name</replaceable>. and <literal>new.</literal><replaceable class="parameter">attribute-name</replaceable>.
</para> </para>
<para> <para>
@ -163,13 +158,13 @@
<REFSECT2 ID="R2-SQL-CREATERULE-3"> <REFSECT2 ID="R2-SQL-CREATERULE-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-11</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
</TITLE> </TITLE>
<para> <para>
A note of caution about SQL rules is in order. If the same class name A caution about SQL rules is in order. If the same class name
or instance variable appears in the or instance variable appears in the
<replaceable class="parameter">event</replaceable>, the <replaceable class="parameter">event</replaceable>, the
<replaceable class="parameter">condition</replaceable> and the <replaceable class="parameter">condition</replaceable> and the
@ -179,13 +174,14 @@
variables that are shared between these clauses. For example, the following variables that are shared between these clauses. For example, the following
two rules have the same semantics: two rules have the same semantics:
<programlisting> <programlisting>
on update to EMP.salary where EMP.name = "Joe" on update to EMP.salary where EMP.name = "Joe"
do update EMP ( ... ) where ... do update EMP ( ... ) where ...
on update to EMP-1.salary where EMP-2.name = "Joe" on update to EMP-1.salary where EMP-2.name = "Joe"
do update EMP-3 ( ... ) where ... do update EMP-3 ( ... ) where ...
</programlisting> </programlisting>
Each rule can have the optional tag <literal>instead</literal>. Without Each rule can have the optional tag INSTEAD.
Without
this tag, <replaceable class="parameter">action</replaceable> will be this tag, <replaceable class="parameter">action</replaceable> will be
performed in addition to the user command when the performed in addition to the user command when the
<replaceable class="parameter">event</replaceable> in the <replaceable class="parameter">event</replaceable> in the
@ -194,7 +190,7 @@
<replaceable class="parameter">action</replaceable> part will be done <replaceable class="parameter">action</replaceable> part will be done
instead of the user command. In this later case, the instead of the user command. In this later case, the
<replaceable class="parameter">action</replaceable> can be the keyword <replaceable class="parameter">action</replaceable> can be the keyword
<literal>nothing</literal>. NOTHING.
</para> </para>
<para> <para>
When choosing between the rewrite and instance rule systems for a When choosing between the rewrite and instance rule systems for a
@ -205,32 +201,33 @@
<para> <para>
It is very important to note that the rewrite rule system It is very important to note that the rewrite rule system
will neither detect nor process circular rules. For example, though each will neither detect nor process circular rules. For example, though each
of the following two rule definitions are accepted by Postgres, the of the following two rule definitions are accepted by
retrieve command will cause Postgres to crash: <productname>Postgres</productname>, the
retrieve command will cause <productname>Postgres</productname> to crash:
<example> <example>
<title>Example of a circular rewrite rule combination.</title> <title>Example of a circular rewrite rule combination.</title>
<programlisting> <programlisting>
create rule bad_rule_combination_1 is create rule bad_rule_combination_1 is
on select to EMP on select to EMP
do instead select to TOYEMP do instead select to TOYEMP
create rule bad_rule_combination_2 is create rule bad_rule_combination_2 is
on select to TOYEMP on select to TOYEMP
do instead select to EMP do instead select to EMP
</programlisting> </programlisting>
<para> <para>
This attempt to retrieve from EMP will cause Postgres to crash. This attempt to retrieve from EMP will cause
<productname>Postgres</productname> to crash.
<programlisting> <programlisting>
select * from EMP select * from EMP
</programlisting></para> </programlisting></para>
</example> </example>
</para> </para>
<para> <para>
You must have rule definition access to a class in order You must have rule definition access to a class in order
to define a rule on it (see change acl(l)). to define a rule on it. Use <command>GRANT</command>
<comment> and <command>REVOKE</command> to change permissions.
There is no manpage change or change_acl. What is intended?
</comment>
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</refsect1> </refsect1>
@ -240,13 +237,13 @@
Usage Usage
</TITLE> </TITLE>
<PARA> <PARA>
Make Sam get the same salary adjustment as Joe Make Sam get the same salary adjustment as Joe:
<programlisting> <programlisting>
create rule example_1 is create rule example_1 is
on update EMP.salary where current.name = "Joe" on update EMP.salary where current.name = "Joe"
do update EMP (salary = new.salary) do update EMP (salary = new.salary)
where EMP.name = "Sam" where EMP.name = "Sam"
</programlisting> </programlisting>
At the time Joe receives a salary adjustment, the event At the time Joe receives a salary adjustment, the event
@ -257,44 +254,45 @@
Joe's salary on to Sam. Joe's salary on to Sam.
</para> </para>
<para> <para>
Make Bill get Joe's salary when it is accessed Make Bill get Joe's salary when it is accessed:
<programlisting> <programlisting>
create rule example_2 is create rule example_2 is
on select to EMP.salary
on select to EMP.salary where current.name = "Bill"
where current.name = "Bill" do instead
do instead select (EMP.salary) from EMP
select (EMP.salary) from EMP where EMP.name = "Joe" where EMP.name = "Joe"
</programlisting> </programlisting>
</para> </para>
<para> <para>
Deny Joe access to the salary of employees in the shoe Deny Joe access to the salary of employees in the shoe
department. (<function>pg_username()</function> returns the name of department (<function>current_user</function> returns the name of
the current user) the current user):
<programlisting> <programlisting>
create rule example_3 is create rule example_3 is
on select to EMP.salary on select to EMP.salary
where current.dept = "shoe" and pg_username() = "Joe" where current.dept = "shoe" and current_user = "Joe"
do instead nothing do instead nothing
</programlisting> </programlisting>
</para> </para>
<para> <para>
Create a view of the employees working in the toy department. Create a view of the employees working in the toy department.
<programlisting> <programlisting>
create TOYEMP(name = char16, salary = int4) create TOYEMP(name = char16, salary = int4)
create rule example_4 is create rule example_4 is
on select to TOYEMP on select to TOYEMP
do instead select (EMP.name, EMP.salary) from EMP do instead
where EMP.dept = "toy" select (EMP.name, EMP.salary) from EMP
where EMP.dept = "toy"
</programlisting> </programlisting>
</para> </para>
<para> <para>
All new employees must make 5,000 or less All new employees must make 5,000 or less
<programlisting> <programlisting>
create rule example_5 is create rule example_5 is
on insert to EMP where new.salary > 5000 on insert to EMP where new.salary > 5000
do update newset salary = 5000 do update newset salary = 5000
</programlisting> </programlisting>
</PARA> </PARA>
</REFSECT1> </REFSECT1>
@ -303,9 +301,6 @@
<TITLE> <TITLE>
Bugs Bugs
</TITLE> </TITLE>
<PARA>
<literal>instead</literal> rules do not work properly.
</para>
<para> <para>
The object in a SQL rule cannot be an array reference and The object in a SQL rule cannot be an array reference and
cannot have parameters. cannot have parameters.
@ -328,18 +323,19 @@
Compatibility Compatibility
</TITLE> </TITLE>
<PARA> <PARA>
CREATE RULE statement is a PostgreSQL language extension. CREATE RULE statement is a <productname>Postgres</productname>
language extension.
</PARA> </PARA>
<REFSECT2 ID="R2-SQL-CREATERULE-4"> <REFSECT2 ID="R2-SQL-CREATERULE-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-11</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<para> <para>
There is no CREATE RULE statement in SQL92. There is no CREATE RULE statement in <acronym>SQL92</acronym>.
</para> </para>
</refsect2> </refsect2>
</refsect1> </refsect1>

123
doc/src/sgml/ref/create_sequence.sgml
View File

@ -18,34 +18,28 @@
<DATE>1998-04-15</DATE> <DATE>1998-04-15</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable>
[INCREMENT <replaceable class="parameter">increment</replaceable>] [ INCREMENT <replaceable class="parameter">increment</replaceable> ]
[MINVALUE <replaceable class="parameter">minvalue</replaceable>] [ MINVALUE <replaceable class="parameter">minvalue</replaceable> ]
[MAXVALUE <replaceable class="parameter">maxvalue</replaceable>] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> ]
[START <replaceable class="parameter">start</replaceable>] [ START <replaceable class="parameter">start</replaceable> ]
[CACHE <replaceable class="parameter">cache</replaceable>] [ CACHE <replaceable class="parameter">cache</replaceable> ]
[CYCLE] [ CYCLE ]
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATESEQUENCE-1"> <REFSECT2 ID="R2-SQL-CREATESEQUENCE-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-11</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
</TITLE> </TITLE>
<PARA> <PARA>
</PARA> </PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">seqname</replaceable></ReturnValue> <replaceable class="parameter">seqname</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -55,19 +49,19 @@
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">increment</replaceable></ReturnValue> <replaceable class="parameter">increment</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The <option>INCREMENT <replaceable class="parameter">increment</replaceable></option> clause is optional. A positive value will make an The <option>INCREMENT <replaceable class="parameter">increment</replaceable></option> clause is optional. A positive value will make an
ascending sequence, a negative one a descending sequence. The default value ascending sequence, a negative one a descending sequence.
is 1. The default value is one (1).
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">minvalue</replaceable></ReturnValue> <replaceable class="parameter">minvalue</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -81,7 +75,7 @@
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">maxvalue</replaceable></ReturnValue> <replaceable class="parameter">maxvalue</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -95,7 +89,7 @@
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">start</replaceable></ReturnValue> <replaceable class="parameter">start</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -107,15 +101,12 @@
for ascending sequences and for ascending sequences and
<replaceable class="parameter">maxvalue</replaceable> <replaceable class="parameter">maxvalue</replaceable>
for descending ones. for descending ones.
<comment>
What happens if the user specifies start outside the range?
</comment>
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue><replaceable class="parameter">cache</replaceable></ReturnValue> <replaceable class="parameter">cache</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -128,7 +119,7 @@
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>CYCLE</ReturnValue> CYCLE
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -146,14 +137,11 @@
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
</variablelist> </variablelist>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</REFSECT2> </REFSECT2>
<REFSECT2 ID="R2-SQL-CREATESEQUENCE-2"> <REFSECT2 ID="R2-SQL-CREATESEQUENCE-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-11</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -163,6 +151,7 @@
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable>status</replaceable>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -179,7 +168,7 @@
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<ReturnValue>ERROR: amcreate: '<replaceable class="parameter"> seqname</replaceable>' relation already exists</ReturnValue> <ReturnValue>ERROR: amcreate: '<replaceable class="parameter">seqname</replaceable>' relation already exists</ReturnValue>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -187,6 +176,36 @@
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be > MAXVALUE (<replaceable class="parameter">maxvalue</replaceable>)</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
If the specified starting value is out of range.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be < MINVALUE (<replaceable class="parameter">minvalue</replaceable>)</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
If the specified starting value is out of range.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">minvalue</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">maxvalue</replaceable>)</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
If the minimum and maximum values are inconsistant.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist> </variablelist>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -196,7 +215,7 @@
<REFSECT1 ID="R1-SQL-CREATESEQUENCE-1"> <REFSECT1 ID="R1-SQL-CREATESEQUENCE-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-11</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
@ -210,18 +229,20 @@
</PARA> </PARA>
<para> <para>
After the sequence is created, you may use the function After the sequence is created, you may use the function
<function>nextval()</function> with the <function>nextval(<replaceable class="parameter">seqname</replaceable>)</function>
sequence name as the argument to get a new number from the sequence. to get a new number from the sequence.
The function <function>currval('<replaceable class="parameter">sequence_name</replaceable>')</function> may be used The function
<function>currval('<replaceable class="parameter">seqname</replaceable>')</function>
may be used
to determine the number returned by the last call to to determine the number returned by the last call to
<function>nextval()</function> for the <function>nextval(<replaceable class="parameter">seqname</replaceable>)</function>
specified sequence in the current session. for the specified sequence in the current session.
</para> </para>
<para> <para>
Use a query like Use a query like
<programlisting> <programlisting>
SELECT * FROM sequence_name; SELECT * FROM sequence_name;
</programlisting> </programlisting>
to get the parameters of a sequence. to get the parameters of a sequence.
</para> </para>
@ -232,7 +253,7 @@
<REFSECT2 ID="R2-SQL-CREATESEQUENCE-3"> <REFSECT2 ID="R2-SQL-CREATESEQUENCE-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-11</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
@ -243,7 +264,7 @@
<para> <para>
Each backend uses its own cache to store allocated numbers. Each backend uses its own cache to store allocated numbers.
Numbers that are cached but not used in the current session will be Numbers that are cached but not used in the current session will be
lost. lost, resulting in "holes" in the sequence.
</para> </para>
</REFSECT2> </REFSECT2>
</refsect1> </refsect1>
@ -253,25 +274,25 @@
Usage Usage
</TITLE> </TITLE>
<PARA> <PARA>
Create an ascending sequence called serial, starting at 101: Create an ascending sequence called <literal>serial</literal>, starting at 101:
</PARA> </PARA>
<ProgramListing> <ProgramListing>
CREATE SEQUENCE serial START 101; CREATE SEQUENCE serial START 101;
</ProgramListing> </ProgramListing>
<para> <para>
Select the next number from this sequence Select the next number from this sequence
<programlisting> <programlisting>
SELECT NEXTVAL ('serial'); SELECT NEXTVAL ('serial');
nextval nextval
------- -------
114 114
</programlisting> </programlisting>
</para> </para>
<para> <para>
Use this sequence in an INSERT: Use this sequence in an INSERT:
<programlisting> <programlisting>
INSERT INTO distributors VALUES (NEXTVAL ('serial'),'nothing'); INSERT INTO distributors VALUES (NEXTVAL('serial'),'nothing');
</programlisting> </programlisting>
</para> </para>
</REFSECT1> </REFSECT1>
@ -281,18 +302,20 @@
Compatibility Compatibility
</TITLE> </TITLE>
<PARA> <PARA>
CREATE SEQUENCE statement is a PostgreSQL language extension. <command>CREATE SEQUENCE</command> is a <productname>Postgres</productname>
language extension.
</PARA> </PARA>
<REFSECT2 ID="R2-SQL-CREATESEQUENCE-4"> <REFSECT2 ID="R2-SQL-CREATESEQUENCE-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-04-15</DATE> <DATE>1998-09-11</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no CREATE SEQUENCE statement on SQL92. There is no <command>CREATE SEQUENCE</command> statement
in <acronym>SQL92</acronym>.
</PARA> </PARA>
</refsect2> </refsect2>
</refsect1> </refsect1>

10
doc/src/sgml/ref/drop_index.sgml
View File

@ -84,8 +84,8 @@
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
This message occurs if it is impossible to drop the index This message occurs if "<REPLACEABLE CLASS="PARAMETER">index_name</REPLACEABLE>"
because it does not exist. is not an index in the database.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -121,7 +121,7 @@
</PARA> </PARA>
<PARA> <PARA>
Refer to the <command>CREATE INDEX</command> statement for Refer to the <command>CREATE INDEX</command> statement for
inforamtion on how to create indexes. information on how to create indices.
</PARA> </PARA>
</REFSECT2> </REFSECT2>
@ -152,7 +152,9 @@
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no <command>DROP INDEX</command> statement on SQL92. SQL92 defines commands by which to access a generic relational database.
Indices are an implementation-dependent feature and hence
there is no <command>DROP INDEX</command> statement in SQL92.
</PARA> </PARA>
</refsect2> </refsect2>
</refsect1> </refsect1>

2
doc/src/sgml/ref/drop_language.sgml
View File

@ -172,7 +172,7 @@
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no DROP PROCEDURAL LANGUAGE statement on SQL92. There is no DROP PROCEDURAL LANGUAGE statement in SQL92.
</PARA> </PARA>
</refsect2> </refsect2>
</refsect1> </refsect1>

2
doc/src/sgml/ref/drop_user.sgml
View File

@ -158,7 +158,7 @@
SQL92 SQL92
</TITLE> </TITLE>
<PARA> <PARA>
There is no <command>DROP USER</command> statement on SQL92. There is no <command>DROP USER</command> statement in SQL92.
</PARA> </PARA>
</refsect2> </refsect2>
</refsect1> </refsect1>