mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki 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
Show Stats 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>
<SYNOPSIS>
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>
[*] 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>
RENAME TO <REPLACEABLE CLASS="PARAMETER">newtable</REPLACEABLE>
</SYNOPSIS>
@ -103,14 +103,14 @@ Outputs
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>status</ReturnValue>
<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>ALTER</ReturnValue>
<returnvalue>ALTER</returnvalue>
</TERM>
<LISTITEM>
<PARA>
@ -121,7 +121,7 @@ Outputs
<VARLISTENTRY>
<TERM>
<ReturnValue>NEW</ReturnValue>
<returnvalue>NEW</returnvalue>
</TERM>
<LISTITEM>
<PARA>
@ -156,9 +156,9 @@ Outputs
Description
</TITLE>
<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
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
to change without changing any of the data contained in
the affected table. Thus, the table or column will
@ -178,18 +178,15 @@ Notes
<PARA>
The keyword COLUMN is noise and can be omitted.
<PARA>
ALTER TABLE/RENAME is a PostgreSQL language extension.
<PARA>
<Quote>[*]</Quote> following a name of a table indicates that statement
should be run over that table and all tables below it in the
inheritance hierarchy.
Refer to PostgreSQL User's Guide for further
The PostgreSQL User's Guide has further
information on inheritance.
<PARA>
Refer to the CREATE TABLE reference for further description
Refer to CREATE TABLE for a further description
of valid arguments.
</REFSECT2>
@ -232,23 +229,30 @@ Compatibility
SQL92
</TITLE>
<PARA>
SQL92 specifies some additional capabilities for ALTER TABLE
statement which are not yet directly supported by <ProductName>Postgres</ProductName>:
<command>ALTER TABLE/RENAME</command>
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>
<VARLISTENTRY>
<TERM>
<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>
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>
</TERM>
<LISTITEM>
<PARA>
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.
If a default clause already exists, it will be replaced by
the new definition. If any constraints on this column already
@ -307,7 +311,7 @@ DROP TABLE temp;
<TERM>
<Synopsis>
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>
</TERM>
<LISTITEM>
@ -335,23 +339,3 @@ DROP TABLE temp;
</PARA>
</VARIABLELIST>
</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>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO>
<synopsis>
ALTER USER <replaceable class="PARAMETER">username</replaceable>
[WITH PASSWORD <replaceable class="PARAMETER">password</replaceable>]
[CREATEDB | NOCREATEDB]
[CREATEUSER | NOCREATEUSER]
[IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...] ]
[VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>']
ALTER USER <replaceable class="PARAMETER">username</replaceable>
[ WITH PASSWORD <replaceable class="PARAMETER">password</replaceable> ]
[ CREATEDB | NOCREATEDB ]
[ CREATEUSER | NOCREATEUSER ]
[ IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...] ]
[ VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>' ]
</synopsis>
<REFSECT2 ID="R2-SQL-ALTERUSER-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<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.
</para>
<VARIABLELIST>
@ -47,6 +47,7 @@
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER"> password </REPLACEABLE>
@ -57,6 +58,7 @@
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER"> groupname </REPLACEABLE>
@ -67,13 +69,15 @@
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER"> abstime </REPLACEABLE>
</TERM>
<LISTITEM>
<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>
</LISTITEM>
</VARLISTENTRY>
@ -82,7 +86,7 @@
<REFSECT2 ID="R2-SQL-ALTERUSER-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
@ -92,14 +96,14 @@
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>status</ReturnValue>
<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>ALTER USER</ReturnValue>
<returnvalue>ALTER USER</returnvalue>
</TERM>
<LISTITEM>
<PARA>
@ -110,7 +114,7 @@
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: alterUser: user "username" does not exist</ReturnValue>
<returnvalue>ERROR: alterUser: user "username" does not exist</returnvalue>
</TERM>
<LISTITEM>
<PARA>
@ -129,16 +133,18 @@
<REFSECT1 ID="R1-SQL-ALTERUSER-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
ALTER USER is used to change the attributes of a user's
PostgreSQL account. Please note that it is not possible
<command>ALTER USER</command> is used to change the attributes of a user's
<productname>Postgres</productname> account.
Please note that it is not possible
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
"pg_shadow" to alter user passwords.
</PARA>
@ -150,21 +156,24 @@
<REFSECT2 ID="R2-SQL-ALTERUSER-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
ALTER USER statement is a PostgreSQL language extension.
<command>ALTER USER</command> statement
is a <productname>Postgres</productname>
language extension.
</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.
</para>
<para>
At the current release (6.3.2), the IN GROUP clause is parsed
but has no effect. When it is fully implemented, it is
In the current release (v6.4), the IN GROUP clause is parsed
but has no affect. When it is fully implemented, it is
intended to modify the pg_group relation.
</para>
</REFSECT2>
@ -178,13 +187,13 @@
Change a user password
</PARA>
<ProgramListing>
ALTER USER davide WITH PASSWORD hu8jmn3;
ALTER USER davide WITH PASSWORD hu8jmn3;
</ProgramListing>
<para>
Change a user's valid until date
</para>
<ProgramListing>
ALTER USER manuel VALID UNTIL 'Jan 31 2030';
ALTER USER manuel VALID UNTIL 'Jan 31 2030';
</ProgramListing>
<para>
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
</para>
<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>
<para>
Give a user the ability to create other users and new databases.
</para>
<programlisting>
ALTER USER miriam CREATEUSER CREATEDB;
ALTER USER miriam CREATEUSER CREATEDB;
</programlisting>
<para>
Place a user in two groups
</para>
<programlisting>
ALTER USER miriam IN GROUP sales, payroll;
ALTER USER miriam IN GROUP sales, payroll;
</programlisting>
</REFSECT1>
@ -217,13 +226,15 @@ the time zone which is one hour ahead of UTC
<REFSECT2 ID="R2-SQL-ALTERUSER-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<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.
</PARA>
</refsect1>

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

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

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

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

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

@ -15,15 +15,15 @@
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO>
<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>
<REFSECT2 ID="R2-SQL-CLUSTER-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
@ -33,9 +33,7 @@
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>
<REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE>
</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
@ -45,9 +43,7 @@
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<ReturnValue>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
@ -60,7 +56,7 @@
<REFSECT2 ID="R2-SQL-CLUSTER-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
@ -70,13 +66,14 @@
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>CLUSTER</ReturnValue>
<returnvalue>CLUSTER</returnvalue>
</TERM>
<LISTITEM>
<PARA>
@ -86,11 +83,11 @@
</VARLISTENTRY>
<VARLISTENTRY>
<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>
<LISTITEM>
<PARA>
???
<comment>
This is not documented anywhere. It seems not to be possible to
cluster a table that is inherited.
@ -100,11 +97,11 @@
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<ReturnValue>ERROR: Relation x does not exist!</ReturnValue>
<returnvalue>ERROR: Relation x does not exist!</returnvalue>
</TERM>
<LISTITEM>
<PARA>
???
<comment>
The relation complained of was not shown in the error message,
which contained a random string instead of the relation name.
@ -122,27 +119,37 @@
<REFSECT1 ID="R1-SQL-CLUSTER-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<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
based on the index specified by
<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>
When a class is clustered, it is physically reordered
based on the index information. The clustering is static.
In other words, as the class is updated, the changes are
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.
</para>
<REFSECT2 ID="R2-SQL-CLUSTER-3">
<REFSECT2INFO>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
<para>
The table is actually copied to a temporary table in index
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
table is unimportant. However, if you tend to access some
data more than others, and there is an index that groups
them together, you will benefit from using the CLUSTER
command.
them together, you will benefit from using <command>CLUSTER</command>.
</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
requesting a range of indexed values from a table, or a
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
that match are probably already on the same heap page,
saving disk accesses and speeding up the query.
@ -172,25 +178,27 @@
<para>
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
on large tables because the rows are fetched from the heap
in index order, and if the heap table is unordered, the
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.
</para>
<para>
Another way is to use
<programlisting>SELECT ... INTO TABLE temp FROM ... ORDER BY ...</programlisting>
This uses the PostgreSQL sorting code in
Another way to cluster data is to use
<programlisting>
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
unordered data. You then drop the old table, use
<programlisting>ALTER TABLE RENAME</programlisting>
to rename 'temp' to the old name, and
recreate the b bindexes. The only problem is that oids
will not be preserved. From then on, CLUSTER should be
<command>ALTER TABLE/RENAME</command>
to rename <replaceable class="parameter">temp</replaceable> to the old name, and
recreate any indexes. The only problem is that <acronym>OID</acronym>s
will not be preserved. From then on, <command>CLUSTER</command> should be
fast because most of the heap data has already been
ordered, and the existing index is used.
</para>
@ -204,7 +212,7 @@
Cluster the employees relation on the basis of its salary attribute
</PARA>
<ProgramListing>
CLUSTER emp_ind ON emp
CLUSTER emp_ind ON emp
</ProgramListing>
</REFSECT1>
@ -217,13 +225,13 @@
<REFSECT2 ID="R2-SQL-CLUSTER-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no CLUSTER statement in SQL92.
There is no <command>CLUSTER</command> statement in SQL92.
</PARA>
</refsect2>
</refsect1>

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

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

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

@ -14,69 +14,112 @@
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
COPY [BINARY] <replaceable class="parameter">table</replaceable> [WITH OIDS]
TO|FROM '<replaceable class="parameter">filename</replaceable>'|stdin|stdout
[USING DELIMITERS '<replaceable class="parameter">delimiter</replaceable>']
COPY [ BINARY ] <replaceable class="parameter">table</replaceable> [ WITH OIDS ]
FROM { '<replaceable class="parameter">filename</replaceable>' | <filename>stdin</filename> }
[ USING DELIMITERS '<replaceable class="parameter">delimiter</replaceable>' ]
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>
<REFSECT2 ID="R2-SQL-COPY-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue><replaceable class="parameter">table</replaceable></ReturnValue>
BINARY
</TERM>
<LISTITEM>
<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>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<ReturnValue><replaceable class="parameter">delimiter</replaceable></ReturnValue>
<replaceable class="parameter">table</replaceable>
</TERM>
<LISTITEM>
<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>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-COPY-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
Status
<Replaceable>status</Replaceable>
</TERM>
<LISTITEM>
<PARA>
@ -110,84 +153,82 @@
<REFSECT1 ID="R1-SQL-COPY-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>COPY</command> moves data between PostgreSQL tables and
standard Unix files. The keyword <function>BINARY</function>
changes the behavior of field formatting, as described
below. <replaceable class="parameter">Table</replaceable> is the
name of an existing table. The keyword <function>WITH
OIDS</function> copies the internal unique object id (OID) for each
row. <replaceable class="parameter">Filename</replaceable> is the
absolute Unix pathname of the file. In place of a filename, the
keywords <function>stdin</function> and <function>stdout</function>
can be used, so that input to <command>COPY</command> can be written
by a libpq application and output from <command>COPY</command> can
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>
<command>COPY</command> moves data between
<productname>Postgres</productname> tables and
standard Unix files.
<para>
<command>COPY</command> instructs
the <productname>Postgres</productname> backend
to directly read from or write to a file. The file must be directly visible to
the backend and the name must be specified from the viewpoint of the backend.
If <filename>stdin</filename> or <filename>stdout</filename> are specified, data flows through the client frontend to
the backend.
<REFSECT2 ID="R2-SQL-COPY-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</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>
You must have select access on any table whose values are read by
<command>COPY</command>, and either insert or update access to a
table into which values are being inserted by <command>COPY</command>.
The backend also needs appropriate Unix permissions for any file read
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>
The keyword <function>USING DELIMITERS</function> is inaptly
named, since only a single character may be specified. (If a
group of characters is specified, only the first character is
used.)
</para>
<para>
WARNING: do not confuse <command>COPY</command> with the
<command>psql</command> instruction <command>\copy</command>.
</para>
The keyword phrase USING DELIMITERS specifies a single character
to be used for all delimiters between columns. If multiple characters
are specified in the delimiter string, only the first character is
used.
<tip>
<para>
Do not confuse <command>COPY</command> with the
<application>psql</application> instruction <command>\copy</command>.
</tip>
</REFSECT2>
</refsect1>
<refsect1 ID="R1-SQL-COPY-2">
<refsect1info>
<date>1998-05-04</date>
</refsect1info>
<title>Format of output files</title>
<title>File Formats</title>
<refsect2>
<refsect2info>
<date>1998-05-04</date>
</refsect2info>
<title>ASCII copy format</title>
<title>Text Format</title>
<para>
When <command>COPY</command> is used without <function>BINARY</function>,
the file generated will have each instance on a single line, with each
attribute separated by the delimiter character. Embedded
When <command>COPY TO</command> is used without the BINARY option,
the file generated will have each row (instance) on a single line, with each
column (attribute) separated by the delimiter character. Embedded
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
function for a type should not try to generate the backslash
character; this will be handled by <command>COPY</command> itself.
@ -195,29 +236,31 @@ is neither SQL nor Unix terminology.
<para>
The actual format for each instance is
<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
if <function>WITH OIDS</function> is specified.
if WITH OIDS is specified.
</para>
<para>
If <command>COPY</command> is sending its output to standard
output instead of a file, it will send a backslash(\) and a period
(.) followed immediately by a newline, on a separate line,
output instead of a file, it will send a backslash("\") and a period
(".") followed immediately by a newline, on a separate line,
when it is done. Similarly, if <command>COPY</command> is reading
from standard input, it will expect a backslash (\) and a period
(.) followed by a newline, as the first three characters on a
line, to denote end-of-file. However, <command>COPY</command>
from standard input, it will expect a backslash ("\") and a period
(".") followed by a newline, as the first three characters on a
line to denote end-of-file. However, <command>COPY</command>
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>
The backslash character has special meaning. NULL attributes are
output as \N. A literal backslash character is output as two
consecutive backslashes. A literal tab character is represented
The backslash character has other special meanings. NULL attributes are
output as "\N". A literal backslash character is output as two
consecutive backslashes ("\\"). A literal tab character is represented
as a backslash and a tab. A literal newline character is
represented as a backslash and a newline. When loading ASCII data
not generated by PostgreSQL, you will need to convert backslash
characters (\) to double-backslashes (\\) to ensure that they are loaded
represented as a backslash and a newline. When loading text data
not generated by <acronym>Postgres</acronym>,
you will need to convert backslash
characters ("\") to double-backslashes ("\\") to ensure that they are loaded
properly.
</para>
</refsect2>
@ -225,7 +268,7 @@ is neither SQL nor Unix terminology.
<refsect2info>
<date>1998-05-04</date>
</refsect2info>
<title>Binary copy format</title>
<title>Binary Format</title>
<para>
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
@ -270,16 +313,8 @@ is neither SQL nor Unix terminology.
<entry>number of null attributes</entry>
</row>
<row>
<entry>[uint32</entry>
<entry>attribute number of first null attribute, counting from 0</entry>
</row>
<row>
<entry>...</entry>
<entry>...</entry>
</row>
<row>
<entry>uint32</entry>
<entry>attribute number of last null attribute]</entry>
<entry>[uint32,...,uint32]</entry>
<entry>attribute numbers of attributes, counting from 0</entry>
</row>
<row>
<entry>-</entry>
@ -294,12 +329,12 @@ is neither SQL nor Unix terminology.
<refsect2info>
<date>1998-05-04</date>
</refsect2info>
<title>Alignment of binary data</title>
<title>Alignment of Binary Data</title>
<para>
On Sun-3s, 2-byte attributes are aligned on two-byte boundaries,
and all larger attributes are aligned on four-byte boundaries.
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
preceded by the attribute's length; arrays are simply contiguous
streams of the array element type.
@ -313,19 +348,22 @@ is neither SQL nor Unix terminology.
Usage
</TITLE>
<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>
<ProgramListing>
COPY country TO stdout USING DELIMITERS '|';
COPY country TO <filename>stdout</filename> USING DELIMITERS '|';
</ProgramListing>
<PARA>
To copy data from a Unix file into a table:
To copy data from a Unix file into a table "country":
</PARA>
<ProgramListing>
COPY country FROM '/usr1/proj/bray/sql/country_data';
COPY country FROM '/usr1/proj/bray/sql/country_data';
</ProgramListing>
<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):
</PARA>
<ProgramListing>
@ -338,10 +376,13 @@ has the termination sequence on the last line):
\.
</ProgramListing>
<PARA>
The same data, output in binary format on a Linux Intel machine.
The data is shown after filtering through the Unix utility <command>od -c</command>. The table has
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>
The same data, output in binary format on a Linux/i586 machine.
The data is shown after filtering through
the Unix utility <command>od -c</command>. The table has
three fields; the first is <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
preceded by its length:
</PARA>
@ -359,32 +400,32 @@ has the termination sequence on the last line):
</ProgramListing>
</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">
<title>Bugs</title>
<para>
<command>COPY</command> stops operation at the first error. This
should not lead to problems in the event of a copy from, but the
target relation will, of course, be partially modified in a copy
to. The <command>VACUUM</command> query should be used to clean up
should not lead to problems in the event of
a <command>COPY FROM</command>, but the
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.
</para>
<para>
Because Postgres' current directory is not the same as the user's
working directory, the result of copying to a file "foo" (without
Because the Postgres backend's current working directory
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
naive user. In this case, "foo" will wind up in $PGDATA/foo. In
general, the full pathname should be used when specifying files to
naive user. In this case, <filename>foo</filename>
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.
</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
local disks or on a networked file system.
</para>
@ -405,13 +446,13 @@ has the termination sequence on the last line):
<REFSECT2 ID="R2-SQL-COPY-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no COPY statement in SQL92.
There is no <command>COPY</command> statement in SQL92.
</PARA>
</refsect2>
</refsect1>

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

@ -6,10 +6,6 @@
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</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>
<REFNAME>
CREATE AGGREGATE
@ -19,32 +15,28 @@ haven't done this.</comment>
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
CREATE AGGREGATE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [AS]
([ SFUNC1 = <REPLACEABLE CLASS="PARAMETER">state_transition_function1</REPLACEABLE>
, BASETYPE = <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
, STYPE1 = <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE> ]
[, SFUNC2 = <REPLACEABLE CLASS="PARAMETER">state_transition_function2</REPLACEABLE>
, STYPE2 = <REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE> ]
[, FINALFUNC = <REPLACEABLE CLASS="PARAMETER">final_function</REPLACEABLE> ]
[, INITCOND1 = <REPLACEABLE CLASS="PARAMETER">initial_condition1</REPLACEABLE> ]
[, INITCOND2 = <REPLACEABLE CLASS="PARAMETER">initial_condition2</REPLACEABLE> ]
)
CREATE AGGREGATE <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> [ AS ]
( BASETYPE = <REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
[ , SFUNC1 = <REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
, STYPE1 = <REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE> ]
[ , SFUNC2 = <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>
, STYPE2 = <REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE> ]
[ , FINALFUNC = <REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE> ]
[ , INITCOND1 = <REPLACEABLE CLASS="PARAMETER">initial_condition1</REPLACEABLE> ]
[ , INITCOND2 = <REPLACEABLE CLASS="PARAMETER">initial_condition2</REPLACEABLE> ]
)
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<variablelist>
<varlistentry>
<term></term>
<listitem>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
@ -57,88 +49,115 @@ haven't done this.</comment>
</para>
</LISTITEM>
</varlistentry>
<varlistentry>
<term>
<REPLACEABLE CLASS="PARAMETER">state_transition_function1</REPLACEABLE>
</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<REPLACEABLE CLASS="PARAMETER">data_type</REPLACEABLE>
</term>
<listitem>
<para>
The fundamental data type on which this aggregate function operates.
</para>
</listitem>
</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>
<term>
<REPLACEABLE CLASS="PARAMETER">sfunc1_return_type</REPLACEABLE>
</term>
<listitem>
<para>
The return type of the first transition function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<REPLACEABLE CLASS="PARAMETER">state-transition_function2</REPLACEABLE>
<REPLACEABLE CLASS="PARAMETER">sfunc2</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">sfunc2_return_type</REPLACEABLE>
as the only argument and returns a variable of the same type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>
</term>
<listitem>
<para>
The return type of the second transition function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<REPLACEABLE CLASS="PARAMETER">final_function</REPLACEABLE>
<REPLACEABLE CLASS="PARAMETER">ffunc</REPLACEABLE>
</term>
<listitem>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term>
<REPLACEABLE CLASS="PARAMETER">initial_condition1</REPLACEABLE>
</term>
<listitem>
<para>
The initial value for the first transition function argument.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<REPLACEABLE CLASS="PARAMETER">initial_condition2</REPLACEABLE>
</term>
<listitem>
<para>
The initial value for the second transition function argument.
</para>
</listitem>
</varlistentry>
</variablelist>
</PARA>
</listitem>
</varlistentry>
</variablelist>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
@ -148,6 +167,7 @@ haven't done this.</comment>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
@ -172,82 +192,130 @@ haven't done this.</comment>
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT1INFO>
<TITLE>
Description
</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>
An aggregate function can use up to three functions, two
state transition functions, X1 and X2:
X1( internal-state1, next-data_item ) ---> next-internal-state1
X2( internal-state2 ) ---> next-internal-state2
and a final calculation function, F:
F(internal-state1, internal-state2) ---> aggregate-value
These functions are required to have the following properties:
An aggregate function can require up to three functions, two
state transition functions,
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
and <REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>:
<programlisting>
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>( internal-state1, next-data_item ) ---> next-internal-state1
<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>
<listitem>
<para>
The arguments to state-transition-function-1 must
be (stype1,basetype), and its return value must be
stype1.
The arguments to
<REPLACEABLE CLASS="PARAMETER">sfunc1</REPLACEABLE>
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>
</listitem>
<listitem>
<para>
The argument and return value of state-transition-
function-2 must be stype2.
The argument and return value of
<REPLACEABLE CLASS="PARAMETER">sfunc2</REPLACEABLE>
must be
<REPLACEABLE CLASS="PARAMETER">temp2</REPLACEABLE>
of type
<REPLACEABLE CLASS="PARAMETER">sfunc2_return_type</REPLACEABLE>.
</para>
</listitem>
<listitem>
<para>
The arguments to the final-calculation-function
must be (stype1,stype2), and its return value must
be a POSTGRES base type (not necessarily the same
as basetype.
must be
<REPLACEABLE CLASS="PARAMETER">temp1</REPLACEABLE>
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>
</listitem>
<listitem>
<para>
The final-calculation-function should be specified
FINALFUNC should be specified
if and only if both state-transition functions are
specified.
</para
</listitem>
</itemizedlist>
</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>
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
in the database as fields of type text.
in the database as fields of type <type>text</type>.
</para>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
CREATE AGGREGATE function is a PostgreSQL language extension.
</PARA>
<para>
Refer to DROP AGGREGATE function to drop aggregate functions.
Use <command>DROP AGGREGATE</command>
to drop aggregate functions.
</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>
<REFSECT1 ID="R1-SQL-CREATEAGGREGATE-2">
@ -255,10 +323,10 @@ haven't done this.</comment>
Usage
</TITLE>
<PARA>
</PARA>
<ProgramListing>
</ProgramListing>
Refer to the chapter on aggregate functions
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
on aggregate functions for
complete examples of usage.
</REFSECT1>
@ -267,17 +335,18 @@ haven't done this.</comment>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-CREATEAGGREGATE-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<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>
</REFENTRY>

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

@ -17,7 +17,7 @@
<DATE>1998-04-15</DATE>
</REFSYNOPSISDIVINFO>
<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>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-1">
@ -28,13 +28,6 @@
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
@ -62,9 +55,6 @@
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-2">
@ -79,6 +69,7 @@
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
@ -142,10 +133,11 @@ There was a problem with creating the required directory; this operation will
Notes
</TITLE>
<PARA>
<command>CREATE DATABASE</command> statement is a Postgres language extension.
<command>CREATE DATABASE</command> is a <productname>Postgres</productname>
language extension.
</PARA>
<para>
Refer to <command>DROP DATABASE</command> statement to remove a database.
Use <command>DROP DATABASE</command> to remove a database.
</para>
</REFSECT2>
@ -157,26 +149,26 @@ There was a problem with creating the required directory; this operation will
To create a new database:
</PARA>
<ProgramListing>
<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
</ProgramListing>
<PARA>
To create a new database in an alternate area <filename>~/private_db</filename>:
</PARA>
<ProgramListing>
<prompt>$</prompt> <userinput>mkdir private_db</userinput>
<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
<computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
<prompt>$</prompt> <userinput>mkdir private_db</userinput>
<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
<computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
<prompt>$</prompt> <userinput>psql olly</userinput>
<computeroutput>Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL
<prompt>$</prompt> <userinput>psql olly</userinput>
<computeroutput>Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL
type \? for help on slash commands
type \q to quit
type \g or terminate with semicolon to execute query
You are currently connected to the database: template1
type \? for help on slash commands
type \q to quit
type \g or terminate with semicolon to execute query
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>
</ProgramListing>
</REFSECT1>
@ -186,8 +178,12 @@ There was a problem with creating the required directory; this operation will
Bugs
</TITLE>
<PARA>
There are security and data integrity issues involved with using alternate database locations
specified with absolute path names. See the Administrator's Guide for more information.
There are security and data integrity issues
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>
</refsect1>
@ -207,7 +203,6 @@ Not sure if the dump/reload would guarantee that the alternate data area gets re
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-4">
<REFSECT2INFO>
@ -217,7 +212,7 @@ Not sure if the dump/reload would guarantee that the alternate data area gets re
SQL92
</TITLE>
<PARA>
There is no <command>CREATE DATABASE</command> statement on SQL92.
There is no <command>CREATE DATABASE</command> statement in SQL92.
</PARA>
<para>
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>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ([<replaceable class="parameter">ftype</replaceable> [, ...]])
RETURNS <replaceable class="parameter">rtype</replaceable>
AS <replaceable class="parameter">path</replaceable>
LANGUAGE '<replaceable class="parameter">langname</replaceable>'
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
RETURNS <replaceable class="parameter">rtype</replaceable>
AS <replaceable class="parameter">path</replaceable>
LANGUAGE '<replaceable class="parameter">langname</replaceable>'
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATEFUNCTION-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
@ -87,21 +80,21 @@
</TERM>
<LISTITEM>
<PARA>
may be '<literal>c</literal>', '<literal>sql</literal>', '<literal>internal</literal>' or '<replaceable class="parameter">plname</replaceable>'.
(where '<replaceable class="parameter">plname</replaceable>' is the language name of a created procedural
language. See <command>CREATE LANGUAGE</command> for details).
may be '<literal>C</literal>', '<literal>sql</literal>',
'<literal>internal</literal>'
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>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEFUNCTION-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
@ -111,6 +104,7 @@
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
@ -134,32 +128,34 @@
<REFSECT1 ID="R1-SQL-CREATEFUNCTION-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
With this command, a PostgreSQL user can register a function
with PostgreSQL. Subsequently, this user is treated as the
<command>CREATE FUNCTION</command> allows a
<productname>Postgres</productname> user
to register a function
with a database. Subsequently, this user is treated as the
owner of the function.
</PARA>
<REFSECT2 ID="R2-SQL-CREATEFUNCTION-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Refer to <citetitle>PostgreSQL User's Guide</citetitle> chapter 6 for further information.
<comment>This reference needs to be corrected.</comment>
Refer to the chapter on functions
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
for further information.
</PARA>
<PARA>
Refer to the <citerefentry>
<refentrytitle>DROP FUNCTION</refentrytitle>
</citerefentry> statement to drop functions.
Use <command>DROP FUNCTION</command>
to drop user-defined functions.
</PARA>
</REFSECT2>
@ -171,15 +167,17 @@
To create a simple SQL function:
</PARA>
<ProgramListing>
CREATE FUNCTION one() RETURNS int4
AS 'SELECT 1 AS RESULT'
LANGUAGE 'sql';
CREATE FUNCTION one() RETURNS int4
AS 'SELECT 1 AS RESULT'
LANGUAGE 'sql';
SELECT one() AS answer;
SELECT one() AS answer;
<computeroutput>answer
------
1 </computeroutput>
<computeroutput>
answer
------
1
</computeroutput>
</ProgramListing>
<para>
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.
</para>
<programlisting>
<userinput>CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
<userinput>
CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
CREATE TABLE product
(
id char(8) PRIMARY KEY,
eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
REFERENCES brandname(ean_prefix),
eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
);</userinput>
CREATE TABLE product
(
id char(8) PRIMARY KEY,
eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
REFERENCES brandname(ean_prefix),
eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
);</userinput>
</programlisting>
</REFSECT1>
@ -216,39 +215,44 @@
Compatibility
</TITLE>
<PARA>
The CREATE FUNCTION statement is a PostgreSQL language extension.
<command>CREATE FUNCTION</command> is
a <productname>Postgres</productname> language extension.
</PARA>
<REFSECT2 ID="R2-SQL-CREATEFUNCTION-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
SQL/PSM<footnote>
<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>
SQL/PSM
</TITLE>
<para>
The SQL/PSM CREATE FUNCTION statement has the following syntax:
<programlisting>
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>
</programlisting>
<note>
<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. As of mid-1998, this
has not yet happened, but it is hoped that PSM will
eventually become a standard.
</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>
</refsect2>
</refsect1>
</REFENTRY>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

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

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

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

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

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

@ -15,37 +15,31 @@
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
CREATE OPERATOR <replaceable>name</replaceable>
([ LEFTARG = <replaceable class="parameter">type1</replaceable> ]
[, RIGHTARG = <replaceable class="parameter">type2</replaceable> ]
, PROCEDURE = <replaceable class="parameter">func_name</replaceable>
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ]
[, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ]
[, HASHES ]
[, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
[, SORT = <replaceable class="parameter">sort_op</replaceable> [, ...] ]
)
CREATE OPERATOR <replaceable>name</replaceable>
( PROCEDURE = <replaceable class="parameter">func_name</replaceable>
[, LEFTARG = <replaceable class="parameter">type1</replaceable> ]
[, RIGHTARG = <replaceable class="parameter">type2</replaceable> ]
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ]
[, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ]
[, HASHES ]
[, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
[, SORT = <replaceable class="parameter">sort_op</replaceable> [, ...] ]
)
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
@ -53,25 +47,7 @@
</TERM>
<LISTITEM>
<PARA>
The name of an existing aggregate function.
</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>
The operator to be defined. See below for allowable characters.
</PARA>
</LISTITEM>
</VARLISTENTRY>
@ -81,6 +57,29 @@
</TERM>
<LISTITEM>
<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>
</LISTITEM>
</VARLISTENTRY>
@ -90,6 +89,7 @@
</TERM>
<LISTITEM>
<PARA>
The corresponding commutative operator.
</PARA>
</LISTITEM>
</VARLISTENTRY>
@ -99,6 +99,7 @@
</TERM>
<LISTITEM>
<PARA>
The corresponding negation operator.
</PARA>
</LISTITEM>
</VARLISTENTRY>
@ -108,6 +109,17 @@
</TERM>
<LISTITEM>
<PARA>
The corresponding restriction operator.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
HASHES
</TERM>
<LISTITEM>
<PARA>
This operator can support a hash-join algorithm.
</PARA>
</LISTITEM>
</VARLISTENTRY>
@ -117,6 +129,7 @@
</TERM>
<LISTITEM>
<PARA>
Procedure supporting table joins.
</PARA>
</LISTITEM>
</VARLISTENTRY>
@ -126,18 +139,17 @@
</TERM>
<LISTITEM>
<PARA>
Operator to use for sorting.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</variablelist>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
@ -147,6 +159,7 @@
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
@ -170,59 +183,62 @@
<REFSECT1 ID="R1-SQL-CREATEOPERATOR-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<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.
</para>
<para>
The operator_name is a sequence of up to sixteen punctua
tion characters. The following characters are valid for
single-character operator names:<literallayout>
The operator <replaceable class="parameter">name</replaceable>
is a sequence of up to thirty two (32) characters in any combination
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>
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.
</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
operators, only arg1 should be defined, while for left
unary operators only arg2 should be defined.
operators, only LEFTARG should be defined, while for left
unary operators only RIGHTARG should be defined.
</para>
<para>
The name of the operator, operator_name, can be composed
of symbols only. Also, the func_name procedure must have
been previously defined using create function(l) and must
have one or two arguments.
Also, the
<replaceable class="parameter">func_name</replaceable> procedure must have
been previously defined using <command>CREATE FUNCTION</command> and must
be defined to accept the correct number of arguments
(either one or two).
</para>
<para>
The commutator operator is present so that Postgres can
reverse the order of the operands if it wishes. For exam
ple, the operator area-less-than, >>>, would have a commu
tator operator, area-greater-than, <<<. Suppose that an
operator, area-equal, ===, exists, as well as an area not
equal, !==. Hence, the query optimizer could freely con
vert:
The commutator operator is present so that
<productname>Postgres</productname> can
reverse the order of the operands if it wishes.
For example, the operator area-less-than, &lt;&lt;&lt;,
would have a commutator
operator, area-greater-than, &gt;&gt;&gt;.
Hence, the query optimizer could freely convert:
<programlisting>
"0,0,1,1"::box >>> MYBOXES.description
"0,0,1,1"::box &gt;&gt;&gt; MYBOXES.description
</programlisting>
to
<programlisting>
MYBOXES.description <<< "0,0,1,1"::box</programlisting>
MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box</programlisting>
</para>
<para>
This allows the execution code to always use the latter
@ -230,17 +246,21 @@
what.
</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
<programlisting>
NOT MYBOXES.description === "0,0,1,1"::box
NOT MYBOXES.description === "0,0,1,1"::box
</programlisting>
to
<programlisting>
MYBOXES.description !== "0,0,1,1"::box
MYBOXES.description !== "0,0,1,1"::box
</programlisting>
</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
does not yet have a commutator itself, then the commutator's
entry is updated to have the current (new) operator
@ -256,22 +276,25 @@
</para>
<para>
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
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
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:
<programlisting>
MYBOXES.description === MYBOXES2.description
MYBOXES.description === MYBOXES2.description
</programlisting>
but not for a clause of the form:
<programlisting>
MYBOXES.description <<< MYBOXES2.description.
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description.
</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
usable for the operator in question.</para>
<para>
@ -279,15 +302,16 @@
optimizer whether merge-sort is a usable join strategy and
what operators should be used to sort the two operand
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:
<programlisting>
MYBOXES.description <<< MYBOXES2.description
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description
</programlisting>
</para>
<para>
If other join strategies are found to be practical, Post
gres will change the optimizer and run-time system to use
If other join strategies are found to be practical,
<productname>Postgres</productname>
will change the optimizer and run-time system to use
them and will require additional specification when an
operator is defined. Fortunately, the research community
invents new join strategies infrequently, and the added
@ -299,12 +323,14 @@
the query optimizer can estimate result sizes. If a
clause of the form:
<programlisting>
MYBOXES.description <<< "0,0,1,1"::box
MYBOXES.description &lt;&lt;&lt; "0,0,1,1"::box
</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
satisfy the clause. The function res_proc must be a reg
istered function (meaning it is already defined using
satisfy the clause. The function
<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
data type and returns a floating point number. The
query optimizer simply calls this function, passing the
@ -322,13 +348,14 @@
<para>
The difference between the function
<programlisting>
my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
</programlisting>
and the operator
<programlisting>
MYBOXES.description === "0,0,1,1"::box
MYBOXES.description === "0,0,1,1"::box
</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
operators are involved. However, there is no attempt to
optimize functions, and they are performed by brute force.
@ -338,18 +365,17 @@
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Refer to <citetitle>PostgreSQL User's Guide</citetitle> chapter 5
<comment>
This reference must be corrected.
</comment>
Refer to the chapter on operators in the
<citetitle>PostgreSQL User's Guide</citetitle>
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>
@ -361,16 +387,16 @@
area-equality, for the BOX data type.
</PARA>
<ProgramListing>
CREATE OPERATOR === (
LEFTARG = box,
RIGHTARG = box,
PROCEDURE = area_equal_procedure,
COMMUTATOR = ===,
NEGATOR = !==,
RESTRICT = area_restriction_procedure,
HASHES,
JOIN = area-join-procedure,
SORT = <<<, <<<)
CREATE OPERATOR === (
LEFTARG = box,
RIGHTARG = box,
PROCEDURE = area_equal_procedure,
COMMUTATOR = ===,
NEGATOR = !==,
RESTRICT = area_restriction_procedure,
HASHES,
JOIN = area-join-procedure,
SORT = <<<, <<<)
</ProgramListing>
@ -381,18 +407,18 @@
Compatibility
</TITLE>
<PARA>
CREATE OPERATOR is a PostgreSQL extension of SQL.
CREATE OPERATOR is a <productname>Postgres</productname> extension.
</PARA>
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
<DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no CREATE OPERATOR statement on SQL92.
There is no CREATE OPERATOR statement in <acronym>SQL92</acronym>.
</PARA>
</refsect2>
</refsect1>

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

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

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

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

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

@ -84,8 +84,8 @@
</TERM>
<LISTITEM>
<PARA>
This message occurs if it is impossible to drop the index
because it does not exist.
This message occurs if "<REPLACEABLE CLASS="PARAMETER">index_name</REPLACEABLE>"
is not an index in the database.
</PARA>
</LISTITEM>
</VARLISTENTRY>
@ -121,7 +121,7 @@
</PARA>
<PARA>
Refer to the <command>CREATE INDEX</command> statement for
inforamtion on how to create indexes.
information on how to create indices.
</PARA>
</REFSECT2>
@ -152,7 +152,9 @@
SQL92
</TITLE>
<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>
</refsect2>
</refsect1>

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

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

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

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