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

More editing of reference pages.

This commit is contained in:
Peter Eisentraut 2003-04-22 10:08:08 +00:00
parent 8a703496a2
commit 3450fd08a9
21 changed files with 2561 additions and 3612 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.24 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.25 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -10,166 +10,40 @@ PostgreSQL documentation
</refmeta>
<refnamediv>
<refname>
CREATE AGGREGATE
</refname>
<refpurpose>
define a new aggregate function
</refpurpose>
<refname>CREATE AGGREGATE</refname>
<refpurpose>define a new aggregate function</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2000-07-16</date>
</refsynopsisdivinfo>
<synopsis>
CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE = <replaceable class="PARAMETER">input_data_type</replaceable>,
SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>, STYPE = <replaceable class="PARAMETER">state_type</replaceable>
<synopsis>
CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> (
BASETYPE = <replaceable class="PARAMETER">input_data_type</replaceable>,
SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>,
STYPE = <replaceable class="PARAMETER">state_data_type</replaceable>
[ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ]
[ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ] )
</synopsis>
<refsect2 id="R2-SQL-CREATEAGGREGATE-1">
<refsect2info>
<date>2000-07-16</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an aggregate function to
create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">input_data_type</replaceable></term>
<listitem>
<para>
The input data type on which this aggregate function operates.
This can be specified as <literal>"ANY"</> for an aggregate that does
not examine its input values
(an example is <function>count(*)</function>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">sfunc</replaceable></term>
<listitem>
<para>
The name of the state transition function
to be called for each input data value.
This is normally a function of two arguments, the first being of
type <replaceable class="PARAMETER">state_type</replaceable>
and the second of
type <replaceable class="PARAMETER">input_data_type</replaceable>.
Alternatively, for an aggregate that does not examine its input
values, the function takes just one argument of
type <replaceable class="PARAMETER">state_type</replaceable>.
In either case the function must return a value of
type <replaceable class="PARAMETER">state_type</replaceable>.
This function takes the current state value and the current
input data item, and returns the next state value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">state_type</replaceable></term>
<listitem>
<para>
The data type for the aggregate's state value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">ffunc</replaceable></term>
<listitem>
<para>
The name of the final function called to compute the aggregate's
result after all input data has been traversed. The function
must take a single argument of type
<replaceable class="PARAMETER">state_type</replaceable>.
The output data type of the aggregate is defined as the return
type of this function.
If <replaceable class="PARAMETER">ffunc</replaceable>
is not specified, then the ending state value is used as the
aggregate's result, and the output type is
<replaceable class="PARAMETER">state_type</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">initial_condition</replaceable></term>
<listitem>
<para>
The initial setting for the state value. This must be a literal
constant in the form accepted for the data type
<replaceable class="PARAMETER">state_type</replaceable>.
If not specified, the state value starts out NULL.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATEAGGREGATE-2">
<refsect2info>
<date>1998-09-09</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE AGGREGATE
</computeroutput></term>
<listitem>
<para>
Message returned if the command completes successfully.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
[ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ]
)
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATEAGGREGATE-1">
<refsect1info>
<date>2000-07-16</date>
</refsect1info>
<title>
Description
</title>
<refsect1>
<title>Description</title>
<para>
<command>CREATE AGGREGATE</command>
allows a user or programmer to extend <productname>PostgreSQL</productname>
functionality by defining new aggregate functions. Some aggregate functions
<command>CREATE AGGREGATE</command> defines a new aggregate function. Some aggregate functions
for base types such as <function>min(integer)</function>
and <function>avg(double precision)</function> are already provided in the base
and <function>avg(double precision)</function> are already provided in the standard
distribution. If one defines new types or needs an aggregate function not
already provided, then <command>CREATE AGGREGATE</command>
can be used to provide the desired features.
</para>
<para>
If a schema name is given (for example, <literal>CREATE AGGREGATE
myschema.myagg ...</>) then the aggregate function is created in the
specified schema. Otherwise it is created in the current schema (the one
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
specified schema. Otherwise it is created in the current schema.
</para>
<para>
An aggregate function is identified by its name and input data type.
Two aggregates in the same schema can have the same name if they operate on
@ -178,6 +52,7 @@ CREATE AGGREGATE
the name and input data type(s) of every ordinary function in the same
schema.
</para>
<para>
An aggregate function is made from one or two ordinary
functions:
@ -186,11 +61,12 @@ CREATE AGGREGATE
and an optional final calculation function
<replaceable class="PARAMETER">ffunc</replaceable>.
These are used as follows:
<programlisting>
<programlisting>
<replaceable class="PARAMETER">sfunc</replaceable>( internal-state, next-data-item ) ---> next-internal-state
<replaceable class="PARAMETER">ffunc</replaceable>( internal-state ) ---> aggregate-value
</programlisting>
</programlisting>
</para>
<para>
<productname>PostgreSQL</productname> creates a temporary variable
of data type <replaceable class="PARAMETER">stype</replaceable>
@ -198,7 +74,7 @@ CREATE AGGREGATE
data item,
the state transition function is invoked to calculate a new
internal state value. After all the data has been processed,
the final function is invoked once to calculate the aggregate's output
the final function is invoked once to calculate the aggregate's return
value. If there is no final function then the ending state value
is returned as-is.
</para>
@ -206,67 +82,163 @@ CREATE AGGREGATE
<para>
An aggregate function may provide an initial condition,
that is, an initial value for the internal state value.
This is specified and stored in the database as a field of type
This is specified and stored in the database as a column of type
<type>text</type>, but it must be a valid external representation
of a constant of the state value data type. If it is not supplied
then the state value starts out NULL.
then the state value starts out null.
</para>
<para>
If the state transition function is declared <quote>strict</quote>,
then it cannot be called with NULL inputs. With such a transition
function, aggregate execution behaves as follows. NULL input values
then it cannot be called with null inputs. With such a transition
function, aggregate execution behaves as follows. Null input values
are ignored (the function is not called and the previous state value
is retained). If the initial state value is NULL, then the first
non-NULL input value replaces the state value, and the transition
function is invoked beginning with the second non-NULL input value.
is retained). If the initial state value is null, then the first
nonnull input value replaces the state value, and the transition
function is invoked beginning with the second nonnull input value.
This is handy for implementing aggregates like <function>max</function>.
Note that this behavior is only available when
<replaceable class="PARAMETER">state_type</replaceable>
<replaceable class="PARAMETER">state_data_type</replaceable>
is the same as
<replaceable class="PARAMETER">input_data_type</replaceable>.
When these types are different, you must supply a non-NULL initial
condition or use a non-strict transition function.
When these types are different, you must supply a nonnull initial
condition or use a nonstrict transition function.
</para>
<para>
If the state transition function is not strict, then it will be called
unconditionally at each input value, and must deal with NULL inputs
and NULL transition values for itself. This allows the aggregate
unconditionally at each input value, and must deal with null inputs
and null transition values for itself. This allows the aggregate
author to have full control over the aggregate's handling of null values.
</para>
<para>
If the final function is declared <quote>strict</quote>, then it will not
be called when the ending state value is NULL; instead a NULL result
will be output automatically. (Of course this is just the normal
be called when the ending state value is null; instead a null result
will be returned automatically. (Of course this is just the normal
behavior of strict functions.) In any case the final function has
the option of returning NULL. For example, the final function for
<function>avg</function> returns NULL when it sees there were zero
input tuples.
the option of returning a null value. For example, the final function for
<function>avg</function> returns null when it sees there were zero
input rows.
</para>
<refsect2 id="R2-SQL-CREATEAGGREGATE-3">
<refsect2info>
<date>2000-07-16</date>
</refsect2info>
<title>
Notes
</title>
<para>
Use <command>DROP AGGREGATE</command>
to drop aggregate functions.
</para>
<para>
The parameters of <command>CREATE AGGREGATE</command> can be written
in any order, not just the order illustrated above.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-CREATEAGGREGATE-2">
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of the aggregate function
to create.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">input_data_type</replaceable></term>
<listitem>
<para>
The input data type on which this aggregate function operates.
This can be specified as <literal>"ANY"</> for an aggregate that
does not examine its input values (an example is
<function>count(*)</function>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">sfunc</replaceable></term>
<listitem>
<para>
The name of the state transition function to be called for each
input data value. This is normally a function of two arguments,
the first being of type <replaceable
class="PARAMETER">state_data_type</replaceable> and the second
of type <replaceable
class="PARAMETER">input_data_type</replaceable>. Alternatively,
for an aggregate that does not examine its input values, the
function takes just one argument of type <replaceable
class="PARAMETER">state_data_type</replaceable>. In either case
the function must return a value of type <replaceable
class="PARAMETER">state_data_type</replaceable>. This function
takes the current state value and the current input data item,
and returns the next state value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">state_data_type</replaceable></term>
<listitem>
<para>
The data type for the aggregate's state value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">ffunc</replaceable></term>
<listitem>
<para>
The name of the final function called to compute the aggregate's
result after all input data has been traversed. The function
must take a single argument of type <replaceable
class="PARAMETER">state_data_type</replaceable>. The return
data type of the aggregate is defined as the return type of this
function. If <replaceable class="PARAMETER">ffunc</replaceable>
is not specified, then the ending state value is used as the
aggregate's result, and the return type is <replaceable
class="PARAMETER">state_data_type</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">initial_condition</replaceable></term>
<listitem>
<para>
The initial setting for the state value. This must be a string
constant in the form accepted for the data type <replaceable
class="PARAMETER">state_data_type</replaceable>. If not
specified, the state value starts out null.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The parameters of <command>CREATE AGGREGATE</command> can be
written in any order, not just the order illustrated above.
</para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE AGGREGATE</computeroutput></term>
<listitem>
<para>
Message returned if the command completes successfully.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
Use <command>DROP AGGREGATE</command> to drop aggregate functions.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
@ -274,24 +246,14 @@ CREATE AGGREGATE
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATEAGGREGATE-3">
<title>
Compatibility
</title>
<refsect1>
<title>Compatibility</title>
<refsect2 id="R2-SQL-CREATEAGGREGATE-4">
<refsect2info>
<date>1998-09-09</date>
</refsect2info>
<title>
SQL92
</title>
<para>
<command>CREATE AGGREGATE</command>
is a <productname>PostgreSQL</productname> language extension.
There is no <command>CREATE AGGREGATE</command> in SQL92.
</para>
</refsect2>
<para>
<command>CREATE AGGREGATE</command> is a
<productname>PostgreSQL</productname> language extension. The SQL
standard does not provide for user-defined aggregate function.
</para>
</refsect1>
</refentry>

41
doc/src/sgml/ref/create_cast.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.10 2003/03/25 16:15:39 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.11 2003/04/22 10:08:08 petere Exp $ -->
<refentry id="SQL-CREATECAST">
<refmeta>
@ -58,11 +58,11 @@ SELECT CAST(42 AS text);
<para>
If the cast is marked <literal>AS ASSIGNMENT</> then it can be invoked
implicitly when assigning to a column of the target data type.
implicitly when assigning a value to a column of the target data type.
For example, supposing that <literal>foo.f1</literal> is a column of
type <type>text</type>, then
<programlisting>
INSERT INTO foo(f1) VALUES(42);
INSERT INTO foo (f1) VALUES (42);
</programlisting>
will be allowed if the cast from type <type>integer</type> to type
<type>text</type> is marked <literal>AS ASSIGNMENT</>, otherwise
@ -75,7 +75,7 @@ INSERT INTO foo(f1) VALUES(42);
If the cast is marked <literal>AS IMPLICIT</> then it can be invoked
implicitly in any context, whether assignment or internally in an
expression. For example, since <literal>||</> takes <type>text</>
arguments,
operands,
<programlisting>
SELECT 'The time is ' || now();
</programlisting>
@ -106,14 +106,16 @@ SELECT 'The time is ' || CAST(now() AS text);
<para>
To be able to create a cast, you must own the source or the target
data type. To create a binary-compatible cast, you must be superuser
(this restriction is made because an erroneous binary-compatible cast
conversion can easily crash the server).
data type. To create a binary-compatible cast, you must be superuser.
(This restriction is made because an erroneous binary-compatible cast
conversion can easily crash the server.)
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<title>Parameters</title>
<varlistentry>
<term><replaceable>sourcetype</replaceable></term>
@ -183,6 +185,21 @@ SELECT 'The time is ' || CAST(now() AS text);
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE CAST</computeroutput></term>
<listitem>
<para>
Message returned if the cast was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="sql-createcast-notes">
<title>Notes</title>
@ -201,8 +218,8 @@ SELECT 'The time is ' || CAST(now() AS text);
argument of a different type was automatically a cast function.
This convention has been abandoned in face of the introduction of
schemas and to be able to represent binary compatible casts in the
catalogs. (The built-in cast functions still follow this naming
scheme, but they have to be shown as casts in <literal>pg_cast</>
system catalogs. (The built-in cast functions still follow this naming
scheme, but they have to be shown as casts in the system catalog <literal>pg_cast</>
now.)
</para>
</refsect1>
@ -227,7 +244,7 @@ CREATE CAST (text AS int4) WITH FUNCTION int4(text);
<para>
The <command>CREATE CAST</command> command conforms to SQL99,
except that SQL99 does not make provisions for binary compatible
except that SQL99 does not make provisions for binary-compatible
types. <literal>AS IMPLICIT</> is a <productname>PostgreSQL</productname>
extension, too.
</para>

83
doc/src/sgml/ref/create_constraint.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_constraint.sgml,v 1.8 2002/05/18 15:44:47 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_constraint.sgml,v 1.9 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,30 +8,35 @@ PostgreSQL documentation
<refentrytitle id="sql-createconstraint-title">CREATE CONSTRAINT TRIGGER</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE CONSTRAINT TRIGGER
</refname>
<refpurpose>
define a new constraint trigger
</refpurpose>
<refname>CREATE CONSTRAINT TRIGGER</refname>
<refpurpose>define a new constraint trigger</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2000-04-13</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
AFTER <replaceable class="parameter">events</replaceable> ON
<replaceable class="parameter">relation</replaceable> <replaceable class="parameter">constraint</replaceable> <replaceable class="parameter">attributes</replaceable>
FOR EACH ROW EXECUTE PROCEDURE <replaceable class="parameter">func</replaceable> '(' <replaceable class="parameter">args</replaceable> ')'
</synopsis>
<replaceable class="parameter">table</replaceable> <replaceable class="parameter">constraint</replaceable> <replaceable class="parameter">attributes</replaceable>
FOR EACH ROW EXECUTE PROCEDURE <replaceable class="parameter">func</replaceable> ( <replaceable class="parameter">args</replaceable> )
</synopsis>
</refsynopsisdiv>
<refsect2 id="R2-SQL-CREATECONSTRAINT-1">
<title>
Inputs
</title>
<para>
<refsect1>
<title>Description</title>
<para>
<command>CREATE CONSTRAINT TRIGGER</command> is used within
<command>CREATE TABLE</command>/<command>ALTER TABLE</command> and by
<application>pg_dump</application> to create the special triggers for
referential integrity.
It is not intended for general use.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
@ -53,10 +58,10 @@ CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">relation</replaceable></term>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name (possibly schema-qualified) of the relation in which
The name (possibly schema-qualified) of the table in which
the triggering events occur.
</para>
</listitem>
@ -75,7 +80,7 @@ CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
<term><replaceable class="PARAMETER">attributes</replaceable></term>
<listitem>
<para>
Constraint attributes.
The constraint attributes.
</para>
</listitem>
</varlistentry>
@ -84,25 +89,19 @@ CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
<term><replaceable class="PARAMETER">func</replaceable>(<replaceable class="PARAMETER">args</replaceable>)</term>
<listitem>
<para>
Function to call as part of the trigger processing.
The function to call as part of the trigger processing.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsect1>
<refsect2 id="R2-SQL-CREATECONSTRAINT-2">
<title>
Outputs
</title>
<para>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE TRIGGER
</computeroutput></term>
<term><computeroutput>CREATE TRIGGER</computeroutput></term>
<listitem>
<para>
Message returned if successful.
@ -110,24 +109,6 @@ CREATE TRIGGER
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATECONSTRAINT-1">
<title>
Description
</title>
<para>
<command>CREATE CONSTRAINT TRIGGER</command> is used within
<command>CREATE/ALTER TABLE</command> and by
<application>pg_dump</application> to create the special triggers for
referential integrity.
</para>
<para>
It is not intended for general use.
</para>
</refsect1>
</refentry>

66
doc/src/sgml/ref/create_conversion.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_conversion.sgml,v 1.7 2003/03/25 16:15:39 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_conversion.sgml,v 1.8 2003/04/22 10:08:08 petere Exp $ -->
<refentry id="SQL-CREATECONVERSION">
<refmeta>
@ -23,21 +23,24 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
<para>
<command>CREATE CONVERSION</command> defines a new encoding
conversion. Conversion names may be used in the CONVERT() function
conversion. Conversion names may be used in the <function>convert</function> function
to specify a particular encoding conversion. Also, conversions that
are marked DEFAULT can be used for automatic encoding conversion between
frontend and backend. For this purpose, two conversions, from encoding A to
B AND from encoding B to A, must be defined.
are marked <literal>DEFAULT</> can be used for automatic encoding conversion between
client and server. For this purpose, two conversions, from encoding A to
B <emphasis>and</emphasis> from encoding B to A, must be defined.
</para>
<para>
To be able to create a conversion, you must have the execute right
on the function and the create right on the destination schema.
To be able to create a conversion, you must have <literal>EXECUTE</literal> privilege
on the function and <literal>CREATE</literal> privilege on the destination schema.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<title>Parameters</title>
<varlistentry>
<term><literal>DEFAULT</literal></term>
@ -75,7 +78,7 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
</varlistentry>
<varlistentry>
<term><replaceable>source_encoding</replaceable></term>
<term><replaceable>dest_encoding</replaceable></term>
<listitem>
<para>
@ -92,25 +95,39 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
The function used to perform the conversion. The function name may
be schema-qualified. If it is not, the function will be looked
up in the path.
</para>
</para>
<para>
<para>
The function must have the following signature:
<programlisting>
conv_proc(
INTEGER, -- source encoding id
INTEGER, -- destination encoding id
CSTRING, -- source string (null terminated C string)
CSTRING, -- destination string (null terminated C string)
INTEGER -- source string length
) returns VOID;
</programlisting>
<programlisting>
conv_proc(
integer, -- source encoding ID
integer, -- destination encoding ID
cstring, -- source string (null terminated C string)
cstring, -- destination string (null terminated C string)
integer -- source string length
) RETURNS void;
</programlisting>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE CONVERSION</computeroutput></term>
<listitem>
<para>
Message returned if the conversion was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="sql-createconversion-notes">
@ -124,15 +141,14 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
The privileges required to create a conversion may be changed in a future
release.
</para>
</refsect1>
<refsect1 id="sql-createconversion-examples">
<title>Examples</title>
<para>
To create a conversion from encoding UNICODE to LATIN1 using <function>myfunc</>:
To create a conversion from encoding <literal>UNICODE</literal> to
<literal>LATIN1</literal> using <function>myfunc</>:
<programlisting>
CREATE CONVERSION myconv FOR 'UNICODE' TO 'LATIN1' FROM myfunc;
</programlisting>
@ -147,7 +163,7 @@ CREATE CONVERSION myconv FOR 'UNICODE' TO 'LATIN1' FROM myfunc;
<command>CREATE CONVERSION</command>
is a <productname>PostgreSQL</productname> extension.
There is no <command>CREATE CONVERSION</command>
statement in <acronym>SQL99</acronym>.
statement in the SQL standard.
</para>
</refsect1>

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

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.33 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.34 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,34 +8,81 @@ PostgreSQL documentation
<refentrytitle id="sql-createdatabase-title">CREATE DATABASE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE DATABASE
</refname>
<refpurpose>
create a new database
</refpurpose>
<refname>CREATE DATABASE</refname>
<refpurpose>create a new database</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-12-11</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
[ [ WITH ] [ OWNER [=] <replaceable class="parameter">dbowner</replaceable> ]
[ LOCATION [=] '<replaceable class="parameter">dbpath</replaceable>' ]
[ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ]
[ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ] ]
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect2 id="R2-SQL-CREATEDATABASE-1">
<refsect2info>
<date>1999-12-11</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<refsect1>
<title>Description</title>
<para>
<command>CREATE DATABASE</command> creates a new
<productname>PostgreSQL</productname> database.
</para>
<para>
Normally, the creator becomes the owner of the new database.
Superusers can create databases owned by other users using the
<literal>OWNER</> clause. They can even create databases owned by
users with no special privileges. Non-superusers with <literal>CREATEDB</>
privilege can only create databases owned by themselves.
</para>
<para>
An alternative location can be specified in order to,
for example, store the database on a different disk.
The path must have been prepared with the
<xref linkend="APP-INITLOCATION" endterm="APP-INITLOCATION-title">
command.
</para>
<para>
If the path name does not contain a slash, it is interpreted
as an environment variable name, which must be known to the
server process. This way the database administrator can
exercise control over locations in which databases can be created.
(A customary choice is, e.g., <envar>PGDATA2</envar>.)
If the server is compiled with <literal>ALLOW_ABSOLUTE_DBPATHS</literal>
(not so by default), absolute path names, as identified by
a leading slash
(e.g., <filename>/usr/local/pgsql/data</filename>),
are allowed as well.
</para>
<para>
By default, the new database will be created by cloning the standard
system database <literal>template1</>. A different template can be
specified by writing <literal>TEMPLATE
<replaceable class="parameter">name</replaceable></literal>. In particular,
by writing <literal>TEMPLATE template0</>, you can create a virgin
database containing only the standard objects predefined by your
version of <productname>PostgreSQL</productname>. This is useful
if you wish to avoid copying
any installation-local objects that may have been added to
<literal>template1</>.
</para>
<para>
The optional encoding parameter allows selection of the database
encoding. When not specified, it defaults to the encoding used by
the selected template database.
</para>
</refsect1>
<refsect1>
<title>Parameter</title>
<variablelist>
<varlistentry>
@ -50,7 +97,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
<term><replaceable class="parameter">dbowner</replaceable></term>
<listitem>
<para>
Name of the database user who will own the new database,
The name of the database user who will own the new database,
or <literal>DEFAULT</literal> to use the default (namely, the
user executing the command).
</para>
@ -70,7 +117,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
<term><replaceable class="parameter">template</replaceable></term>
<listitem>
<para>
Name of template from which to create the new database,
The name of the template from which to create the new database,
or <literal>DEFAULT</literal> to use the default template
(<literal>template1</literal>).
</para>
@ -80,32 +127,30 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
<term><replaceable class="parameter">encoding</replaceable></term>
<listitem>
<para>
Multibyte encoding method to use in the new database. Specify
a string literal name (e.g., <literal>'SQL_ASCII'</literal>),
Character set encoding to use in the new database. Specify
a string constant (e.g., <literal>'SQL_ASCII'</literal>),
or an integer encoding number, or <literal>DEFAULT</literal>
to use the default encoding.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATEDATABASE-2">
<refsect2info>
<date>1999-12-11</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<para>
Optional parameters can be written in any order, not only the order
illustrated above.
</para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE DATABASE</computeroutput></term>
<listitem>
<para>
Message returned if the command completes successfully.
Message returned if the database was successfully created.
</para>
</listitem>
</varlistentry>
@ -125,8 +170,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
<term><computeroutput>ERROR: createdb: database "<replaceable class="parameter">name</replaceable>" already exists</computeroutput></term>
<listitem>
<para>
This occurs if a database with the <replaceable class="parameter">name</replaceable>
specified already exists.
This occurs if a database with the specified name already
exists.
</para>
</listitem>
</varlistentry>
@ -166,186 +211,73 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
</refsect1>
<refsect1 id="R1-SQL-CREATEDATABASE-1">
<refsect1info>
<date>1999-12-11</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>CREATE DATABASE</command> creates a new
<productname>PostgreSQL</productname> database.
</para>
<refsect1>
<title>Notes</title>
<para>
Normally, the creator becomes the owner of the new database.
Superusers can create databases owned by other users using the
<option>OWNER</> clause. They can even create databases owned by
users with no special privileges. Non-superusers with <literal>CREATEDB</>
privilege can only create databases owned by themselves.
</para>
<para>
An alternate location can be specified in order to,
for example, store the database on a different disk.
The path must have been prepared with the
<xref linkend="APP-INITLOCATION" endterm="APP-INITLOCATION-title">
command.
</para>
<para>
If the path name does not contain a slash, it is interpreted
as an environment variable name, which must be known to the
server process. This way the database administrator can
exercise control over locations in which databases can be created.
(A customary choice is, e.g., <envar>PGDATA2</envar>.)
If the server is compiled with <literal>ALLOW_ABSOLUTE_DBPATHS</literal>
(not so by default), absolute path names, as identified by
a leading slash
(e.g., <filename>/usr/local/pgsql/data</filename>),
are allowed as well.
</para>
<para>
By default, the new database will be created by cloning the standard
system database <literal>template1</>. A different template can be
specified by writing <literal>TEMPLATE =</>
<replaceable class="parameter">name</replaceable>. In particular,
by writing <literal>TEMPLATE = template0</>, you can create a virgin
database containing only the standard objects predefined by your
version of <productname>PostgreSQL</productname>. This is useful
if you wish to avoid copying
any installation-local objects that may have been added to
<literal>template1</>.
</para>
<para>
The optional encoding parameter allows selection of the database
encoding. When not specified, it defaults to the encoding used by
the selected template database.
</para>
<para>
Optional parameters can be written in any order, not only the order
illustrated above.
</para>
<refsect2 id="R2-SQL-CREATEDATABASE-3">
<refsect2info>
<date>1999-12-11</date>
</refsect2info>
<title>
Notes
</title>
<para>
<command>CREATE DATABASE</command> is a <productname>PostgreSQL</productname>
language extension.
</para>
<para>
Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
</para>
<para>
The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a
shell script wrapper around this command, provided for convenience.
wrapper program around this command, provided for convenience.
</para>
<para>
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 <xref linkend="manage-ag-alternate-locs"> for more information.
</para>
<!--
comment from Olly; response from Thomas...
<comment>
initlocation does not create a PG_VERSION file in the specified location.
How will PostgreSQL handle the situation if it is upgraded to an
incompatible database version?
</comment>
Hmm. This isn't an issue since the upgrade would do
a dump/reload from the main database area also.
Not sure if the dump/reload would guarantee that
the alternate data area gets refreshed though...
-->
<para>
There are security issues involved with using alternate database
locations specified with absolute path names. See <xref
linkend="manage-ag-alternate-locs"> for more information.
</para>
<para>
Although it is possible to copy a database other than <literal>template1</>
by specifying its name as the template, this is not (yet) intended as
a general-purpose COPY DATABASE facility.
a general-purpose <quote><command>COPY DATABASE</command></quote> facility.
We recommend that databases used as templates be treated as read-only.
See <xref linkend="user-manag"> for more information.
See <xref linkend="manage-ag-templatedbs"> for more information.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-CREATEDATABASE-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
To create a new database:
<programlisting>
<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
</programlisting>
<programlisting>
CREATE DATABASE lusiadas;
</programlisting>
</para>
<para>
To create a new database in an alternate area <filename>~/private_db</filename>:
To create a new database in an alternate area
<filename>~/private_db</filename>, execute the following from the
shell:
<programlisting>
<prompt>$</prompt> <userinput>mkdir private_db</userinput>
<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
<computeroutput>
The location will be initialized with username "olly".
This user will own all the files and must also own the server process.
Creating directory /home/olly/private_db
Creating directory /home/olly/private_db/base
<programlisting>
mkdir private_db
initlocation ~/private_db
</programlisting>
initlocation is complete.
</computeroutput>
<prompt>$</prompt> <userinput>psql olly</userinput>
<computeroutput>
Welcome to psql, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help on internal slash commands
\g or terminate with semicolon to execute query
\q to quit
Then execute the following from within a
<application>psql</application> session:
<prompt>olly=></prompt></computeroutput> <userinput>CREATE DATABASE elsewhere WITH LOCATION = '/home/olly/private_db';</userinput>
<computeroutput>CREATE DATABASE</computeroutput>
</programlisting>
<programlisting>
CREATE DATABASE elsewhere WITH LOCATION '/home/olly/private_db';
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATEDATABASE-4">
<title>
Compatibility
</title>
<refsect1>
<title>Compatibility</title>
<refsect2 id="R2-SQL-CREATEDATABASE-4">
<refsect2info>
<date>1998-04-15</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>CREATE DATABASE</command> statement in SQL92.
Databases are equivalent to catalogs, whose creation is
implementation-defined.
</para>
</refsect2>
<para>
There is no <command>CREATE DATABASE</command> statement in the SQL
standard. Databases are equivalent to catalogs, whose creation is
implementation-defined.
</para>
</refsect1>
</refentry>

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

@ -1,28 +1,21 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.12 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.13 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
<refentry id="SQL-CREATEDOMAIN">
<refmeta>
<refentrytitle id="sql-createdomain-title">
CREATE DOMAIN
</refentrytitle>
<refentrytitle id="sql-createdomain-title">CREATE DOMAIN</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE DOMAIN
</refname>
<refpurpose>
define a new domain
</refpurpose>
<refname>CREATE DOMAIN</refname>
<refpurpose>define a new domain</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2002-02-24</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
CREATE DOMAIN <replaceable class="parameter">domainname</replaceable> [AS] <replaceable class="parameter">data_type</replaceable>
[ DEFAULT <replaceable>default_expr</> ]
[ <replaceable class="PARAMETER">constraint</replaceable> [ ... ] ]
@ -31,16 +24,35 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
{ NOT NULL | NULL | CHECK (<replaceable class="PARAMETER">expression</replaceable>) }
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect2 id="R2-SQL-CREATEDOMAIN-1">
<refsect2info>
<date>2002-02-24</date>
</refsect2info>
<title>
Parameters
</title>
<para>
<refsect1>
<title>Description</title>
<para>
<command>CREATE DOMAIN</command> creates a new data domain. The
user who defines a domain becomes its owner.
</para>
<para>
If a schema name is given (for example, <literal>CREATE DOMAIN
myschema.mydomain ...</>) then the domain is created in the
specified schema. Otherwise it is created in the current schema.
The domain name must be unique among the types and domains existing
in its schema.
</para>
<para>
Domains are useful for abstracting common fields between tables into
a single location for maintenance. For example, an email address column may be used
in several tables, all with the same properties. Define a domain and
use that rather than setting up each table's constraints individually.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
@ -63,32 +75,26 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
</varlistentry>
<varlistentry>
<term><literal>DEFAULT
<replaceable>default_expr</replaceable></literal></term>
<term><literal>DEFAULT <replaceable>default_expr</replaceable></literal></term>
<listitem>
<para>
The <literal>DEFAULT</> clause specifies a default value for
columns of the domain data type. The value
is any variable-free expression (but subselects are not allowed).
The
data type of the default expression must match the data type of the
domain.
columns of the domain data type. The value is any
variable-free expression (but subqueries are not allowed).
The data type of the default expression must match the data
type of the domain. If no default value is specified, then
the default value is the null value.
</para>
<para>
The default expression will be used in any insert operation that
does not specify a value for the column. If there is no default
for a domain, then the default is NULL.
The default expression will be used in any insert operation
that does not specify a value for the column. If a default
value is defined for a particular column, it overrides any
default associated with the domain. In turn, the domain
default overrides any default value associated with the
underlying data type.
</para>
<note>
<para>
If a default value is specified for a particular column, it
overrides any default associated with the domain. In turn,
the domain default overrides any default value associated with
the underlying data type.
</para>
</note>
</listitem>
</varlistentry>
@ -106,7 +112,7 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
<term><literal>NOT NULL</></term>
<listitem>
<para>
Values of this domain are not allowed to be NULL.
Values of this domain are not allowed to be null.
</para>
</listitem>
</varlistentry>
@ -115,12 +121,12 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
<term><literal>NULL</></term>
<listitem>
<para>
Values of this domain are allowed to be NULL. This is the default.
Values of this domain are allowed to be null. This is the default.
</para>
<para>
This clause is only available for compatibility with
non-standard SQL databases. Its use is discouraged in new
This clause is only intended for compatibility with
nonstandard SQL databases. Its use is discouraged in new
applications.
</para>
</listitem>
@ -139,84 +145,50 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
<para>
Currently, <literal>CHECK</literal> expressions cannot contain
subselects nor refer to variables other than <literal>VALUE</>.
subqueries nor refer to variables other than <literal>VALUE</>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</variablelist>
</para>
</refsect2>
<refsect1>
<title>Diagnostics</title>
<refsect2 id="R2-SQL-CREATEDOMAIN-2">
<refsect2info>
<date>2002-02-24</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE DOMAIN
</computeroutput></term>
<listitem>
<para>
Message returned if the domain is successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATEDOMAIN-1">
<refsect1info>
<date>2002-02-24</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>CREATE DOMAIN</command> allows the user to register a new
data domain with <productname>PostgreSQL</> for use in the
current data base. The user who defines a domain becomes its owner.
</para>
<para>
If a schema name is given (for example, <literal>CREATE DOMAIN
myschema.mydomain ...</>) then the domain is created in the
specified schema. Otherwise it is created in the current schema (the one
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
The domain name must be unique among the types and domains existing
in its schema.
</para>
<para>
Domains are useful for abstracting common fields between tables into
a single location for maintenance. An email address column may be used
in several tables, all with the same properties. Define a domain and
use that rather than setting up each table's constraints individually.
</para>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE DOMAIN</computeroutput></term>
<listitem>
<para>
Message returned if the domain was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
This example creates the <type>country_code</type> data type and then uses the
type in a table definition:
<programlisting>
CREATE DOMAIN country_code char(2) NOT NULL;
CREATE TABLE countrylist (id INT4, country country_code);
CREATE TABLE countrylist (id integer, country country_code);
</programlisting>
</para>
</refsect1>
<refsect1 id="SQL-CREATEDOMAIN-compatibility">
<title>Compatibility</title>
<para>
The command <command>CREATE DOMAIN</command> conforms to the SQL
standard.
</para>
</refsect1>
<refsect1 id="SQL-CREATEDOMAIN-see-also">
<title>See Also</title>

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

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.46 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.47 2003/04/22 10:08:08 petere Exp $
-->
<refentry id="SQL-CREATEFUNCTION">
@ -38,25 +38,48 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
</para>
<para>
The user that creates the function becomes the owner of the function.
If a schema name is included, then the function is created in the
specified schema. Otherwise it is created in the current schema.
The name of the new function must not match any existing function
with the same argument types in the same schema. However,
functions of different argument types may share a name (this is
called <firstterm>overloading</>).
</para>
<para>
To update the definition of an existing function, use
<command>CREATE OR REPLACE FUNCTION</command>. It is not possible
to change the name or argument types of a function this way (if you
tried, you'd just be creating a new, distinct function). Also,
<command>CREATE OR REPLACE FUNCTION</command> will not let you
change the return type of an existing function. To do that, you
must drop and recreate the function.
</para>
<para>
If you drop and then recreate a function, the new function is not
the same entity as the old; you will break existing rules, views,
triggers, etc. that referred to the old function. Use
<command>CREATE OR REPLACE FUNCTION</command> to change a function
definition without breaking objects that refer to the function.
</para>
<para>
The user that creates the function becomes the owner of the function.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<title>Parameters</title>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of a function to create. If a schema name is included,
then the function is created in the
specified schema. Otherwise it is created in the current schema (the
one at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
The name of the new function must not match any existing function
with the same argument types in the same schema. However, functions of
different argument types may share a name (this is called
<firstterm>overloading</>).
The name of a function to create.
</para>
</listitem>
</varlistentry>
@ -67,20 +90,21 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<listitem>
<para>
The data type(s) of the function's arguments (optionally
schema-qualified), if any. The input types may be base, complex, or
domain types, or the same as the type of an existing column.
schema-qualified), if any. The argument types may be base, complex, or
domain types, or copy the type of an existing column.
</para>
<para>
The type of a column is referenced by writing <replaceable
The type of a column is referenced by writing
<literal><replaceable
class="parameter">tablename</replaceable>.<replaceable
class="parameter">columnname</replaceable><literal>%TYPE</literal>;
class="parameter">columnname</replaceable>%TYPE</literal>;
using this can sometimes help make a function independent from
changes to the definition of a table.
</para>
<para>
Depending on the implementation language it may also be allowed
to specify <quote>pseudo-types</> such as <type>cstring</>.
Pseudo-types indicate that the actual argument type is either
to specify <quote>pseudotypes</> such as <type>cstring</>.
Pseudotypes indicate that the actual argument type is either
incompletely specified, or outside the set of ordinary SQL data types.
</para>
</listitem>
@ -92,15 +116,15 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<listitem>
<para>
The return data type (optionally schema-qualified). The return type
may be specified as a base, complex, domain type
or the same as the type of an existing column. See the description
may be specified as a base, complex, or domain type,
or may copy the type of an existing column. See the description
under <literal>argtype</literal> above on how to reference the type
of an existing column.
</para>
<para>
Depending on the implementation language it may also be allowed
to specify <quote>pseudo-types</> such as <type>cstring</>.
The <literal>setof</literal>
to specify <quote>pseudotypes</> such as <type>cstring</>.
The <literal>SETOF</literal>
modifier indicates that the function will return a set of
items, rather than a single item.
</para>
@ -123,9 +147,9 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
</varlistentry>
<varlistentry>
<term>IMMUTABLE</term>
<term>STABLE</term>
<term>VOLATILE</term>
<term><literal>IMMUTABLE</literal></term>
<term><literal>STABLE</literal></term>
<term><literal>VOLATILE</literal></term>
<listitem>
<para>
@ -140,7 +164,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<literal>IMMUTABLE</literal> indicates that the function always
returns the same result when given the same argument values; that
is, it does not do database lookups or otherwise use information not
directly present in its parameter list. If this option is given,
directly present in its argument list. If this option is given,
any call of the function with all-constant arguments can be
immediately replaced with the function value.
</para>
@ -152,7 +176,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
result could change across SQL statements. This is the appropriate
selection for functions whose results depend on database lookups,
parameter variables (such as the current time zone), etc. Also note
that the <literal>CURRENT_TIMESTAMP</> family of functions qualify
that the <function>current_timestamp</> family of functions qualify
as stable, since their values do not change within a transaction.
</para>
@ -170,9 +194,9 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
</varlistentry>
<varlistentry>
<term>CALLED ON NULL INPUT</term>
<term>RETURNS NULL ON NULL INPUT</term>
<term>STRICT</term>
<term><literal>CALLED ON NULL INPUT</literal></term>
<term><literal>RETURNS NULL ON NULL INPUT</literal></term>
<term><literal>STRICT</literal></term>
<listitem>
<para>
@ -186,17 +210,17 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<para>
<literal>RETURNS NULL ON NULL INPUT</literal> or
<literal>STRICT</literal> indicates that the function always
returns NULL whenever any of its arguments are NULL. If this
returns null whenever any of its arguments are null. If this
parameter is specified, the function is not executed when there
are NULL arguments; instead a NULL result is assumed
are null arguments; instead a null result is assumed
automatically.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><optional>EXTERNAL</optional> SECURITY INVOKER</term>
<term><optional>EXTERNAL</optional> SECURITY DEFINER</term>
<term><literal><optional>EXTERNAL</optional> SECURITY INVOKER</literal></term>
<term><literal><optional>EXTERNAL</optional> SECURITY DEFINER</literal></term>
<listitem>
<para>
@ -209,7 +233,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<para>
The key word <literal>EXTERNAL</literal> is present for SQL
compatibility but is optional since, unlike in SQL, this feature
conformance but is optional since, unlike in SQL, this feature
does not only apply to external functions.
</para>
</listitem>
@ -222,25 +246,26 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<para>
A string defining the function; the meaning depends on the
language. It may be an internal function name, the path to an
object file, an SQL query, or text in a procedural language.
object file, an SQL command, or text in a procedural language.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">obj_file</replaceable>, <replaceable class="parameter">link_symbol</replaceable></term>
<term><literal><replaceable class="parameter">obj_file</replaceable>, <replaceable class="parameter">link_symbol</replaceable></literal></term>
<listitem>
<para>
This form of the <literal>AS</literal> clause is used for
dynamically linked C language functions when the function name
dynamically loadable C language functions when the function name
in the C language source code is not the same as the name of
the SQL function. The string <replaceable
class="parameter">obj_file</replaceable> is the name of the
file containing the dynamically loadable object, and
<replaceable class="parameter">link_symbol</replaceable> is the
object's link symbol, that is, the name of the function in the C
language source code.
function's link symbol, that is, the name of the function in the C
language source code. If the link symbol is omitted, it is assumed
to be the same as the name of the SQL function being defined.
</para>
</listitem>
</varlistentry>
@ -285,48 +310,47 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE FUNCTION</computeroutput></term>
<listitem>
<para>
Message returned if the function was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="sql-createfunction-notes">
<title>Notes</title>
<para>
Refer to <xref linkend="xfunc"> for further information on writing
external functions.
functions.
</para>
<para>
The full <acronym>SQL</acronym> type syntax is allowed for
input arguments and return value. However, some details of the
type specification (e.g., the precision field for
<type>numeric</type> types) are the responsibility of the
type <type>numeric</type>) are the responsibility of the
underlying function implementation and are silently swallowed
(i.e., not recognized or
enforced) by the <command>CREATE FUNCTION</command> command.
</para>
<para>
<productname>PostgreSQL</productname> allows function <firstterm>overloading</firstterm>;
that is, the same name can be used for several different functions
so long as they have distinct argument types. This facility must
be used with caution for internal and C-language functions, however.
</para>
<para>
Two <literal>internal</literal>
functions cannot have the same C name without causing
errors at link time. To get around that, give them different C names
(for example, use the argument types as part of the C names), then
specify those names in the AS clause of <command>CREATE FUNCTION</command>.
If the AS clause is left empty, then <command>CREATE FUNCTION</command>
assumes the C name of the function is the same as the SQL name.
</para>
<para>
Similarly, when overloading SQL function names with multiple C-language
functions, give
each C-language instance of the function a distinct name, then use
the alternative form of the <command>AS</command> clause in the
<command>CREATE FUNCTION</command> syntax to select the appropriate
C-language implementation of each overloaded SQL function.
<productname>PostgreSQL</productname> allows function
<firstterm>overloading</firstterm>; that is, the same name can be
used for several different functions so long as they have distinct
argument types. However, the C names of all functions must be
different, so you must give overloaded C functions different C
names (for example, use the argument types as part of the C
names).
</para>
<para>
@ -341,116 +365,26 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
to remove user-defined functions.
</para>
<para>
To update the definition of an existing function, use
<command>CREATE OR REPLACE FUNCTION</command>. Note that it is
not possible to change the name or argument types of a function
this way (if you tried, you'd just be creating a new, distinct
function). Also, <command>CREATE OR REPLACE FUNCTION</command>
will not let you change the return type of an existing function.
To do that, you must drop and re-create the function.
</para>
<para>
If you drop and then re-create a function, the new function is not
the same entity as the old; you will break existing rules, views,
triggers, etc that referred to the old function. Use
<command>CREATE OR REPLACE FUNCTION</command> to change a function
definition without breaking objects that refer to the function.
</para>
<para>
To be able to define a function, the user must have the
<literal>USAGE</literal> privilege on the language.
</para>
<para>
By default, only the owner (creator) of the function has the right
to execute it. Other users must be granted the
<literal>EXECUTE</literal> privilege on the function to be able to
use it.
</para>
</refsect1>
<refsect1 id="sql-createfunction-examples">
<title>Examples</title>
<para>
To create a simple SQL function:
Here is a trivial example to help you get startet. For more
information and examples, see <xref linkend="xfunc">.
<programlisting>
CREATE FUNCTION one() RETURNS integer
AS 'SELECT 1 AS RESULT;'
LANGUAGE SQL;
SELECT one() AS answer;
<computeroutput>
answer
--------
1
</computeroutput>
CREATE FUNCTION add(integer, integer) RETURNS integer
AS 'select $1 + $2;'
LANGUAGE SQL
IMMUTABLE
RETURNS NULL ON NULL INPUT;
</programlisting>
</para>
<para>
The next example creates a C function by calling a routine from a
user-created shared library named <filename>funcs.so</> (the extension
may vary across platforms). The shared library file is sought in the
server's dynamic library search path. This particular routine calculates
a check digit and returns true if the check digit in the function
parameters is correct. It is intended for use in a CHECK
constraint.
<programlisting>
CREATE FUNCTION ean_checkdigit(char, char) RETURNS boolean
AS 'funcs' 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))
);
</programlisting>
</para>
<para>
The next example creates a function that does type conversion from the
user-defined type complex to the built-in type point. The
function is implemented by a dynamically loaded object that was
compiled from C source (we illustrate the now-deprecated alternative
of specifying the absolute file name to the shared object file).
For <productname>PostgreSQL</productname> to
find a type conversion function automatically, the SQL function has
to have the same name as the return type, and so overloading is
unavoidable. The function name is overloaded by using the second
form of the <command>AS</command> clause in the SQL definition:
<programlisting>
CREATE FUNCTION point(complex) RETURNS point
AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point'
LANGUAGE C STRICT;
</programlisting>
The C declaration of the function could be:
<programlisting>
Point * complex_to_point (Complex *z)
{
Point *p;
p = (Point *) palloc(sizeof(Point));
p->x = z->x;
p->y = z->y;
return p;
}
</programlisting>
Note that the function is marked <quote>strict</>; this allows us
to skip checking for NULL input in the function body.
</para>
</refsect1>

117
doc/src/sgml/ref/create_group.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_group.sgml,v 1.10 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_group.sgml,v 1.11 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,35 +8,41 @@ PostgreSQL documentation
<refentrytitle id="sql-creategroup-title">CREATE GROUP</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE GROUP
</refname>
<refpurpose>
define a new user group
</refpurpose>
<refname>CREATE GROUP</refname>
<refpurpose>define a new user group</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2000-01-14</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
CREATE GROUP <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
where <replaceable class="PARAMETER">option</replaceable> can be:
SYSID <replaceable class="PARAMETER">gid</replaceable>
| USER <replaceable class="PARAMETER">username</replaceable> [, ...]
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>CREATE GROUP</command> will create a new group in the
database cluster. You must be a database
superuser to use this command.
</para>
<para>
Use <xref linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title">
to change a group's membership, and <xref linkend="SQL-DROPGROUP"
endterm="SQL-DROPGROUP-title"> to remove a group.
</para>
</refsect1>
<refsect2 id="R2-SQL-CREATEGROUP-1">
<refsect2info>
<date>2000-01-14</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
@ -53,11 +59,11 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<listitem>
<para>
The <literal>SYSID</literal> clause can be used to choose
the <productname>PostgreSQL</productname> group id of the new
the <productname>PostgreSQL</productname> group ID of the new
group. It is not necessary to do so, however.
</para>
<para>
If this is not specified, the highest assigned group id plus one,
If this is not specified, the highest assigned group ID plus one,
starting at 1, will be used as default.
</para>
</listitem>
@ -73,54 +79,26 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsect1>
<refsect2 id="R2-SQL-CREATEGROUP-2">
<refsect2info>
<date>2000-01-14</date>
</refsect2info>
<title>
Outputs
</title>
<refsect1>
<title>Diagnostics</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE GROUP</computeroutput></term>
<listitem>
<para>
Message returned if the command completes successfully.
Message returned if the group was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
</refsect1>
<refsect1>
<title>Examples</title>
<refsect1 id="R1-SQL-CREATEGROUP-1">
<refsect1info>
<date>2000-01-14</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>CREATE GROUP</command> will create a new group in the
database installation. You must be a database
superuser to use this command.
</para>
<para>
Use <xref linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title">
to change a group's membership, and <xref linkend="SQL-DROPGROUP"
endterm="SQL-DROPGROUP-title"> to remove a group.
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATEGROUP-2">
<title>
Usage
</title>
<para>
Create an empty group:
<programlisting>
@ -136,24 +114,13 @@ CREATE GROUP marketing WITH USER jonathan, david;
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATEGROUP-3">
<title>
Compatibility
</title>
<refsect1>
<title>Compatibility</title>
<refsect2 id="R2-SQL-CREATEGROUP-4">
<refsect2info>
<date>2000-01-14</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>CREATE GROUP</command> statement in SQL92.
Roles are similar in concept to groups.
</para>
</refsect2>
<para>
There is no <command>CREATE GROUP</command> statement in the SQL
standard. Roles are similar in concept to groups.
</para>
</refsect1>
</refentry>

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

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.37 2002/09/21 18:32:54 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.38 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,39 +8,101 @@ PostgreSQL documentation
<refentrytitle id="sql-createindex-title">CREATE INDEX</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE INDEX
</refname>
<refpurpose>
define a new index
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2001-07-15</date>
</refsynopsisdivinfo>
<synopsis>
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
[ USING <replaceable class="parameter">acc_method</replaceable> ] ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable> ] [, ...] )
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
[ USING <replaceable class="parameter">acc_method</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) [ <replaceable class="parameter">ops_name</replaceable> ] )
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
</synopsis>
<refsect2 id="R2-SQL-CREATEINDEX-1">
<refsect2info>
<date>1998-09-09</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<refnamediv>
<refname>CREATE INDEX</refname>
<refpurpose>define a new index</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
[ USING <replaceable class="parameter">method</replaceable> ] ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable> ] [, ...] )
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
[ USING <replaceable class="parameter">method</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) [ <replaceable class="parameter">ops_name</replaceable> ] )
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>CREATE INDEX</command> constructs an index <replaceable
class="parameter">index_name</replaceable> on the specified table.
Indexes are primarily used to enhance database performance. But
inappropriate use will result in slower performance.
</para>
<para>
In the first syntax shown above, the key field(s) for the
index are specified as column names.
Multiple fields can be specified if the index method supports
multicolumn indexes.
</para>
<para>
In the second syntax shown above, an index is defined on the result
of a user-specified function <replaceable
class="parameter">func_name</replaceable> applied to one or more
columns of a single table. These <firstterm>functional
indexes</firstterm> can be used to obtain fast access to data based
on operators that would normally require some transformation to apply
them to the base data. For example, a functional index on
<literal>upper(col)</> would allow the clause
<literal>WHERE upper(col) = 'JIM'</> to use an index.
</para>
<para>
<application>PostgreSQL</application> provides the index methods
B-tree, R-tree, hash, and GiST. The B-tree index method is an
implementation of Lehman-Yao high-concurrency B-trees. The R-tree
index method implements standard R-trees using Guttman's quadratic
split algorithm. The hash index method is an implementation of
Litwin's linear hashing. Users can also define their own index
methods, but that is fairly complicated.
</para>
<para>
When the <literal>WHERE</literal> clause is present, a
<firstterm>partial index</firstterm> is created.
A partial index is an index that contains entries for only a portion of
a table, usually a portion that is somehow more interesting than the
rest of the table. For example, if you have a table that contains both
billed and unbilled orders where the unbilled orders take up a small
fraction of the total table and yet that is an often used section, you
can improve performance by creating an index on just that portion.
Another possible application is to use <literal>WHERE</literal> with
<literal>UNIQUE</literal> to enforce uniqueness over a subset of a
table.
</para>
<para>
The expression used in the <literal>WHERE</literal> clause may refer
only to columns of the underlying table (but it can use all columns,
not only the one(s) being indexed). Presently, subqueries and
aggregate expressions are also forbidden in <literal>WHERE</literal>.
</para>
<para>
All functions and operators used in an index definition must be
<quote>immutable</>, that is, their results must depend only on
their arguments and never on any outside influence (such as
the contents of another table or the current time). This restriction
ensures that the behavior of the index is well-defined. To use a
user-defined function in an index, remember to mark the function immutable
when you create it.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>UNIQUE</term>
<term><literal>UNIQUE</literal></term>
<listitem>
<para>
Causes the system to check for
@ -73,52 +135,13 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">acc_method</replaceable></term>
<term><replaceable class="parameter">method</replaceable></term>
<listitem>
<para>
The name of the access method to be used for the index. The
default access method is <literal>BTREE</literal>.
<application>PostgreSQL</application> provides four access
methods for indexes:
<variablelist>
<varlistentry>
<term><literal>BTREE</></term>
<listitem>
<para>
an implementation of Lehman-Yao
high-concurrency B-trees.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>RTREE</></term>
<listitem>
<para>implements standard R-trees using Guttman's
quadratic split algorithm.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>HASH</></term>
<listitem>
<para>
an implementation of Litwin's linear hashing.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>GIST</></term>
<listitem>
<para>
Generalized Index Search Trees.
</para>
</listitem>
</varlistentry>
</variablelist>
The name of the method to be used for the index. Choices are
<literal>btree</literal>, <literal>hash</literal>,
<literal>rtree</literal>, and <literal>gist</literal>. The
default method is <literal>btree</literal>.
</para>
</listitem>
</varlistentry>
@ -159,249 +182,73 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsect1>
<refsect2 id="R2-SQL-CREATEINDEX-2">
<refsect2info>
<date>1998-09-09</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE INDEX
</computeroutput></term>
<listitem>
<para>
The message returned if the index is successfully created.
</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE INDEX</computeroutput></term>
<listitem>
<para>
Message returned if the index was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<varlistentry>
<term><computeroutput>
ERROR: Cannot create index: 'index_name' already exists.
</computeroutput></term>
<listitem>
<para>
This error occurs if it is impossible to create the index.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1>
<title>Notes</title>
<refsect1 id="R1-SQL-CREATEINDEX-1">
<refsect1info>
<date>1998-09-09</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>CREATE INDEX</command> constructs an index
<replaceable class="parameter">index_name</replaceable>
on the specified <replaceable class="parameter">table</replaceable>.
<tip>
<para>
Indexes are primarily used to enhance database performance.
But inappropriate use will result in slower performance.
</para>
</tip>
See <xref linkend="indexes"> for information about when indexes can
be used, when they are not used, and in which particular situations
can be useful.
</para>
<para>
In the first syntax shown above, the key field(s) for the
index are specified as column names.
Multiple fields can be specified if the index access method supports
multicolumn indexes.
Currently, only the B-tree and GiST index methods support
multicolumn indexes. Up to 32 fields may be specified by default.
(This limit can be altered when building
<application>PostgreSQL</application>.) Only B-tree currently
supports unique indexes.
</para>
<para>
In the second syntax shown above, an index is defined on the result
of a user-specified function <replaceable
class="parameter">func_name</replaceable> applied to one or more
columns of a single table. These <firstterm>functional
indexes</firstterm> can be used to obtain fast access to data based
on operators that would normally require some transformation to apply
them to the base data. For example, a functional index on
<literal>upper(col)</> would allow the clause
<literal>WHERE upper(col) = 'JIM'</> to use an index.
</para>
<para>
<application>PostgreSQL</application> provides B-tree, R-tree, hash,
and GiST access methods for indexes. The B-tree access method is an
implementation of Lehman-Yao high-concurrency B-trees. The R-tree
access method implements standard R-trees using Guttman's quadratic
split algorithm. The hash access method is an implementation of
Litwin's linear hashing. We mention the algorithms used solely to
indicate that all of these access methods are fully dynamic and do
not have to be optimized periodically (as is the case with, for
example, static hash access methods).
</para>
<para>
When the <command>WHERE</command> clause is present, a
<firstterm>partial index</firstterm> is created.
A partial index is an index that contains entries for only a portion of
a table, usually a portion that is somehow more interesting than the
rest of the table. For example, if you have a table that contains both
billed and unbilled orders where the unbilled orders take up a small
fraction of the total table and yet that is an often used section, you
can improve performance by creating an index on just that portion.
Another possible application is to use <command>WHERE</command> with
<command>UNIQUE</command> to enforce uniqueness over a subset of a
table.
</para>
<para>
The expression used in the <command>WHERE</command> clause may refer
only to columns of the underlying table (but it can use all columns,
not only the one(s) being indexed). Presently, subqueries and
aggregate expressions are also forbidden in <command>WHERE</command>.
</para>
<para>
All functions and operators used in an index definition must be
<firstterm>immutable</>, that is, their results must depend only on
their input arguments and never on any outside influence (such as
the contents of another table or the current time). This restriction
ensures that the behavior of the index is well-defined. To use a
user-defined function in an index, remember to mark the function immutable
when you create it.
</para>
<para>
Use <xref linkend="sql-dropindex" endterm="sql-dropindex-title">
to remove an index.
</para>
<refsect2 id="R2-SQL-CREATEINDEX-3">
<refsect2info>
<date>1998-09-09</date>
</refsect2info>
<title>
Notes
</title>
<para>
The <productname>PostgreSQL</productname>
query optimizer will consider using a B-tree index whenever
an indexed attribute is involved in a comparison using one of:
<simplelist type="inline">
<member>&lt;</member>
<member>&lt;=</member>
<member>=</member>
<member>&gt;=</member>
<member>&gt;</member>
</simplelist>
</para>
<para>
The <productname>PostgreSQL</productname>
query optimizer will consider using an R-tree index whenever
an indexed attribute is involved in a comparison using one of:
<simplelist type="inline">
<member>&lt;&lt;</member>
<member>&amp;&lt;</member>
<member>&amp;&gt;</member>
<member>&gt;&gt;</member>
<member>@</member>
<member>~=</member>
<member>&amp;&amp;</member>
</simplelist>
</para>
<para>
The <productname>PostgreSQL</productname>
query optimizer will consider using a hash index whenever
an indexed attribute is involved in a comparison using
the <literal>=</literal> operator.
</para>
<para>
Testing has shown PostgreSQL's hash indexes to be similar or slower
than B-tree indexes, and the index size and build time for hash
indexes is much worse. Hash indexes also suffer poor performance
under high concurrency. For these reasons, hash index use is
discouraged.
</para>
<para>
Currently, only the B-tree and gist access methods support multicolumn
indexes. Up to 32 keys may be specified by default (this limit
can be altered when building
<application>PostgreSQL</application>). Only B-tree currently supports
unique indexes.
</para>
<para>
An <firstterm>operator class</firstterm> can be specified for each
column of an index. The operator class identifies the operators to be
used by the index for that column. For example, a B-tree index on
four-byte integers would use the <literal>int4_ops</literal> class;
this operator class includes comparison functions for four-byte
integers. In practice the default operator class for the field's data
integers. In practice the default operator class for the column's data
type is usually sufficient. The main point of having operator classes
is that for some data types, there could be more than one meaningful
ordering. For example, we might want to sort a complex-number data
type either by absolute value or by real part. We could do this by
defining two operator classes for the data type and then selecting
the proper class when making an index. There are also some operator
classes with special purposes:
<itemizedlist>
<listitem>
<para>
The operator classes <literal>box_ops</literal> and
<literal>bigbox_ops</literal> both support R-tree indexes on the
<literal>box</literal> data type.
The difference between them is that <literal>bigbox_ops</literal>
scales box coordinates down, to avoid floating-point exceptions from
doing multiplication, addition, and subtraction on very large
floating-point coordinates. (Note: this was true some time ago,
but currently the two operator classes both use floating point
and are effectively identical.)
</para>
</listitem>
</itemizedlist>
the proper class when making an index. More information about
operator classes is in <xref linkend="indexes-opclass"> and in <xref
linkend="xindex">.
</para>
<para>
The following query shows all defined operator classes:
<programlisting>
SELECT am.amname AS acc_method,
opc.opcname AS ops_name
FROM pg_am am, pg_opclass opc
WHERE opc.opcamid = am.oid
ORDER BY acc_method, ops_name;
</programlisting>
</para>
</refsect2>
<para>
Use <xref linkend="sql-dropindex" endterm="sql-dropindex-title">
to remove an index.
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATEINDEX-2">
<title>
Usage
</title>
<para>To create a B-tree index on the field <literal>title</literal>
in the table <literal>films</literal>:
<refsect1>
<title>Examples</title>
<para>
To create a B-tree index on the column <literal>title</literal> in
the table <literal>films</literal>:
<programlisting>
CREATE UNIQUE INDEX title_idx ON films (title);
</programlisting>
</para>
<programlisting>
CREATE UNIQUE INDEX title_idx
ON films (title);
</programlisting>
<!--
<comment>
@ -422,25 +269,14 @@ SELECT * FROM points
</refsect1>
<refsect1 id="R1-SQL-CREATEINDEX-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEINDEX-4">
<refsect2info>
<date>1998-09-09</date>
</refsect2info>
<title>
SQL92
</title>
<para>
CREATE INDEX is a <productname>PostgreSQL</productname> language extension.
</para>
<para>
There is no <command>CREATE INDEX</command> command in SQL92.
</para>
</refsect2>
<refsect1>
<title>Compatibility</title>
<para>
<command>CREATE INDEX</command> is a
<productname>PostgreSQL</productname> language extension. There
are no provisions for indexes in the SQL standard.
</para>
</refsect1>
</refentry>

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

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.31 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.32 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -60,7 +60,7 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langna
<literal>TRUSTED</literal> specifies that the call handler for
the language is safe, that is, it does not offer an
unprivileged user any functionality to bypass access
restrictions. If this keyword is omitted when registering the
restrictions. If this key word is omitted when registering the
language, only users with the
<productname>PostgreSQL</productname> superuser privilege can
use this language to create new functions.
@ -84,8 +84,8 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langna
<listitem>
<para>
The name of the new procedural language. The language name is
case insensitive. A procedural language cannot override one of
the built-in languages of <productname>PostgreSQL</productname>.
case insensitive. The name must be unique among the languages
in the database.
</para>
<para>
@ -146,45 +146,16 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langna
<refsect1 id="sql-createlanguage-diagnostics">
<title>Diagnostics</title>
<msgset>
<msgentry>
<msg>
<msgmain>
<msgtext>
<screen>
CREATE LANGUAGE
</screen>
</msgtext>
</msgmain>
</msg>
<msgexplan>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE LANGUAGE</computeroutput></term>
<listitem>
<para>
This message is returned if the language is successfully
created.
Message returned if the language was successfully created.
</para>
</msgexplan>
</msgentry>
<msgentry>
<msg>
<msgmain>
<msgtext>
<screen>
ERROR: PL handler function <replaceable class="parameter">funcname</replaceable>() doesn't exist
</screen>
</msgtext>
</msgmain>
</msg>
<msgexplan>
<para>
This error is returned if the function <replaceable
class="parameter">funcname</replaceable>() is not found.
</para>
</msgexplan>
</msgentry>
</msgset>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="sql-createlanguage-notes">
@ -194,7 +165,7 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
This command normally should not be executed directly by users.
For the procedural languages supplied in the
<productname>PostgreSQL</productname> distribution, the <xref
linkend="app-createlang"> script should be used, which will also
linkend="app-createlang"> program should be used, which will also
install the correct call handler. (<command>createlang</command>
will call <command>CREATE LANGUAGE</command> internally.)
</para>
@ -205,7 +176,7 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
type <type>opaque</>, rather than <type>language_handler</>.
To support loading
of old dump files, <command>CREATE LANGUAGE</> will accept a function
declared as returning <type>opaque</>, but it will issue a NOTICE and
declared as returning <type>opaque</>, but it will issue a notice and
change the function's declared return type to <type>language_handler</>.
</para>
@ -216,35 +187,19 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
<para>
Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref
linkend="app-droplang"> script, to drop procedural languages.
linkend="app-droplang"> program, to drop procedural languages.
</para>
<para>
The system catalog <classname>pg_language</classname> records
information about the currently installed procedural languages.
<screen>
Table "pg_language"
Attribute | Type | Modifier
---------------+-----------+----------
lanname | name |
lanispl | boolean |
lanpltrusted | boolean |
lanplcallfoid | oid |
lanvalidator | oid |
lanacl | aclitem[] |
lanname | lanispl | lanpltrusted | lanplcallfoid | lanvalidator | lanacl
-------------+---------+--------------+---------------+--------------+--------
internal | f | f | 0 | 2246 |
c | f | f | 0 | 2247 |
sql | f | t | 0 | 2248 | {=U}
</screen>
The system catalog <classname>pg_language</classname> (see <xref
linkend="catalog-pg-language">) records information about the
currently installed languages. Also <command>createlang</command>
has an option to list the installed languages.
</para>
<para>
At present, with the exception of the permissions, the definition
of a procedural language cannot be changed once it has been created.
The definition of a procedural language cannot be changed once it
has been created, with the exception of the privileges.
</para>
<para>
@ -262,7 +217,7 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
The following two commands executed in sequence will register a new
procedural language and the associated call handler.
<programlisting>
CREATE FUNCTION plsample_call_handler () RETURNS language_handler
CREATE FUNCTION plsample_call_handler() RETURNS language_handler
AS '$libdir/plsample'
LANGUAGE C;
CREATE LANGUAGE plsample
@ -280,15 +235,6 @@ CREATE LANGUAGE plsample
</para>
</refsect1>
<refsect1>
<title>History</title>
<para>
The <command>CREATE LANGUAGE</command> command first appeared in
<productname>PostgreSQL</productname> 6.3.
</para>
</refsect1>
<refsect1>
<title>See Also</title>

426
doc/src/sgml/ref/create_opclass.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_opclass.sgml,v 1.6 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_opclass.sgml,v 1.7 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,206 +8,44 @@ PostgreSQL documentation
<refentrytitle id="sql-createopclass-title">CREATE OPERATOR CLASS</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE OPERATOR CLASS
</refname>
<refpurpose>
define a new operator class for indexes
</refpurpose>
</refnamediv>
<refname>CREATE OPERATOR CLASS</refname>
<refpurpose>define a new operator class for indexes</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2002-07-28</date>
</refsynopsisdivinfo>
<synopsis>
CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAULT ] FOR TYPE <replaceable class="parameter">data_type</replaceable> USING <replaceable class="parameter">access_method</replaceable> AS
{ OPERATOR <replaceable class="parameter">strategy_number</replaceable> <replaceable class="parameter">operator_id</replaceable> [ ( <replaceable class="parameter">type</replaceable>, <replaceable class="parameter">type</replaceable> ) ] [ RECHECK ]
| FUNCTION <replaceable class="parameter">support_number</replaceable> <replaceable class="parameter">func_name</replaceable> ( <replaceable class="parameter">parameter_types</replaceable> )
<synopsis>
CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAULT ] FOR TYPE <replaceable class="parameter">data_type</replaceable> USING <replaceable class="parameter">index_method</replaceable> AS
{ OPERATOR <replaceable class="parameter">strategy_number</replaceable> <replaceable class="parameter">operator_name</replaceable> [ ( <replaceable class="parameter">op_type</replaceable>, <replaceable class="parameter">op_type</replaceable> ) ] [ RECHECK ]
| FUNCTION <replaceable class="parameter">support_number</replaceable> <replaceable class="parameter">func_name</replaceable> ( <replaceable class="parameter">argument_types</replaceable> )
| STORAGE <replaceable class="parameter">storage_type</replaceable>
} [, ... ]
</synopsis>
<refsect2 id="R2-SQL-CREATEOPCLASS-1">
<refsect2info>
<date>2002-07-28</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of the operator class to be created.
The name may be schema-qualified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>DEFAULT</></term>
<listitem>
<para>
If present, the operator class will become the default index
operator class for its data type. At most one operator class
can be the default for a specific data type and access method.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">data_type</replaceable></term>
<listitem>
<para>
The column data type that this operator class is for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">access_method</replaceable></term>
<listitem>
<para>
The name of the index access method this operator class is for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">strategy_number</replaceable></term>
<listitem>
<para>
The index access method's strategy number for an operator associated
with the operator class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">operator_id</replaceable></term>
<listitem>
<para>
The identifier (optionally schema-qualified) of an operator associated
with the operator class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">type</replaceable></term>
<listitem>
<para>
The input data type(s) of an operator, or <literal>NONE</> to
signify a left-unary or right-unary operator. The input data types
may be omitted in the normal case where they are the same as the
operator class's data type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>RECHECK</></term>
<listitem>
<para>
If present, the index is <quote>lossy</> for this operator,
and so the tuples retrieved using the index must be rechecked
to verify that they actually satisfy the qualification clause
involving this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">support_number</replaceable></term>
<listitem>
<para>
The index access method's support procedure number for a function
associated with the operator class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">func_name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of a function that is
an index access method support procedure for the operator class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">parameter_types</replaceable></term>
<listitem>
<para>
The parameter data type(s) of the function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">storage_type</replaceable></term>
<listitem>
<para>
The data type actually stored in the index. Normally this is the
same as the column data type, but some index access methods (only
GIST at this writing) allow it to be different. The
<literal>STORAGE</> clause must be omitted unless the index access
method allows a different type to be used.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATEOPCLASS-2">
<refsect2info>
<date>2002-07-28</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE OPERATOR CLASS
</computeroutput></term>
<listitem>
<para>
Message returned if the operator class is successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATEOPCLASS-1">
<refsect1info>
<date>2002-07-28</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>CREATE OPERATOR CLASS</command> defines a new operator class,
<replaceable class="parameter">name</replaceable>.
</para>
<refsect1>
<title>Description</title>
<para>
<command>CREATE OPERATOR CLASS</command> creates a new operator class.
An operator class defines how a particular data type can be used with
an index. The operator class specifies that certain operators will fill
particular roles or <quote>strategies</> for this data type and this
access method. The operator class also specifies the support procedures to
index method. The operator class also specifies the support procedures to
be used by
the index access method when the operator class is selected for an
the index method when the operator class is selected for an
index column. All the operators and functions used by an operator
class must be defined before the operator class is created.
</para>
<para>
If a schema name is given then the operator class is created in the
specified schema. Otherwise it is created in the current schema (the one
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
specified schema. Otherwise it is created in the current schema.
Two operator classes in the same schema can have the same name only if they
are for different index access methods.
are for different index methods.
</para>
<para>
The user who defines an operator class becomes its owner. Presently,
the creating user must be a superuser. (This restriction is made because
@ -217,41 +55,187 @@ CREATE OPERATOR CLASS
<para>
<command>CREATE OPERATOR CLASS</command> does not presently check
whether the class definition includes all the operators and functions
required by the index access method. It is the user's
whether the operator class definition includes all the operators and functions
required by the index method. It is the user's
responsibility to define a valid operator class.
</para>
<para>
Refer to <xref linkend="xindex"> for further information.
</para>
<refsect2 id="R2-SQL-CREATEOPCLASS-3">
<refsect2info>
<date>2002-07-28</date>
</refsect2info>
<title>
Notes
</title>
<para>
Refer to
<xref linkend="sql-dropopclass" endterm="sql-dropopclass-title">
to delete user-defined operator classes from a database.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-CREATEOPCLASS-2">
<title>
Usage
</title>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of the operator class to be created. The name may be
schema-qualified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>DEFAULT</></term>
<listitem>
<para>
If present, the operator class will become the default
operator class for its data type. At most one operator class
can be the default for a specific data type and index method.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">data_type</replaceable></term>
<listitem>
<para>
The column data type that this operator class is for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">index_method</replaceable></term>
<listitem>
<para>
The name of the index method this operator class is for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">strategy_number</replaceable></term>
<listitem>
<para>
The index method's strategy number for an operator
associated with the operator class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">operator_name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of an operator associated
with the operator class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">op_type</replaceable></term>
<listitem>
<para>
The operand data type(s) of an operator, or <literal>NONE</> to
signify a left-unary or right-unary operator. The operand data
types may be omitted in the normal case where they are the same
as the operator class's data type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>RECHECK</></term>
<listitem>
<para>
If present, the index is <quote>lossy</> for this operator, and
so the rows retrieved using the index must be rechecked to
verify that they actually satisfy the qualification clause
involving this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">support_number</replaceable></term>
<listitem>
<para>
The index method's support procedure number for a
function associated with the operator class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">func_name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of a function that is an
index method support procedure for the operator class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">argument_types</replaceable></term>
<listitem>
<para>
The parameter data type(s) of the function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">storage_type</replaceable></term>
<listitem>
<para>
The data type actually stored in the index. Normally this is
the same as the column data type, but some index methods
(only GiST at this writing) allow it to be different. The
<literal>STORAGE</> clause must be omitted unless the index
method allows a different type to be used.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The <literal>OPERATOR</>, <literal>FUNCTION</>, and <literal>STORAGE</>
clauses may appear in any order.
</para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE OPERATOR CLASS</computeroutput></term>
<listitem>
<para>
Message returned if the operator class was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
Refer to
<xref linkend="sql-dropopclass" endterm="sql-dropopclass-title">
to delete user-defined operator classes from a database.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
The following example command defines a GiST index operator class
for data type <literal>_int4</> (array of int4). See
for the data type <literal>_int4</> (array of <type>int4</type>). See
<filename>contrib/intarray/</> for the complete example.
</para>
<programlisting>
<programlisting>
CREATE OPERATOR CLASS gist__int_ops
DEFAULT FOR TYPE _int4 USING gist AS
OPERATOR 3 &&,
@ -266,34 +250,18 @@ CREATE OPERATOR CLASS gist__int_ops
FUNCTION 5 g_int_penalty (internal, internal, internal),
FUNCTION 6 g_int_picksplit (internal, internal),
FUNCTION 7 g_int_same (_int4, _int4, internal);
</programlisting>
<para>
The <literal>OPERATOR</>, <literal>FUNCTION</>, and <literal>STORAGE</>
clauses may appear in any order.
</para>
</programlisting>
</refsect1>
<refsect1 id="R1-SQL-CREATEOPCLASS-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEOPCLASS-4">
<refsect2info>
<date>2002-07-28</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
<command>CREATE OPERATOR CLASS</command>
is a <productname>PostgreSQL</productname> extension.
There is no <command>CREATE OPERATOR CLASS</command>
statement in <acronym>SQL92</acronym>.
</para>
</refsect2>
<para>
<command>CREATE OPERATOR CLASS</command> is a
<productname>PostgreSQL</productname> extension. There is no
<command>CREATE OPERATOR CLASS</command> statement in the SQL
standard.
</para>
</refsect1>
</refentry>

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

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.34 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.35 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,218 +8,43 @@ PostgreSQL documentation
<refentrytitle id="sql-createoperator-title">CREATE OPERATOR</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE OPERATOR
</refname>
<refpurpose>
define a new operator
</refpurpose>
</refnamediv>
<refname>CREATE OPERATOR</refname>
<refpurpose>define a new operator</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2000-03-25</date>
</refsynopsisdivinfo>
<synopsis>
CREATE OPERATOR <replaceable>name</replaceable> ( PROCEDURE = <replaceable class="parameter">func_name</replaceable>
[, LEFTARG = <replaceable class="parameter">lefttype</replaceable>
] [, RIGHTARG = <replaceable class="parameter">righttype</replaceable> ]
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
[, HASHES ] [, MERGES ]
[, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ] [, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ]
[, LTCMP = <replaceable class="parameter">less_than_op</replaceable> ] [, GTCMP = <replaceable class="parameter">greater_than_op</replaceable> ] )
</synopsis>
<refsect2 id="R2-SQL-CREATEOPERATOR-1">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The operator to be defined. See below for allowable characters.
The name may be schema-qualified, for example
<literal>CREATE OPERATOR myschema.+ (...)</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">func_name</replaceable></term>
<listitem>
<para>
The function used to implement this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">lefttype</replaceable></term>
<listitem>
<para>
The type of the left-hand argument of the operator, if any.
This option would be omitted for a left-unary operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">righttype</replaceable></term>
<listitem>
<para>
The type of the right-hand argument of the operator, if any.
This option would be omitted for a right-unary operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">com_op</replaceable></term>
<listitem>
<para>
The commutator of this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">neg_op</replaceable></term>
<listitem>
<para>
The negator of this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">res_proc</replaceable></term>
<listitem>
<para>
The restriction selectivity estimator function for this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">join_proc</replaceable></term>
<listitem>
<para>
The join selectivity estimator function for this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>HASHES</term>
<listitem>
<para>
Indicates this operator can support a hash join.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>MERGES</term>
<listitem>
<para>
Indicates this operator can support a merge join.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">left_sort_op</replaceable></term>
<listitem>
<para>
If this operator can support a merge join, the less-than
operator that sorts the left-hand data type of this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">right_sort_op</replaceable></term>
<listitem>
<para>
If this operator can support a merge join, the less-than
operator that sorts the right-hand data type of this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">less_than_op</replaceable></term>
<listitem>
<para>
If this operator can support a merge join, the less-than
operator that compares the input data types of this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">greater_than_op</replaceable></term>
<listitem>
<para>
If this operator can support a merge join, the greater-than
operator that compares the input data types of this operator.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATEOPERATOR-2">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE OPERATOR
</computeroutput></term>
<listitem>
<para>
Message returned if the operator is successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<synopsis>
CREATE OPERATOR <replaceable>name</replaceable> (
PROCEDURE = <replaceable class="parameter">func_name</replaceable>
[, LEFTARG = <replaceable class="parameter">lefttype</replaceable> ] [, RIGHTARG = <replaceable class="parameter">righttype</replaceable> ]
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
[, HASHES ] [, MERGES ]
[, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ] [, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ]
[, LTCMP = <replaceable class="parameter">less_than_op</replaceable> ] [, GTCMP = <replaceable class="parameter">greater_than_op</replaceable> ]
)
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATEOPERATOR-1">
<refsect1info>
<date>2000-03-25</date>
</refsect1info>
<title>
Description
</title>
<refsect1>
<title>Description</title>
<para>
<command>CREATE OPERATOR</command> defines a new operator,
<replaceable class="parameter">name</replaceable>.
The user who defines an operator becomes its owner.
</para>
<para>
If a schema name is given then the operator is created in the
specified schema. Otherwise it is created in the current schema (the one
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
</para>
<para>
Two operators in the same schema can have the same name if they operate on
different data types. This is called <firstterm>overloading</>. The
system will attempt to pick the intended operator based on the actual
input data types when there is ambiguity.
<command>CREATE OPERATOR</command> defines a new operator,
<replaceable class="parameter">name</replaceable>. The user who
defines an operator becomes its owner. If a schema name is given
then the operator is created in the specified schema. Otherwise it
is created in the current schema.
</para>
<para>
The operator <replaceable class="parameter">name</replaceable>
is a sequence of up to <symbol>NAMEDATALEN</>-1 (63 by default) characters
from the following list:
<literallayout>
The operator name is a sequence of up to <symbol>NAMEDATALEN</>-1
(63 by default) characters from the following list:
<literallayout>
+ - * / &lt; &gt; = ~ ! @ # % ^ &amp; | ` ? $
</literallayout>
</literallayout>
There are a few restrictions on your choice of name:
<itemizedlist>
@ -240,263 +65,258 @@ CREATE OPERATOR
A multicharacter operator name cannot end in <literal>+</literal> or
<literal>-</literal>,
unless the name also contains at least one of these characters:
<literallayout>
<literallayout>
~ ! @ # % ^ &amp; | ` ? $
</literallayout>
</literallayout>
For example, <literal>@-</literal> is an allowed operator name,
but <literal>*-</literal> is not.
This restriction allows <productname>PostgreSQL</productname> to
parse SQL-compliant queries without requiring spaces between tokens.
parse SQL-compliant commands without requiring spaces between tokens.
</para>
</listitem>
</itemizedlist>
</para>
<note>
<para>
When working with non-SQL-standard operator names, you will usually
need to separate adjacent operators with spaces to avoid ambiguity.
For example, if you have defined a left-unary operator named <literal>@</literal>,
you cannot write <literal>X*@Y</literal>; you must write
<literal>X* @Y</literal> to ensure that
<productname>PostgreSQL</productname> reads it as two operator names
not one.
</para>
</note>
</para>
<para>
The operator <literal>!=</literal> is mapped to <literal>&lt;&gt;</literal> on input, so these two names
are always equivalent.
The operator <literal>!=</literal> is mapped to
<literal>&lt;&gt;</literal> on input, so these two names are always
equivalent.
</para>
<para>
At least one of <literal>LEFTARG</> and <literal>RIGHTARG</> must be defined. For
binary operators, both should be defined. For right unary
operators, only <literal>LEFTARG</> should be defined, while for left
binary operators, both must be defined. For right unary
operators, only <literal>LEFTARG</> should be defined, while for left
unary operators only <literal>RIGHTARG</> should be defined.
</para>
<para>
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) of the indicated types.
</para>
<para>
The commutator operator should be identified if one exists,
so that <productname>PostgreSQL</productname> can
reverse the order of the operands if it wishes.
For example, the operator area-less-than, &lt;&lt;&lt;,
would probably have a commutator
operator, area-greater-than, &gt;&gt;&gt;.
Hence, the query optimizer could freely convert:
<programlisting>
box '((0,0), (1,1))' &gt;&gt;&gt; MYBOXES.description
</programlisting>
<para>
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) of the indicated types.
</para>
to
<para>
The other clauses specify optional operator optimization clauses.
Their meaning is detailed in <xref linkend="xoper">.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of the operator to be defined. See above for allowable
characters. The name may be schema-qualified, for example
<literal>CREATE OPERATOR myschema.+ (...)</>. If not, then
the operator is created in the current schema. Two operators
in the same schema can have the same name if they operate on
different data types. This is called
<firstterm>overloading</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">func_name</replaceable></term>
<listitem>
<para>
The function used to implement this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">lefttype</replaceable></term>
<listitem>
<para>
The type of the left-hand argument of the operator, if any.
This option would be omitted for a left-unary operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">righttype</replaceable></term>
<listitem>
<para>
The type of the right-hand argument of the operator, if any.
This option would be omitted for a right-unary operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">com_op</replaceable></term>
<listitem>
<para>
The commutator of this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">neg_op</replaceable></term>
<listitem>
<para>
The negator of this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">res_proc</replaceable></term>
<listitem>
<para>
The restriction selectivity estimator function for this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">join_proc</replaceable></term>
<listitem>
<para>
The join selectivity estimator function for this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>HASHES</literal></term>
<listitem>
<para>
Indicates this operator can support a hash join.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>MERGES</literal></term>
<listitem>
<para>
Indicates this operator can support a merge join.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">left_sort_op</replaceable></term>
<listitem>
<para>
If this operator can support a merge join, the less-than
operator that sorts the left-hand data type of this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">right_sort_op</replaceable></term>
<listitem>
<para>
If this operator can support a merge join, the less-than
operator that sorts the right-hand data type of this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">less_than_op</replaceable></term>
<listitem>
<para>
If this operator can support a merge join, the less-than
operator that compares the input data types of this operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">greater_than_op</replaceable></term>
<listitem>
<para>
If this operator can support a merge join, the greater-than
operator that compares the input data types of this operator.
</para>
</listitem>
</varlistentry>
</variablelist>
<programlisting>
MYBOXES.description &lt;&lt;&lt; box '((0,0), (1,1))'
</programlisting>
</para>
<para>
This allows the execution code to always use the latter
representation and simplifies the query optimizer somewhat.
</para>
<para>
Similarly, if there is a negator operator then it should be
identified.
Suppose that an
operator, area-equal, ===, exists, as well as an area not
equal, !==.
The negator link allows the query optimizer to simplify
<programlisting>
NOT MYBOXES.description === box '((0,0), (1,1))'
</programlisting>
to
<programlisting>
MYBOXES.description !== box '((0,0), (1,1))'
</programlisting>
</para>
<para>
If a commutator operator name is supplied,
<productname>PostgreSQL</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 newly created operator as its
commutator. This applies to the negator, as well.
This is to allow the definition of two operators that are
the commutators or the negators of each other. The first
operator should be defined without a commutator or negator
(as appropriate). When the second operator is defined,
name the first as the commutator or negator. The first
will be updated as a side effect. (As of
<application>PostgreSQL</application> <literal>6.5</literal>,
it also works to just have both operators refer to each other.)
</para>
<para>
The <literal>HASHES</>, <literal>MERGES</>, <literal>SORT1</>,
<literal>SORT2</>, <literal>LTCMP</>, and <literal>GTCMP</> options
are present to support the query optimizer in performing joins.
<productname>PostgreSQL</productname> can always evaluate a join
(i.e., processing a clause with two tuple variables separated by an
operator that returns a <type>boolean</type>) by iterative
substitution <!--[WONG76]-->. In addition,
<productname>PostgreSQL</productname> can use a hash-join algorithm
<!--along the lines of [SHAP86]-->; however, it must know whether this
strategy is applicable. The current hash-join algorithm is only
correct for operators that represent equality tests; furthermore,
equality of the data type must mean bitwise equality of the
representation of the type. (For example, a data type that
contains unused bits that don't matter for equality tests could not
be hash-joined.) The <literal>HASHES</> flag indicates to the query optimizer
that a hash join may safely be used with this operator.
</para>
<para>
Similarly, the <literal>MERGES</> flag indicates whether merge-sort
is a usable join strategy for this operator. A merge join requires
that the two input data types have consistent orderings, and that
the merge-join operator behave like equality with respect to that
ordering. For example, it is possible to merge-join equality
between an integer and a float variable by sorting both inputs in
ordinary numeric order. Execution of a merge join requires that
the system be able to identify four operators related to the
merge-join equality operator: less-than comparison for the left
input data type, less-than comparison for the right input data
type, less-than comparison between the two data types, and
greater-than comparison between the two data types. It is possible
to specify these by name, as the <literal>SORT1</>,
<literal>SORT2</>, <literal>LTCMP</>, and <literal>GTCMP</> options
respectively. The system will fill in the default names
<literal>&lt;</>, <literal>&lt;</>, <literal>&lt;</>,
<literal>&gt;</> respectively if any of these are omitted when
<literal>MERGES</> is specified. Also, <literal>MERGES</> will be
assumed to be implied if any of these four operator options appear.
</para>
<para>
If other join strategies are found to be practical,
<productname>PostgreSQL</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
generality of user-defined join strategies was not felt to
be worth the complexity involved.
</para>
<para>
The <literal>RESTRICT</> and <literal>JOIN</> options assist the
query optimizer in estimating result sizes. If a clause of the
form:
To give a schema-qualified operator name in <replaceable
class="parameter">com_op</replaceable> or the other optional
arguments, use the <literal>OPERATOR()</> syntax, for example
<programlisting>
myboxes.description &lt;&lt;&lt; box '((0,0), (1,1))'
</programlisting>
is present in the qualification,
then <productname>PostgreSQL</productname> may have to
estimate the fraction of the instances in <literal>myboxes</> that
satisfy the clause. The function
<replaceable class="parameter">res_proc</replaceable>
must be a registered function (meaning it is already defined using
<command>CREATE FUNCTION</command>) which accepts arguments of the correct
data types and returns a floating-point number. The
query optimizer simply calls this function, passing the
parameter <literal>((0,0), (1,1))</literal> and multiplies the result by the relation
size to get the expected number of instances.
</para>
<para>
Similarly, when the operands of the operator both contain
instance variables, the query optimizer must estimate the
size of the resulting join. The function <function>join_proc</> will
return another floating-point number which will be multiplied
by the cardinalities of the two tables involved to
compute the expected result size.
</para>
<para>
The difference between the function
<programlisting>
my_procedure_1 (MYBOXES.description, box '((0,0), (1,1))')
</programlisting>
and the operator
<programlisting>
MYBOXES.description === box '((0,0), (1,1))'
</programlisting>
is that <productname>PostgreSQL</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.
Moreover, functions can have any number of arguments while
operators are restricted to one or two.
</para>
<refsect2 id="R2-SQL-CREATEOPERATOR-3">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
Notes
</title>
<para>
Refer to <xref linkend="xoper"> for further information.
Use <command>DROP OPERATOR</command> to delete
user-defined operators from a database.
</para>
<para>
To give a schema-qualified operator name in <replaceable
class="parameter">com_op</replaceable> or the other optional
arguments, use the <literal>OPERATOR()</> syntax, for example
<programlisting>
COMMUTATOR = OPERATOR(myschema.===) ,
COMMUTATOR = OPERATOR(myschema.===) ,
</programlisting>
</para>
</refsect2>
</para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE OPERATOR</computeroutput></term>
<listitem>
<para>
Message returned if the operator was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="R1-SQL-CREATEOPERATOR-2">
<title>
Usage
</title>
<para>The following command defines a new operator,
area-equality, for the BOX data type:
<refsect1>
<title>Notes</title>
<para>
Refer to <xref linkend="xoper"> for further information.
</para>
<programlisting>
<para>
Use <command>DROP OPERATOR</command> to delete user-defined
operators from a database.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
The following command defines a new operator, area-equality, for
the data type <type>box</type>:
<programlisting>
CREATE OPERATOR === (
LEFTARG = box,
RIGHTARG = box,
PROCEDURE = area_equal_procedure,
COMMUTATOR = ===,
NEGATOR = !==,
RESTRICT = area_restriction_procedure,
JOIN = area_join_procedure,
HASHES,
SORT1 = &lt;&lt;&lt;,
SORT2 = &lt;&lt;&lt;
-- Since sort operators were given, MERGES is implied.
-- LTCMP and GTCMP are assumed to be &lt; and &gt; respectively
LEFTARG = box,
RIGHTARG = box,
PROCEDURE = area_equal_procedure,
COMMUTATOR = ===,
NEGATOR = !==,
RESTRICT = area_restriction_procedure,
JOIN = area_join_procedure,
HASHES,
SORT1 = &lt;&lt;&lt;,
SORT2 = &lt;&lt;&lt;
-- Since sort operators were given, MERGES is implied.
-- LTCMP and GTCMP are assumed to be &lt; and &gt; respectively
);
</programlisting>
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATEOPERATOR-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEOPERATOR-4">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
<command>CREATE OPERATOR</command>
is a <productname>PostgreSQL</productname> extension.
There is no <command>CREATE OPERATOR</command>
statement in <acronym>SQL92</acronym>.
</para>
</refsect2>
<para>
<command>CREATE OPERATOR</command> is a
<productname>PostgreSQL</productname> extension. There are no
provisions for user-defined operators in the SQL standard.
</para>
</refsect1>
</refentry>

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

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.38 2002/11/21 23:34:43 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.39 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,138 +8,22 @@ PostgreSQL documentation
<refentrytitle id="sql-createrule-title">CREATE RULE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE RULE
</refname>
<refpurpose>
define a new rewrite rule
</refpurpose>
<refname>CREATE RULE</refname>
<refpurpose>define a new rewrite rule</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2001-01-05</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS ON <replaceable class="parameter">event</replaceable>
TO <replaceable class="parameter">table</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
DO [ INSTEAD ] <replaceable class="parameter">action</replaceable>
where <replaceable class="PARAMETER">action</replaceable> can be:
NOTHING
| <replaceable class="parameter">query</replaceable>
| ( <replaceable class="parameter">query</replaceable> ; <replaceable class="parameter">query</replaceable> ... )
</synopsis>
<refsect2 id="R2-SQL-CREATERULE-1">
<refsect2info>
<date>2001-01-05</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of a rule to create. This must be distinct from the name
of any other rule for the same table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><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>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of the table or view the rule
applies to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">condition</replaceable></term>
<listitem>
<para>
Any SQL conditional expression (returning <type>boolean</type>).
The condition expression may not
refer to any tables except <literal>new</literal> and
<literal>old</literal>, and may not contain aggregate functions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">query</replaceable></term>
<listitem>
<para>
The query or queries making up the
<replaceable class="PARAMETER">action</replaceable>
can be any SQL <literal>SELECT</literal>, <literal>INSERT</literal>,
<literal>UPDATE</literal>, <literal>DELETE</literal>, or
<literal>NOTIFY</literal> statement.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Within the <replaceable class="parameter">condition</replaceable>
and <replaceable class="PARAMETER">action</replaceable>, the special
table names <literal>new</literal> and <literal>old</literal> may be
used to refer to values in the referenced table.
<literal>new</literal> is valid in ON INSERT and ON UPDATE rules
to refer to the new row being inserted or updated.
<literal>old</literal> is valid in ON UPDATE and ON DELETE
rules to refer to the existing row being updated or deleted.
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATERULE-2">
<refsect2info>
<date>1998-09-11</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE RULE
</computeroutput></term>
<listitem>
<para>
Message returned if the rule is successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
DO [ INSTEAD ] { NOTHING | <replaceable class="parameter">command</replaceable> | ( <replaceable class="parameter">command</replaceable> ; <replaceable class="parameter">command</replaceable> ... ) }
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATERULE-1">
<refsect1info>
<date>1998-09-11</date>
</refsect1info>
<title>
Description
</title>
<refsect1>
<title>Description</title>
<para>
<command>CREATE RULE</command> defines a new rule applying to a specified
@ -150,186 +34,206 @@ CREATE RULE
</para>
<para>
The <productname>PostgreSQL</productname>
<firstterm>rule system</firstterm> allows one to define an
alternate action to be performed on inserts, updates, or deletions
from database tables. Rules are used to
implement table views as well.
</para>
<para>
The semantics of a rule is that at the time an individual instance (row)
is
accessed, inserted, updated, or deleted, there is an old instance (for
selects, updates and deletes) and a new instance (for inserts and
updates). All the rules for the given event type and the given target
table are examined successively (in order by name). If the
<replaceable class="parameter">condition</replaceable> specified in the
WHERE clause (if any) is true, the
<replaceable class="parameter">action</replaceable> part of the rule is
executed. The <replaceable class="parameter">action</replaceable> is
done instead of the original query if INSTEAD is specified; otherwise
it is done after the original query in the case of ON INSERT, or before
the original query in the case of ON UPDATE or ON DELETE.
Within both the <replaceable class="parameter">condition</replaceable>
and <replaceable class="parameter">action</replaceable>, values from
fields in the old instance and/or the new instance are substituted for
<literal>old.</literal><replaceable class="parameter">attribute-name</replaceable>
and <literal>new.</literal><replaceable class="parameter">attribute-name</replaceable>.
</para>
<para>
The <replaceable class="parameter">action</replaceable> part of the
rule can consist of one or more queries. To write multiple queries,
surround them with parentheses. Such queries will be performed in the
specified order. The <replaceable
class="parameter">action</replaceable> can also be NOTHING indicating
no action. Thus, a DO INSTEAD NOTHING rule suppresses the original
query from executing (when its condition is true); a DO NOTHING rule
is useless.
</para>
<para>
The <replaceable class="parameter">action</replaceable> part of the rule
executes with the same command and transaction identifier as the user
command that caused activation.
</para>
<para>
It is important to realize that a rule is really a query transformation
mechanism, or query macro. The entire query is processed to convert it
into a series of queries that include the rule actions. This occurs
before evaluation of the query starts. So, conditional rules are
handled by adding the rule condition to the WHERE clause of the action(s)
derived from the rule. The above description of a rule as an operation
that executes for each row is thus somewhat misleading. If you actually
want an operation that fires independently for each physical row, you
probably want to use a trigger not a rule. Rules are most useful for
situations that call for transforming entire queries independently of
the specific data being handled.
The <productname>PostgreSQL</productname> rule system allows one to
define an alternate action to be performed on insertions, updates,
or deletions in database tables. Roughly speaking, a rule causes
additional commands to be executed when a given command on a given
table is executed. Alternatively, a rule can replace a given
command by another, or cause a command not to be executed at all.
Rules are used to implement table views as well. It is important
to realize that a rule is really a command transformation
mechanism, or command macro. The transformation happens before the
execution of the commands starts. If you actually want an
operation that fires independently for each physical row, you
probably want to use a trigger, not a rule. More information about
the rules system is in <xref linkend="rules">.
</para>
<refsect2 id="R2-SQL-CREATERULE-3">
<refsect2info>
<date>2001-11-06</date>
</refsect2info>
<title>
Rules and Views
</title>
<para>
Presently, ON SELECT rules must be unconditional INSTEAD rules and must
have actions that consist of a single SELECT query. Thus, an ON SELECT
rule effectively turns the table into a view, whose visible
contents are the rows returned by the rule's SELECT query rather than
whatever had been stored in the table (if anything). It is considered
better style to write a CREATE VIEW command than to create a real table
and define an ON SELECT rule for it.
</para>
<para>
Presently, <literal>ON SELECT</literal> rules must be unconditional
<literal>INSTEAD</literal> rules and must have actions that consist
of a single <command>SELECT</command> command. Thus, an
<literal>ON SELECT</literal> rule effectively turns the table into
a view, whose visible contents are the rows returned by the rule's
<command>SELECT</command> command rather than whatever had been
stored in the table (if anything). It is considered better style
to write a <command>CREATE VIEW</command> command than to create a
real table and define an <literal>ON SELECT</literal> rule for it.
</para>
<para>
<xref linkend="sql-createview" endterm="sql-createview-title"> creates a dummy table (with no underlying
storage) and associates an ON SELECT rule with it. The system will not
allow updates to the view, since it knows there is no real table there.
You can create the
illusion of an updatable view by defining ON INSERT, ON UPDATE, and
ON DELETE rules (or any subset of those that's sufficient
for your purposes) to replace update actions on the view with
appropriate updates on other tables.
</para>
<para>
You can create the illusion of an updatable view by defining
<literal>ON INSERT</literal>, <literal>ON UPDATE</literal>, and
<literal>ON DELETE</literal> rules (or any subset of those that's
sufficient for your purposes) to replace update actions on the view
with appropriate updates on other tables.
</para>
<para>
There is a catch if you try to use conditional
rules for view updates: there <emphasis>must</> be an unconditional
INSTEAD rule for each action you wish to allow on the view. If the
rule is conditional, or is not INSTEAD, then the system will still reject
attempts to perform the update action, because it thinks it might end up
trying to perform the action on the dummy table in some cases.
If you want to
handle all the useful cases in conditional rules, you can; just add an
unconditional DO INSTEAD NOTHING rule to ensure that the system
understands it will never be called on to update the dummy table. Then
make the conditional rules non-INSTEAD; in the cases where they fire,
they add to the default INSTEAD NOTHING action.
</para>
</refsect2>
<para>
There is a catch if you try to use conditional rules for view
updates: there <emphasis>must</> be an unconditional
<literal>INSTEAD</literal> rule for each action you wish to allow
on the view. If the rule is conditional, or is not
<literal>INSTEAD</literal>, then the system will still reject
attempts to perform the update action, because it thinks it might
end up trying to perform the action on the dummy table of the view
in some cases. If you want to handle all the useful cases in
conditional rules, you can; just add an unconditional <literal>DO
INSTEAD NOTHING</literal> rule to ensure that the system
understands it will never be called on to update the dummy table.
Then make the conditional rules not <literal>INSTEAD</literal>; in
the cases where they are applied, they add to the default
<literal>INSTEAD NOTHING</literal> action.
</para>
</refsect1>
<refsect2 id="R2-SQL-CREATERULE-4">
<refsect2info>
<date>2001-01-05</date>
</refsect2info>
<title>
Notes
</title>
<para>
You must have rule definition access to a table in order
to define a rule on it. Use <command>GRANT</command>
and <command>REVOKE</command> to change permissions.
</para>
<refsect1>
<title>Parameters</title>
<para>
It is very important to take care to avoid circular rules.
For example, though each
of the following two rule definitions are accepted by
<productname>PostgreSQL</productname>, the
select command will cause <productname>PostgreSQL</productname> to
report an error because the query cycled too many times:
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of a rule to create. This must be distinct from the
name of any other rule for the same table. Multiple rules on
the same table and same event type are applied in alphabetical
name order.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">event</replaceable></term>
<listitem>
<para>
The even is one of <literal>SELECT</literal>,
<literal>INSERT</literal>, <literal>UPDATE</literal>, or
<literal>DELETE</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of the table or view the
rule applies to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">condition</replaceable></term>
<listitem>
<para>
Any SQL conditional expression (returning <type>boolean</type>).
The condition expression may not refer to any tables except
<literal>NEW</literal> and <literal>OLD</literal>, and may not
contain aggregate functions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">command</replaceable></term>
<listitem>
<para>
The command or commands that make up the rule action. Valid
commands are <literal>SELECT</literal>,
<literal>INSERT</literal>, <literal>UPDATE</literal>,
<literal>DELETE</literal>, or <literal>NOTIFY</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Within <replaceable class="parameter">condition</replaceable> and
<replaceable class="parameter">command</replaceable>, the special
table names <literal>NEW</literal> and <literal>OLD</literal> may
be used to refer to values in the referenced table.
<literal>NEW</literal> is valid in <literal>ON INSERT</literal> and
<literal>ON UPDATE</literal> rules to refer to the new row being
inserted or updated. <literal>OLD</literal> is valid in
<literal>ON UPDATE</literal> and <literal>ON DELETE</literal> rules
to refer to the existing row being updated or deleted.
</para>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE RULE</computeroutput></term>
<listitem>
<para>
Message returned if the rule was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
You must have the privilege <literal>RULE</literal> on a table to
be allowed to define a rule on it.
</para>
<para>
It is very important to take care to avoid circular rules. For
example, though each of the following two rule definitions are
accepted by <productname>PostgreSQL</productname>, the
<command>SELECT</command> command would cause
<productname>PostgreSQL</productname> to report an error because
the query cycled too many times:
<programlisting>
CREATE RULE "_RETURN" AS
ON SELECT TO emp
ON SELECT TO t1
DO INSTEAD
SELECT * FROM toyemp;
SELECT * FROM t2;
CREATE RULE "_RETURN" AS
ON SELECT TO toyemp
ON SELECT TO t2
DO INSTEAD
SELECT * FROM emp;
SELECT * FROM t1;
SELECT * FROM t1;
</programlisting>
</para>
This attempt to select from <literal>EMP</literal> will cause
<productname>PostgreSQL</productname> to issue an error
because the queries cycled too many times:
<programlisting>
SELECT * FROM emp;
</programlisting>
</para>
<para>
Presently, if a rule contains a NOTIFY query, the NOTIFY will be executed
unconditionally --- that is, the NOTIFY will be issued even if there are
not any rows that the rule should apply to. For example, in
<programlisting>
<para>
Presently, if a rule action contains a <command>NOTIFY</command>
command, the <command>NOTIFY</command> command will be executed
unconditionally, that is, the <command>NOTIFY</command> will be
issued even if there are not any rows that the rule should apply
to. For example, in
<programlisting>
CREATE RULE notify_me AS ON UPDATE TO mytable DO NOTIFY mytable;
UPDATE mytable SET name = 'foo' WHERE id = 42;
</programlisting>
one NOTIFY event will be sent during the UPDATE, whether or not there
are any rows with id = 42. This is an implementation restriction that
may be fixed in future releases.
</para>
</refsect2>
</programlisting>
one <command>NOTIFY</command> event will be sent during the
<command>UPDATE</command>, whether or not there are any rows with
<literal>id = 42</literal>. This is an implementation restriction
that may be fixed in future releases.
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATERULE-4">
<title>
Compatibility
</title>
<refsect1>
<title>Compatibility</title>
<refsect2 id="R2-SQL-CREATERULE-5">
<refsect2info>
<date>1998-09-11</date>
</refsect2info>
<title>
SQL92
</title>
<para>
<command>CREATE RULE</command> is a <productname>PostgreSQL</productname>
language extension.
There is no <command>CREATE RULE</command> statement in <acronym>SQL92</acronym>.
</para>
</refsect2>
<para>
<command>CREATE RULE</command> is a
<productname>PostgreSQL</productname> language extension, as is the
entire rules system.
</para>
</refsect1>
</refentry>

256
doc/src/sgml/ref/create_schema.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_schema.sgml,v 1.4 2003/02/03 15:56:50 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_schema.sgml,v 1.5 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,25 +8,51 @@ PostgreSQL documentation
<refentrytitle id="sql-createschema-title">CREATE SCHEMA</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE SCHEMA
</refname>
<refpurpose>
define a new schema
</refpurpose>
<refname>CREATE SCHEMA</refname>
<refpurpose>define a new schema</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<synopsis>
CREATE SCHEMA <replaceable class="parameter">schemaname</replaceable> [ AUTHORIZATION <replaceable class="parameter">username</replaceable> ] [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
CREATE SCHEMA AUTHORIZATION <replaceable class="parameter">username</replaceable> [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>CREATE SCHEMA</command> will enter a new schema
into the current database.
The schema name must be distinct from the name of any existing schema
in the current database.
</para>
<para>
A schema is essentially a namespace:
it contains named objects (tables, data types, functions, and operators)
whose names may duplicate those of other objects existing in other
schemas. Named objects are accessed either by <quote>qualifying</>
their names with the schema name as a prefix, or by setting a search
path that includes the desired schema(s). Unqualified objects are
created in the current schema (the one at the front of the search path,
which can be determined with the function <function>current_schema</function>).
</para>
<para>
Optionally, <command>CREATE SCHEMA</command> can include subcommands
to create objects within the new schema. The subcommands are treated
essentially the same as separate commands issued after creating the
schema, except that if the <literal>AUTHORIZATION</> clause is used,
all the created objects will be owned by that user.
</para>
</refsect1>
<refsect2 id="R2-SQL-CREATESCHEMA-1">
<title>
Inputs
</title>
<para>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
@ -63,164 +89,112 @@ CREATE SCHEMA AUTHORIZATION <replaceable class="parameter">username</replaceable
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATESCHEMA-2">
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE SCHEMA
</computeroutput></term>
<listitem>
<para>
Message returned if the command is successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: namespace "<replaceable class="parameter">schemaname</replaceable>" already exists
</computeroutput></term>
<listitem>
<para>
If the schema specified already exists.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATESCHEMA-1">
<title>
Description
</title>
<para>
<command>CREATE SCHEMA</command> will enter a new schema
into the current database.
The schema name must be distinct from the name of any existing schema
in the current database.
</para>
<para>
A schema is essentially a namespace:
it contains named objects (tables, data types, functions, and operators)
whose names may duplicate those of other objects existing in other
schemas. Named objects are accessed either by <quote>qualifying</>
their names with the schema name as a prefix, or by setting a search
path that includes the desired schema(s). Unqualified objects are
created in the current schema (the one at the front of the search path;
see <literal>CURRENT_SCHEMA()</>).
</para>
<para>
Optionally, <command>CREATE SCHEMA</command> can include subcommands
to create objects within the new schema. The subcommands are treated
essentially the same as separate commands issued after creating the
schema, except that if the <literal>AUTHORIZATION</> clause is used,
all the created objects will be owned by that user.
</para>
<refsect2 id="R2-SQL-CREATESCHEMA-3">
<title>
Notes
</title>
<para>
To create a schema, the invoking user must have <literal>CREATE</>
privilege for the current database. (Of course, superusers bypass
this check.)
</para>
<para>
Use <command>DROP SCHEMA</command> to remove a schema.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-CREATESCHEMA-2">
<title>
Examples
</title>
<para>
Create a schema:
<refsect1>
<title>Diagnostics</title>
<programlisting>
CREATE SCHEMA myschema;
</programlisting>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE SCHEMA</computeroutput></term>
<listitem>
<para>
Message returned if the schema was successfully created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: namespace "<replaceable class="parameter">schemaname</replaceable>" already exists</computeroutput></term>
<listitem>
<para>
Message returned if the schema specified already exists.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
To create a schema, the invoking user must have <literal>CREATE</>
privilege for the current database. (Of course, superusers bypass
this check.)
</para>
<para>
Create a schema for user <literal>joe</> --- the schema will also
be named <literal>joe</>:
Use <command>DROP SCHEMA</command> to remove a schema.
</para>
</refsect1>
<programlisting>
<refsect1>
<title>Examples</title>
<para>
Create a schema:
<programlisting>
CREATE SCHEMA myschema;
</programlisting>
</para>
<para>
Create a schema for user <literal>joe</>; the schema will also be
named <literal>joe</>:
<programlisting>
CREATE SCHEMA AUTHORIZATION joe;
</programlisting>
</programlisting>
</para>
<para>
Create a schema and create a table and view within it:
<programlisting>
<programlisting>
CREATE SCHEMA hollywood
CREATE TABLE films (title text, release date, awards text[])
CREATE VIEW winners AS
SELECT title, release FROM films WHERE awards IS NOT NULL;
</programlisting>
</programlisting>
Notice that the individual subcommands do not end with semicolons.
</para>
<para>
The following is an equivalent way of accomplishing the same result:
<programlisting>
<programlisting>
CREATE SCHEMA hollywood;
CREATE TABLE hollywood.films (title text, release date, awards text[]);
CREATE VIEW hollywood.winners AS
SELECT title, release FROM hollywood.films WHERE awards IS NOT NULL;
</programlisting>
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATESCHEMA-3">
<title>
Compatibility
</title>
<refsect1>
<title>Compatibility</title>
<refsect2 id="R2-SQL-CREATESCHEMA-4">
<title>
SQL92
</title>
<para>
The SQL standard allows a <literal>DEFAULT CHARACTER SET</> clause
in <command>CREATE SCHEMA</command>, as well as more subcommand
types than are presently accepted by
<productname>PostgreSQL</productname>.
</para>
<para>
SQL92 allows a <literal>DEFAULT CHARACTER SET</> clause in
<command>CREATE SCHEMA</command>, as well as more subcommand types
than are presently accepted by <productname>PostgreSQL</productname>.
</para>
<para>
The SQL standard specifies that the subcommands in <command>CREATE
SCHEMA</command> may appear in any order. The present
<productname>PostgreSQL</productname> implementation does not
handle all cases of forward references in subcommands; it may
sometimes be necessary to reorder the subcommands to avoid forward
references.
</para>
<para>
SQL92 specifies that the subcommands in <command>CREATE SCHEMA</command>
may appear in any order. The present
<productname>PostgreSQL</productname> implementation does not handle all
cases of forward references in subcommands; it may sometimes be necessary
to reorder the subcommands to avoid forward references.
</para>
<para>
In SQL92, the owner of a schema always owns all objects within it.
<productname>PostgreSQL</productname> allows schemas to contain objects
owned by users other than the schema owner. This can happen only if the
schema owner grants <literal>CREATE</> rights on his schema to someone
else.
</para>
</refsect2>
<para>
According to the SQL standard, the owner of a schema always owns
all objects within it. <productname>PostgreSQL</productname>
allows schemas to contain objects owned by users other than the
schema owner. This can happen only if the schema owner grants the
<literal>CREATE</> privilege on his schema to someone else.
</para>
</refsect1>
</refentry>

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

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.32 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.33 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,248 +8,36 @@ PostgreSQL documentation
<refentrytitle id="sql-createsequence-title">CREATE SEQUENCE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE SEQUENCE
</refname>
<refpurpose>
define a new sequence generator
</refpurpose>
<refname>CREATE SEQUENCE</refname>
<refpurpose>define a new sequence generator</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
CREATE [ TEMPORARY | TEMP ] SEQUENCE <replaceable class="parameter">seqname</replaceable> [ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ]
[ MINVALUE <replaceable class="parameter">minvalue</replaceable> | NO MINVALUE ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> | NO MAXVALUE ]
[ START [ WITH ] <replaceable class="parameter">start</replaceable> ] [ CACHE <replaceable class="parameter">cache</replaceable> ] [ [ NO ] CYCLE ]
</synopsis>
<refsect2 id="R2-SQL-CREATESEQUENCE-1">
<refsect2info>
<date>1998-09-11</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term>TEMPORARY or TEMP</term>
<listitem>
<para>
If specified, the sequence object is created only for this session,
and is automatically dropped on session exit.
Existing permanent sequences with the same name are not visible
(in this session) while the temporary sequence exists, unless
they are referenced with schema-qualified names.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">seqname</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of a sequence to be created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">increment</replaceable></term>
<listitem>
<para>
The
<option>INCREMENT BY <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 one (1).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">minvalue</replaceable></term>
<term>NO MINVALUE</term>
<listitem>
<para>
The optional clause <option>MINVALUE
<replaceable class="parameter">minvalue</replaceable></option>
determines the minimum value
a sequence can generate. If this clause is not supplied or <option>NO MINVALUE</option>
is specified, then defaults will be used. The defaults are 1 and -2^63-1 for
ascending and descending sequences, respectively.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">maxvalue</replaceable></term>
<term>NO MAXVALUE</term>
<listitem>
<para>
The optional clause <option>MAXVALUE
<replaceable class="parameter">maxvalue</replaceable></option>
determines the maximum
value for the sequence. If this clause is not supplied or
<option>NO MAXVALUE</option> is specified, then default values will be used.
The defaults are 2^63-1 and -1 for ascending and descending sequences, respectively.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">start</replaceable></term>
<listitem>
<para>
The optional <option>START WITH
<replaceable class="parameter">start</replaceable>
clause</option> enables the sequence to begin anywhere.
The default starting value is
<replaceable class="parameter">minvalue</replaceable>
for ascending sequences and
<replaceable class="parameter">maxvalue</replaceable>
for descending ones.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">cache</replaceable></term>
<listitem>
<para>
The <option>CACHE <replaceable class="parameter">cache</replaceable></option> option
enables sequence numbers to be preallocated
and stored in memory for faster access. The minimum
value is 1 (only one value can be generated at a time, i.e., no cache)
and this is also the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CYCLE</term>
<listitem>
<para>
The optional <option>CYCLE</option> keyword may be used to enable
the sequence to wrap around when the
<replaceable class="parameter">maxvalue</replaceable> or
<replaceable class="parameter">minvalue</replaceable> has been
reached by
an ascending or descending sequence respectively. If the limit is
reached, the next number generated will be the
<replaceable class="parameter">minvalue</replaceable> or
<replaceable class="parameter">maxvalue</replaceable>,
respectively.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>NO CYCLE</term>
<listitem>
<para>
If the optional <option>NO CYCLE</option> keyword is specified, any
calls to <function>nextval</function> after the sequence has reached
its maximum value will return an error. If neither
<option>CYCLE</option> or <option>NO CYCLE</option> are specified,
<option>NO CYCLE</option> is the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATESEQUENCE-2">
<refsect2info>
<date>1998-09-11</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE SEQUENCE
</computeroutput></term>
<listitem>
<para>
Message returned if the command is successful.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: Relation '<replaceable class="parameter">seqname</replaceable>' already exists
</computeroutput></term>
<listitem>
<para>
If the sequence specified already exists.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">start</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)
</computeroutput></term>
<listitem>
<para>
If the specified starting value is out of range.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be < MINVALUE (<replaceable class="parameter">min</replaceable>)
</computeroutput></term>
<listitem>
<para>
If the specified starting value is out of range.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)
</computeroutput></term>
<listitem>
<para>
If the minimum and maximum values are inconsistent.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATESEQUENCE-1">
<refsect1info>
<date>1998-09-11</date>
</refsect1info>
<title>
Description
</title>
<refsect1>
<title>Description</title>
<para>
<command>CREATE SEQUENCE</command> will enter a new sequence number generator
into the current database. This involves creating and initializing a
new single-row
table with the name <replaceable class="parameter">seqname</replaceable>.
The generator will be owned by the user issuing the command.
<command>CREATE SEQUENCE</command> creates a new sequence number
generator. This involves creating and initializing a new special
single-row table with the name <replaceable
class="parameter">seqname</replaceable>. The generator will be
owned by the user issuing the command.
</para>
<para>
If a schema name is given then the sequence is created in the
specified schema. Otherwise it is created in the current schema (the one
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
TEMP sequences exist in a special schema, so a schema name may not be
given when creating a TEMP sequence.
specified schema. Otherwise it is created in the current schema.
Temporary sequences exist in a special schema, so a schema name may not be
given when creating a temporary sequence.
The sequence name must be distinct from the name of any other sequence,
table, index, or view in the same schema.
</para>
@ -257,7 +45,7 @@ ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceabl
<para>
After a sequence is created, you use the functions
<function>nextval</function>,
<function>currval</function> and
<function>currval</function>, and
<function>setval</function>
to operate on the sequence. These functions are documented in
<xref linkend="functions-sequence">.
@ -266,132 +54,293 @@ ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceabl
<para>
Although you cannot update a sequence directly, you can use a query like
<programlisting>
<programlisting>
SELECT * FROM <replaceable>seqname</replaceable>;
</programlisting>
</programlisting>
to examine the parameters and current state of a sequence. In particular,
the <literal>last_value</> field of the sequence shows the last value
allocated by any backend process. (Of course, this value may be obsolete
by the time it's printed, if other processes are actively doing
allocated by any session. (Of course, this value may be obsolete
by the time it's printed, if other sessions are actively doing
<function>nextval</> calls.)
</para>
<caution>
<para>
Unexpected results may be obtained if a <replaceable class="parameter">cache</replaceable> setting greater than one
is used for a sequence object that will be used concurrently by multiple
backends. Each backend will allocate and cache successive sequence values
during one access to the sequence object and increase the sequence
object's <literal>last_value</> accordingly. Then, the next <replaceable class="parameter">cache</replaceable>-1 uses of <function>nextval</>
within that backend simply return the preallocated values without touching
the shared object. So, any numbers allocated but not used within a session
will be lost when that session ends. Furthermore, although multiple backends are guaranteed to
allocate distinct sequence values, the values may be generated out of
sequence when all the backends are considered. (For example, with a <replaceable class="parameter">cache</replaceable>
setting of 10, backend A might reserve values 1..10 and return <function>nextval</function>=1,
then
backend B might reserve values 11..20 and return <function>nextval</function>=11 before backend
A has generated <literal>nextval</literal>=2.) Thus, with a <replaceable class="parameter">cache</replaceable> setting of one it is safe
to assume that <function>nextval</> values are generated sequentially; with a <replaceable class="parameter">cache</replaceable>
setting greater than one you should only assume that the <function>nextval</> values
are all distinct, not that they are generated purely sequentially.
Also, <literal>last_value</> will reflect the latest value reserved by any backend,
whether or not it has yet been returned by <function>nextval</>.
Another consideration is that a <function>setval</> executed on such a sequence
will not be noticed by other backends until they have used up any
preallocated values they have cached.
</para>
</caution>
<refsect2 id="R2-SQL-CREATESEQUENCE-3">
<refsect2info>
<date>1998-09-11</date>
</refsect2info>
<title>
Notes
</title>
<para>
Use <command>DROP SEQUENCE</command> to remove a sequence.
</para>
<para>
Sequences are based on <type>bigint</> arithmetic, so the range cannot
exceed the range of an eight-byte integer
(-9223372036854775808 to 9223372036854775807). On some older platforms,
there may be no compiler support for eight-byte integers, in which case
sequences use regular <type>integer</> arithmetic (range
-2147483648 to +2147483647).
</para>
<para>
When <replaceable class="parameter">cache</replaceable> is greater than
one, each backend uses its own cache to store preallocated numbers.
Numbers that are cached but not used in the current session will be
lost, resulting in <quote>holes</quote> in the sequence.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-CREATESEQUENCE-2">
<title>
Usage
</title>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term>
<listitem>
<para>
If specified, the sequence object is created only for this
session, and is automatically dropped on session exit. Existing
permanent sequences with the same name are not visible (in this
session) while the temporary sequence exists, unless they are
referenced with schema-qualified names.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">seqname</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of the sequence to be created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">increment</replaceable></term>
<listitem>
<para>
The optional clause <literal>INCREMENT BY <replaceable
class="parameter">increment</replaceable></literal> specified,
which value is added to the current sequence value to create a
new value. A positive value will make an ascending sequence, a
negative one a descending sequence. The default value is 1.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">minvalue</replaceable></term>
<term><literal>NO MINVALUE</literal></term>
<listitem>
<para>
The optional clause <literal>MINVALUE <replaceable
class="parameter">minvalue</replaceable></literal> determines
the minimum value a sequence can generate. If this clause is not
supplied or <option>NO MINVALUE</option> is specified, then
defaults will be used. The defaults are 1 and
-2<superscript>63</>-1 for ascending and descending sequences,
respectively.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">maxvalue</replaceable></term>
<term><literal>NO MAXVALUE</literal></term>
<listitem>
<para>
The optional clause <literal>MAXVALUE <replaceable
class="parameter">maxvalue</replaceable></literal> determines
the maximum value for the sequence. If this clause is not
supplied or <option>NO MAXVALUE</option> is specified, then
default values will be used. The defaults are
2<superscript>63</>-1 and -1 for ascending and descending
sequences, respectively.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">start</replaceable></term>
<listitem>
<para>
The optional clause <literal>START WITH <replaceable
class="parameter">start</replaceable> </literal> allows the
sequence to begin anywhere. The default starting value is
<replaceable class="parameter">minvalue</replaceable> for
ascending sequences and <replaceable
class="parameter">maxvalue</replaceable> for descending ones.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">cache</replaceable></term>
<listitem>
<para>
The optional clause <literal>CACHE <replaceable
class="parameter">cache</replaceable></literal> specifies how
many sequence numbers are to be preallocated and stored in
memory for faster access. The minimum value is 1 (only one value
can be generated at a time, i.e., no cache), and this is also the
default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>CYCLE</literal></term>
<term><literal>NO CYCLE</literal></term>
<listitem>
<para>
The <literal>CYCLE</literal> option allows the sequence to wrap
around when the <replaceable
class="parameter">maxvalue</replaceable> or <replaceable
class="parameter">minvalue</replaceable> has been reached by an
ascending or descending sequence respectively. If the limit is
reached, the next number generated will be the <replaceable
class="parameter">minvalue</replaceable> or <replaceable
class="parameter">maxvalue</replaceable>, respectively.
</para>
<para>
If <literal>NO CYCLE</literal> is specified, any calls to
<function>nextval</function> after the sequence has reached its
maximum value will return an error. If neither
<literal>CYCLE</literal> or <literal>NO CYCLE</literal> are
specified, <literal>NO CYCLE</literal> is the default.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE SEQUENCE</computeroutput></term>
<listitem>
<para>
Message returned if the sequence was successfully created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: Relation '<replaceable class="parameter">seqname</replaceable>' already exists</computeroutput></term>
<listitem>
<para>
A sequence, table, view, or index of the specified name already exists.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">start</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)</computeroutput></term>
<term><computeroutput>ERROR: DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be < MINVALUE (<replaceable class="parameter">min</replaceable>)</computeroutput></term>
<listitem>
<para>
The specified starting value is out of range.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)</computeroutput></term>
<listitem>
<para>
The minimum and maximum values are inconsistent.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
Use <command>DROP SEQUENCE</command> to remove a sequence.
</para>
<para>
Sequences are based on <type>bigint</> arithmetic, so the range
cannot exceed the range of an eight-byte integer
(-9223372036854775808 to 9223372036854775807). On some older
platforms, there may be no compiler support for eight-byte
integers, in which case sequences use regular <type>integer</>
arithmetic (range -2147483648 to +2147483647).
</para>
<para>
Unexpected results may be obtained if a <replaceable
class="parameter">cache</replaceable> setting greater than one is
used for a sequence object that will be used concurrently by
multiple sessions. Each session will allocate and cache successive
sequence values during one access to the sequence object and
increase the sequence object's <literal>last_value</> accordingly.
Then, the next <replaceable class="parameter">cache</replaceable>-1
uses of <function>nextval</> within that session simply return the
preallocated values without touching the sequence object. So, any
numbers allocated but not used within a session will be lost when
that session ends, resulting in <quote>holes</quote> in the
sequence.
</para>
<para>
Furthermore, although multiple sessions are guaranteed to allocate
distinct sequence values, the values may be generated out of
sequence when all the sessions are considered. FFor example, with
a <replaceable class="parameter">cache</replaceable> setting of 10,
session A might reserve values 1..10 and return
<function>nextval</function>=1, then session B might reserve values
11..20 and return <function>nextval</function>=11 before session A
has generated <literal>nextval</literal>=2. Thus, with a
<replaceable class="parameter">cache</replaceable> setting of one
it is safe to assume that <function>nextval</> values are generated
sequentially; with a <replaceable
class="parameter">cache</replaceable> setting greater than one you
should only assume that the <function>nextval</> values are all
distinct, not that they are generated purely sequentially. Also,
<literal>last_value</> will reflect the latest value reserved by
any session, whether or not it has yet been returned by
<function>nextval</>.
</para>
<para>
Another consideration is that a <function>setval</> executed on
such a sequence will not be noticed by other sessions until they
have used up any preallocated values they have cached.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
Create an ascending sequence called <literal>serial</literal>, starting at 101:
</para>
<programlisting>
<programlisting>
CREATE SEQUENCE serial START 101;
</programlisting>
<para>
Select the next number from this sequence:
<programlisting>
SELECT nextval('serial');
nextval
-------
114
</programlisting>
</para>
<para>
Use this sequence in an INSERT:
<programlisting>
INSERT INTO distributors VALUES (nextval('serial'), 'nothing');
</programlisting>
</programlisting>
</para>
<para>
Update the sequence value after a COPY FROM:
<programlisting>
Select the next number from this sequence:
<programlisting>
SELECT nextval('serial');
nextval
---------
114
</programlisting>
</para>
<para>
Use this sequence in an <command>INSERT</command> command:
<programlisting>
INSERT INTO distributors VALUES (nextval('serial'), 'nothing');
</programlisting>
</para>
<para>
Update the sequence value after a <command>COPY FROM</command>:
<programlisting>
BEGIN;
COPY distributors FROM 'input_file';
SELECT setval('serial', max(id)) FROM distributors;
COPY distributors FROM 'input_file';
SELECT setval('serial', max(id)) FROM distributors;
END;
</programlisting>
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATESEQUENCE-3">
<title>
Compatibility
</title>
<refsect1>
<title>Compatibility</title>
<refsect2 id="R2-SQL-CREATESEQUENCE-4">
<refsect2info>
<date>1998-09-11</date>
</refsect2info>
<title>
SQL92
</title>
<para>
<command>CREATE SEQUENCE</command> is a <productname>PostgreSQL</productname>
language extension.
There is no <command>CREATE SEQUENCE</command> statement
in <acronym>SQL92</acronym>.
</para>
</refsect2>
<para>
<command>CREATE SEQUENCE</command> is a
<productname>PostgreSQL</productname> language extension. There is
no <command>CREATE SEQUENCE</command> statement in the SQL
standard.
</para>
</refsect1>
</refentry>

321
doc/src/sgml/ref/create_table.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table.sgml,v 1.66 2003/04/14 18:08:58 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table.sgml,v 1.67 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -29,7 +29,7 @@ where <replaceable class="PARAMETER">column_constraint</replaceable> is:
[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
{ NOT NULL | NULL | UNIQUE | PRIMARY KEY |
CHECK (<replaceable class="PARAMETER">expression</replaceable>) |
REFERENCES <replaceable class="PARAMETER">reftable</replaceable> [ ( <replaceable class="PARAMETER">refcolumn</replaceable> ) ] [ MATCH FULL | MATCH PARTIAL ]
REFERENCES <replaceable class="PARAMETER">reftable</replaceable> [ ( <replaceable class="PARAMETER">refcolumn</replaceable> ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ]
[ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ] }
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
@ -40,7 +40,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
PRIMARY KEY ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] ) |
CHECK ( <replaceable class="PARAMETER">expression</replaceable> ) |
FOREIGN KEY ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] ) REFERENCES <replaceable class="PARAMETER">reftable</replaceable> [ ( <replaceable class="PARAMETER">refcolumn</replaceable> [, ... ] ) ]
[ MATCH FULL | MATCH PARTIAL ] [ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ] }
[ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ] }
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
</synopsis>
@ -58,17 +58,16 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<para>
If a schema name is given (for example, <literal>CREATE TABLE
myschema.mytable ...</>) then the table is created in the
specified schema. Otherwise it is created in the current schema (the one
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
TEMP tables exist in a special schema, so a schema name may not be
given when creating a TEMP table.
specified schema. Otherwise it is created in the current schema.
Temporary tables exist in a special schema, so a schema name may not be
given when creating a temporary table.
The table name must be distinct from the name of any other table,
sequence, index, or view in the same schema.
</para>
<para>
<command>CREATE TABLE</command> also automatically creates a data
type that represents the tuple type (structure type) corresponding
type that represents the composite type corresponding
to one row of the table. Therefore, tables cannot have the same
name as any existing data type in the same schema.
</para>
@ -81,9 +80,8 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<para>
The optional constraint clauses specify constraints (or tests) that
new or updated rows must satisfy for an insert or update operation
to succeed. A constraint is a named rule: an SQL object which
helps define valid sets of values by putting limits on the results
of insert, update, or delete operations performed on a table.
to succeed. A constraint is an SQL object that helps define the
set of valid values in the table in various ways.
</para>
<para>
@ -158,7 +156,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<para>
The <literal>DEFAULT</> clause assigns a default data value for
the column whose column definition it appears within. The value
is any variable-free expression (subselects and cross-references
is any variable-free expression (subqueries and cross-references
to other columns in the current table are not allowed). The
data type of the default expression must match the data type of the
column.
@ -167,7 +165,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<para>
The default expression will be used in any insert operation that
does not specify a value for the column. If there is no default
for a column, then the default is NULL.
for a column, then the default is null.
</para>
</listitem>
</varlistentry>
@ -212,7 +210,8 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
</varlistentry>
<varlistentry>
<term><literal>WITH OIDS</> or <literal>WITHOUT OIDS</></term>
<term><literal>WITH OIDS</></term>
<term><literal>WITHOUT OIDS</></term>
<listitem>
<para>
This optional clause specifies whether rows of the new table
@ -250,7 +249,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<term><literal>NOT NULL</></term>
<listitem>
<para>
The column is not allowed to contain NULL values.
The column is not allowed to contain null values.
</para>
</listitem>
</varlistentry>
@ -259,7 +258,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<term><literal>NULL</></term>
<listitem>
<para>
The column is allowed to contain NULL values. This is the default.
The column is allowed to contain null values. This is the default.
</para>
<para>
@ -276,7 +275,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<listitem>
<para>
The <literal>UNIQUE</literal> constraint specifies a rule that a
The <literal>UNIQUE</literal> constraint specifies that a
group of one or more distinct columns of a table may contain
only unique values. The behavior of the unique table constraint
is the same as that for column constraints, with the additional
@ -284,7 +283,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
</para>
<para>
For the purpose of a unique constraint, NULL values are not
For the purpose of a unique constraint, null values are not
considered equal.
</para>
@ -303,11 +302,11 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<listitem>
<para>
The primary key constraint specifies that a column or columns of a table
may contain only unique (non-duplicate), non-NULL values.
may contain only unique (non-duplicate), nonnull values.
Technically, <literal>PRIMARY KEY</literal> is merely a
combination of <literal>UNIQUE</> and <literal>NOT NULL</>, but
identifying a set of columns as primary key also provides
meta-data about the design of the schema, as a primary key
metadata about the design of the schema, as a primary key
implies that other tables
may rely on this set of columns as a unique identifier for rows.
</para>
@ -329,21 +328,19 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<term><literal>CHECK (<replaceable class="PARAMETER">expression</replaceable>)</literal></term>
<listitem>
<para>
<literal>CHECK</> clauses specify integrity constraints or tests
which new or updated rows must satisfy for an insert or update
operation to succeed. Each constraint must be an expression
producing a Boolean result. A condition appearing within a
column definition should reference that column's value only,
while a condition appearing as a table constraint may reference
multiple columns.
The <literal>CHECK</> clause specifies an expression producing a
Boolean result which new or updated rows must satisfy for an
insert or update operation to succeed. A check constraint
specified as a column constraint should reference that column's
value only, while an expression appearing in a table constraint
may reference multiple columns.
</para>
<para>
Currently, <literal>CHECK</literal> expressions cannot contain
subselects nor refer to variables other than columns of the
subqueries nor refer to variables other than columns of the
current row.
</para>
</listitem>
</varlistentry>
@ -360,7 +357,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<listitem>
<para>
The <literal>REFERENCES</literal> column constraint specifies
Theses clauses specify a foreign key constraint, which specifies
that a group of one or more columns of the new table must only
contain values which match against values in the referenced
column(s) <replaceable class="parameter">refcolumn</replaceable>
@ -374,23 +371,23 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
</para>
<para>
A value added to these columns is matched against the values of
the referenced table and referenced columns using the given
match type. There are three match types: <literal>MATCH
FULL</>, <literal>MATCH PARTIAL</>, and a default match type if
none is specified. <literal>MATCH FULL</> will not allow one
column of a multicolumn foreign key to be NULL unless all
foreign key columns are NULL. The default match type allows some
foreign key columns to be NULL while other parts of the foreign
key are not NULL. <literal>MATCH PARTIAL</> is not yet
implemented.
A value inserted into these columns is matched against the
values of the referenced table and referenced columns using the
given match type. There are three match types: <literal>MATCH
FULL</>, <literal>MATCH PARTIAL</>, and <literal>MATCH
SIMPLE</literal>, which is also the default. <literal>MATCH
FULL</> will not allow one column of a multicolumn foreign key
to be null unless all foreign key columns are null.
<literal>MATCH SIMPLE</literal> allows some foreign key columns
to be null while other parts of the foreign key are not
null. <literal>MATCH PARTIAL</> is not yet implemented.
</para>
<para>
In addition, when the data in the referenced columns is changed,
certain actions are performed on the data in this table's
columns. The <literal>ON DELETE</literal> clause specifies the
action to do when a referenced row in the referenced table is
action to perform when a referenced row in the referenced table is
being deleted. Likewise, the <literal>ON UPDATE</literal>
clause specifies the action to perform when a referenced column
in the referenced table is being updated to a new value. If the
@ -434,7 +431,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<term><literal>SET NULL</literal></term>
<listitem>
<para>
Set the referencing column values to NULL.
Set the referencing column values to null.
</para>
</listitem>
</varlistentry>
@ -449,19 +446,20 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
</varlistentry>
</variablelist>
</para>
<para>
If primary key column is updated frequently, it may be wise to
add an index to the <literal>REFERENCES</literal> column so that
<literal>NO ACTION</literal> and <literal>CASCADE</literal>
actions associated with the <literal>REFERENCES</literal>
column can be more efficiently performed.
add an index to the foreign key column so that <literal>NO
ACTION</literal> and <literal>CASCADE</literal> actions
associated with the foreign key column can be more efficiently
performed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>DEFERRABLE</literal> or <literal>NOT DEFERRABLE</literal></term>
<term><literal>DEFERRABLE</literal></term>
<term><literal>NOT DEFERRABLE</literal></term>
<listitem>
<para>
This controls whether the constraint can be deferred. A
@ -477,7 +475,8 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
</varlistentry>
<varlistentry>
<term><literal>INITIALLY IMMEDIATE</literal> or <literal>INITIALLY DEFERRED</literal></term>
<term><literal>INITIALLY IMMEDIATE</literal></term>
<term><literal>INITIALLY DEFERRED</literal></term>
<listitem>
<para>
If a constraint is deferrable, this clause specifies the default
@ -541,45 +540,16 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<refsect1 id="SQL-CREATETABLE-diagnostics">
<title>Diagnostics</title>
<msgset>
<msgentry>
<msg>
<msgmain>
<msgtext>
<simpara><computeroutput>CREATE TABLE</computeroutput></simpara>
</msgtext>
</msgmain>
</msg>
<msgexplan>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE TABLE</computeroutput></term>
<listitem>
<para>
Message returned if table is successfully created.
Message returned if the table was successfully created.
</para>
</msgexplan>
</msgentry>
<msgentry>
<msg>
<msgmain>
<msgtext>
<simpara><computeroutput>ERROR</computeroutput></simpara>
</msgtext>
</msgmain>
</msg>
<msgexplan>
<para>
Message returned if table creation failed. This is usually
accompanied by some descriptive text, such as:
<computeroutput>ERROR: Relation '<replaceable
class="parameter">table</replaceable>' already
exists</computeroutput>, which occurs at run time if the table
specified already exists in the database.
</para>
</msgexplan>
</msgentry>
</msgset>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
@ -622,17 +592,6 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
</para>
</listitem>
<listitem>
<para>
The SQL92 standard says that <literal>CHECK</> column constraints
may only refer to the column they apply to; only
<literal>CHECK</> table constraints may refer to multiple
columns. <productname>PostgreSQL</productname> does not enforce
this restriction; it treats column and table check constraints
alike.
</para>
</listitem>
<listitem>
<para>
Unique constraints and primary keys are not inherited in the
@ -653,19 +612,19 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
<programlisting>
CREATE TABLE films (
code CHARACTER(5) CONSTRAINT firstkey PRIMARY KEY,
title CHARACTER VARYING(40) NOT NULL,
did DECIMAL(3) NOT NULL,
date_prod DATE,
kind CHAR(10),
len INTERVAL HOUR TO MINUTE
code char(5) CONSTRAINT firstkey PRIMARY KEY,
title varchar(40) NOT NULL,
did integer NOT NULL,
date_prod date,
kind varchar(10),
len interval hour to minute
);
</programlisting>
<programlisting>
CREATE TABLE distributors (
did DECIMAL(3) PRIMARY KEY DEFAULT NEXTVAL('serial'),
name VARCHAR(40) NOT NULL CHECK (name &lt;&gt; '')
did integer PRIMARY KEY DEFAULT nextval('serial'),
name varchar(40) NOT NULL CHECK (name &lt;&gt; '')
);
</programlisting>
</para>
@ -675,23 +634,24 @@ CREATE TABLE distributors (
<programlisting>
CREATE TABLE array (
vector INT[][]
vector int[][]
);
</programlisting>
</para>
<para>
Define a unique table constraint for the table films. Unique table
constraints can be defined on one or more columns of the table:
Define a unique table constraint for the table
<literal>films</literal>. Unique table constraints can be defined
on one or more columns of the table.
<programlisting>
CREATE TABLE films (
code CHAR(5),
title VARCHAR(40),
did DECIMAL(3),
date_prod DATE,
kind VARCHAR(10),
len INTERVAL HOUR TO MINUTE,
code char(5),
title varchar(40),
did integer,
date_prod date,
kind varchar(10),
len interval hour to minute,
CONSTRAINT production UNIQUE(date_prod)
);
</programlisting>
@ -702,8 +662,8 @@ CREATE TABLE films (
<programlisting>
CREATE TABLE distributors (
did DECIMAL(3) CHECK (did > 100),
name VARCHAR(40)
did integer CHECK (did > 100),
name varchar(40)
);
</programlisting>
</para>
@ -713,8 +673,8 @@ CREATE TABLE distributors (
<programlisting>
CREATE TABLE distributors (
did DECIMAL(3),
name VARCHAR(40)
did integer,
name varchar(40)
CONSTRAINT con1 CHECK (did > 100 AND name &lt;&gt; '')
);
</programlisting>
@ -727,12 +687,12 @@ CREATE TABLE distributors (
<programlisting>
CREATE TABLE films (
code CHAR(5),
title VARCHAR(40),
did DECIMAL(3),
date_prod DATE,
kind VARCHAR(10),
len INTERVAL HOUR TO MINUTE,
code char(5),
title varchar(40),
did integer,
date_prod date,
kind varchar(10),
len interval hour to minute,
CONSTRAINT code_title PRIMARY KEY(code,title)
);
</programlisting>
@ -746,33 +706,33 @@ CREATE TABLE films (
<programlisting>
CREATE TABLE distributors (
did DECIMAL(3),
name CHAR VARYING(40),
did integer,
name varchar(40),
PRIMARY KEY(did)
);
</programlisting>
<programlisting>
CREATE TABLE distributors (
did DECIMAL(3) PRIMARY KEY,
name VARCHAR(40)
did integer PRIMARY KEY,
name varchar(40)
);
</programlisting>
</para>
<para>
This assigns a literal constant default value for the column
<literal>name</literal>, and arranges for the default value of
column <literal>did</literal> to be generated by selecting the next
value of a sequence object. The default value of
<literal>modtime</literal> will be the time at which the row is
<literal>name</literal>, arranges for the default value of column
<literal>did</literal> to be generated by selecting the next value
of a sequence object, and makes the default value of
<literal>modtime</literal> be the time at which the row is
inserted.
<programlisting>
CREATE TABLE distributors (
name VARCHAR(40) DEFAULT 'luso films',
did INTEGER DEFAULT NEXTVAL('distributors_serial'),
modtime TIMESTAMP DEFAULT CURRENT_TIMESTAMP
name varchar(40) DEFAULT 'Luso Films',
did integer DEFAULT nextval('distributors_serial'),
modtime timestamp DEFAULT current_timestamp
);
</programlisting>
</para>
@ -784,8 +744,8 @@ CREATE TABLE distributors (
<programlisting>
CREATE TABLE distributors (
did DECIMAL(3) CONSTRAINT no_null NOT NULL,
name VARCHAR(40) NOT NULL
did integer CONSTRAINT no_null NOT NULL,
name varchar(40) NOT NULL
);
</programlisting>
</para>
@ -795,8 +755,8 @@ CREATE TABLE distributors (
<programlisting>
CREATE TABLE distributors (
did DECIMAL(3),
name VARCHAR(40) UNIQUE
did integer,
name varchar(40) UNIQUE
);
</programlisting>
@ -804,8 +764,8 @@ CREATE TABLE distributors (
<programlisting>
CREATE TABLE distributors (
did DECIMAL(3),
name VARCHAR(40),
did integer,
name varchar(40),
UNIQUE(name)
);
</programlisting>
@ -818,8 +778,7 @@ CREATE TABLE distributors (
<para>
The <command>CREATE TABLE</command> command conforms to SQL92
and to a subset of SQL99, with exceptions listed below and in the
descriptions above.
and to a subset of SQL99, with exceptions listed below.
</para>
<refsect2>
@ -827,27 +786,25 @@ CREATE TABLE distributors (
<para>
Although the syntax of <literal>CREATE TEMPORARY TABLE</literal>
resembles that of SQL92, the effect is not the same. In the standard,
resembles that of SQL standard, the effect is not the same. In the standard,
temporary tables are defined just once and automatically exist (starting
with empty contents) in every session that needs them.
<productname>PostgreSQL</productname> instead
requires each session to issue its own <literal>CREATE TEMPORARY
TABLE</literal> command for each temporary table to be used. This allows
different sessions to use the same temporary table name for different
purposes, whereas the spec's approach constrains all instances of a
purposes, whereas the standard's approach constrains all instances of a
given temporary table name to have the same table structure.
</para>
<note>
<para>
The spec-mandated behavior of temporary tables is widely ignored.
<productname>PostgreSQL</productname>'s behavior on this point is similar
to that of several other RDBMSs.
</para>
</note>
<para>
The behavior of temporary tables mandated by the standard is
widely ignored. <productname>PostgreSQL</productname>'s behavior
on this point is similar to that of several other SQL databases.
</para>
<para>
SQL92's distinction between global and local temporary tables
The standard's distinction between global and local temporary tables
is not in <productname>PostgreSQL</productname>, since that distinction
depends on the concept of modules, which
<productname>PostgreSQL</productname> does not have.
@ -855,12 +812,24 @@ CREATE TABLE distributors (
<para>
The <literal>ON COMMIT</literal> clause for temporary tables
also resembles SQL92, but has some differences.
If the <literal>ON COMMIT</> clause is omitted, SQL92 specifies that the
also resembles the SQL standard, but has some differences.
If the <literal>ON COMMIT</> clause is omitted, SQL specifies that the
default behavior is <literal>ON COMMIT DELETE ROWS</>. However, the
default behavior in <productname>PostgreSQL</productname> is
<literal>ON COMMIT PRESERVE ROWS</literal>. The <literal>ON COMMIT
DROP</literal> option does not exist in SQL92.
DROP</literal> option does not exist in SQL.
</para>
</refsect2>
<refsect2>
<title>Column Check Constraints</title>
<para>
The SQL standard says that <literal>CHECK</> column constraints
may only refer to the column they apply to; only <literal>CHECK</>
table constraints may refer to multiple columns.
<productname>PostgreSQL</productname> does not enforce this
restriction; it treats column and table check constraints alike.
</para>
</refsect2>
@ -870,49 +839,13 @@ CREATE TABLE distributors (
<para>
The <literal>NULL</> <quote>constraint</quote> (actually a
non-constraint) is a <productname>PostgreSQL</productname>
extension to SQL92 that is included for compatibility with some
other RDBMSs (and for symmetry with the <literal>NOT
extension to the SQL standard that is included for compatibility with some
other database systems (and for symmetry with the <literal>NOT
NULL</literal> constraint). Since it is the default for any
column, its presence is simply noise.
</para>
</refsect2>
<refsect2>
<title>Assertions</title>
<para>
An assertion is a special type of integrity constraint and shares
the same namespace as other constraints. However, an assertion is
not necessarily dependent on one particular table as constraints
are, so SQL92 provides the <command>CREATE ASSERTION</command>
statement as an alternate method for defining a constraint:
<synopsis>
CREATE ASSERTION <replaceable>name</replaceable> CHECK ( <replaceable>condition</replaceable> )
</synopsis>
</para>
<para>
<productname>PostgreSQL</> does not implement assertions at present.
</para>
</refsect2>
<!--
<para>
Domain constraints are defined by <command>CREATE
DOMAIN</command> or <command>ALTER DOMAIN</command> statements:
</para>
<para>
Domain constraint:
<synopsis>
[ CONSTRAINT <replaceable>constraint_name</replaceable> ] CHECK <replaceable>constraint</replaceable>
[ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
[ [ NOT ] DEFERRABLE ]
</synopsis>
</para>
-->
<refsect2>
<title>Inheritance</title>

30
doc/src/sgml/ref/create_table_as.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.11 2002/11/21 23:34:43 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.12 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -18,16 +18,12 @@ PostgreSQL documentation
<synopsis>
CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable> [ (<replaceable>column_name</replaceable> [, ...] ) ]
AS <replaceable>query</replaceable>
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect1>
<refsect1info>
<date>2001-03-20</date>
</refsect1info>
<title>
Description
</title>
<title>Description</title>
<para>
<command>CREATE TABLE AS</command> creates a table and fills it
with data computed by a <command>SELECT</command> command. The
@ -75,10 +71,9 @@ CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replace
<term><replaceable>column_name</replaceable></term>
<listitem>
<para>
The name of a column in the new table. Multiple column names can
be specified using a comma-delimited list of column names. If
column names are not provided, they are taken from the output
column names of the query.
The name of a column in the new table. If column names are not
provided, they are taken from the output column names of the
query.
</para>
</listitem>
</varlistentry>
@ -124,21 +119,12 @@ CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replace
<para>
This command is modeled after an <productname>Oracle</productname>
feature. There is no command with equivalent functionality in
SQL92 or SQL99. However, a combination of <literal>CREATE
the SQL standard. However, a combination of <literal>CREATE
TABLE</literal> and <literal>INSERT ... SELECT</literal> can
accomplish the same thing with little more effort.
</para>
</refsect1>
<refsect1>
<title>History</title>
<para>
The <command>CREATE TABLE AS</command> command has been available
since <productname>PostgreSQL</productname> 6.3.
</para>
</refsect1>
<refsect1>
<title>See Also</title>

447
doc/src/sgml/ref/create_trigger.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_trigger.sgml,v 1.33 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_trigger.sgml,v 1.34 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,186 +8,57 @@ PostgreSQL documentation
<refentrytitle id="SQL-CREATETRIGGER-TITLE">CREATE TRIGGER</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE TRIGGER
</refname>
<refpurpose>
define a new trigger
</refpurpose>
<refname>CREATE TRIGGER</refname>
<refpurpose>define a new trigger</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2000-03-25</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTER } { <replaceable class="PARAMETER">event</replaceable> [ OR ... ] }
ON <replaceable class="PARAMETER">table</replaceable> [ FOR [ EACH ] { ROW | STATEMENT } ]
EXECUTE PROCEDURE <replaceable class="PARAMETER">func</replaceable> ( <replaceable class="PARAMETER">arguments</replaceable> )
</synopsis>
<refsect2 id="R2-SQL-CREATETRIGGER-1">
<refsect2info>
<date>1998-09-21</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name to give the new trigger. This must be distinct from the name
of any other trigger for the same table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BEFORE</term>
<term>AFTER</term>
<listitem>
<para>
Determines whether the function is called before or after the
event.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">event</replaceable></term>
<listitem>
<para>
One of <command>INSERT</command>, <command>DELETE</command> or
<command>UPDATE</command>; this specifies the event that will
fire the trigger. Multiple events can be specified using
<literal>OR</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of the table the
trigger is for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FOR EACH ROW</term>
<term>FOR EACH STATEMENT</term>
<listitem>
<para>
This specifies whether the trigger procedure should be fired
once for every row affected by the trigger event, or just once
per SQL statement. If neither is specified, <literal>FOR EACH
STATEMENT</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">func</replaceable></term>
<listitem>
<para>
A user-supplied function that is declared as taking no arguments
and returning type <literal>trigger</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">arguments</replaceable></term>
<listitem>
<para>
An optional comma-separated list of arguments to be provided to
the function when the trigger is executed, along with the standard
trigger data such as old and new tuple contents. The arguments
are literal string constants. Simple names and numeric constants
may be written here too, but they will all be converted to
strings. Note that these arguments are not provided as normal
function parameters (since a trigger procedure must be declared to
take zero parameters), but are instead accessed through the
<literal>TG_ARGV</literal> array.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATETRIGGER-2">
<refsect2info>
<date>1998-09-21</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE TRIGGER
</computeroutput></term>
<listitem>
<para>
This message is returned if the trigger is successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATETRIGGER-1">
<refsect1info>
<date>1998-09-21</date>
</refsect1info>
<title>
Description
</title>
<refsect1>
<title>Description</title>
<para>
<command>CREATE TRIGGER</command> will enter a new trigger into the current
database. The trigger will be associated with the relation
<replaceable class="parameter">table</replaceable> and will execute
the specified function <replaceable class="parameter">func</replaceable>.
<command>CREATE TRIGGER</command> creates a new trigger. The
trigger will be associated with the specified table and will
execute the specified function <replaceable
class="parameter">func</replaceable> when certain events occur.
</para>
<para>
The trigger can be specified to fire either before BEFORE the
operation is attempted on a tuple (before constraints are checked and
the <command>INSERT</command>, <command>UPDATE</command> or
<command>DELETE</command> is attempted) or AFTER the operation has
been attempted (e.g., after constraints are checked and the
<command>INSERT</command>, <command>UPDATE</command> or
<command>DELETE</command> has completed). If the trigger fires before
the event, the trigger may skip the operation for the current tuple,
or change the tuple being inserted (for <command>INSERT</command> and
<command>UPDATE</command> operations only). If the trigger fires
after the event, all changes, including the last insertion, update,
or deletion, are <quote>visible</quote> to the trigger.
The trigger can be specified to fire either before before the
operation is attempted on a row (before constraints are checked and
the <command>INSERT</command>, <command>UPDATE</command>, or
<command>DELETE</command> is attempted) or after the operation has
completed (after constraints are checked and the
<command>INSERT</command>, <command>UPDATE</command>, or
<command>DELETE</command> has completed). If the trigger fires
before the event, the trigger may skip the operation for the
current row, or change the row being inserted (for
<command>INSERT</command> and <command>UPDATE</command> operations
only). If the trigger fires after the event, all changes, including
the last insertion, update, or deletion, are <quote>visible</quote>
to the trigger.
</para>
<para>
A trigger that executes <literal>FOR EACH ROW</literal> of the
specified operation is called once for every row that the operation
modifies. For example, a <command>DELETE</command> that affects 10
rows will cause any <literal>ON DELETE</literal> triggers on the
target relation to be called 10 separate times, once for each
deleted tuple. In contrast, a trigger that executes <literal>FOR
EACH STATEMENT</literal> of the specified operation only executes
once for any given operation, regardless of how many rows it
modifies (in particular, an operation that modifies zero rows will
still result in the execution of any applicable <literal>FOR EACH
STATEMENT</literal> triggers).
A trigger that is marked <literal>FOR EACH ROW</literal> is called
once for every row that the operation modifies. For example, a
<command>DELETE</command> that affects 10 rows will cause any
<literal>ON DELETE</literal> triggers on the target relation to be
called 10 separate times, once for each deleted row. In contrast, a
trigger that is marked <literal>FOR EACH STATEMENT</literal> only
executes once for any given operation, regardless of how many rows
it modifies (in particular, an operation that modifies zero rows
will still result in the execution of any applicable <literal>FOR
EACH STATEMENT</literal> triggers).
</para>
<para>
@ -202,9 +73,114 @@ CREATE TRIGGER
</para>
<para>
Refer to <xref linkend="server-programming"> for more information.
Refer to <xref linkend="triggers"> for more information about triggers.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name to give the new trigger. This must be distinct from
the name of any other trigger for the same table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>BEFORE</literal></term>
<term><literal>AFTER</literal></term>
<listitem>
<para>
Determines whether the function is called before or after the
event.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">event</replaceable></term>
<listitem>
<para>
One of <command>INSERT</command>, <command>UPDATE</command>, or
<command>DELETE</command>; this specifies the event that will
fire the trigger. Multiple events can be specified using
<literal>OR</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">table</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of the table the trigger
is for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>FOR EACH ROW</literal></term>
<term><literal>FOR EACH STATEMENT</literal></term>
<listitem>
<para>
This specifies whether the trigger procedure should be fired
once for every row affected by the trigger event, or just once
per SQL statement. If neither is specified, <literal>FOR EACH
STATEMENT</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">func</replaceable></term>
<listitem>
<para>
A user-supplied function that is declared as taking no arguments
and returning type <literal>trigger</>, which is executed when
the trigger fires.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">arguments</replaceable></term>
<listitem>
<para>
An optional comma-separated list of arguments to be provided to
the function when the trigger is executed. The arguments are
literal string constants. Simple names and numeric constants
may be written here, too, but they will all be converted to
strings. Please check the description of the implementation
language of the trigger function about how the trigger arguments
are accessible within the function; it may be different from
normal function arguments.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE TRIGGER</computeroutput></term>
<listitem>
<para>
Message returned if the trigger was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="SQL-CREATETRIGGER-notes">
<title>Notes</title>
@ -219,13 +195,13 @@ CREATE TRIGGER
necessary to declare trigger functions as returning the placeholder
type <type>opaque</>, rather than <type>trigger</>. To support loading
of old dump files, <command>CREATE TRIGGER</> will accept a function
declared as returning <type>opaque</>, but it will issue a NOTICE and
declared as returning <type>opaque</>, but it will issue a notice and
change the function's declared return type to <type>trigger</>.
</para>
<para>
Refer to the <xref linkend="sql-droptrigger" endterm="sql-droptrigger-title"> command for
information on how to remove triggers.
Use <xref linkend="sql-droptrigger"
endterm="sql-droptrigger-title"> to remove a trigger.
</para>
</refsect1>
@ -233,111 +209,64 @@ CREATE TRIGGER
<title>Examples</title>
<para>
Check if the specified distributor code exists in the distributors
table before appending or updating a row in the table films:
<programlisting>
CREATE TRIGGER if_dist_exists
BEFORE INSERT OR UPDATE ON films FOR EACH ROW
EXECUTE PROCEDURE check_primary_key ('did', 'distributors', 'did');
</programlisting>
</para>
<para>
Before cancelling a distributor or updating its code, remove every
reference to the table films:
<programlisting>
CREATE TRIGGER if_film_exists
BEFORE DELETE OR UPDATE ON distributors FOR EACH ROW
EXECUTE PROCEDURE check_foreign_key (1, 'CASCADE', 'did', 'films', 'did');
</programlisting>
</para>
<para>
The second example can also be done by using a foreign key,
constraint as in:
<programlisting>
CREATE TABLE distributors (
did DECIMAL(3),
name VARCHAR(40),
CONSTRAINT if_film_exists
FOREIGN KEY(did) REFERENCES films
ON UPDATE CASCADE ON DELETE CASCADE
);
</programlisting>
<xref linkend="trigger-example"> contains a complete example.
</para>
</refsect1>
<refsect1 id="SQL-CREATETRIGGER-compatibility">
<title>Compatibility</title>
<variablelist>
<varlistentry>
<term>SQL92</term>
<para>
The <command>CREATE TRIGGER</command> statement in
<productname>PostgreSQL</productname> implements a subset of the
SQL99 standard. (There are no provisions for triggers in SQL92.)
The following functionality is missing:
<itemizedlist>
<listitem>
<para>
There is no <command>CREATE TRIGGER</command> statement in <acronym>SQL92</acronym>.
SQL99 allows triggers to fire on updates to specific columns
(e.g., <literal>AFTER UPDATE OF col1, col2</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SQL99</term>
<listitem>
<para>
The <command>CREATE TRIGGER</command> statement in
<productname>PostgreSQL</productname> implements a subset of the
SQL99 standard. The following functionality is missing:
<itemizedlist>
<listitem>
<para>
SQL99 allows triggers to fire on updates to specific columns
(e.g., <literal>AFTER UPDATE OF col1, col2</literal>).
</para>
</listitem>
<listitem>
<para>
SQL99 allows you to define aliases for the <quote>old</quote>
and <quote>new</quote> rows or tables for use in the definition
of the triggered action (e.g., <literal>CREATE TRIGGER ... ON
tablename REFERENCING OLD ROW AS somename NEW ROW AS
othername ...</literal>). Since
<productname>PostgreSQL</productname> allows trigger
procedures to be written in any number of user-defined
languages, access to the data is handled in a
language-specific way.
</para>
</listitem>
<listitem>
<para>
<productname>PostgreSQL</productname> only allows the
execution of a stored procedure for the triggered action.
SQL99 allows the execution of a number of other SQL commands,
such as <command>CREATE TABLE</command> as triggered action.
This limitation is not hard to work around by creating a
stored procedure that executes these commands.
</para>
</listitem>
</itemizedlist>
</para>
<para>
SQL99 specifies that multiple triggers should be fired in
time-of-creation order. <productname>PostgreSQL</productname>
uses name order, which was judged more convenient to work with.
</para>
<para>
The ability to specify multiple actions for a single trigger
using <literal>OR</literal> is a <productname>PostgreSQL</>
extension of the SQL standard.
SQL99 allows you to define aliases for the <quote>old</quote>
and <quote>new</quote> rows or tables for use in the definition
of the triggered action (e.g., <literal>CREATE TRIGGER ... ON
tablename REFERENCING OLD ROW AS somename NEW ROW AS othername
...</literal>). Since <productname>PostgreSQL</productname>
allows trigger procedures to be written in any number of
user-defined languages, access to the data is handled in a
language-specific way.
</para>
</listitem>
</varlistentry>
</variablelist>
<listitem>
<para>
<productname>PostgreSQL</productname> only allows the execution
of a user-defined function for the triggered action. SQL99
allows the execution of a number of other SQL commands, such as
<command>CREATE TABLE</command> as triggered action. This
limitation is not hard to work around by creating a user-defined
function that executes the desired commands.
</para>
</listitem>
</itemizedlist>
</para>
<para>
SQL99 specifies that multiple triggers should be fired in
time-of-creation order. <productname>PostgreSQL</productname> uses
name order, which was judged more convenient to work with.
</para>
<para>
The ability to specify multiple actions for a single trigger using
<literal>OR</literal> is a <productname>PostgreSQL</> extension of
the SQL standard.
</para>
</refsect1>
<refsect1>

533
doc/src/sgml/ref/create_type.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.40 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.41 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,22 +8,17 @@ PostgreSQL documentation
<refentrytitle id="sql-createtype-title">CREATE TYPE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE TYPE
</refname>
<refpurpose>
define a new data type
</refpurpose>
<refname>CREATE TYPE</refname>
<refpurpose>define a new data type</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <replaceable class="parameter">input_function</replaceable>, OUTPUT = <replaceable class="parameter">output_function</replaceable>
, INTERNALLENGTH = { <replaceable
class="parameter">internallength</replaceable> | VARIABLE }
<synopsis>
CREATE TYPE <replaceable class="parameter">typename</replaceable> (
INPUT = <replaceable class="parameter">input_function</replaceable>, OUTPUT = <replaceable class="parameter">output_function</replaceable>
, INTERNALLENGTH = { <replaceable class="parameter">internallength</replaceable> | VARIABLE }
[ , DEFAULT = <replaceable class="parameter">default</replaceable> ]
[ , ELEMENT = <replaceable class="parameter">element</replaceable> ] [ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ]
[ , PASSEDBYVALUE ]
@ -32,184 +27,26 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
)
CREATE TYPE <replaceable class="parameter">typename</replaceable> AS
( <replaceable class="PARAMETER">column_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [, ... ] )
</synopsis>
<refsect2 id="R2-SQL-CREATETYPE-1">
<refsect2info>
<date>1998-09-21</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">typename</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of a type to be created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">internallength</replaceable></term>
<listitem>
<para>
A literal value, which specifies the internal length of
the new type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">input_function</replaceable></term>
<listitem>
<para>
The name of a function, created by
<command>CREATE FUNCTION</command>, which
converts data from its external form to the type's
internal form.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">output_function</replaceable></term>
<listitem>
<para>
The name of a function, created by
<command>CREATE FUNCTION</command>, which
converts data from its internal form to a form suitable
for display.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">element</replaceable></term>
<listitem>
<para>
The type being created is an array; this specifies
the type of the array elements.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">delimiter</replaceable></term>
<listitem>
<para>
The delimiter character to be used between values in arrays made
of this type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">default</replaceable></term>
<listitem>
<para>
The default value for the data type. Usually this is omitted,
so that the default is NULL.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">alignment</replaceable></term>
<listitem>
<para>
Storage alignment requirement of the data type. If specified, must
be <literal>char</literal>, <literal>int2</literal>,
<literal>int4</literal>, or <literal>double</literal>;
the default is <literal>int4</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">storage</replaceable></term>
<listitem>
<para>
Storage technique for the data type. If specified, must
be <literal>plain</literal>, <literal>external</literal>,
<literal>extended</literal>, or <literal>main</literal>;
the default is <literal>plain</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">column_name</replaceable></term>
<listitem>
<para>
The name of a column of the composite type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">data_type</replaceable></term>
<listitem>
<para>
The name of an existing data type.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATETYPE-2">
<refsect2info>
<date>1998-09-21</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE TYPE
</computeroutput></term>
<listitem>
<para>
Message returned if the type is successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
( <replaceable class="PARAMETER">attribute_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [, ... ] )
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATETYPE-1">
<refsect1info>
<date>1998-09-21</date>
</refsect1info>
<title>
Description
</title>
<refsect1>
<title>Description</title>
<para>
<command>CREATE TYPE</command> allows the user to register a new data
type with <productname>PostgreSQL</> for use in the current data base.
The user who defines a type becomes its owner.
<command>CREATE TYPE</command> registers a new data type for use in
the current data base. The user who defines a type becomes its
owner.
</para>
<para>
If a schema name is given then the type is created in the
specified schema. Otherwise it is created in the current schema (the one
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
The type name must be distinct from the name of any existing type or
domain in the same schema. (Because tables have associated data types,
type names also must not conflict with table names in the same schema.)
If a schema name is given then the type is created in the specified
schema. Otherwise it is created in the current schema. The type
name must be distinct from the name of any existing type or domain
in the same schema. (Because tables have associated data types,
the type name must also be distinct from the name of any existing
table in the same schema.)
</para>
<refsect2>
@ -220,74 +57,59 @@ CREATE TYPE
(scalar type). It requires the
registration of two functions (using <command>CREATE
FUNCTION</command>) before defining the
type. The representation of a new base type is determined by
type. The internal representation of the new base type is determined by
<replaceable class="parameter">input_function</replaceable>, which
converts the type's external representation to an internal
converts the type's external representation to an internal
representation usable by the
operators and functions defined for the type. Naturally,
operators and functions defined for the type.
<replaceable class="parameter">output_function</replaceable>
performs the reverse transformation. The input function may be
declared as taking one argument of type <type>cstring</type>,
or as taking three arguments of types
<type>cstring</type>, <type>OID</type>, <type>int4</type>.
(The first argument is the input text as a C string, the second
<type>cstring</type>, <type>oid</type>, <type>integer</type>.
The first argument is the input text as a C string, the second
argument is the element type in case this is an array type,
and the third is the <literal>typmod</> of the destination column, if known.)
and the third is the <literal>typmod</> of the destination column, if known.
It should return a value of the data type itself.
The output function may be
declared as taking one argument of the new data type, or as taking
two arguments of which the second is type <type>OID</type>.
(The second argument is again the array element type for array types.)
two arguments of which the second is type <type>oid</type>.
The second argument is again the array element type for array types.
The output function should return type <type>cstring</type>.
</para>
<para>
You should at this point be wondering how the input and output functions
can be declared to have results or inputs of the new type, when they have
can be declared to have results or arguments of the new type, when they have
to be created before the new type can be created. The answer is that the
input function must be created first, then the output function, then the
data type.
<productname>PostgreSQL</productname> will first see the name of the new
data type as the return type of the input function. It will create a
<quote>shell</> type, which is simply a placeholder entry in
<literal>pg_type</>, and link the input function definition to the shell
the system catalog, and link the input function definition to the shell
type. Similarly the output function will be linked to the (now already
existing) shell type. Finally, <command>CREATE TYPE</> replaces the
shell entry with a complete type definition, and the new type can be used.
</para>
<note>
<para>
In <productname>PostgreSQL</productname> versions before 7.3, it was
customary to avoid creating a shell type by replacing the functions'
forward references to the type name with the placeholder pseudo-type
<type>OPAQUE</>. The <type>cstring</> inputs and
results also had to be declared as <type>OPAQUE</> before 7.3.
To support loading
of old dump files, <command>CREATE TYPE</> will accept functions
declared using <type>opaque</>, but it will issue a NOTICE and
change the function's declaration to use the correct types.
</para>
</note>
<para>
New base data types can be fixed length, in which case
Base data types can be fixed-length, in which case
<replaceable class="parameter">internallength</replaceable> is a
positive integer, or variable length, indicated by setting
<replaceable class="parameter">internallength</replaceable>
to <option>VARIABLE</option>. (Internally, this is represented
to <literal>VARIABLE</literal>. (Internally, this is represented
by setting <literal>typlen</> to -1.) The internal representation of all
variable-length types must start with an integer giving the total
variable-length types must start with a 4-byte integer giving the total
length of this value of the type.
</para>
<para>
To indicate that a type is an array,
specify the type of the array
elements using the <option>ELEMENT</> keyword. For example, to define
an array of 4-byte integers ("int4"), specify
<programlisting>ELEMENT = int4</programlisting>
More details about array types appear below.
To indicate that a type is an array, specify the type of the array
elements using the <literal>ELEMENT</> key word. For example, to
define an array of 4-byte integers (<type>int4</type>), specify
<literal>ELEMENT = int4</literal> More details about array types
appear below.
</para>
<para>
@ -295,29 +117,28 @@ CREATE TYPE
representation of arrays of this type, <replaceable
class="parameter">delimiter</replaceable> can be
set to a specific character. The default delimiter is the comma
('<literal>,</literal>'). Note that the delimiter is associated
(<literal>,</literal>). Note that the delimiter is associated
with the array element type, not the array type itself.
</para>
<para>
A default value may be specified, in case a user wants columns of the
data type to default to something other than NULL.
Specify the default with the <option>DEFAULT</option> keyword.
(Such a default may be overridden by an explicit <option>DEFAULT</option>
data type to default to something other than the null value.
Specify the default with the <literal>DEFAULT</literal> key word.
(Such a default may be overridden by an explicit <literal>DEFAULT</literal>
clause attached to a particular column.)
</para>
<para>
The optional flag, <option>PASSEDBYVALUE</option>, indicates that
values of this data type are passed
by value rather than by reference. Note that you
may not pass by value types whose internal representation is
longer than the width of the <type>Datum</> type (four bytes on
most machines, eight bytes on a few).
The optional flag <literal>PASSEDBYVALUE</literal> indicates that
values of this data type are passed by value rather than by
reference. You may not pass by value types whose internal
representation is larger than the size of the <type>Datum</> type
(4 bytes on most machines, 8 bytes on a few).
</para>
<para>
The <replaceable class="parameter">alignment</replaceable> keyword
The <replaceable class="parameter">alignment</replaceable> parameter
specifies the storage alignment required for the data type. The
allowed values equate to alignment on 1, 2, 4, or 8 byte boundaries.
Note that variable-length types must have an alignment of at least
@ -325,21 +146,22 @@ CREATE TYPE
</para>
<para>
The <replaceable class="parameter">storage</replaceable> keyword
allows selection of storage strategies for variable-length data types
(only <literal>plain</literal> is allowed for fixed-length types).
<literal>plain</literal> disables TOAST for the data type: it will always
be stored in-line and not compressed.
<literal>extended</literal> gives full TOAST capability: the system will
first try to compress a long data value, and will move the value out of
The <replaceable class="parameter">storage</replaceable> parameter
allows selection of storage strategies for variable-length data
types. (Only <literal>plain</literal> is allowed for fixed-length
types.) <literal>plain</literal> specifies that data of the type
will always be stored in-line and not compressed.
<literal>extended</literal> specifies that the system will first
try to compress a long data value, and will move the value out of
the main table row if it's still too long.
<literal>external</literal> allows the value to be moved out of the main
table, but the system will not try to compress it.
<literal>main</literal> allows compression, but discourages moving the
value out of the main table. (Data items with this storage method may
still be moved out of the main table if there is no other way to make
a row fit, but they will be kept in the main table preferentially over
<literal>extended</literal> and <literal>external</literal> items.)
<literal>external</literal> allows the value to be moved out of the
main table, but the system will not try to compress it.
<literal>main</literal> allows compression, but discourages moving
the value out of the main table. (Data items with this storage
strategy may still be moved out of the main table if there is no
other way to make a row fit, but they will be kept in the main
table preferentially over <literal>extended</literal> and
<literal>external</literal> items.)
</para>
</refsect2>
@ -349,7 +171,7 @@ CREATE TYPE
<para>
The second form of <command>CREATE TYPE</command>
creates a composite type.
The composite type is specified by a list of column names and data types.
The composite type is specified by a list of attribute names and data types.
This is essentially the same as the row type
of a table, but using <command>CREATE TYPE</command> avoids the need to
create an actual table when all that is wanted is to define a type.
@ -373,19 +195,19 @@ CREATE TYPE
</para>
<para>
You might reasonably ask <quote>why is there an <option>ELEMENT</>
option, if the system makes the correct array type automatically?</quote>
You might reasonably ask why there is an <option>ELEMENT</>
option, if the system makes the correct array type automatically.
The only case where it's useful to use <option>ELEMENT</> is when you are
making a fixed-length type that happens to be internally an array of N
identical things, and you want to allow the N things to be accessed
making a fixed-length type that happens to be internally an array of a number of
identical things, and you want to allow these things to be accessed
directly by subscripting, in addition to whatever operations you plan
to provide for the type as a whole. For example, type <type>name</>
allows its constituent <type>char</>s to be accessed this way.
A 2-D <type>point</> type could allow its two component floats to be
allows its constituent <type>char</> elements to be accessed this way.
A 2-D <type>point</> type could allow its two component numbers to be
accessed like <literal>point[0]</> and <literal>point[1]</>.
Note that
this facility only works for fixed-length types whose internal form
is exactly a sequence of N identical fixed-length fields. A subscriptable
is exactly a sequence of identical fixed-length fields. A subscriptable
variable-length type must have the generalized internal representation
used by <literal>array_in</> and <literal>array_out</>.
For historical reasons (i.e., this is clearly wrong but it's far too
@ -394,41 +216,196 @@ CREATE TYPE
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Parameter</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">typename</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of a type to be created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">internallength</replaceable></term>
<listitem>
<para>
A numeric constant that specifies the internal length of the new
type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">input_function</replaceable></term>
<listitem>
<para>
The name of a function that converts data from the type's
external form to the its internal form.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">output_function</replaceable></term>
<listitem>
<para>
The name of a function that converts data from the type's
internal form to a form suitable for display.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">element</replaceable></term>
<listitem>
<para>
The type being created is an array; this specifies the type of
the array elements.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">delimiter</replaceable></term>
<listitem>
<para>
The delimiter character to be used between values in arrays made
of this type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">default</replaceable></term>
<listitem>
<para>
The default value for the data type. If this is omitted, the
default is null.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">alignment</replaceable></term>
<listitem>
<para>
The storage alignment requirement of the data type. If specified,
it must be <literal>char</literal>, <literal>int2</literal>,
<literal>int4</literal>, or <literal>double</literal>; the
default is <literal>int4</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">storage</replaceable></term>
<listitem>
<para>
The storage strateg for the data type. If specified, must be
<literal>plain</literal>, <literal>external</literal>,
<literal>extended</literal>, or <literal>main</literal>; the
default is <literal>plain</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">attribute_name</replaceable></term>
<listitem>
<para>
The name of an attribute of the composite type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">data_type</replaceable></term>
<listitem>
<para>
The name of an existing data type.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE TYPE</computeroutput></term>
<listitem>
<para>
Message returned if the type was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="SQL-CREATETYPE-notes">
<title>Notes</title>
<para>
User-defined type names cannot begin with the underscore character
(<quote><literal>_</literal></quote>) and can only be 62
characters long (or in general <symbol>NAMEDATALEN</symbol> - 2, rather than
the <symbol>NAMEDATALEN</symbol> - 1 characters allowed for other names).
Type names beginning with underscore are
reserved for internally-created array type names.
</para>
<para>
User-defined type names cannot begin with the underscore character
(<literal>_</literal>) and can only be 62 characters
long (or in general <symbol>NAMEDATALEN</symbol> - 2, rather than
the <symbol>NAMEDATALEN</symbol> - 1 characters allowed for other
names). Type names beginning with underscore are reserved for
internally-created array type names.
</para>
<para>
In <productname>PostgreSQL</productname> versions before 7.3, it
was customary to avoid creating a shell type by replacing the
functions' forward references to the type name with the placeholder
pseudotype <type>opaque</>. The <type>cstring</> arguments and
results also had to be declared as <type>opaque</> before 7.3. To
support loading of old dump files, <command>CREATE TYPE</> will
accept functions declared using <type>opaque</>, but it will issue
a notice and change the function's declaration to use the correct
types.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
This example creates the <type>box</type> data type and then uses the
This example creates the data type <type>box</type> and then uses the
type in a table definition:
<programlisting>
CREATE TYPE box (INTERNALLENGTH = 16,
INPUT = my_procedure_1, OUTPUT = my_procedure_2);
CREATE TABLE myboxes (id INT4, description box);
CREATE TYPE box (
INTERNALLENGTH = 16,
INPUT = my_box_in_function,
OUTPUT = my_box_out_function
);
CREATE TABLE myboxes (
id integer,
description box
);
</programlisting>
</para>
<para>
If <type>box</type>'s internal structure were an array of four
<type>float4</>s, we might instead say
If the internal structure of <type>box</type> were an array of four
<type>float4</> elements, we might instead use
<programlisting>
CREATE TYPE box (INTERNALLENGTH = 16,
INPUT = my_procedure_1, OUTPUT = my_procedure_2,
ELEMENT = float4);
CREATE TYPE box (
INTERNALLENGTH = 16,
INPUT = my_box_in_function,
OUTPUT = my_box_out_function,
ELEMENT = float4
);
</programlisting>
which would allow a box value's component floats to be accessed
which would allow a box value's component numbers to be accessed
by subscripting. Otherwise the type behaves the same as before.
</para>
@ -436,20 +413,30 @@ CREATE TYPE box (INTERNALLENGTH = 16,
This example creates a large object type and uses it in
a table definition:
<programlisting>
CREATE TYPE bigobj (INPUT = lo_filein, OUTPUT = lo_fileout,
INTERNALLENGTH = VARIABLE);
CREATE TABLE big_objs (id int4, obj bigobj);
CREATE TYPE bigobj (
INPUT = lo_filein, OUTPUT = lo_fileout,
INTERNALLENGTH = VARIABLE
);
CREATE TABLE big_objs (
id integer,
obj bigobj
);
</programlisting>
</para>
<para>
This example creates a composite type and uses it in
a table function definition:
a function definition:
<programlisting>
CREATE TYPE compfoo AS (f1 int, f2 text);
CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS 'SELECT fooid, fooname FROM foo' LANGUAGE SQL;
</programlisting>
</para>
<para>
More examples, including suitable input and output functions, are
in <xref linkend="extend">.
</para>
</refsect1>
<refsect1 id="SQL-CREATETYPE-compatibility">

81
doc/src/sgml/ref/create_user.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.25 2003/03/25 16:15:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.26 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -33,16 +33,17 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<title>Description</title>
<para>
<command>CREATE USER</command> will add a new user to an instance
of <productname>PostgreSQL</productname>. Refer to <xref linkend="user-manag">
for information about managing users and authentication. You must
be a database superuser to use this command.
<command>CREATE USER</command> adds a new user to a
<productname>PostgreSQL</productname> database cluster. Refer to
<xref linkend="user-manag"> and <xref
linkend="client-authentication"> for information about managing
users and authentication. You must be a database superuser to use
this command.
</para>
</refsect1>
<refsect2>
<title>Parameters</title>
<para>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
@ -60,9 +61,9 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<para>
The <literal>SYSID</literal> clause can be used to choose the
<productname>PostgreSQL</productname> user ID of the user that
is being created. It is not at all necessary that those match
the Unix user IDs, but some people choose to keep the numbers
the same.
is being created. This is not normally not necessary, but may
be useful if you need to recreate the owner of an orphaned
object.
</para>
<para>
If this is not specified, the highest assigned user ID plus one
@ -76,10 +77,11 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<listitem>
<para>
Sets the user's password. If you do not plan to use password
authentication you can omit this option, but the user
won't be able to connect to a password-authenticated server.
The password can be set or changed later, using
<xref linkend="SQL-ALTERUSER" endterm="SQL-ALTERUSER-title">.
authentication you can omit this option, but then the user
won't be able to connect if you decide to switch to password
authentication. The password can be set or changed later,
using <xref linkend="SQL-ALTERUSER"
endterm="SQL-ALTERUSER-title">.
</para>
</listitem>
</varlistentry>
@ -89,23 +91,22 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<term><literal>UNENCRYPTED</></term>
<listitem>
<para>
These keywords control whether the password is stored
encrypted in <literal>pg_shadow</>. (If neither is specified,
the default behavior is determined by the
<varname>PASSWORD_ENCRYPTION</varname> server parameter.) If
the presented string is already in MD5-encrypted format, then
it is stored as-is, regardless of whether
<literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified.
This allows reloading of encrypted passwords during
dump/restore.
These key words control whether the password is stored
encrypted in the system catalogs. (If neither is specified,
the default behavior is determined by the configuration
parameter <varname>password_encryption</varname>.) If the
presented password string is already in MD5-encrypted format,
then it is stored encrypted as-is, regardless of whether
<literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified
(since the system cannot decrypt the specified encrypted
password string). This allows reloading of encrypted
passwords during dump/restore.
</para>
<para>
See <xref linkend="client-authentication">
for details on how to set up authentication mechanisms. Note
that older clients may lack support for the MD5 authentication
mechanism that is needed to work with passwords that are
stored encrypted.
Note that older clients may lack support for the MD5
authentication mechanism that is needed to work with passwords
that are stored encrypted.
</para>
</listitem>
</varlistentry>
@ -160,26 +161,21 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE USER</computeroutput></term>
<listitem>
<para>
Message returned if the command completes successfully.
Message returned if the user account was successfully created.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
@ -191,9 +187,12 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
endterm="SQL-DROPUSER-title"> to remove a user. Use <xref
linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title"> to add the
user to groups or remove the user from groups.
</para>
<para>
<productname>PostgreSQL</productname> includes a program <xref
linkend="APP-CREATEUSER" endterm="APP-CREATEUSER-title"> that has
the same functionality as this command (in fact, it calls this
the same functionality as <command>CREATE USER</command> (in fact, it calls this
command) but can be run from the command shell.
</para>
</refsect1>
@ -216,12 +215,12 @@ CREATE USER davide WITH PASSWORD 'jw8s0F4';
</para>
<para>
Create a user with a password, whose account is valid until the end of 2001.
Note that after one second has ticked in 2002, the account is not
valid:
Create a user with a password that is valid until the end of 2004.
After one second has ticked in 2005, the password is no longer
valid.
<programlisting>
CREATE USER miriam WITH PASSWORD 'jw8s0F4' VALID UNTIL 'Jan 1 2002';
CREATE USER miriam WITH PASSWORD 'jw8s0F4' VALID UNTIL '2005-01-01';
</programlisting>
</para>

321
doc/src/sgml/ref/create_view.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_view.sgml,v 1.21 2002/11/21 23:34:43 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_view.sgml,v 1.22 2003/04/22 10:08:08 petere Exp $
PostgreSQL documentation
-->
@ -8,136 +8,26 @@ PostgreSQL documentation
<refentrytitle id="SQL-CREATEVIEW-TITLE">CREATE VIEW</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE VIEW
</refname>
<refpurpose>
define a new view
</refpurpose>
<refname>CREATE VIEW</refname>
<refpurpose>define a new view</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2000-03-25</date>
</refsynopsisdivinfo>
<synopsis>
CREATE [ OR REPLACE ] VIEW <replaceable class="PARAMETER">view</replaceable> [ ( <replaceable
class="PARAMETER">column name list</replaceable> ) ] AS SELECT <replaceable class="PARAMETER">query</replaceable>
</synopsis>
<refsect2 id="R2-SQL-CREATEVIEW-1">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">view</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of a view to be created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">column name list</replaceable></term>
<listitem>
<para>
An optional list of names to be used for columns of the view.
If given, these names override the column names that would be
deduced from the SQL query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">query</replaceable></term>
<listitem>
<para>
An SQL query (that is, a <command>SELECT</> statement)
which will provide the columns and rows of the view.
</para>
<para>
Refer to <xref linkend="sql-select" endterm="sql-select-title"> for more information
about valid arguments.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATEVIEW-2">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
<term><computeroutput>
CREATE VIEW
</computeroutput></term>
<listitem>
<para>
The message returned if the view is successfully created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: Relation '<replaceable class="parameter">view</replaceable>' already exists
</computeroutput></term>
<listitem>
<para>
This error occurs if the view specified already exists in the database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
WARNING: Attribute '<replaceable class="parameter">column</replaceable>' has an unknown type
</computeroutput></term>
<listitem>
<para>
The view will be created having a column with an unknown type
if you do not specify it. For example, the following command gives
a warning:
<programlisting>
CREATE VIEW vista AS SELECT 'Hello World'
</programlisting>
whereas this command does not:
<programlisting>
CREATE VIEW vista AS SELECT text 'Hello World'
</programlisting>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<synopsis>
CREATE [ OR REPLACE ] VIEW <replaceable class="PARAMETER">name</replaceable> [ ( <replaceable
class="PARAMETER">column_name</replaceable> [, ...] ) ] AS <replaceable class="PARAMETER">query</replaceable>
</synopsis>
</refsynopsisdiv>
<refsect1 id="R1-SQL-CREATEVIEW-1">
<refsect1info>
<date>2000-03-25</date>
</refsect1info>
<title>
Description
</title>
<refsect1>
<title>Description</title>
<para>
<command>CREATE VIEW</command> defines a view of a query.
The view is not physically materialized. Instead, a query
rewrite rule (an <literal>ON SELECT</> rule) is automatically generated to
support SELECT operations on views.
<command>CREATE VIEW</command> defines a view of a query. The view
is not physically materialized. Instead, the query is run everytime
the view is referenced in a query.
</para>
<para>
@ -150,19 +40,87 @@ CREATE VIEW vista AS SELECT text 'Hello World'
<para>
If a schema name is given (for example, <literal>CREATE VIEW
myschema.myview ...</>) then the view is created in the
specified schema. Otherwise it is created in the current schema (the one
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
specified schema. Otherwise it is created in the current schema.
The view name must be distinct from the name of any other view, table,
sequence, or index in the same schema.
</para>
</refsect1>
<refsect2 id="R2-SQL-CREATEVIEW-3">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
Notes
</title>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name (optionally schema-qualified) of a view to be created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">column_name</replaceable></term>
<listitem>
<para>
An optional list of names to be used for columns of the view.
If not given, the column names are deduced from the query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">query</replaceable></term>
<listitem>
<para>
A query (that is, a <command>SELECT</> statement) which will
provide the columns and rows of the view.
</para>
<para>
Refer to <xref linkend="sql-select" endterm="sql-select-title">
for more information about valid queries.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>CREATE VIEW</computeroutput></term>
<listitem>
<para>
Message returned if the view was successfully created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>WARNING: Attribute '<replaceable class="parameter">column</replaceable>' has an unknown type</computeroutput></term>
<listitem>
<para>
The view will be created having a column with an unknown type if
you do not specify it. For example, the following command gives
this warning:
<programlisting>
CREATE VIEW vista AS SELECT 'Hello World'
</programlisting>
whereas this command does not:
<programlisting>
CREATE VIEW vista AS SELECT text 'Hello World'
</programlisting>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
Currently, views are read only: the system will not allow an insert,
@ -175,100 +133,79 @@ CREATE VIEW vista AS SELECT text 'Hello World'
<para>
Use the <command>DROP VIEW</command> statement to drop views.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-SQL-CREATEVIEW-2">
<title>
Usage
</title>
<para>
Create a view consisting of all Comedy films:
<refsect1>
<title>Examples</title>
<programlisting>
CREATE VIEW kinds AS
<para>
Create a view consisting of all comedy films:
<programlisting>
CREATE VIEW comedies AS
SELECT *
FROM films
WHERE kind = 'Comedy';
SELECT * FROM kinds;
code | title | did | date_prod | kind | len
-------+---------------------------+-----+------------+--------+-------
UA502 | Bananas | 105 | 1971-07-13 | Comedy | 01:22
C_701 | There's a Girl in my Soup | 107 | 1970-06-11 | Comedy | 01:36
(2 rows)
</programlisting>
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATEVIEW-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEVIEW-5">
<refsect2info>
<date>2000-03-25</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
SQL92 specifies some additional capabilities for the
<command>CREATE VIEW</command> statement:
</para>
<synopsis>
CREATE VIEW <replaceable class="parameter">view</replaceable> [ <replaceable class="parameter">column</replaceable> [, ...] ]
AS SELECT <replaceable class="parameter">expression</replaceable> [ AS <replaceable class="parameter">colname</replaceable> ] [, ...]
FROM <replaceable class="parameter">table</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
<para>
The SQL standard specifies some additional capabilities for the
<command>CREATE VIEW</command> statement:
<synopsis>
CREATE VIEW <replaceable class="parameter">name</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
AS query
[ WITH [ CASCADE | LOCAL ] CHECK OPTION ]
</synopsis>
</synopsis>
</para>
<para>
The optional clauses for the full SQL92 command are:
<para>
The optional clauses for the full SQL command are:
<variablelist>
<varlistentry>
<term>CHECK OPTION</term>
<term><literal>CHECK OPTION</literal></term>
<listitem>
<para>
This option is to do with updatable views.
All <command>INSERT</> and <command>UPDATE</> commands on the view will be
checked to ensure data satisfy the view-defining
condition. If they do not, the update will be rejected.
This option is to do with updatable views. All
<command>INSERT</> and <command>UPDATE</> commands on the view
will be checked to ensure data satisfy the view-defining
condition (that is, the new data would be visible through the
view). If they do not, the update will be rejected.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LOCAL</term>
<term><literal>LOCAL</literal></term>
<listitem>
<para>
Check for integrity on this view.
Check for integrity on this view.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CASCADE</term>
<term><literal>CASCADE</literal></term>
<listitem>
<para>
Check for integrity on this view and on any dependent
view. CASCADE is assumed if neither CASCADE nor LOCAL is specified.
Check for integrity on this view and on any dependent
view. <literal>CASCADE</> is assumed if neither
<literal>CASCADE</> nor <literal>LOCAL</> is specified.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</variablelist>
</para>
<para>
<command>CREATE OR REPLACE VIEW</command> is a
<productname>PostgreSQL</productname> language extension.
</para>
</refsect2>
<para>
<command>CREATE OR REPLACE VIEW</command> is a
<productname>PostgreSQL</productname> language extension.
</para>
</refsect1>
</refentry>