</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>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
-<ReturnValue>status</ReturnValue>
+<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
-<ReturnValue>ALTER</ReturnValue>
+<returnvalue>ALTER</returnvalue>
</TERM>
<LISTITEM>
<PARA>
<VARLISTENTRY>
<TERM>
-<ReturnValue>NEW</ReturnValue>
+<returnvalue>NEW</returnvalue>
</TERM>
<LISTITEM>
<PARA>
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
<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>
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
<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>
</PARA>
</VARIABLELIST>
</REFENTRY>
-
-<!--
-<REPLACEABLE CLASS="PARAMETER">
-</REPLACEABLE>
-<ReturnValue></ReturnValue>
-<PARA>
-</PARA>
-<VARIABLELIST>
-<VARLISTENTRY>
-<TERM>•
-</TERM>
-<LISTITEM>
-<PARA>
-</PARA>
-</LISTITEM>
-</VARLISTENTRY>
-</VARIABLELIST>
-<PARA>
-</PARA>
--->
</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>
</PARA>
</LISTITEM>
</VARLISTENTRY>
+
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER"> password </REPLACEABLE>
</PARA>
</LISTITEM>
</VARLISTENTRY>
+
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER"> groupname </REPLACEABLE>
</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>
<REFSECT2 ID="R2-SQL-ALTERUSER-2">
<REFSECT2INFO>
- <DATE>1998-04-15</DATE>
+ <DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
<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>
<VARLISTENTRY>
<TERM>
- <ReturnValue>ERROR: alterUser: user "username" does not exist</ReturnValue>
+ <returnvalue>ERROR: alterUser: user "username" does not exist</returnvalue>
</TERM>
<LISTITEM>
<PARA>
<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>
<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>
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
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>
<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>
<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
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
- status
+ <replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
- <ReturnValue>BEGIN</ReturnValue>
+ <returnvalue>BEGIN</returnvalue>
</TERM>
<LISTITEM>
<PARA>
</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>
<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.
<REFSECT2 ID="R2-SQL-BEGINWORK-3">
<REFSECT2INFO>
- <DATE>1998-04-15</DATE>
+ <DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Notes
The keyword TRANSACTION is just a cosmetic alternative to WORK.
Neither keyword need be specified.
</PARA>
-
- <PARA>
- BEGIN statement is a PostgreSQL language extension.
- </PARA>
-
+
<PARA>
- Refer to the LOCK statement for further information about locking
- tables inside a transaction.
+ Refer to the <command>LOCK</command> 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>
Usage
</TITLE>
<PARA>To begin a user transaction:
- </PARA>
+
<ProgramListing>
- BEGIN WORK;
+BEGIN WORK;
</ProgramListing>
</REFSECT1>
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>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
- <DATE>1998-04-15</DATE>
+ <DATE>1998-09-08</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
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>
</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
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
+ <replaceable>
+ status
+ </replaceable>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
- <ReturnValue>
- CLOSE
- </ReturnValue>
+<ReturnValue>CLOSE</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
</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>
<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>
Close the cursor liahona:
</PARA>
<ProgramListing>
- CLOSE liahona;
+CLOSE liahona;
</ProgramListing>
</REFSECT1>
<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>
<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
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
- <ReturnValue>
<REPLACEABLE CLASS="PARAMETER">indexname</REPLACEABLE>
- </ReturnValue>
</TERM>
<LISTITEM>
<PARA>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
- <ReturnValue>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
- </ReturnValue>
</TERM>
<LISTITEM>
<PARA>
<REFSECT2 ID="R2-SQL-CLUSTER-2">
<REFSECT2INFO>
- <DATE>1998-04-15</DATE>
+ <DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
+<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
- <ReturnValue>CLUSTER</ReturnValue>
+ <returnvalue>CLUSTER</returnvalue>
</TERM>
<LISTITEM>
<PARA>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
- <ReturnValue>ERROR: relation <<REPLACEABLE CLASS="PARAMETER">tablerelation_number</REPLACEABLE>> inherits "invoice"</ReturnValue>
+<returnvalue>ERROR: relation <<REPLACEABLE CLASS="PARAMETER">tablerelation_number</REPLACEABLE>> 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.
</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.
<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
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.
<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>
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>
<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>
<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>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
- <ReturnValue>NOTICE EndTransactionBlock and not inprogress/abort state
-</ReturnValue>
+ <returnvalue>NOTICE EndTransactionBlock and not inprogress/abort state</returnvalue>
</TERM>
<LISTITEM>
<PARA>
<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>
To make all changes permanent:
</PARA>
<ProgramListing>
- COMMIT WORK;
+COMMIT WORK;
</ProgramListing>
</REFSECT1>
<REFSECT2 ID="R2-SQL-COMMIT-4">
<REFSECT2INFO>
- <DATE>1998-04-15</DATE>
+ <DATE>1998-09-08</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</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>
<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>
+ <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-09-08</DATE>
+ </REFSECT2INFO>
+ <TITLE>
+ Notes
+ </TITLE>
<para>
- The <function>BINARY</function> keyword will force all data to be
- stored/read as binary objects rather than as ASCII text. It is
+ 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, an ASCII copy uses a tab (\t) character as a delimiter.
+ 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 <function>USING DELIMITERS</function>. Characters
+ with the keyword phrase USING DELIMITERS. Characters
in data fields which happen to match the delimiter character will
be quoted.
</para>
- <REFSECT2 ID="R2-SQL-COPY-3">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Notes
- </TITLE>
<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.
<para>
The actual format for each instance is
<programlisting>
- <attr1><<replaceable class=parameter>separator</replaceable>><attr2><<replaceable class=parameter>separator</replaceable>>...<<replaceable class=parameter>separator</replaceable>><attr<replaceable class="parameter">n</replaceable>><newline></programlisting>
+<attr1><<replaceable class=parameter>separator</replaceable>><attr2><<replaceable class=parameter>separator</replaceable>>...<<replaceable class=parameter>separator</replaceable>><attr<replaceable class="parameter">n</replaceable>><newline>
+</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>
<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
<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>
<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.
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>
\.
</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>
</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>
<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>
<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
</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>
</para>
</LISTITEM>
</varlistentry>
+
<varlistentry>
<term>
- <REPLACEABLE CLASS="PARAMETER">state_transition_function1</REPLACEABLE>
+ <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">data_type</REPLACEABLE>
+ <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
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
+<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<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">
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>
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>
<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">
Inputs
</TITLE>
<PARA>
- </PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- </TERM>
- <LISTITEM>
- <PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
- </LISTITEM>
- </VARLISTENTRY>
- </VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-2">
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
+ <replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
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>
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>
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>
Compatibility
</TITLE>
<PARA>
- </PARA>
<REFSECT2 ID="R2-SQL-CREATEDATABASE-4">
<REFSECT2INFO>
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>.
<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>
</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
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
+<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<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>
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
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>
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>
+ SQL/PSM
+ </TITLE>
+ <para>
+
+<note>
<para>
- PSM stands for Persistent Stored Modules, it is a procedural
+ 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
+ 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>
- </footnote>
- </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>
+
+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
</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
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>
</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
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
+<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<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
<REFSECT2 ID="R2-SQL-CREATEINDEX-3">
<REFSECT2INFO>
- <DATE>1998-04-15</DATE>
+ <DATE>1998-09-09</DATE>
</REFSECT2INFO>
<TITLE>
Notes
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>
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">
<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>
<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>
</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
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
+<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<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
<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>
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
<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>
</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">
</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>
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>
<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>
</TERM>
<LISTITEM>
<PARA>
- The name of an existing aggregate function.
+ The operator to be defined. See below for allowable characters.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
- <replaceable class="parameter">type1</replaceable>
+ <replaceable class="parameter">func_name</replaceable>
</TERM>
<LISTITEM>
<PARA>
+The function used to implement this operator.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
- <replaceable class="parameter">type2</replaceable>
+ <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">func_name</replaceable>
+ <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>
</TERM>
<LISTITEM>
<PARA>
+The corresponding commutative operator.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</TERM>
<LISTITEM>
<PARA>
+The corresponding negation operator.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</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>
</TERM>
<LISTITEM>
<PARA>
+Procedure supporting table joins.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</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
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
+<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<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>
+ + - * / < > = ~ ! @ # % ^ & | ` ? $ :
+</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>
-
- | $ : + - * / < > =</literallayout>
</para>
<para>
- The operator "!=" is mapped to "<>" on input, and they are
+ The operator "!=" is mapped to "<>" 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, <<<,
+ would have a commutator
+ operator, area-greater-than, >>>.
+ Hence, the query optimizer could freely convert:
<programlisting>
- "0,0,1,1"::box >>> MYBOXES.description
+"0,0,1,1"::box >>> MYBOXES.description
</programlisting>
to
<programlisting>
- MYBOXES.description <<< "0,0,1,1"::box</programlisting>
+MYBOXES.description <<< "0,0,1,1"::box</programlisting>
</para>
<para>
This allows the execution code to always use the latter
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
</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 <<< 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>
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, <<<. On the other
hand, merge-sort is not usable with the clause:
<programlisting>
- MYBOXES.description <<< MYBOXES2.description
+MYBOXES.description <<< 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
the query optimizer can estimate result sizes. If a
clause of the form:
<programlisting>
- MYBOXES.description <<< "0,0,1,1"::box
+MYBOXES.description <<< "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
<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.
<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>
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>
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>
</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>
</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>
</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
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
+<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
<REFSECT1 ID="R1-SQL-CREATERULE-1">
<REFSECT1INFO>
- <DATE>1998-04-15</DATE>
+ <DATE>1998-09-11</DATE>
</REFSECT1INFO>
<TITLE>
Description
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>
<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
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
<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
<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>
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
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>
<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.
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>
<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>
</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>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
- <ReturnValue><replaceable class="parameter">maxvalue</replaceable></ReturnValue>
+ <replaceable class="parameter">maxvalue</replaceable>
</TERM>
<LISTITEM>
<PARA>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
- <ReturnValue><replaceable class="parameter">start</replaceable></ReturnValue>
+ <replaceable class="parameter">start</replaceable>
</TERM>
<LISTITEM>
<PARA>
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>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
- <ReturnValue>CYCLE</ReturnValue>
+ CYCLE
</TERM>
<LISTITEM>
<PARA>
</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
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
+<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>
</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>
</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>
<REFSECT1 ID="R1-SQL-CREATESEQUENCE-1">
<REFSECT1INFO>
- <DATE>1998-04-15</DATE>
+ <DATE>1998-09-11</DATE>
</REFSECT1INFO>
<TITLE>
Description
</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>
<REFSECT2 ID="R2-SQL-CREATESEQUENCE-3">
<REFSECT2INFO>
- <DATE>1998-04-15</DATE>
+ <DATE>1998-09-11</DATE>
</REFSECT2INFO>
<TITLE>
Notes
<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>
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>
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>
</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>
</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>
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>
SQL92
</TITLE>
<PARA>
- There is no DROP PROCEDURAL LANGUAGE statement on SQL92.
+ There is no DROP PROCEDURAL LANGUAGE statement in SQL92.
</PARA>
</refsect2>
</refsect1>
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>
projects / postgresql / commitdiff